Teams 并行 Agent（智能体） 协作

超越单 Agent 限制：同一进程内的多个并行 Agent 实例通过消息传递机制协同工作，构建大规模多视角 AI 编程工作流。

文章概述

当单个 Agent 无法满足复杂工程场景的需求时，Teams 并行 Agent 协作提供了解决方案。与 Agent 派生（父子关系）不同，Teams 是同一进程内的多个并行 Agent 实例的平级协作——每个 Team 成员都是独立的 Agent 会话实例，有自己的上下文、技能和生命周期，通过消息传递机制通信和同步。所有成员运行在同一个 OMO 进程中，而非独立的操作系统进程。

读完本文，你将能够设计大规模 Teams 并行 Agent 协作架构，理解通信协议和消息传递机制，以及在性能与隔离性之间做出合理的权衡决策。

本文从 Teams 的架构设计原则入手，解释为什么需要从单 Agent 走向并行 Agent 协作。你会理解 Team 的成员角色定义、通信协议（team_send_message 的工作原理）和基于 inbox 文件的消息传递机制。我们深入讨论同一进程内多个 Agent 协作的优缺点——资源竞争和隔离问题如何管理，团队的生命周期如何维护。然后通过对比表分析 Team Mode 与独立 Agent 的适用场景，帮助你在性能与隔离性之间做出权衡。最后，讨论大规模 Teams 的工程实践：分层协调设计、监控和日志收集、故障恢复策略。

从后端架构师视角，我们将探讨多服务上下文的 Agent 编排策略；从架构顾问视角，我们将分析 Teams 架构的设计原则和权衡决策；从渗透测试员视角，我们将深入审查 Team Mode 的数据隔离安全边界。

⏱ 时间有限？先读这些： Teams 架构概述 → 消息传递与 inbox 机制 → Team Mode vs 独立 Agent → 大规模 Teams 的工程实践

Teams 架构概述

为什么需要 Teams 架构

单进程 Agent 存在三个核心限制，这些限制在复杂工程场景中尤为突出：

1. 上下文窗口瓶颈：单个 Agent 的上下文窗口有限，当任务涉及多个代码仓库、多种技术栈时，上下文溢出导致决策质量下降。后端架构师在微服务架构中经常面临这个问题——一个变更可能涉及 API 网关、认证服务、业务服务、数据库迁移等多个上下文。

2. 资源竞争问题：CPU、内存、网络连接等资源在单进程内竞争。当 Agent 执行 CPU 密集型任务（代码分析）和 I/O 密集型任务（网络请求）时，资源竞争导致整体效率下降。

3. 故障隔离需求：单进程内的任何错误都可能影响整个 Agent。当某个子任务失败（如依赖安装超时），可能导致主任务也被中断。

Teams 架构通过并行 Agent 协作解决这些问题：每个 Team 成员是同一进程内的独立 Agent 会话实例，拥有独立的 Prompt（提示词） 上下文和故障边界。

相关 Skill：OpenCode 内置了 team-mode Skill，可通过 skill(name="team-mode") 加载团队编排的完整指令参考，了解 Team 成员角色定义、通信协议和生命周期管理的详细规范。完整内置 Skill 列表见 附录 B 内置 Skill 参考。

Team 的成员角色定义

Team 成员的角色定义遵循职责分离原则。每个成员专注于特定领域，通过消息传递协作完成复杂任务。

flowchart TB
    subgraph Team["Team: 安全审计团队"]
        direction TB
        A[Team Lead<br/>任务分配与汇总] --> B[Vulnerability Scanner<br/>漏洞扫描]
        A --> C[Code Analyzer<br/>代码分析]
        A --> D[PoC Engineer<br/>漏洞验证]
        
        B --> E[漏洞列表]
        C --> F[代码风险报告]
        D --> G[验证结果]
        
        E --> H[Team Lead<br/>结果汇总]
        F --> H
        G --> H
    end
    
    style A fill:#4A90D9,color:#fff
    style B fill:#50C878,color:#fff
    style C fill:#50C878,color:#fff
    style D fill:#50C878,color:#fff
    style H fill:#FF9F43,color:#fff

角色定义配置示例：

{
  "team": {
    "name": "security-audit-team",
    "description": "安全审计团队：漏洞扫描、代码分析、漏洞验证",
    "members": [
      {
        "id": "team-lead",
        "role": "coordinator",
        "model": "best-capability-model",
        "skills": ["overall-planning", "dispatching-parallel-agents"],
        "permissions": {
          "read": "allow",
          "edit": "deny",
          "bash": "deny",
          "team_send_message": "allow"
        },
        "responsibilities": ["任务分解", "进度监控", "结果汇总"]
      },
      {
        "id": "vuln-scanner",
        "role": "worker",
        "model": "balanced-model",
        "skills": ["vulnerability-manager", "blue-team-defender"],
        "permissions": {
          "read": "allow",
          "edit": "deny",
          "bash": "allow",
          "team_send_message": "allow"
        },
        "responsibilities": ["漏洞扫描", "CVE 匹配", "风险评分"]
      },
      {
        "id": "code-analyzer",
        "role": "worker",
        "model": "balanced-model",
        "skills": ["security-architect", "penetration-tester"],
        "permissions": {
          "read": "allow",
          "edit": "deny",
          "bash": "allow",
          "team_send_message": "allow"
        },
        "responsibilities": ["代码审计", "安全模式检查", "敏感数据发现"]
      },
      {
        "id": "poc-engineer",
        "role": "worker",
        "model": "balanced-model",
        "skills": ["elite-red-team-hacker", "penetration-tester"],
        "permissions": {
          "read": "allow",
          "edit": "ask",
          "bash": "ask",
          "team_send_message": "allow"
        },
        "responsibilities": ["漏洞验证", "PoC 编写", "修复建议"]
      }
    ]
  }
}

基于 Inbox 文件的通信机制

Team 成员之间的通信基于单个 JSON 文件的消息传递协议（每封消息一个独立文件），而非共享内存或操作系统进程间通信（IPC）。所有成员运行在同一个 OMO 进程中，通过文件系统实现消息的持久化和异步投递。

概念消息类型说明：本节定义的以下消息类型（task_assignment / status_sync / result_aggregation / error_report / heartbeat）是为方便理解而引入的概念分类，并非 OMO 内置的消息类型。实际 Team Mode 通过 team_send_message 发送自由文本消息，消息的含义由发送者和接收者的上下文协商决定。

概念消息类型体系：

Inbox 文件机制：

Team Mode 的底层通信基于 per-message JSON 文件，存储在 ~/.omo/runtime/{teamRunId}/inboxes/ 目录下：

1. 每个 Team 成员拥有一个专用的 inbox 目录：~/.omo/runtime/{teamRunId}/inboxes/{memberName}/
2. 每封消息写入一个独立的 {uuid}.json 文件（原子写入，非 append-only 日志）
3. 消息格式为 { version: 1, messageId: "uuid", from: "sender", to: "recipient", kind: "message", body: "文本内容", timestamp: 1700000000000, correlationId?: "关联ID", summary?: "摘要" }
4. 消息的投递是 fire-and-forget（即发即忘） 模式——team_send_message 立即返回，无需同步等待回复

消息投递流程：

发送方调用 team_send_message → 写入接收方 inbox/{uuid}.json
  → 后台自动执行 Live Delivery：重命名为 .delivering-{uuid}.json
    → promptAsync 注入 <peer_message> 到接收方会话
      → 接收方处理完成后，文件移至 inbox/processed/{uuid}.json
  → 如接收方处于空闲状态，autoWake 机制注入唤醒提示
  → 如投递失败（会话崩溃），.delivering- 文件 10 分钟后释放回未读状态

消息传递机制

team_send_message 的工作原理

team_send_message 是 Team Mode 的核心通信工具，实现了 Agent 间的异步消息传递。消息以单个 JSON 文件形式写入接收方的 inbox 目录（{uuid}.json），属于 fire-and-forget（即发即忘） 模式——team_send_message 立即返回，无需同步等待回复。

sequenceDiagram
    participant A as Team Lead
    participant F as Inbox 文件系统
    participant B as Worker 1
    participant C as Worker 2
    
    A->>F: team_send_message → 写入 B 的 inbox/
    Note over F: ~/.omo/runtime/{runId}/inboxes/b/{uuid}.json
    F-->>B: promptAsync 注入合成用户消息
    B->>B: autoWake（如空闲）→ 重启 Prompt 循环
    
    B->>F: team_send_message → 写入 A 的 inbox/
    F-->>A: promptAsync 注入
    
    C->>F: team_send_message → 写入 A 的 inbox/
    F-->>A: promptAsync 注入
    
    B->>F: team_send_message → 写入 A 的 inbox/
    F-->>A: promptAsync 注入
    
    A->>A: 汇总结果

底层实现机制：

1. 消息写入：消息写入接收方的 ~/.omo/runtime/{teamRunId}/inboxes/{memberName}/{uuid}.json
2. 预留投递（Live Delivery）：发送方将文件重命名为 .delivering-{uuid}.json，表示正在投递中
3. 会话注入：通过 promptAsync 将 inbox 消息包装为 <peer_message> XML 包，作为合成用户消息注入接收方的对话上下文
4. 投递确认（Ack）：消息被接收方处理后，从 inbox 根目录移动到 inboxes/{memberName}/processed/{uuid}.json
5. autoWake：如果接收方处于空闲状态且有未读消息，autoWake 机制自动注入唤醒提示
6. 故障恢复：如果投递过程中接收方会话崩溃，.delivering- 文件在 10 分钟 TTL 后释放回未读状态，供下次轮询使用

team_send_message 参数详解：

{
  "team_send_message": {
    "to": "vuln-scanner",
    "body": "请扫描 /api/auth 路由的 SQL 注入漏洞。目标文件: src/api/auth.ts, src/db/queries.ts。超时时间: 300000ms",
    "summary": "SQL 注入扫描任务 #scan-001",
    "references": [
      { "path": "src/api/auth.ts", "description": "认证 API 路由" },
      { "path": "src/db/queries.ts", "description": "数据库查询" }
    ]
  }
}

消息类型详解

任务分配（Task Assignment）

Team Lead 向 Worker 分配子任务的消息类型：

{
  "type": "task_assignment",
  "payload": {
    "task_id": "unique-task-id",
    "description": "任务描述",
    "skills_required": ["penetration-tester"],
    "context": {
      "files": ["path/to/file"],
      "constraints": {}
    },
    "deadline": "2024-01-15T10:00:00Z",
    "priority": "high"
  }
}

任务分配策略：

状态同步（Status Sync）

Worker 向 Team Lead 汇报执行状态：

{
  "type": "status_sync",
  "payload": {
    "task_id": "scan-001",
    "status": "in_progress",
    "progress": 45,
    "metrics": {
      "files_scanned": 12,
      "files_total": 27,
      "issues_found": 3
    },
    "eta": "2024-01-15T09:45:00Z"
  }
}

状态类型：

• pending：任务已接收，等待执行
• in_progress：任务执行中
• blocked：任务被阻塞（等待依赖）
• completed：任务完成
• failed：任务失败

结果汇总（Result Aggregation）

Worker 提交执行结果给 Team Lead：

{
  "type": "result_aggregation",
  "payload": {
    "task_id": "scan-001",
    "status": "completed",
    "output": {
      "vulnerabilities": [
        {
          "type": "SQL_INJECTION",
          "severity": "HIGH",
          "location": "src/api/auth.ts:45",
          "payload": "' OR '1'='1",
          "recommendation": "使用参数化查询"
        }
      ],
      "summary": {
        "total": 1,
        "high": 1,
        "medium": 0,
        "low": 0
      }
    },
    "artifacts": [
      {
        "type": "report",
        "path": "/tmp/scan-001-report.json"
      }
    ]
  }
}

消息处理的现实约束

⚠️ 关键差异：OMO Team Mode 的 inbox 机制与消息队列中间件有本质区别。以下对比帮助理解这些差异带来的工程含义。

与消息队列的对比清单：

这些限制并非缺陷，而是设计选择——Team Mode 优先保证简单性和可靠性，通过 LLM 的上下文理解能力来协商消息处理顺序和确认，而非依赖复杂的基础设施组件。

进程内集群

多 Agent 同进程协作的优缺点

进程内集群（In-Process Cluster）是指多个 Agent 在同一个进程内协作的模式。这种模式在特定场景下具有优势，但也存在明显的局限性。

优势分析：

劣势分析：

资源竞争和隔离策略

同一进程内的多 Agent 协作需要关注两类资源竞争：系统资源（CPU/内存）和 LLM API 资源（速率限制/Token 配额）。

LLM API 速率限制（最现实的瓶颈）

在实际使用中，LLM API 速率限制和 Token 配额是 Team Mode 最常见的资源竞争问题——比 CPU/内存竞争频繁得多。

典型场景：

应对策略：

• 错峰调度：避免所有 Worker 同时启动，让 Team Lead 分批发起任务
• 模型分离：Lead 使用高端模型进行决策，Worker 使用轻量模型执行具体任务
• 重试机制：在 Worker 层面对 429 错误实现退避重试
• Token 预算：每个 Worker 设定明确的 Token 上限（maxTokens），避免单个成员耗尽配额

系统资源隔离

⚠️ 注意：以下配置（cfs_quota、cgroups、bandwidth_limit）均为 Linux 内核特性，macOS 不支持。macOS 用户无法直接应用这些设置。

{
  "resourceIsolation": {
    "cpu": {
      "strategy": "cfs_quota",      // ⚠️ Linux only
      "limits": {
        "team-lead": { "quota": 50, "period": 100 },
        "worker": { "quota": 100, "period": 100 }
      }
    },
    "memory": {
      "strategy": "cgroups",        // ⚠️ Linux only
      "limits": {
        "team-lead": "512MB",
        "worker": "1GB"
      },
      "oomPolicy": "kill_oldest"     // ⚠️ Linux only
    },
    "network": {
      "strategy": "bandwidth_limit", // ⚠️ Linux only
      "limits": {
        "team-lead": "10MB/s",
        "worker": "50MB/s"
      }
    },
    "fileDescriptors": {
      "limit": 1024,
      "strategy": "per_agent"
    }
  }
}

macOS 替代方案：在 macOS 上无法使用 cgroups/cfs_quota 进行精细化资源控制。建议采用应用层策略：通过配置每个 Agent 的 maxTokens 和 steps 限制来间接控制资源消耗，或使用 ulimit 进行进程级别的粗粒度限制。

竞争检测和缓解：

{
  "contentionManagement": {
    "detection": {
      "cpuThreshold": 0.8,
      "memoryThreshold": 0.85,
      "networkThreshold": 0.9,
      "checkInterval": 5000
    },
    "mitigation": {
      "strategies": ["throttle", "queue", "reject"],
      "throttleThreshold": 0.9,
      "queueSize": 100,
      "rejectThreshold": 0.95
    }
  }
}

死锁分析与防范

Team Mode 由于缺乏集中式调度器和死锁检测机制，在多成员协作时可能出现以下死锁场景。当前 OMO 不提供内置的死锁检测，需要架构设计层面主动防范。

死锁场景分析：

推荐防范配置：

{
  "deadlockPrevention": {
    "taskDependency": {
      "allowCycles": false,
      "maxChainLength": 5,
      "timeoutPerTask": 300000
    },
    "fileAccess": {
      "workerOutputDir": "./output/{agent_id}/",
      "namingPattern": "{agent_id}_{task_id}_{timestamp}"
    },
    "messageControl": {
      "maxConcurrentMessages": 3,
      "requireCompletionBeforeNewTask": true
    }
  }
}

集群生命周期管理

集群生命周期遵循创建→扩容→运行→缩容→销毁的五阶段状态机模型。与传统的无状态服务集群不同，Agent 集群的每个阶段涉及 LLM 会话初始化、Skill 上下文加载和 Inbox 目录的创建与清理，因此生命周期管理对资源隔离和故障恢复至关重要。运行阶段是集群的稳态，期间根据负载指标动态决定是否扩容或缩容；当所有任务完成后，先进入缩容阶段回收空闲 Worker，最终进入销毁阶段完成整体清理。以下流程图展示了完整的生命周期状态转换：

flowchart TB
    A[创建阶段] --> B[扩容阶段]
    B --> C[运行阶段]
    C --> D{需要缩容?}
    D -->|是| E[缩容阶段]
    E --> C
    D -->|否| F{任务完成?}
    F -->|否| C
    F -->|是| G[销毁阶段]
        
    style A fill:#4A90D9,color:#fff
    style B fill:#50C878,color:#fff
    style E fill:#FF9F43,color:#fff
    style G fill:#999,color:#fff

创建阶段

创建阶段是集群的起点，负责从零初始化整个 Team 的运行环境。四个步骤按序执行：

flowchart TB
    subgraph 创建阶段
        A1[初始化 Team 配置] --> A2[创建 Team Lead]
        A2 --> A3[创建 Worker 池]
        A3 --> A4[初始化 Inbox 目录]
    end

    style A1 fill:#4A90D9,color:#fff
    style A2 fill:#50C878,color:#fff
    style A3 fill:#FF9F43,color:#fff
    style A4 fill:#999,color:#fff

1. 初始化 Team 配置：加载 JSON 配置文件中定义的 Team 名称、成员角色、Skill 依赖和权限策略
2. 创建 Team Lead：实例化协调者 Agent，加载顶层规划 Skill（如 overall-planning、dispatching-parallel-agents），设置消息路由权限
3. 创建 Worker 池：根据 minWorkers 批量实例化 Worker Agent，每个 Worker 拥有独立的 Prompt 上下文和 Skill 组合
4. 初始化 Inbox 目录：在 ~/.omo/runtime/{teamRunId}/inboxes/ 下为每个成员创建收件目录，供消息持久化和异步投递使用

配置项 warmup 控制是否预加载 Agent 会话以减少首次任务延迟，prefetchSkills 决定是否提前拉取 Skill 依赖，initTimeout 设定创建阶段的最长等待时间。

扩容阶段

下图展示了集群扩容阶段的执行流程，从负载检测到新 Worker 加入的完整步骤。

flowchart TB
    subgraph 扩容阶段
        B1[监控负载指标] --> B2{负载 > 阈值?}
        B2 -->|是| B3[创建新 Worker]
        B2 -->|否| B4[保持现状]
    end

    style B1 fill:#4A90D9,color:#fff
    style B2 fill:#50C878,color:#fff
    style B3 fill:#FF9F43,color:#fff
    style B4 fill:#999,color:#fff

运行阶段中，Team Lead 持续监控集群负载指标——包括 CPU 使用率、Inbox 消息积压深度和 Worker 任务队列长度。当综合负载超过 scaleUpThreshold（默认 0.7）时，自动创建新的 Worker 加入集群分担任务，Worker 数量上限由 maxWorkers（默认 10）控制。扩容后进入 cooldownPeriod（默认 60 秒），避免频繁伸缩导致的震荡。若负载未达到阈值，集群维持当前规模继续运行。

缩容阶段

下图展示了集群缩容阶段的执行流程，从空闲 Worker 识别到资源回收的步骤。

flowchart TB
    subgraph 缩容阶段
        E1[识别空闲 Worker] --> E2[迁移未完成任务]
        E2 --> E3[优雅关闭 Worker]
    end
    
    style E1 fill:#4A90D9,color:#fff
    style E2 fill:#50C878,color:#fff
    style E3 fill:#FF9F43,color:#fff

当集群负载持续低于 scaleDownThreshold（默认 0.3）时，Team Lead 启动缩容以减少资源占用。流程遵循“先迁移、再关闭“的安全策略：首先识别空闲或低负载 的 Worker，将其未完成任务通过 team_send_message 迁移到其他活跃 Worker；确认任务迁移完成后，向目标 Worker 发送 team_shutdown_request 并发起优雅关闭，等待其在 taskCompletionTimeout 内处理完当前任务。缩容完成后集群回到运行阶段继续服务。

销毁阶段

销毁阶段是集群生命周期的终点，执行完整的资源回收。流程按照“先停止流入、再排空存量、最后清理痕迹“的顺序执行：

flowchart TB
    subgraph 销毁阶段
        G1[停止接收新任务] --> G2[等待任务完成]
        G2 --> G3[清理资源]
        G3 --> G4[销毁 Team]
    end

    style G1 fill:#4A90D9,color:#fff
    style G2 fill:#50C878,color:#fff
    style G3 fill:#FF9F43,color:#fff
    style G4 fill:#999,color:#fff

1. 停止接收新任务：Team Lead 停止分配新任务，拒绝新的 team_send_message 请求
2. 等待任务完成：等待所有已在执行的任务在 taskCompletionTimeout（默认 300 秒）内自然完成；超时未完成的由 forceKillTimeout（默认 60 秒）强制终止
3. 清理资源：回收 Agent 会话、关闭 Inbox 文件句柄、清空 ~/.omo/runtime/{teamRunId}/ 下的运行时目录
4. 销毁 Team：调用 team_delete 删除 Team 记录，释放所有会话和 Inbox 文件

生命周期配置：

以下 JSON 配置对应上述四阶段模型的核心参数。creation 段控制创建阶段的行为（预热、Skill 预取和超时）；scaling 段定义扩容缩容的阈值、Worker 数量范围和冷却周期；termination 段配置优雅关闭和强制终止策略。各参数的含义已在对应阶段的文字说明中解释，此处作为集中参考。

{
  "lifecycle": {
    "creation": {
      "warmup": true,
      "prefetchSkills": true,
      "initTimeout": 60000
    },
    "scaling": {
      "minWorkers": 2,
      "maxWorkers": 10,
      "scaleUpThreshold": 0.7,
      "scaleDownThreshold": 0.3,
      "cooldownPeriod": 60000
    },
    "termination": {
      "gracefulShutdown": true,
      "taskCompletionTimeout": 300000,
      "forceKillTimeout": 60000
    }
  }
}

成员数量建议：大多数 Team 任务建议 2-3 个 Worker（1 个 Lead + 2-3 个 Worker）。对于复杂的安全审计或大规模代码审查，推荐 4-8 个 Worker。超过 8 个成员后，通信协调开销会显著增加，建议拆分多个 Team 分层治理。

共享状态的一致性问题

⚠️ 概念探讨：以下内容是对“如果 Team 成员共享状态“这一场景的架构探讨。当前 OMO Team Mode 不支持 Agent 间的共享内存状态——每个 Agent 拥有独立的 Prompt 上下文，状态必须通过 team_send_message 显式传递。以下模型供架构设计参考。

进程内集群理论上可以使用共享内存简化状态管理，但需要处理一致性问题：

一致性模型选择：

状态同步配置：

{
  "stateSynchronization": {
    "model": "eventual_consistency",
    "sharedState": {
      "taskProgress": {
        "consistency": "eventual",
        "syncInterval": 5000,
        "conflictResolution": "last_write_wins"
      },
      "memberStatus": {
        "consistency": "strong",
        "syncInterval": 1000,
        "conflictResolution": "leader_decides"
      },
      "resourceQuota": {
        "consistency": "strong",
        "syncInterval": 500,
        "conflictResolution": "atomic_increment"
      }
    }
  }
}

Team Mode vs 独立 Agent

适用场景对比

Team Mode 和独立 Agent 各有适用场景，选择取决于任务特性和工程约束。

性能 vs 隔离性权衡

架构顾问需要在性能和隔离性之间做出权衡：

graph LR
    subgraph 性能优先
        A1[进程内集群] --> A2[共享内存通信]
        A2 --> A3[低延迟协作]
    end
    
    subgraph 平衡模式
        B1[Team Mode] --> B2[消息传递通信]
        B2 --> B3[会话隔离]
    end
    
    subgraph 隔离优先
        C1[独立 Agent] --> C2[文件交接通信]
        C2 --> C3[完全隔离]
    end
    
    A3 --> D[适用场景评估]
    B3 --> D
    C3 --> D
    
    D --> E{任务特性}
    E -->|高频交互| A1
    E -->|并行协作| B1
    E -->|安全敏感| C1
    
    style A1 fill:#50C878,color:#fff
    style B1 fill:#4A90D9,color:#fff
    style C1 fill:#A66CFF,color:#fff

权衡决策矩阵：

混合模式设计

⚠️ 概念模型说明：以下“混合模式“是架构设计层面的概念模型，描述如何将 Team Mode 和独立 Agent 编排在一起。当前 OMO 的 Team Mode 所有成员运行在同一进程中，不支持部分成员独立部署为 OS 进程。此处的“独立成员“在实现上应通过 task() 调用的独立 Agent 实现，而非 Team 内部的异构部署。

混合模式结合 Team Mode 和独立 Agent 的优势：核心成员在 Team 内协作，独立成员通过 task() 委派方式运行。

混合架构配置：

{
  "hybridArchitecture": {
    "team": {
      "name": "fullstack-development-team",
      "mode": "hybrid",
      "inProcessMembers": [
        {
          "id": "coordinator",
          "role": "team-lead",
          "reason": "高频消息协调"
        },
        {
          "id": "frontend-worker",
          "role": "worker",
          "reason": "与 coordinator 紧密协作"
        }
      ],
      "independentMembers": [
        {
          "id": "security-auditor",
          "role": "specialist",
          "reason": "安全隔离需求",
          "isolation": {
            "workdir": "./agent-security",
            "network": "isolated",
            "permissions": ["read", "bash"]
          }
        },
        {
          "id": "database-migrator",
          "role": "specialist",
          "reason": "数据库访问隔离",
          "isolation": {
            "workdir": "./agent-db",
            "network": "restricted",
            "allowedHosts": ["db.internal:5432"]
          }
        }
      ]
    },
    "communication": {
      "inProcess": "inbox_message",
      "crossProcess": "inbox_message",
      "external": "file交接"
    }
  }
}

Team Mode 数据隔离审查

从渗透测试员视角，Team Mode 的数据隔离是关键的安全边界。不当的隔离配置可能导致敏感数据泄露或权限提升攻击。

数据隔离级别

完全隔离配置：

{
  "isolation": {
    "level": "complete",
    "workdir": "./agents/{agent_id}",
    "filesystem": {
      "readonly": [],
      "readwrite": ["./agents/{agent_id}"],
      "denied": ["./secrets", "./.env", "./credentials"]
    },
    "network": {
      "mode": "isolated",
      "allowedHosts": [],
      "deniedHosts": ["*"]
    },
    "environment": {
      "inherit": false,
      "variables": {
        "AGENT_ID": "{agent_id}",
        "TEAM_ID": "{team_id}"
      }
    }
  }
}

共享读取配置：

{
  "isolation": {
    "level": "shared_read",
    "workdir": "./agents/{agent_id}",
    "filesystem": {
      "readonly": ["./src", "./docs", "./config"],
      "readwrite": ["./agents/{agent_id}", "./reports"],
      "denied": ["./secrets", "./.env", "./credentials"]
    },
    "network": {
      "mode": "restricted",
      "allowedHosts": ["api.internal", "registry.internal"],
      "deniedHosts": ["*"]
    }
  }
}

安全检查清单

渗透测试员应验证以下安全检查项：

文件系统隔离：

• 敏感文件不在共享目录中（.env、.key、.pem、credentials.*）
• Agent 输出目录有权限控制（仅限该 Agent 可写）
• 临时文件定期清理（避免残留敏感数据）
• 符号链接不指向敏感目录

网络隔离：

• Agent 网络访问按最小权限配置
• 敏感服务（数据库、消息队列）仅限特定 Agent 访问
• 外部网络访问需要审批（bash: ask）
• DNS 解析不泄露内部服务信息

日志安全：

• 日志不包含敏感信息（API Key、密码、Token）
• 日志文件权限正确（仅限审计角色可读）
• 日志轮转配置正确（避免磁盘占满）
• 跨 Agent 日志隔离

会话与进程隔离：

• Agent 进程以非 root 用户运行
• 资源限制配置正确（CPU、内存、文件描述符）
• 子进程继承限制正确
• 信号处理正确（避免被恶意终止）

数据隔离安全配置示例

{
  "securityHardening": {
    "filesystem": {
      "excludePatterns": [
        "*.env", "*.key", "*.pem", "*.p12",
        "credentials*", "secrets*", "password*",
        ".git/", "node_modules/", ".cache/"
      ],
      "redactPatterns": [
        "sk-[a-zA-Z0-9]{48}",
        "xox[baprs]-[a-zA-Z0-9-]+",
        "eyJ[a-zA-Z0-9_-]*\\.eyJ[a-zA-Z0-9_-]*\\.[a-zA-Z0-9_-]*",
        "password\\s*=\\s*['\"][^'\"]+['\"]",
        "api[_-]?key\\s*=\\s*['\"][^'\"]+['\"]"
      ],
      "auditAccess": true,
      "logSensitiveAccess": true
    },
    "network": {
      "defaultDeny": true,
      "allowRules": [
        { "agent": "frontend-worker", "hosts": ["cdn.jsdelivr.net", "registry.npmjs.org"] },
        { "agent": "backend-worker", "hosts": ["api.github.com", "pypi.org"] },
        { "agent": "security-auditor", "hosts": ["cve.mitre.org", "nvd.nist.gov"] }
      ],
      "denyRules": [
        { "agent": "*", "hosts": ["169.254.169.254", "metadata.google.internal"] }
      ]
    },
    "process": {
      "user": "agent",
      "group": "agents",
      "capabilities": ["CAP_NET_BIND_SERVICE"],
      "noNewPrivileges": true,
      "seccompProfile": "runtime/default"
    },
    "audit": {
      "enabled": true,
      "logLevel": "verbose",
      "events": ["file_access", "network_access", "permission_denied", "sensitive_access"],
      "retention": "30d"
    }
  }
}

大规模 Teams 的工程实践

分层 Team 架构

大规模 Teams 采用分层架构，父 Team 包含子 Team 的分层治理模型：

⚠️ 逻辑分层说明：此处的“父 Team 包含子 Team“是业务逻辑层面的概念协调模型，而非物理架构的真实反映。下图展示的是逻辑层级关系，用于说明概念上的任务分解与协调模式。以下配置中的 shared_memory 和 message_queue 通信方式是概念设计，实际 OMO 使用 inbox 文件进行消息传递。

实际约束：

• OMO 禁止 Team 成员调用 team_create——物理嵌套是不可能的
• 所有 Team 成员运行在同一 OMO 进程内，不存在物理进程边界
• 分层协调通过消息传递实现：一个 Team 的 Lead 可以向另一个 Team 的 Lead 发送消息，请求子任务执行
• 12 个 team_* 工具在 API 层面不支持嵌套（参见自定义工作流中 Team Mode 的限制）
• 下图中的箭头表示概念上的任务分配关系，而非进程间通信

team_* 工具速查表：

下图展示了 Team Mode 中 Team Lead 与成员之间的多级任务分配和通信关系。

flowchart TB
    subgraph L1["Level 1: 项目级 Team"]
        A[Project Lead<br/>项目协调]
    end
    
    subgraph L2["Level 2: 领域 Team"]
        B[Frontend Team Lead]
        C[Backend Team Lead]
        D[Security Team Lead]
    end
    
    subgraph L3["Level 3: 执行 Team"]
        E1[UI Developer]
        E2[Component Developer]
        F1[API Developer]
        F2[DB Developer]
        G1[Vuln Scanner]
        G2[Code Auditor]
    end
    
    A --> B
    A --> C
    A --> D
    
    B --> E1
    B --> E2
    C --> F1
    C --> F2
    D --> G1
    D --> G2
    
    style A fill:#4A90D9,color:#fff
    style B fill:#50C878,color:#fff
    style C fill:#50C878,color:#fff
    style D fill:#50C878,color:#fff
    style E1 fill:#FF9F43,color:#fff
    style E2 fill:#FF9F43,color:#fff
    style F1 fill:#FF9F43,color:#fff
    style F2 fill:#FF9F43,color:#fff
    style G1 fill:#FF9F43,color:#fff
    style G2 fill:#FF9F43,color:#fff

分层架构配置：

{
  "hierarchicalTeam": {
    "name": "enterprise-development-project",
    "levels": [
      {
        "level": 1,
        "team": {
          "name": "project-lead",
          "role": "coordinator",
          "model": "best-capability-model",
          "skills": ["overall-planning", "dispatching-parallel-agents"]
        }
      },
      {
        "level": 2,
        "teams": [
          {
            "name": "frontend-team",
            "lead": { "model": "balanced-model", "skills": ["frontend-architect"] },
            "workers": [
              { "id": "ui-developer", "skills": ["ui-designer"] },
              { "id": "component-developer", "skills": ["frontend-architect"] }
            ]
          },
          {
            "name": "backend-team",
            "lead": { "model": "balanced-model", "skills": ["backend-architect"] },
            "workers": [
              { "id": "api-developer", "skills": ["backend-architect"] },
              { "id": "db-developer", "skills": ["backend-architect"] }
            ]
          },
          {
            "name": "security-team",
            "lead": { "model": "best-capability-model", "skills": ["security-architect"] },
            "workers": [
              { "id": "vuln-scanner", "skills": ["vulnerability-manager"] },
              { "id": "code-auditor", "skills": ["penetration-tester"] }
            ]
          }
        ]
      }
    ],
    "communication": {
      "crossLevel": "inbox_message",
      "sameLevel": "inbox_message",
      "timeout": 60000
    }
  }
}

Team 监控和日志

大规模 Teams 需要完善的监控和日志系统：

监控指标：

⚠️ 以下监控指标为概念设计建议，当前 OMO 不内置这些指标采集。实际监控可依赖操作系统级资源监控（如 top、iostat）和手动日志检查。

监控配置：

{
  "monitoring": {
    "metrics": {
      "collection": {
        "interval": 10000,
        "retention": "7d",
        "storage": "prometheus"
      },
      "alerts": [
        {
          "name": "high_message_response_time",
          "condition": "response_time > 120000",
          "severity": "warning",
          "action": "notify"
        },
        {
          "name": "agent_heartbeat_missing",
          "condition": "agent_heartbeat_miss > 3",
          "severity": "critical",
          "action": "restart_agent"
        },
        {
          "name": "inbox_overflow",
          "condition": "inbox_file_count > 100",
          "severity": "warning",
          "action": "notify_lead"
        }
      ]
    },
    "tracing": {
      "enabled": true,
      "samplingRate": 0.1,
      "storage": "jaeger",
      "retention": "24h"
    },
    "logging": {
      "level": "info",
      "format": "json",
      "outputs": ["file", "elasticsearch"],
      "retention": "30d",
      "redactSensitive": true
    }
  }
}

故障恢复策略

成员宕机后的任务重新调度和故障恢复：

flowchart TB
    A[Agent 故障检测] --> B{故障类型}
    
    B -->|心跳丢失| C[等待恢复窗口]
    B -->|会话异常| D[立即重新调度]
    B -->|资源耗尽| E[资源清理]
    
    C --> F{恢复成功?}
    F -->|是| G[恢复执行]
    F -->|否| D
    
    D --> H[选择替代 Agent]
    H --> I[迁移任务状态]
    I --> J[恢复执行]
    
    E --> K[释放资源]
    K --> D
    
    J --> L[记录故障日志]
    G --> L
    
    L --> M[更新监控指标]
    
    style A fill:#ff6b6b,color:#fff
    style D fill:#4A90D9,color:#fff
    style G fill:#50C878,color:#fff
    style J fill:#50C878,color:#fff

故障恢复配置：

{
  "faultRecovery": {
    "detection": {
      "heartbeatInterval": 10000,
      "heartbeatTimeout": 30000,
      "maxMissedHeartbeats": 3,
      "healthCheckInterval": 60000
    },
    "recovery": {
      "strategies": {
        "heartbeat_lost": {
          "action": "wait_and_restart",
          "waitWindow": 60000,
          "maxRetries": 2
        },
        "session_crash": {
          "action": "immediate_reschedule",
          "preserveState": true,
          "notifyTeam": true
        },
        "resource_exhausted": {
          "action": "cleanup_and_reschedule",
          "cleanupTimeout": 30000,
          "resourceThreshold": 0.9
        }
      },
      "taskReschedule": {
        "strategy": "capability_match",
        "fallbackStrategy": "round_robin",
        "preserveProgress": true,
        "maxRescheduleAttempts": 3
      }
    },
    "degradation": {
      "enabled": true,
      "triggers": {
        "memberFailureRate": 0.3,
        "inboxFileCount": 100,
        "systemLoad": 0.9
      },
      "actions": {
        "reduceParallelism": true,
        "skipNonCriticalTasks": true,
        "fallbackToSimpleAgent": true
      }
    }
  }
}

Teams 的设计哲学

Teams 是 Agent 协作的操作系统

Team Mode 提供了 Agent 间通信、任务调度、状态管理的完整基础设施，可以被视为 Agent 协作的“操作系统“。

操作系统类比：

消息传递 vs 文件交接

Team 的内部通信使用 inbox 消息传递，对外输出使用文件（WORKFLOW_STATE.md）。两者各有侧重：

消息传递（内部 — Inbox 文件）：

• 实时性高，适合频繁交互
• 消息以单文件形式持久化存储在 ~/.omo/runtime/{teamRunId}/inboxes/{memberName}/{uuid}.json，进程重启后可从 inbox 恢复未处理消息
• 适合状态同步、任务分配

文件交接（对外 — WORKFLOW_STATE.md）：

• 结构化持久化，适合人工查阅和审计
• 写入频率低（仅在关键节点更新）
• 适合最终输出、跨 Team 协作

WORKFLOW_STATE.md 模板：

# WORKFLOW_STATE

## 元数据
- team_id: security-audit-team-001
- created_at: 2024-01-15T08:00:00Z
- updated_at: 2024-01-15T09:30:00Z
- status: in_progress

## 任务进度
| task_id | assignee | status | progress | updated_at |
|---------|----------|--------|----------|------------|
| scan-001 | vuln-scanner | completed | 100% | 2024-01-15T08:45:00Z |
| scan-002 | code-analyzer | in_progress | 60% | 2024-01-15T09:15:00Z |
| scan-003 | poc-engineer | pending | 0% | - |

## 结果汇总
### 已完成
- scan-001: 发现 2 个高危漏洞（SQL 注入、XSS）

### 待处理
- scan-002: 代码审计进行中
- scan-003: 等待 scan-002 完成

## 下一步
1. 完成 scan-002 代码审计
2. 启动 scan-003 漏洞验证
3. 汇总最终报告

Teams 协作模式对比

常见多 Agent 协作模式对比

以下对比将 OMO Team Mode 与几种常见的多 Agent 协作方案进行比较，帮助理解不同设计选择的工程含义。

协作模式映射

Inbox 实现特征

适用场景

小结

Teams 并行 Agent 协作是超越单 Agent 限制的关键架构。通过基于 inbox 文件的消息传递机制，同一进程内的多个并行 Agent 实例可以协同工作，构建大规模多视角 AI 编程工作流。

从架构顾问视角，Teams 架构需要在性能与隔离性之间权衡：进程内集群适合高频交互场景，Team Mode 适合并行协作任务，独立 Agent 适合安全敏感场景。混合模式可以结合各种模式的优势。

从后端架构师视角，大规模 Teams 需要分层协调设计、完善的监控日志系统、健壮的故障恢复策略。基于 inbox 文件的消息传递机制（team_send_message）是 Team Mode 的核心。

从渗透测试员视角，Team Mode 的数据隔离是关键安全边界。完全隔离、共享读取、完全共享三种隔离级别适用于不同场景，安全检查清单确保敏感数据不泄露。

常见反模式

在 Teams 中混入有竟态依赖的任务

现象：将两个 Worker 分别分配了需要读取对方输出的任务，形成循环依赖。

原因：Task 分解时未识别任务间的依赖关系，默认所有任务应该可以并行。

对策：在 Team Lead 层面设计明确的 DAG（有向无环图）依赖。Worker A 的输出作为 Worker B 的输入时，使用串行调度而非并行。使用 requireCompletionBeforeNewTask: true 控制消息处理顺序。

所有成员共享同一个上下文窗口

现象：Team 中所有 Agent 使用相同的模型和上下文配置，高成本模型浪费在简单 Worker 上。

原因：配置时使用默认模板，未针对不同角色优化模型选择和上下文大小。

对策：为 Team Lead 配置最强模型（决策和协调需要高质量输出），为 Worker 配置性价比模型（执行具体任务不需要最强能力）。Worker 的上下文窗口可以设置得比 Lead 更小，因为 Worker 只需要关注自己的子任务。

常见错误与陷阱

Team 间竞态条件导致数据不一致

场景：两个 Team 同时写入同一个文件或共享目录，导致文件损坏或数据丢失。

后果：Team 的最终输出不完整，部分结果被覆盖。

预防：为每个 Team 分配独立的工作目录，输出文件使用唯一命名模式（如 {team_id}_{task_id}_{timestamp}.json）。跨 Team 的数据交换通过消息传递而非共享文件。

Inbox 溢出导致消息丢失

场景：Team Lead 同时向多个 Worker 广播消息，Worker 处理速度跟不上，Inbox 目录积压超过容量。

后果：消息丢失且无重试机制，Worker 漏掉关键任务。

预防：控制并发消息数，避免一次性广播。设置 maxConcurrentMessages 限制。Worker 处理完当前任务后再接收新消息。监控 Inbox 文件数量，超过阈值时告警。

适用场景与限制

Team Mode 适合需要大规模多 Agent 并行协作的复杂工程场景：全栈应用开发（前后端并行）、安全审计（多角度同时扫描）、大规模代码审查（多 Reviewer 并行审查）。

以下情况 Team Mode 不是最佳选择：简单串行任务——独立 Agent 开箱即用且协调开销更小；单一技能即可完成的任务——不需要 Team 的多角色能力；对隔离性要求极高的安全敏感任务——独立进程的 Agent 更安全。

Team Mode 硬性限制：单 Team 最多 10 个成员，最多同时 5 个 Team，禁止嵌套 Team，禁止 Team 成员调用 delegate_task()。这些限制是为了防止资源无限扩张。Team Mode 所有成员运行在同一 OMO 进程中，不存在进程级别的隔离。

学习检查清单

完成本章学习后，请确认你能够：

• 解释 Teams 架构的设计原则和适用场景
• 使用 team_send_message 进行 Agent 间通信
• 区分进程内集群与独立 Agent 的优缺点
• 配置 Team Mode 的数据隔离策略
• 设计分层 Team 架构
• 配置 Team 监控和故障恢复策略
• 理解消息传递与文件交接的使用场景

关联章节

• ← Agent 派生模式 — 派生是 Team 的基础
• ← 多 Agent 协作 — Team Mode 之前的轻量级后台任务机制（后台任务机制）
• → 案例研究 — 案例中的 Team Mode 应用
• → 自定义 Agent 与 Plugin（插件） — 自定义 Agent 在 Team 中的集成