# Agent Teams：多智能体协作

> Agent Teams 让你协调多个 CodeBuddy Code 实例组成团队协作，通过共享任务列表、成员间消息通信和集中式管理完成复杂任务。该功能目前存在[已知限制](#已知限制)。

Agent Teams 让你协调多个 CodeBuddy Code 实例共同工作。一个会话作为团队领导（team-lead），负责协调工作、分配任务和汇总成果；其余成员（teammates）各自独立工作，拥有自己的上下文窗口，并通过消息系统直接相互沟通。

与[子代理（Sub-agents）](sub-agents.md)不同的是，子代理在单一会话内运行、只能将结果报告给主代理；而 Agent Teams 的成员之间可以直接通信，你也可以绕过领导直接与任意成员对话。


## 何时使用 Agent Teams

Agent Teams 在**并行探索能创造真正价值**的任务中最为有效。典型场景包括：

- **研究与评审**：多个成员同时调研问题的不同方面，然后共享和质疑彼此的发现
- **新模块开发**：每个成员负责独立的模块，互不干扰
- **竞争性假设调试**：成员并行测试不同假设，更快收敛到正确答案
- **跨层协调**：前端、后端、测试各由不同成员负责，同步推进

Agent Teams 会带来额外的协调开销，Token 消耗也显著高于单会话。当成员能独立工作时效果最好。对于顺序执行的任务、同文件编辑或依赖关系复杂的工作，单会话或子代理更合适。

### 与子代理的对比

| | 子代理 | Agent Teams |
| :--- | :--- | :--- |
| **上下文** | 独立上下文窗口，结果返回给调用者 | 独立上下文窗口，完全独立 |
| **通信** | 只能向主代理报告结果 | 成员之间可直接发送消息 |
| **协调** | 主代理管理所有工作 | 共享任务列表，成员自主认领 |
| **适用场景** | 聚焦型任务，只关心最终结果 | 需要讨论和协作的复杂工作 |
| **Token 消耗** | 较低：结果汇总回主上下文 | 较高：每个成员是独立实例 |

简单来说：需要快速执行的独立子任务用子代理，需要成员之间相互沟通和协调的复杂任务用 Agent Teams。

## 创建你的第一个团队

用自然语言告诉 CodeBuddy 你想要什么样的团队。CodeBuddy 会根据你的描述自动创建团队、生成成员、分配任务。

```
我正在设计一个帮助开发者追踪代码中 TODO 注释的 CLI 工具。
创建一个团队从不同角度探索这个问题：一个负责用户体验设计，
一个负责技术架构，一个扮演"挑刺者"的角色提出质疑。
```

CodeBuddy 会：

1. 创建团队和共享任务列表
2. 为每个角色生成独立的成员
3. 协调各成员的工作
4. 汇总最终成果

团队创建完成后，终端会显示所有成员及其当前状态。你可以通过 `@成员名` 的方式直接与任意成员对话。

### 团队创建后的界面

创建成功后，你会看到类似如下信息：

```
Team design-review created
```

随后领导通过 Agent 工具生成成员，每个成员以 `@成员名 · 描述` 的形式展示，并以不同颜色标识。

## 控制你的团队

用自然语言告诉领导你的意图，它会处理团队协调、任务分配和工作委派。

### 与成员交互

你可以直接与任何成员对话，无需通过领导中转。

**@提及补全**：在输入框中输入 `@` 触发成员名称的 Tab 自动补全。支持模糊搜索，输入部分名称即可匹配。下拉菜单中会以成员各自的颜色显示名称，并标注状态（如 `✓ completed`）。选择成员后输入消息即可直接发送。

**@all 广播**：输入 `@all` 可向所有成员同时发送消息，相当于广播。当成员数量大于 1 时，`@all` 选项会出现在补全列表的最前面。

> **提示**：已完成任务的成员也会显示在 `@` 补全列表中。选择一个已完成的成员并发送消息，可以重新唤醒它继续工作。

### 实时状态栏

输入框下方会显示团队状态栏，展示各成员的工作状态：

```
Team (2 active) · @ux-designer ● @tech-architect ● @devils-advocate ✓
```

- `●` 表示正在工作
- `✓` 表示已完成
- `✗` 表示失败
- `—` 表示已取消或被终止

每个成员名称以其分配的颜色渲染，并实时显示 Token 消耗和工具调用次数。当打开补全下拉菜单时，状态栏会自动隐藏以避免遮挡。

### 成员焦点导航

在输入框为空时，按 `↓` 进入成员切换模式，使用方向键选择成员，回车确认切换：

| 快捷键 | 功能 |
| :--- | :--- |
| **↓** | 进入成员切换模式 |
| **←/→** | 在成员之间切换选择 |
| **Enter** | 确认并切换到选中成员的视图 |
| **Esc** | 取消选择，退出切换模式 |
| **Ctrl+O** | 返回主视图（团队领导） |

聚焦成员后：

- 终端会显示该成员的完整对话历史、实时进度和 Token 消耗
- 输入框自动切换为向该成员发送消息的模式，直接输入即可发送
- 使用 `@main` 可将消息路由回主代理（团队领导）

> **提示**：焦点导航是查看成员工作详情的最便捷方式。相比 `@成员名` 只能发送消息，焦点导航还能浏览成员的历史对话和当前工作状态。

### 指定成员和模型

CodeBuddy 会根据任务自动决定生成多少成员，也可以明确指定：

```
创建一个 4 人团队并行重构这些模块，每个成员使用 lite 模型。
```

### 要求成员在实施前提交计划

对于复杂或高风险的任务，可以要求成员在实施前先提交计划：

```
生成一个架构师成员来重构认证模块，要求在修改代码前先提交计划等待审批。
```

成员完成计划后，会向领导发送计划审批请求。领导审核后批准或拒绝（附带反馈）。被拒绝的成员会保持计划模式，修改后重新提交。

### 委派模式

默认情况下，领导可能会自己动手实现任务，而不是等成员完成。按 `Shift+Tab` 可以切换到委派模式（Delegate Mode），限制领导只能使用协调工具（Agent、TaskStop、SendMessage、AskUserQuestion、StructuredOutput），不直接修改代码或读取文件。

委派模式下：
- 领导不能自己探索代码、运行命令或编辑文件，所有工作都通过 subagent/成员完成
- Subagent 默认使用 `default` 权限模式（完整工具访问），不继承领导的委派限制
- 可通过 Agent 工具的 `mode` 参数为单个 subagent 指定权限模式（如 `mode: "bypassPermissions"`）
- 委派模式下不走 fork 路径，强制使用标准 subagent

适合你希望领导专注于任务拆分、分配和汇总的场景。

### 任务分配与认领

共享任务列表是团队协调的核心。任务有三种状态：待处理、进行中、已完成。任务还支持依赖关系：被依赖的任务完成后，下游任务自动解除阻塞。

- **领导分配**：告诉领导把哪个任务分给哪个成员
- **成员自主认领**：成员完成当前任务后，自动从列表中认领下一个未分配且未阻塞的任务

按 `Ctrl+T` 可在终端中切换显示任务列表。

### 关闭成员

要优雅地结束某个成员的会话：

```
让研究员成员关闭
```

领导会发送关闭请求，成员可以接受（优雅退出）或拒绝（附带解释）。

### 清理团队

工作完成后，让领导清理团队资源：

```
清理团队
```

这会移除共享的团队资源目录。清理前需要先关闭所有活跃成员，否则会失败。

> **重要**：始终通过领导来清理团队。成员不应执行清理操作，因为其团队上下文可能无法正确解析。

## 工作原理

### 团队架构

一个 Agent Team 由以下组件构成：

| 组件 | 作用 |
| :--- | :--- |
| **团队领导（Team Lead）** | 创建团队、生成成员、协调工作的主会话 |
| **成员（Teammates）** | 独立的 CodeBuddy Code 实例，各自执行分配的任务 |
| **任务列表（Task List）** | 所有成员共享的工作列表，支持认领和状态追踪 |
| **消息系统（Mailbox）** | 成员间的通信机制，支持直接消息和广播 |

### 执行模式

成员以进程内（in-process）方式运行在主终端中。所有成员共享同一个终端窗口，通过 `@成员名` 的方式与指定成员交互。

### 上下文与通信

每个成员拥有独立的上下文窗口。生成时，成员会加载与普通会话相同的项目上下文（CODEBUDDY.md、MCP 服务器、技能等），并接收领导的初始 Prompt。领导的对话历史不会传递给成员。

**消息类型**：

| 类型 | 用途 |
| :--- | :--- |
| `message` | 向指定成员发送消息 |
| `broadcast` | 向所有成员广播（谨慎使用，Token 消耗随成员数线性增长） |
| `shutdown_request` | 请求成员关闭 |
| `shutdown_response` | 成员响应关闭请求 |
| `plan_approval_response` | 计划审批响应 |

**自动重启机制**：已完成任务的成员在收到新消息时会自动重新启动，无需手动干预。这意味着你可以随时向任何成员发送消息，即使它已经完成工作。

### 数据存储

团队和任务数据存储在本地：

- **团队配置**：`~/.codebuddy/teams/{team-name}/config.json`
- **成员信箱**：`~/.codebuddy/teams/{team-name}/inboxes/{member}.json`
- **任务列表**：`~/.codebuddy/tasks/{team-name}/`

### 权限

成员的权限模式按以下优先级确定：

1. **Agent `mode` 参数**：为单个成员指定权限模式（如 `Agent({ mode: "bypassPermissions" })`）
2. **CLI `--subagent-permission-mode`**：本次会话所有 subagent 的默认权限
3. **环境变量 `CODEBUDDY_SUBAGENT_PERMISSION_MODE`**：进程级覆盖
4. **Settings `permissions.subagentPermissionMode`**：全局或项目级配置
5. **继承主 session**：默认继承领导的权限模式（但委派模式不继承，subagent 使用 `default`）

> **委派模式特殊规则**：委派模式的工具限制只约束领导自身。subagent/成员默认使用 `default` 权限（完整工具访问），因为它们需要完整能力执行实际工作。

## 使用场景示例

### 并行代码审查

将审查标准拆分为独立的维度，每个成员专注一个方向：

```
创建一个团队审查 PR #142，生成三个审查员：
- 一个关注安全影响
- 一个检查性能瓶颈
- 一个验证测试覆盖率
让他们各自审查后汇报发现。
```

每个审查员从不同视角审查同一个 PR。领导在所有人完成后汇总发现。

### 竞争性假设调试

当根因不明确时，让多个成员并行验证不同假设：

```
用户反馈应用在发送一条消息后就断开了连接。
生成 5 个成员分别调查不同的假设。让他们互相讨论，
试图推翻对方的理论，像科学辩论一样。
把最终共识更新到排查文档中。
```

这种"辩论"结构的关键在于克服锚定偏差：顺序调查容易被第一个找到的解释所主导，而多个独立调查者互相质疑时，最终存活的理论更可能是真正的根因。

### 跨层功能开发

前端、后端、测试各由不同成员负责：

```
我需要给用户管理模块添加批量导入功能。创建一个团队：
- 一个负责后端 API 和数据库迁移
- 一个负责前端界面和交互
- 一个负责编写集成测试
先让架构师成员设计接口规范，其他人基于规范并行开发。
```

## 最佳实践

### 给成员提供充分的上下文

成员会自动加载项目上下文，但不会继承领导的对话历史。在初始 Prompt 中包含任务需要的具体信息：

```
生成一个安全审查员，Prompt 如下：
"审查 src/auth/ 目录的认证模块，重点关注 Token 处理、
会话管理和输入验证。应用使用 JWT Token 存储在 httpOnly Cookie 中。
对发现的问题按严重等级排序报告。"
```

### 合理划分任务粒度

- **太小**：协调开销超过并行收益
- **太大**：成员长时间不汇报，增加返工风险
- **恰当**：自包含的工作单元，产出明确的交付物（一个函数、一个测试文件、一份审查报告）

> **提示**：领导会自动将工作拆分为任务并分配。如果觉得任务拆得不够细，可以要求领导进一步拆分。每个成员保持 5-6 个任务可以让所有人保持高效，也方便领导在某人卡住时重新分配工作。

### 等待成员完成

有时领导会自己动手实现，而不是等成员完成。如果发现这种情况：

```
等你的成员完成各自的任务后再继续
```

或者直接切换到[委派模式](#委派模式)。

### 避免文件冲突

两个成员同时编辑同一个文件会导致互相覆盖。拆分工作时确保每个成员负责不同的文件集合。

### 定期检查进度

关注成员的工作进展，及时纠正方向偏差，随时汇总阶段性成果。长时间无人监管的团队更容易产生浪费。

## 故障排除

### 成员没有出现

- 查看团队状态栏确认成员是否已生成并在运行中
- 确认任务复杂度足以需要团队。CodeBuddy 会根据任务判断是否需要生成成员

### 权限请求过多

成员的权限请求会汇集到领导，这可能造成干扰。在生成成员前，先在[权限设置]中预先批准常见操作。

### 成员遇到错误后停止

成员可能在遇到错误后停止工作。通过 `@成员名` 直接给它发送额外指令，或让领导生成一个替代成员继续工作。

### 领导过早结束

领导可能在所有任务完成前就认为工作结束了。如果发生这种情况，告诉它继续等待，或使用委派模式限制其行为。

## 已知限制

Agent Teams 仍处于实验阶段，目前存在以下限制：

- **无会话恢复**：`/resume` 和 `/rewind` 不会恢复成员。恢复会话后领导可能尝试向已不存在的成员发消息，这时让领导重新生成成员即可
- **任务状态可能滞后**：成员有时未能及时标记任务为已完成，导致依赖任务被阻塞。如果发现任务卡住，手动检查工作是否已完成并更新状态
- **关闭可能较慢**：成员会先完成当前的请求或工具调用再关闭
- **每个会话只能管理一个团队**：清理当前团队后才能创建新团队
- **不支持嵌套团队**：成员无法创建自己的子团队，只有领导可以管理团队
- **领导角色固定**：创建团队的会话在整个生命周期中都是领导，不能转让
- **权限在生成时确定**：所有成员继承领导的权限模式

> **提示**：CODEBUDDY.md 正常工作 — 成员会从其工作目录读取 CODEBUDDY.md 文件。利用这一点可以为所有成员提供项目级的指导。

## 相关功能

- **轻量级委派**：[子代理](sub-agents.md)在会话内生成辅助代理，适合不需要成员间协调的聚焦型任务
- **手动并行**：[Git worktrees](common-workflows.md) 允许手动运行多个 CodeBuddy Code 会话，无需自动化的团队协调
