Agent Teams：多智能体协作

协调多个 CodeBuddy Code 实例组成团队协作，通过共享任务列表、成员间消息通信和集中式管理完成复杂任务。

实验性功能：Agent Teams 默认开启。可通过 /config 中的 [Experimental] Agent Teams 开关关闭，或设置环境变量 CODEBUDDY_CODE_EXPERIMENTAL_AGENT_TEAMS=0。该功能目前存在已知限制。

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

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

何时使用 Agent Teams

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

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

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

与子代理的对比

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

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

禁用 Agent Teams

Agent Teams 默认开启。如需关闭，有以下方式：

方式一：通过 /config 开关（推荐）

在交互会话中输入 /config，找到 [Experimental] Agent Teams 选项，按回车切换为 false。

方式二：通过环境变量

export CODEBUDDY_CODE_EXPERIMENTAL_AGENT_TEAMS=0

也可以在 settings.json 中设置：

{
  "env": {
    "CODEBUDDY_CODE_EXPERIMENTAL_AGENT_TEAMS": "0"
  }
}

或直接使用配置项：

{
  "agentTeam": {
    "enabled": false
  }
}

创建你的第一个团队

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

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

CodeBuddy 会：

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

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

团队创建后的界面

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

Team design-review created

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

控制你的团队

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

与成员交互

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

@提及补全：在输入框中输入 @ 触发成员名称的 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），限制领导只能使用协调工具（生成成员、发送消息、管理任务），不直接修改代码。

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

任务分配与认领

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

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

按 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}/

权限

成员继承领导的权限设置。如果领导使用 --dangerously-skip-permissions 启动，所有成员也会如此。

使用场景示例

并行代码审查

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

创建一个团队审查 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 文件。利用这一点可以为所有成员提供项目级的指导。

相关功能

• 轻量级委派：子代理在会话内生成辅助代理，适合不需要成员间协调的聚焦型任务
• 手动并行：Git worktrees 允许手动运行多个 CodeBuddy Code 会话，无需自动化的团队协调