CC源码剖析 #04 · 多阶段任务编排器

1
2

// 派生 Worker 时指定 subagent_type = "worker"
AGENT_TOOL_NAME({ description: "Investigate auth bug", subagent_type: "worker", prompt: "..." })

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

// Coordinator 的 workers 使用受限工具集
const INTERNAL_WORKER_TOOLS = new Set([
  TEAM_CREATE_TOOL_NAME,
  TEAM_DELETE_TOOL_NAME,
  SEND_MESSAGE_TOOL_NAME,
  SYNTHETIC_OUTPUT_TOOL_NAME,
])

// SIMPLE 模式下只有 Bash/Read/Edit
const workerTools = isEnvTruthy(process.env.CLAUDE_CODE_SIMPLE)
  ? [BASH_TOOL_NAME, FILE_READ_TOOL_NAME, FILE_EDIT_TOOL_NAME]
  : Array.from(ASYNC_AGENT_ALLOWED_TOOLS)
      .filter(name => !INTERNAL_WORKER_TOOLS.has(name))

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

<task-notification>
<task-id>{agentId}</task-id>
<status>completed|failed|killed</status>
<summary>{human-readable status summary}</summary>
<result>{agent's final text response}</result>
<usage>
  <total_tokens>N</total_tokens>
  <tool_uses>N</tool_uses>
  <duration_ms>N</duration_ms>
</usage>
</task-notification>

1
2
3
4
5
6

// Coordinator 系统提示中的并行指导：
"Launch independent workers concurrently whenever possible
— don't serialize work that can run simultaneously and look
for opportunities to fan out. When doing research, cover
multiple angles. To launch workers in parallel, make
multiple tool calls in a single message."

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

// 核心原则：Worker 看不到你的对话
// 每个 prompt 必须自包含所有必要信息

// Anti-pattern（禁止）：
AGENT_TOOL_NAME({ prompt: "Based on your findings, fix the auth bug", ... })

// Good（必须）：
AGENT_TOOL_NAME({
  prompt: "Fix the null pointer in src/auth/validate.ts:42.
  The user field on Session (src/auth/types.ts:15) is undefined
  when sessions expire but the token remains cached.
  Add a null check before user.id access — if null, return 401
  with 'Session expired'. Commit and report the hash.",
  ...
})

1
2
3
4
5
6
7
8

"You are Claude Code, an AI assistant that orchestrates
software engineering tasks across multiple workers."

// Coordinator 的职责：
// 1. 帮助用户达成目标
// 2. 指挥 workers 研究、实现、验证
// 3. 合成结果与用户沟通
// 4. 能直接回答的不委托

1
2
3
4
5
6

// Worker 结果是内部信号，不是对话伙伴
// 不要感谢或确认它们
"Every message you send is to the user. Worker results
and system notifications are internal signals, not
conversation partners — never thank or acknowledge them.
Summarize new information for the user as it arrives."

1
2
3
4

// Worker 报告失败（测试失败、构建错误）：
// → 用 SendMessageTool 继续同一 Worker（有完整错误上下文）
// → 修正失败则尝试不同方法
// → 无法恢复则报告用户

1
2
3
4
5

// 用 TASK_STOP_TOOL_NAME 停止方向错误的 Worker
TASK_STOP_TOOL_NAME({ task_id: "agent-x7q" })

// 然后用 SendMessageTool 继续，给出正确方向
SEND_MESSAGE_TOOL_NAME({ to: "agent-x7q", message: "Stop the JWT refactor..." })

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

// main.tsx 中条件导入
const coordinatorModeModule = feature('COORDINATOR_MODE')
  ? require('./coordinator/coordinatorMode.js')
  : null;

// coordinatorMode.ts 中检查
export function isCoordinatorMode(): boolean {
  if (feature('COORDINATOR_MODE')) {
    return isEnvTruthy(process.env.CLAUDE_CODE_COORDINATOR_MODE)
  }
  return false
}