5.2 Coordinator：多 Agent 编排模式

源码位置：src/coordinator/coordinatorMode.ts（370 行） 编译开关：feature('COORDINATOR_MODE') 环境变量：CLAUDE_CODE_COORDINATOR_MODE

一句话理解

Coordinator 模式将一个 Claude 变成"指挥官"，把任务分发给多个 Worker Claude 并行执行。

普通模式:
  用户 → Claude → 直接做任务（一个人干所有活）

Coordinator 模式:
  用户 → Coordinator Claude（只规划、只指挥）
               ├── Worker 1（并行：研究代码库）
               ├── Worker 2（并行：实施 A 模块）
               └── Worker 3（并行：实施 B 模块）

角色分工

角色职责可用工具
Coordinator理解目标、拆解任务、综合结果、与用户沟通Agent（派任务）、SendMessage（跟进）、TaskStop（终止）
Worker具体代码操作（读文件、写代码、执行命令）完整工具集（BashTool、FileEditTool 等）

Coordinator 不直接操作代码——它就是一个纯粹的指挥官。

激活方式

// src/coordinator/coordinatorMode.ts
  if (feature('COORDINATOR_MODE')) {
    return isEnvTruthy(process.env.CLAUDE_CODE_COORDINATOR_MODE)
  }
  return false
}

启动方式：

CLAUDE_CODE_COORDINATOR_MODE=1 claude

Coordinator System Prompt 的核心规则

getCoordinatorSystemPrompt() 返回一个约 400 行的系统提示，其中有几条绝对铁律：

1. 不允许甩锅式委派

DO NOT: delegate research without giving the worker full context
DO NOT: write "based on your findings" — you must synthesize first, THEN instruct
DO: tell workers exactly which files to change, at which lines, doing what

这是最重要的规则。Coordinator 必须先综合分析 Worker 的发现，然后给出精确的实施指令——不能让 Worker 自己去搞清楚该做什么。

2. Worker 不可以知道对方的存在

Workers cannot see the Coordinator's conversation.
Each prompt must be fully self-contained.

每个 Worker 的 Prompt 必须包含所有必要的上下文，因为 Worker 看不到 Coordinator 和其他 Worker 的对话。

3. 不要预测 Worker 的结果

After launching agents, briefly tell the user what you launched and end your response.
Never fabricate or predict agent results in any format.
Results arrive as separate messages.

Worker 结果的通信机制

Worker 完成任务后，结果以 XML 格式注入回 Coordinator 的对话流：

<task-notification>
  <task-id>{agentId}</task-id>
  <status>completed</status>
  <summary>Worker 的一句话状态摘要</summary>
  <result>Worker 的完整最终响应文本</result>
  <usage>
    <total_tokens>15420</total_tokens>
  </usage>
</task-notification>

这些消息对用户不可见，只传给 Coordinator Claude 用于综合分析。

标准任务流（四阶段）

阶段 1: Research（研究）
  └── 多个 Worker 并行
  └── 调查代码库、查找文件、理解问题

阶段 2: Synthesis（综合）
  └── Coordinator 自己完成
  └── 阅读所有发现，写出精确的实施规格

阶段 3: Implementation（实施）
  └── 多个 Worker（按文件分区）
  └── 按规格做精准代码修改

阶段 4: Verification（验证）
  └── Worker
  └── 运行测试，确认改动正确

Continue vs Spawn 决策

Coordinator 需要决定是继续现有 Worker（SendMessage）还是创建新 Worker（Agent）：

场景建议原因
研究的文件就是要修改的文件SendMessage 继续避免重新加载上下文
研究范围广，实施范围窄Agent 新建避免锚定于不相关发现
修正失败或扩展近期工作SendMessage 继续利用已有上下文
验证另一 Worker 刚写的代码Agent 新建保持独立视角
第一次方案完全错误Agent 新建避免锚定效应

Scratchpad：跨 Worker 共享知识

当 GrowthBook tengu_scratch 开启时，Coordinator 可以告知 Worker 一个共享目录：

// src/coordinator/coordinatorMode.ts
if (scratchpadDir && isScratchpadGateEnabled()) {
  content += `\n\nScratchpad directory: ${scratchpadDir}\n` +
    `Workers can read and write here without permission prompts.` +
    `Use this for durable cross-worker knowledge.`
}

Worker 可以自由读写这个目录，用于跨 Worker 的持久化知识共享（例如，Research Worker 把发现写到 scratchpad，Implementation Worker 从中读取）。

Simple 模式

CLAUDE_CODE_SIMPLE=1 CLAUDE_CODE_COORDINATOR_MODE=1 claude

简单模式下 Worker 工具集大幅缩减：

const workerTools = isEnvTruthy(process.env.CLAUDE_CODE_SIMPLE)
  ? [BASH_TOOL_NAME, FILE_READ_TOOL_NAME, FILE_EDIT_TOOL_NAME]  // 3 个工具
  : Array.from(ASYNC_AGENT_ALLOWED_TOOLS)  // 完整工具集

会话恢复的模式对齐

当恢复一个历史 Coordinator 会话时，matchSessionMode() 确保模式一致：

// 如果历史会话是 coordinator 模式，但当前不是
// 自动将环境变量翻转为 coordinator 模式
if (sessionIsCoordinator && !currentIsCoordinator) {
  process.env.CLAUDE_CODE_COORDINATOR_MODE = '1'
}

下一步