Skip to content

20-coordinator-swarm-and-teammate-collaboration.md

Latest commit

 

History

History
163 lines (111 loc) · 7.33 KB

20-coordinator-swarm-and-teammate-collaboration.md

File metadata and controls

163 lines (111 loc) · 7.33 KB

20. Coordinator、Swarm 与 Teammate 协作

研究问题

Anthropic 为什么要把多 agent 协作做成 coordinator、leader、teammate、team file 这一整套组织结构，而不是简单并发几个 worker？

一句话结论

Claude Code 的多 agent 设计重点不是并发，而是组织学：谁研究、谁综合、谁审批、谁汇报，都被明确建模了。

这篇讲什么

这一章解释 Claude Code 在“普通 subagent”之外的另一条多代理路径：coordinator mode、team、in-process teammate、leader approval、mailbox 和权限同步。

如果你不看源码，只看这一章，应该记住什么

  • coordinator 模式的核心是综合与委派，而不是“更强的单 agent”。
  • teammate 不只是后台任务，而是带身份、权限模式和可恢复状态的正式成员。
  • leader approval 说明 Anthropic 不把多 agent 设计成完全自治系统。

Anthropic 的设计目标

从当前实现看，Anthropic 在多 agent 上追求的不是“同时多开几个模型”，而是把多代理工作做成类似工程团队：

  • 有 leader
  • 有 teammate
  • 有共享 team state
  • 有权限上收
  • 有 idle 与 mailbox 协调

这会让系统更慢一些，但也更接近真实工程组织能接受的自动化方式。

先给结论

当前快照显示，Claude Code 的多代理协作已经不是简单的后台任务列表，而是一个带团队语义的协作系统：

  • coordinator 负责分派与综合
  • teammate 具有 agentName@teamName 身份
  • team file 持久化成员、mode、worktree 与 backend 信息
  • worker 的权限请求可以转发给 leader 审批
  • in-process teammate 与 pane backend teammate 共享同一套 team 语义

源码依据

Mermaid 图：coordinator / teammate 协作图

flowchart TD
    A["Coordinator"] --> B["AgentTool / TeamCreate"]
    B --> C["spawn teammate"]
    C --> D{"backend"}
    D -- in-process --> E["InProcessTeammateTask"]
    D -- pane-tmux-iTerm --> F["team file + backend runner"]
    E --> G["team mailbox / idle notification"]
    F --> G
    E --> H["permission request"]
    F --> H
    H --> I["leader approval / permission bridge"]
    I --> J["response 回传 worker"]
Loading

coordinator mode 不是普通 prompt 变体

src/coordinator/coordinatorMode.ts 里：

  • isCoordinatorMode() 直接读取环境变量与 feature gate
  • matchSessionMode() 会在 resume 时切换当前 mode 以匹配 session
  • getCoordinatorSystemPrompt() 给 coordinator 写了完整工作流、并发策略和 worker prompt 编写要求

这说明 coordinator mode 是正式运行模式，而不是零散提示词实验。

coordinator 的核心身份是什么

同一个文件里的 coordinator prompt 明确要求它：

  • 自己负责 synthesis
  • 用 worker 做 research / implementation / verification
  • 不要让 worker 互相查看彼此
  • worker 完成后再由 coordinator 总结给用户

这和普通 AgentTool 的“单个子代理”很不一样。这里已经是一个 team lead 模型。

in-process teammate 的特征

src/utils/swarm/spawnInProcess.ts 和 src/tasks/InProcessTeammateTask/InProcessTeammateTask.tsx 直接表明：

  • in-process teammate 运行在同一 Node.js 进程中
  • 通过 AsyncLocalStorage 风格的 teammate context 做身份隔离
  • 任务状态中保存 identity、permissionMode、awaitingPlanApproval、pendingUserMessages
  • teammate 可以是 running，也可以 idle，且可在 transcript 视图里注入用户消息

所以这不是“线程池 worker”，而是可交互、可追踪、可审批的常驻协作者。

team file 持久化了什么

src/utils/swarm/teamHelpers.ts 的 TeamFile 结构里有：

  • leadAgentId
  • teamAllowedPaths
  • members[]
  • 每个成员的 agentType、model、prompt、cwd、worktreePath
  • subscriptions
  • backendType
  • mode

这说明 team 不是 UI 里的暂存列表，而是落盘的协作配置对象。

权限是如何跨 teammate 同步的

src/utils/swarm/permissionSync.ts 给出了完整注释：

  1. worker 遇到权限请求
  2. 生成 permission request
  3. 写到 team 的 pending 目录 / mailbox
  4. leader 在自己的 UI 中审批
  5. leader 回写 permission response
  6. worker 继续执行

而 src/utils/swarm/leaderPermissionBridge.ts 又把 leader REPL 的 permission dialog setter 暴露给 in-process teammate。也就是说，in-process teammate 不需要另造一套审批 UI，而是桥接回 leader 的标准权限流。

teammate idle 与团队级权限

src/utils/swarm/teammateInit.ts 还做了两件事：

  • 启动时把 teamAllowedPaths 应用到当前 teammate 的 permission context
  • 注册 Stop hook，在 teammate 变 idle 时向 leader mailbox 写入通知

这两点合起来说明 team 协作里既有“共享权限面”，也有“共享状态面”。

与 11 章的区别

11-agents-and-tasks.md 主要回答“怎么启动和管理子代理任务”；这一章则回答“当系统进入 team / coordinator 语义后，多个 agent 如何被组织成可审批、可同步、可持久化的协作结构”。

对研究者的意义

这一层最能体现 Anthropic 的工程化倾向：

  • 多代理不是裸并发，而是 team 组织。
  • 权限不是各 worker 自治，而是可上收给 leader。
  • teammate identity、mailbox、team file 让协作具备持久化语义。
  • coordinator prompt 强调 synthesis 与 prompt-writing，像在训练一个工程经理。

这一章的工作结论

Claude Code 在 swarm / coordinator 路径上，已经把多代理系统推进到“团队协作框架”级别：有 leader，有 teammate，有 team file，有权限转发，也有 idle/状态同步。

延伸阅读