第13章 · 多Agent系统：三条技术路线

13.1 Coordinator模式：Leader-Worker架构

coordinator/coordinatorMode.ts实现了经典的Leader-Worker多Agent架构。Coordinator作为"主管"，接收用户任务后将其分解为子任务，分配给Worker执行。

系统提示（111-240行）定义了Coordinator的核心职责：

帮助用户达成目标
指导Worker进行研究、实现和验证
综合整理结果
在不需要工具调用时直接回答

Worker能力矩阵：

标准工具（Bash、Edit、Read等）
MCP服务器提供的工具
通过Skill工具使用技能（如/commit、/verify）
可选的共享暂存目录（Scratchpad）用于跨Worker的持久化存储

并发模型体现了Anthropic对并行安全性的深入思考：

只读任务：可以自由并行
写入密集型任务：按文件集串行化
验证可以与不同区域的实现重叠执行

"不委托理解"原则是Coordinator设计中的关键约束——Coordinator不应将"理解代码结构"这样的元认知任务委托给Worker，而应自己综合Worker的研究结果来建立理解。这避免了多层委托导致的信息衰减。

Worker结果格式使用结构化XML：

<task-notification>
  <task-id>{agentId}</task-id>
  <status>completed|failed|killed</status>
  <summary>{人类可读的状态摘要}</summary>
  <result>{Agent的最终文本响应}</result>
  <usage>
    <total_tokens>N</total_tokens>
    <tool_uses>N</tool_uses>
    <duration_ms>N</duration_ms>
  </usage>
</task-notification>

usage信息的包含表明Coordinator需要进行成本感知的任务分配——如果某个Worker消耗了过多Token，Coordinator可以决定调整策略。

13.2 Swarm系统：对等协作

utils/swarm/实现了一个完全不同的多Agent范式——对等协作的Swarm系统。

核心常量（constants.ts）：

export const TEAM_LEAD_NAME = 'team-lead'
export const SWARM_SESSION_NAME = 'claude-swarm'
export const SWARM_VIEW_WINDOW_NAME = 'swarm-view'
export const TMUX_COMMAND = 'tmux'
export const HIDDEN_SESSION_NAME = 'claude-hidden'

Swarm与Coordinator的关键区别：

无中心节点：Team Lead只是命名约定，不是特权角色
tmux可视化：每个Agent运行在自己的tmux窗口中，用户可以实时观察所有Agent的活动
权限同步（permissionSync.ts）：Leader和Teammate之间的权限桥接，确保安全策略的一致性
进程级隔离：每个Agent是独立的进程，拥有自己的上下文和状态

In-Process Runner（inProcessRunner.ts）是Swarm的轻量级变体，使用AsyncLocalStorage进行上下文隔离而非进程隔离：

包裹runAgent()用于进程内Teammate执行
runWithTeammateContext()实现基于AsyncLocalStorage的上下文隔离
支持进度追踪和AppState更新
完成时向Leader发送Idle通知
支持Plan Mode审批流程

13.3 InProcessTeammate：进程内队友

tasks/InProcessTeammateTask/types.ts定义了进程内Teammate的完整状态模型：

Teammate身份：

export type TeammateIdentity = {
  agentId: string              // 例如 "researcher@my-team"
  agentName: string            // 例如 "researcher"
  teamName: string
  color?: string               // 终端显示颜色
  planModeRequired: boolean
  parentSessionId: string      // Leader的会话ID
}

状态模型中最引人注目的设计是50消息的UI上限：

export const TEAMMATE_MESSAGES_UI_CAP = 50

这一限制的来源有一个生动的工程故事——代码注释中记录了一个名为"whale session 9a990de8"的事件：在一次测试中，2分钟内生成了292个Agent，导致内存使用量飙升至36.8GB以上。50消息上限是对这次"鲸鱼会话"的直接回应，通过限制AppState中每个Teammate保留的消息数量来防止内存爆炸。

状态字段的丰富程度反映了Teammate生命周期的复杂性：

awaitingPlanApproval — 等待Plan Mode审批
permissionMode — 权限模式
isIdle / shutdownRequested — 空闲和关闭状态
onIdleCallbacks — 空闲时的回调队列
pendingUserMessages — 待处理的用户消息队列
lastReportedToolCount / lastReportedTokenCount — 进度报告状态

13.4 三条路线的适用场景对比

维度	Coordinator	Swarm/tmux	InProcessTeammate
架构	中心化Leader-Worker	去中心化对等	进程内轻量级
隔离级别	进程级（可选Worktree）	进程级（tmux）	线程级（AsyncLocalStorage）
并发模型	Coordinator调度	自组织	Leader分配
适用场景	复杂项目、多阶段任务	探索性研究、并行实验	快速子任务、低开销
最大Agent数	受系统资源限制	tmux窗口数限制	受内存限制（50消息/Agent）
通信方式	结构化XML通知	tmux IPC	Mailbox + AppState
成本追踪	usage XML字段	独立计量	lastReportedTokenCount
用户可见性	任务状态通知	tmux实时可视化	UI进度条

13.5 AgentTool的Worktree隔离

AgentTool支持Git Worktree级别的隔离，为每个Worker Agent创建独立的工作目录副本：

Worker在隔离的worktree中工作，可以自由修改文件而不影响主工作目录
完成后，Worker的变更可以被合并回主分支
如果Worker的工作被放弃，worktree可以被无副作用地清理

这种设计特别适合以下场景：

并行尝试多种实现方案
在不干扰当前工作的情况下进行实验性重构
代码审查中的自动修复建议（在独立分支上生成修复，等待人类审批后合并）

Worktree隔离与Coordinator的并发模型配合，实现了"写入密集型任务按文件集串行化"的目标——不同Worktree本质上就是不同的文件集。

第13章 · 多Agent系统：三条技术路线