Skip to main content

编排 CSC 会话团队

协调多个 CSC 实例作为团队协同工作，支持共享任务、代理间消息传递和集中管理。

⚠️ 警告： Agent teams是实验性功能，默认禁用。通过在 settings.json 或环境变量中添加 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS 来启用。Agent teams在会话恢复、任务协调和关闭行为方面存在已知限制。

Agent teams让你可以协调多个 CSC 实例协同工作。一个会话充当团队负责人，协调工作、分配任务和综合结果。队友独立工作，各自在自己的上下文窗口中，并直接相互通信。

与Subagents不同——Subagents在单个会话内运行，只能向主代理汇报——你还可以直接与各个队友交互，无需通过负责人。

本页涵盖：

  • 何时使用Agent teams，包括最佳用例以及与Subagents的比较
  • 启动团队
  • 控制队友，包括显示模式、任务分配和委派
  • 并行工作的最佳实践

何时使用Agent teams​

Agent teams在并行探索能带来真正价值的任务中最有效。完整的场景示例请参见用例示例。最佳用例包括：

  • 研究和审查：多个队友可以同时调查问题的不同方面，然后分享并质疑彼此的发现
  • 新模块或功能：队友可以各自拥有独立的部分，互不干扰
  • 竞争性假设调试：队友并行测试不同理论，更快地收敛到答案
  • 跨层协调：涉及前端、后端和测试的变更，每个由不同的队友负责

Agent teams会增加协调开销，并且比单个会话消耗明显更多的 token。当队友可以独立操作时效果最佳。对于顺序任务、同文件编辑或有许多依赖关系的工作，单个会话或Subagents更有效。

与Subagents的比较​

Agent teams和Subagents都允许你并行化工作，但它们的运作方式不同。根据你的工作者是否需要相互通信来选择：

SubagentsAgent teams
上下文拥有上下文窗口；结果返回给调用者拥有上下文窗口；完全独立
通信仅向主代理汇报结果队友直接相互发消息
协调主代理管理所有工作共享任务列表，自我协调
最适合只关注结果的聚焦任务需要讨论和协作的复杂工作
Token 成本较低：结果汇总回主上下文较高：每个队友是独立的 CSC 实例

当你需要快速、聚焦且只需汇报结果的工作者时，使用Subagents。当队友需要分享发现、互相质疑并自行协调时，使用Agent teams。

启用Agent teams​

Agent teams默认禁用。通过在 shell 环境或 settings.json 中将 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS 环境变量设置为 1 来启用：

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

启动你的第一个Agent teams​

启用Agent teams后，告诉 CSC 创建一个Agent teams，并用自然语言描述你想要的任务和团队结构。CSC 会根据你的提示创建团队、生成队友并协调工作。

以下示例效果很好，因为三个角色是独立的，可以在不等待彼此的情况下探索问题：

我正在设计一个帮助开发者追踪代码库中 TODO 注释的 CLI 工具。
创建一个Agent teams从不同角度探索：一个队友负责 UX，
一个负责技术架构，一个扮演魔鬼代言人。

从那里，CSC 会创建一个带有共享任务列表的团队，为每个视角生成队友，让他们探索问题，综合发现，并在完成时尝试清理团队。

负责人的终端会列出所有队友及其正在做的工作。使用 Shift+Down 在队友之间切换并直接给他们发消息。在最后一个队友之后，Shift+Down 会循环回到负责人。

如果你希望每个队友在自己的分屏窗格中，请参见选择显示模式。

控制你的Agent teams​

用自然语言告诉负责人你想要什么。它会根据你的指示处理团队协调、任务分配和委派。

选择显示模式​

Agent teams支持两种显示模式：

  • 进程内模式：所有队友在你的主终端内运行。使用 Shift+Down 在队友之间切换，然后输入内容直接给他们发消息。适用于任何终端，无需额外设置。
  • 分屏窗格模式：每个队友有自己的窗格。你可以同时看到所有人的输出，并点击窗格直接交互。需要 tmux 或 iTerm2。

注意： tmux 在某些操作系统上有已知限制，传统上在 macOS 上效果最好。建议在 iTerm2 中使用 tmux -CC 作为 tmux 的入口。

默认值为 "auto"，如果你已经在 tmux 会话中运行，则使用分屏窗格，否则使用进程内模式。"tmux" 设置启用分屏窗格模式，并根据你的终端自动检测是使用 tmux 还是 iTerm2。要覆盖此设置，在 ~/.costrict.json 的全局配置中设置 teammateMode：

{
  "teammateMode": "in-process"
}

要为单个会话强制使用进程内模式，将其作为标志传入：

csc --teammate-mode in-process

分屏窗格模式需要 tmux 或带有 it2 CLI 的 iTerm2。手动安装：

  • tmux：通过系统包管理器安装。有关平台特定的说明，请参见 tmux wiki。
  • iTerm2：安装 it2 CLI，然后在 iTerm2 → Settings → General → Magic → Enable Python API 中启用 Python API。

指定队友和模型​

CSC 根据你的任务决定要生成的队友数量，或者你可以明确指定你想要的：

创建一个有 4 个队友的团队来并行重构这些模块。
每个队友使用 Sonnet。

要求队友的计划审批​

对于复杂或有风险的任务，你可以要求队友在实施前先制定计划。队友在只读计划模式下工作，直到负责人批准他们的方案：

生成一个架构师队友来重构认证模块。
在他们做任何更改之前要求计划审批。

当队友完成计划后，它会向负责人发送计划审批请求。负责人审查计划，然后批准或拒绝并附带反馈。如果被拒绝，队友保持计划模式，根据反馈修改并重新提交。一旦批准，队友退出计划模式并开始实施。

负责人自主做出审批决定。要影响负责人的判断，在提示中给出标准，例如"只批准包含测试覆盖的计划"或"拒绝修改数据库架构的计划"。

直接与队友交流​

每个队友都是一个完整的、独立的 CSC 会话。你可以直接给任何队友发消息，提供额外指示、提出后续问题或重新调整他们的方向。

  • 进程内模式：使用 Shift+Down 在队友之间切换，然后输入内容发送消息。按 Enter 查看队友的会话，然后按 Escape 中断他们当前的回合。按 Ctrl+T 切换任务列表。
  • 分屏窗格模式：点击队友的窗格直接与其会话交互。每个队友都有自己终端的完整视图。

分配和认领任务​

共享任务列表协调整个团队的工作。负责人创建任务，队友完成这些任务。任务有三种状态：待处理、进行中和已完成。任务也可以依赖其他任务：具有未解决依赖的待处理任务在那些依赖完成之前不能被认领。

负责人可以明确分配任务，或者队友可以自行认领：

  • 负责人分配：告诉负责人将哪个任务给哪个队友
  • 自行认领：完成一个任务后，队友自行挑选下一个未分配、未阻塞的任务

任务认领使用文件锁来防止多个队友同时尝试认领同一任务时的竞争条件。

关闭队友​

要优雅地结束队友的会话：

让研究员队友关闭

负责人发送关闭请求。队友可以批准并优雅退出，或者拒绝并说明原因。

清理团队​

完成后，让负责人清理：

清理团队

这会移除共享的团队资源。当负责人运行清理时，它会检查是否有活跃的队友，如果有则失败，所以请先关闭它们。

⚠️ 警告： 始终使用负责人来清理。队友不应运行清理，因为他们的团队上下文可能无法正确解析，可能导致资源处于不一致状态。

使用Hooks强制执行质量门​

使用Hooks在队友完成工作或任务被创建或完成时强制执行规则：

  • TeammateIdle：当队友即将空闲时运行。以代码 2 退出可发送反馈并让队友继续工作。
  • TaskCreated：当任务被创建时运行。以代码 2 退出可阻止创建并发送反馈。
  • TaskCompleted：当任务被标记为完成时运行。以代码 2 退出可阻止完成并发送反馈。

Agent teams的工作原理​

本节介绍Agent teams背后的架构和机制。如果你想开始使用它们，请参见上面的控制你的Agent teams。

CSC 如何启动Agent teams​

Agent teams有两种启动方式：

  • 你请求一个团队：给 CSC 一个受益于并行工作的任务，并明确要求创建Agent teams。CSC 根据你的指示创建一个。
  • CSC 建议一个团队：如果 CSC 确定你的任务受益于并行工作，它可能会建议创建一个团队。在继续之前你需要确认。

在这两种情况下，你保持控制。CSC 不会在未经你批准的情况下创建团队。

架构​

Agent teams由以下部分组成：

组件角色
团队负责人创建团队、生成队友并协调工作的主 CSC 会话
队友各自处理分配任务的独立 CSC 实例
任务列表队友认领和完成的工作项共享列表
邮箱代理之间通信的消息系统

有关显示配置选项，请参见选择显示模式。队友消息会自动到达负责人。

系统自动管理任务依赖。当队友完成其他任务所依赖的任务时，被阻塞的任务会自动解除阻塞，无需手动干预。

团队和任务在本地存储：

  • 团队配置：~/.costrict/teams/{team-name}/config.json
  • 任务列表：~/.costrict/tasks/{team-name}/

创建团队时 CSC 会自动生成这两项，并在队友加入、空闲或离开时更新它们。团队配置保存运行时状态，如会话 ID 和 tmux 窗格 ID，因此不要手动编辑或预先编写：你的更改会在下次状态更新时被覆盖。

要定义可重用的队友角色，请改用Subagents定义。

团队配置包含一个 members 数组，包含每个队友的名称、代理 ID 和代理类型。队友可以读取此文件来发现其他团队成员。

没有项目级别的团队配置等效项。项目目录中的 .costrict/teams/teams.json 等文件不会被识别为配置；CSC 将其视为普通文件。

使用Subagents定义作为队友​

生成队友时，你可以引用来自任何Subagents范围的Subagents类型：项目、用户、Plugins或 CLI 定义的。这让你可以一次定义一个角色，例如安全审查员或测试运行器，并将其同时用作委派的Subagents和Agent teams的队友。

要使用Subagents定义，在要求 CSC 生成队友时按名称提及它：

使用 security-reviewer 代理类型生成一个队友来审计认证模块。

队友会遵循该定义的 tools 白名单和 model，定义的内容会作为额外指令附加到队友的系统提示中，而不是替换它。团队协调工具（如 SendMessage）和任务管理工具在队友中始终可用，即使 tools 限制了其他工具。

注意： Subagents定义中的 skills 和 mcpServers frontmatter 字段在该定义作为队友运行时不会被应用。队友从你的项目和用户设置加载Skills和 MCP 服务器，与常规会话相同。

权限​

队友以负责人的权限设置启动。如果负责人以 --dangerously-skip-permissions 运行，所有队友也是如此。生成后，你可以更改各个队友的模式，但不能在生成时设置每个队友的模式。

上下文和通信​

每个队友都有自己的上下文窗口。生成时，队友加载与常规会话相同的项目上下文：AGENTS.md、MCP 服务器和Skills。它还接收来自负责人的生成提示。负责人的对话历史不会传递。

队友如何共享信息：

  • 自动消息传递：当队友发送消息时，消息会自动传递给接收者。负责人不需要轮询更新。
  • 空闲通知：当队友完成工作并停止时，他们会自动通知负责人。
  • 共享任务列表：所有代理都可以看到任务状态并认领可用工作。

队友消息传递：

  • 消息：向一个特定队友发送消息
  • 广播：同时向所有队友发送。谨慎使用，因为成本随团队规模增长。

负责人在生成每个队友时为其分配一个名称，任何队友都可以通过该名称给其他队友发消息。要获得可以在后续提示中引用的可预测名称，在生成指令中告诉负责人如何称呼每个队友。

Token 使用量​

Agent teams比单个会话消耗明显更多的 token。每个队友有自己的上下文窗口，token 使用量随活跃队友数量增长。对于研究、审查和新功能开发，额外的 token 通常是值得的。对于常规任务，单个会话更具成本效益。有关使用指南，请参见Agent teams token 成本。

用例示例​

这些示例展示了Agent teams如何处理并行探索能带来价值的任务。

运行并行代码审查​

单个审查者倾向于一次关注一种类型的问题。将审查标准分成独立的领域意味着安全性、性能和测试覆盖率都能同时得到充分关注。提示为每个队友分配不同的视角，这样他们就不会重叠：

创建一个Agent teams来审查 PR #142。生成三个审查者：
- 一个关注安全隐患
- 一个检查性能影响
- 一个验证测试覆盖率
让他们各自审查并报告发现。

每个审查者从同一个 PR 出发，但应用不同的筛选器。负责人在他们完成后综合所有三个审查者的发现。

用竞争性假设进行调查​

当根本原因不明确时，单个代理倾向于找到一个看似合理的解释就停止寻找。提示通过让队友明确对立来解决这个问题：每个人的工作不仅是调查自己的理论，还要质疑其他人的理论。

用户报告应用在一条消息后退出而不是保持连接。
生成 5 个代理队友来调查不同的假设。让他们互相交流，
试图反驳彼此的理论，就像科学辩论一样。
用达成的任何共识更新发现文档。

辩论结构是这里的关键机制。顺序调查存在锚定效应：一旦探索了一个理论，后续的调查就会偏向它。

有多个独立的调查者积极尝试反驳彼此，存活下来的理论更有可能是真正的根本原因。

最佳实践​

给队友足够的上下文​

队友自动加载项目上下文，包括 AGENTS.md、MCP 服务器和Skills，但他们不继承负责人的对话历史。有关详细信息，请参见上下文和通信。在生成提示中包含任务特定的细节：

生成一个安全审查队友，提示为："审查 src/auth/ 中认证模块
的安全漏洞。关注 token 处理、会话管理和输入验证。
应用使用存储在 httpOnly cookie 中的 JWT token。
报告任何问题及其严重性评级。"

选择合适的团队规模​

队友数量没有硬性限制，但实际约束适用：

  • Token 成本线性增长：每个队友有自己的上下文窗口并独立消耗 token。有关详细信息，请参见Agent teams token 成本。
  • 协调开销增加：更多队友意味着更多通信、任务协调和潜在冲突
  • 边际收益递减：超过一定点后，额外的队友不会按比例加速工作

大多数工作流从 3-5 个队友开始。这平衡了并行工作和可管理的协调。本指南中的示例使用 3-5 个队友，因为这个范围在不同任务类型中效果良好。

每个队友 5-6 个任务可以让每个人都保持高效，而不会过度切换上下文。如果你有 15 个独立任务，3 个队友是一个好的起点。

只有当工作真正受益于队友同时工作时才扩大规模。三个专注的队友通常胜过五个分散的。

合理划分任务大小​

  • 太小：协调开销超过收益
  • 太大：队友工作时间过长没有检查点，增加浪费精力的风险
  • 刚好：产生明确交付物的自包含单元，如函数、测试文件或审查

💡 提示： 负责人自动将工作分解为任务并分配给队友。如果它创建的任务不够，要求它将工作分成更小的部分。每个队友 5-6 个任务可以让每个人都保持高效，并让负责人在有人卡住时重新分配工作。

等待队友完成​

有时负责人会自己开始实施任务而不是等待队友。如果你注意到这种情况：

在继续之前等待你的队友完成他们的任务

从研究和审查开始​

如果你刚接触Agent teams，从有明确边界且不需要编写代码的任务开始：审查 PR、研究库或调查 bug。这些任务展示了并行探索的价值，而没有并行实现带来的协调挑战。

避免文件冲突​

两个队友编辑同一个文件会导致覆盖。将工作分开，使每个队友拥有不同的文件集。

监控和引导​

检查队友的进展，重定向不起作用的方法，并在发现结果出现时进行综合。让团队无人看管太久会增加浪费精力的风险。

故障排除​

队友未出现​

如果你要求 CSC 创建团队后队友没有出现：

  • 在进程内模式下，队友可能已经在运行但不可见。按 Shift+Down 循环浏览活跃的队友。
  • 检查你给 CSC 的任务是否足够复杂以需要团队。CSC 根据任务决定是否生成队友。
  • 如果你明确要求了分屏窗格，确保 tmux 已安装并在你的 PATH 中可用： 
    which tmux
  • 对于 iTerm2，验证 it2 CLI 已安装且 iTerm2 偏好设置中已启用 Python API。

权限提示过多​

队友的权限请求会上报到负责人，这可能会造成摩擦。在生成队友之前，在权限设置中预批准常见操作以减少中断。

队友因错误停止​

队友在遇到错误后可能会停止而不是恢复。在进程内模式下使用 Shift+Down 或在分屏模式下点击窗格检查他们的输出，然后：

  • 直接给他们额外指示
  • 生成一个替代队友继续工作

负责人在工作完成前关闭​

负责人可能在工作实际完成之前就决定团队已完成。如果发生这种情况，告诉它继续。你还可以告诉负责人在队友完成之前等待，如果它开始自己做工作而不是委派。

孤立的 tmux 会话​

如果团队结束后 tmux 会话仍然存在，可能没有被完全清理。列出会话并终止团队创建的会话：

tmux ls
tmux kill-session -t <session-name>

限制​

Agent teams是实验性的。当前需要注意的限制：

  • 进程内队友无法恢复会话：/resume 和 /rewind 不能恢复进程内队友。恢复会话后，负责人可能会尝试给不再存在的队友发消息。如果发生这种情况，告诉负责人生成新的队友。
  • 任务状态可能滞后：队友有时未能将任务标记为已完成，这会阻塞依赖任务。如果任务看起来卡住了，检查工作是否实际完成，手动更新任务状态或告诉负责人提醒队友。
  • 关闭可能很慢：队友在关闭前完成当前的请求或工具调用，这可能需要时间。
  • 每个会话一个团队：负责人一次只能管理一个团队。在开始新团队之前清理当前团队。
  • 不允许嵌套团队：队友不能生成自己的团队或队友。只有负责人可以管理团队。
  • 负责人是固定的：创建团队的会话在其生命周期内是负责人。你不能将队友提升为负责人或转移领导权。
  • 权限在生成时设置：所有队友以负责人的权限模式启动。你可以在生成后更改各个队友的模式，但不能在生成时设置每个队友的模式。
  • 分屏窗格需要 tmux 或 iTerm2：默认的进程内模式在任何终端中工作。分屏窗格模式不支持 VS Code 的集成终端、Windows Terminal 或 Ghostty。

💡 提示： AGENTS.md 正常工作：队友从其工作目录读取 AGENTS.md 文件。使用它为所有队友提供项目特定的指导。