概述
Agent Teams 让您协调多个 CodeBuddy Code 实例组成团队协作，通过共享任务列表、成员间消息通信和集中式管理完成复杂任务。
说明：
该功能目前存在已知限制。
Agent Teams 让您协调多个 CodeBuddy Code 实例共同工作。一个会话作为团队领导（team-lead），负责协调工作、分配任务和汇总成果；其余成员（teammates）各自独立工作，拥有自己的上下文窗口，并通过消息系统直接相互沟通。
何时使用 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 模型。
团队成员与普通子代理使用相同的模型解析规则，并按
subagent_type 匹配持久化配置：提示词中明确指定的模型属于本次调用设置，仍可被
CODEBUDDY_CODE_SUBAGENT_MODEL 统一覆盖。未明确指定模型时，系统依次考虑项目级和用户全局的按子代理设置、内置声明，最后继承团队领导的主模型。
使用
/agents 管理按子代理设置，使用 /model 管理 lite / reasoning 对应的具体模型。要求成员在实施前提交计划
对于复杂或高风险的任务，可以要求成员在实施前先提交计划：
生成一个架构师成员来重构认证模块，要求在修改代码前先提交计划等待审批。
成员完成计划后，会向领导发送计划审批请求。领导审核后批准或拒绝（附带反馈）。被拒绝的成员会保持计划模式，修改后重新提交。
委派模式
默认情况下，领导可能会自己动手实现任务，而不是等成员完成。按
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 文件。利用这一点可以为所有成员提供项目级的指导。
相关功能
轻量级委派：子代理在会话内生成辅助代理，适合不需要成员间协调的聚焦型任务
手动并行：Git worktrees 允许手动运行多个 CodeBuddy Code 会话，无需自动化的团队协调
