Coordinator

这是什么

Coordinator 模式改变主 Claude 的角色。开启后，主线程（编排者）只能使用 Agent、SendMessage、TaskStop 三个工具派发和控制工作，不直接触碰文件；真正干活的是被派出的 worker 子 agent。这种「主线程只编排、worker 只执行」的分离，让一个主脑可以 并发调度多个任务，并在实现与验证之间切换视角。

核心约束：

• 编排者工具池受限：仅 Agent（派发 worker）、 SendMessage（继续已有 worker）、TaskStop（停止 worker）， 外加结构化输出工具与（若可用）PR 活动订阅类 MCP 工具。
• worker 用完整工具集：标准工具（Bash、Read、Edit 等）+ 已连接 MCP 工具 + Skill 工具；但排除 TeamCreate、TeamDelete、 SendMessage、SyntheticOutput，因此 worker 不能再嵌套编排。
• worker 看不到你的对话：每个 worker 的 prompt 必须自包含，包含文件路径、行号、 错误信息与验收标准。
• 结果以通知回流：worker 完成后以 <task-notification> （user-role 消息，但不是用户输入）回到下一轮，编排者据此继续派发。

与 Workflow（确定性脚本编排）和多实例群控（跨进程 Pipe IPC）不同，Coordinator 是单进程内的星型编排：编排者居中，worker 是它派出的异步本地子 agent，不涉及 团队邮箱、共享任务白板或跨机器通信。

前置条件

安装启用

1. （推荐）会话内切换

   在交互式会话里执行 /coordinator 即可开/关。命令只在 COORDINATOR_MODE 特性编译进产物时可见。开启时会设置 QS_COORDINATOR_MODE=1，关闭时清除该变量。

   qsdashi 会话 复制

   # 开启：主线程变为编排者
   /coordinator
   # → Coordinator mode enabled — use Agent(subagent_type: "worker") to dispatch tasks
   
   # 再次执行即关闭，回到普通模式
   /coordinator
   # → Coordinator mode disabled — back to normal mode

2. 启动时注入环境变量

   交互切换外，也可在启动前设置环境变量直接进入。dev 模式示例（特性已默认开启）：

   Terminal 复制

   # dev 模式（如需显式声明特性）
   FEATURE_COORDINATOR_MODE=1 QS_COORDINATOR_MODE=1 bun run dev
   
   # Simple 模式：worker 工具面降到 Bash / Read / Edit
   FEATURE_COORDINATOR_MODE=1 QS_COORDINATOR_MODE=1 \
     QS_SIMPLE=1 bun run dev

3. 会话恢复自动对齐

   coordinator 是会话属性，写入主 session JSONL 的 mode 元数据。恢复旧会话时 matchSessionMode() 会按存储的模式自动设置或清除 QS_COORDINATOR_MODE，避免在普通环境恢复编排会话（或反之）。

配置

Coordinator 通过环境变量与 feature flag 配置，不写入 settings.json。

模式持久化与恢复相关的位置：

常用命令与参数

斜杠命令：

编排者可用工具（由模型调用，非人类斜杠命令）：

实战示例

并行研究，再综合派发实现（编排者视角）：

# 1. 并行派发两个只读研究 worker（同一消息内多次调用即并行）
Agent({ description: "调查 auth bug",
        subagent_type: "worker",
        prompt: "在 src/auth/ 定位会话/令牌校验附近的空指针风险，报告文件、行号、类型。不要改文件。" })
Agent({ description: "研究 auth 测试",
        subagent_type: "worker",
        prompt: "列出 src/auth/ 相关测试文件与覆盖缺口，报告结构。不要改文件。" })

# 2. worker 完成后收到 <task-notification>，编排者综合发现
#    再写出含具体位置的实现指令（继续同一 worker 以复用其上下文）
SendMessage({ to: "agent-a1b",
              message: "修复 src/auth/validate.ts:42 的空指针：user.id 前加空检查，为 null 时返回 401。提交并报告 hash。" })

# 3. 方向错误时先停后纠
TaskStop({ task_id: "agent-x7q" })
SendMessage({ to: "agent-x7q",
              message: "停止 JWT 重构，改为只修复 validate.ts:42 的空指针。" })

worker 结果通知格式（回到下一轮的 user-role 消息）：

<task-notification>
  <task-id>agent-a1b</task-id>
  <status>completed|failed|killed</status>
  <summary>Agent "调查 auth bug" completed</summary>
  <result>Found null pointer in src/auth/validate.ts:42...</result>
  <usage>
    <total_tokens>N</total_tokens>
    <tool_uses>N</tool_uses>
    <duration_ms>N</duration_ms>
  </usage>
</task-notification>

编排者的典型流水线是：Research（worker 并行）→ Synthesis（编排者综合）→ Implementation（worker）→ Verification（worker）。

常见问题排错