第8章 多 Agent 协调算法

// 简化的 runAgent 签名（源自 AgentTool/runAgent.ts）
async function* runAgent({
  agentDefinition,     // Agent 定义：类型、工具集、系统提示
  promptMessages,      // 任务指令
  toolUseContext,      // 父 Agent 的工具使用上下文
  isAsync,             // 同步 or 异步执行
  forkContextMessages, // 可选：从父 Agent 继承的对话历史
  allowedTools,        // 工具权限白名单
  worktreePath,        // 可选：隔离的 git worktree 路径
  ...
}): AsyncGenerator<Message, void>

// 默认模式：不传递 forkContextMessages
const contextMessages: Message[] = forkContextMessages
  ? filterIncompleteToolCalls(forkContextMessages)
  : []  // 空数组 → 干净的上下文

// Fork 模式：传递过滤后的父对话历史
const contextMessages = filterIncompleteToolCalls(forkContextMessages)
const initialMessages = [...contextMessages, ...promptMessages]

// forkSubagent.ts - 构建 Fork 消息
function buildForkedMessages(
  directive: string,
  assistantMessage: AssistantMessage,
): Message[] {
  // 1. 保留完整的 assistant 消息（包含所有 tool_use 块）
  const fullAssistantMessage = { ...assistantMessage, uuid: randomUUID() }

  // 2. 为每个 tool_use 生成统一的占位符 tool_result
  const toolResultBlocks = toolUseBlocks.map(block => ({
    type: 'tool_result',
    tool_use_id: block.id,
    content: [{ type: 'text', text: 'Fork started — processing in background' }],
  }))

  // 3. 拼接：统一占位符 + 本 fork 独有的 directive
  return [fullAssistantMessage, createUserMessage({
    content: [...toolResultBlocks, { type: 'text', text: buildChildMessage(directive) }],
  })]
}

// forkedAgent.ts - 简化的子 Agent 上下文创建
function createSubagentContext(
  parentContext: ToolUseContext,
  overrides?: SubagentContextOverrides,
): ToolUseContext {
  return {
    // ---- 隔离的状态 ----
    readFileState: cloneFileStateCache(parentContext.readFileState),  // 克隆文件缓存
    nestedMemoryAttachmentTriggers: new Set<string>(),               // 全新的触发器集合
    toolDecisions: undefined,                                         // 独立的决策记录
    contentReplacementState: cloneContentReplacementState(...),       // 克隆内容替换状态

    // ---- 独立的 ID 和控制 ----
    agentId: overrides?.agentId ?? createAgentId(),                  // 每个 Agent 有唯一 ID
    abortController: createChildAbortController(parentContext.abortController),

    // ---- 可选共享的回调 ----
    setAppState: overrides?.shareSetAppState
      ? parentContext.setAppState
      : () => {},  // 默认是 no-op

    // ---- 任务注册始终共享 ----
    setAppStateForTasks: parentContext.setAppStateForTasks ?? parentContext.setAppState,

    // ---- UI 回调全部隔离 ----
    addNotification: undefined,
    setToolJSX: undefined,
  }
}

// builtInAgents.ts - 内置 Agent 类型
function getBuiltInAgents(): AgentDefinition[] {
  if (isCoordinatorMode()) {
    return getCoordinatorAgents()  // Coordinator 模式有专门的 Agent 集
  }

  const agents = [
    GENERAL_PURPOSE_AGENT,   // 通用 Agent：可读可写，执行多步骤任务
    STATUSLINE_SETUP_AGENT,  // 状态栏配置 Agent
  ]

  if (areExplorePlanAgentsEnabled()) {
    agents.push(EXPLORE_AGENT, PLAN_AGENT)  // 只读搜索 Agent 和规划 Agent
  }

  return agents
}

const EXPLORE_AGENT: BuiltInAgentDefinition = {
  agentType: 'Explore',
  disallowedTools: [AGENT_TOOL_NAME, FILE_EDIT_TOOL_NAME, FILE_WRITE_TOOL_NAME, ...],
  model: 'haiku',         // 用更快更便宜的模型
  omitClaudeMd: true,     // 省略 CLAUDE.md 项目配置
  getSystemPrompt: () => '... READ-ONLY MODE - NO FILE MODIFICATIONS ...',
}

// coordinatorMode.ts
function isCoordinatorMode(): boolean {
  return isEnvTruthy(process.env.CLAUDE_CODE_COORDINATOR_MODE)
}

你是一个协调者（coordinator）。你的工作是：
- 帮助用户实现目标
- 指挥 Worker 进行研究、实现和验证代码变更
- 综合结果并与用户沟通
- 在可以直接回答时不要委派工作

// coordinatorMode.ts - Coordinator 可用的工具
const coordinatorTools = [
  AGENT_TOOL_NAME,         // 派生新 Worker
  SEND_MESSAGE_TOOL_NAME,  // 向已有 Worker 发送消息
  TASK_STOP_TOOL_NAME,     // 停止运行中的 Worker
]

// 反模式 — 惰性委派
Agent({ prompt: "Based on your findings, fix the auth bug" })

// 正确 — 综合后的具体规格
Agent({ prompt: "Fix the null pointer in src/auth/validate.ts:42.
  The user field on Session 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'." })

// SendMessage 的核心路由逻辑
if (typeof input.message === 'string' && input.to !== '*') {
  const task = appState.tasks[agentId]

  if (isLocalAgentTask(task) && task.status === 'running') {
    // Worker 仍在运行 → 排队消息
    queuePendingMessage(agentId, input.message, setAppState)
    return { success: true, message: 'Message queued for delivery' }
  }

  // Worker 已停止 → 从磁盘 transcript 恢复
  const result = await resumeAgentBackground({
    agentId,
    prompt: input.message,
    toolUseContext: context,
  })
  return { success: true, message: 'Agent resumed with your message' }
}

// TeamCreateTool.ts - 创建 Team
async call(input, context) {
  const teamFile: TeamFile = {
    name: finalTeamName,
    description: _description,
    createdAt: Date.now(),
    leadAgentId,                // Team Leader 的 ID
    leadSessionId: getSessionId(),
    members: [{
      agentId: leadAgentId,
      name: TEAM_LEAD_NAME,    // "team-lead"
      joinedAt: Date.now(),
      cwd: getCwd(),
      subscriptions: [],
    }],
  }

  await writeTeamFileAsync(finalTeamName, teamFile)
  registerTeamForSessionCleanup(finalTeamName)  // 会话结束时清理
  await resetTaskList(taskListId)                // 任务编号从 1 开始
}

// spawnMultiAgent.ts
async function handleSpawn(input, context) {
  // 策略 1：In-Process（同进程）
  if (isInProcessEnabled()) {
    return handleSpawnInProcess(input, context)
  }

  // 策略 2：尝试面板后端（tmux 或 iTerm2）
  try {
    await detectAndGetBackend()
  } catch (error) {
    // 策略 3：面板不可用时回退到 In-Process
    markInProcessFallback()
    return handleSpawnInProcess(input, context)
  }

  // 使用分屏或独立窗口
  return input.use_splitpane !== false
    ? handleSpawnSplitPane(input, context)
    : handleSpawnSeparateWindow(input, context)
}

const teammateArgs = [
  `--agent-id ${quote([teammateId])}`,
  `--agent-name ${quote([sanitizedName])}`,
  `--team-name ${quote([teamName])}`,
  `--agent-color ${quote([teammateColor])}`,
  `--parent-session-id ${quote([getSessionId()])}`,
]

文件布局：
~/.claude/teams/{team_name}/inboxes/
  ├── team-lead.json      # Leader 的收件箱
  ├── researcher.json     # Researcher 的收件箱
  └── implementer.json    # Implementer 的收件箱

// teammateMailbox.ts
type TeammateMessage = {
  from: string       // 发送者名称
  text: string       // 消息内容
  timestamp: string  // 时间戳
  read: boolean      // 是否已读
  color?: string     // 发送者颜色
  summary?: string   // UI 预览摘要
}

async function writeToMailbox(
  recipientName: string,
  message: Omit<TeammateMessage, 'read'>,
  teamName?: string,
) {
  const inboxPath = getInboxPath(recipientName, teamName)
  // 使用带重试的文件锁，防止多个 Agent 同时写入
  const LOCK_OPTIONS = {
    retries: { retries: 10, minTimeout: 5, maxTimeout: 100 },
  }
  // ... 加锁、读取、追加、写入、释放锁
}

// 点对点消息
SendMessage({ to: "researcher", message: "查找 auth 模块的入口点" })

// 广播消息
SendMessage({ to: "*", message: "所有人暂停，需求变更了" })

// 结构化消息（用于协议级通信）
SendMessage({ to: "worker-1", message: {
  type: "shutdown_request",
  reason: "任务已完成"
}})

// runAgent.ts - 同步 Agent 的消息流
for await (const message of query({
  messages: initialMessages,
  systemPrompt: agentSystemPrompt,
  toolUseContext: agentToolUseContext,
  maxTurns: maxTurns ?? agentDefinition.maxTurns,
})) {
  if (isRecordableMessage(message)) {
    // 1. 持久化到 sidechain transcript（磁盘）
    await recordSidechainTranscript([message], agentId, lastRecordedUuid)
    // 2. yield 给父 Agent
    yield message
  }
}

function finalizeAgentTool(agentMessages, agentId, metadata): AgentToolResult {
  const lastAssistantMessage = getLastAssistantMessage(agentMessages)
  return {
    agentId,
    content: lastAssistantMessage.message.content.filter(b => b.type === 'text'),
    totalToolUseCount: countToolUses(agentMessages),
    totalDurationMs: Date.now() - metadata.startTime,
    totalTokens: getTokenCountFromUsage(lastAssistantMessage.message.usage),
    usage: lastAssistantMessage.message.usage,
  }
}

<task-notification>
  <task-id>agent-a1b2c3</task-id>
  <status>completed</status>
  <summary>Agent "Investigate auth bug" completed</summary>
  <result>Found null pointer in src/auth/validate.ts:42...</result>
  <usage>
    <total_tokens>15000</total_tokens>
    <tool_uses>8</tool_uses>
    <duration_ms>12500</duration_ms>
  </usage>
</task-notification>

// agentToolUtils.ts - 简化的异步 Agent 生命周期
async function runAsyncAgentLifecycle({ taskId, makeStream, ... }) {
  try {
    for await (const message of makeStream(onCacheSafeParams)) {
      agentMessages.push(message)
      updateAsyncAgentProgress(taskId, getProgressUpdate(tracker), rootSetAppState)
    }

    // 成功完成
    const agentResult = finalizeAgentTool(agentMessages, taskId, metadata)
    completeAsyncAgent(agentResult, rootSetAppState)
    enqueueAgentNotification({ taskId, status: 'completed', finalMessage, ... })

  } catch (error) {
    if (error instanceof AbortError) {
      // 被用户或 Coordinator 中止
      killAsyncAgent(taskId, rootSetAppState)
      enqueueAgentNotification({ taskId, status: 'killed', ... })
    } else {
      // 执行失败
      failAsyncAgent(taskId, errorMessage(error), rootSetAppState)
      enqueueAgentNotification({ taskId, status: 'failed', error: msg, ... })
    }
  }
}

function filterToolsForAgent({ tools, isBuiltIn, isAsync, permissionMode }) {
  return tools.filter(tool => {
    if (tool.name.startsWith('mcp__')) return true       // MCP 工具始终允许
    if (ALL_AGENT_DISALLOWED_TOOLS.has(tool.name)) return false  // 全局禁止列表
    if (!isBuiltIn && CUSTOM_AGENT_DISALLOWED_TOOLS.has(tool.name)) return false
    if (isAsync && !ASYNC_AGENT_ALLOWED_TOOLS.has(tool.name)) return false
    return true
  })
}

// runAgent.ts - 权限模式覆盖逻辑
const agentGetAppState = () => {
  const state = toolUseContext.getAppState()

  // 父 Agent 的 bypassPermissions 或 acceptEdits 始终优先
  if (agentPermissionMode &&
      state.toolPermissionContext.mode !== 'bypassPermissions' &&
      state.toolPermissionContext.mode !== 'acceptEdits') {
    toolPermissionContext = { ...toolPermissionContext, mode: agentPermissionMode }
  }

  // 异步 Agent 默认不显示权限提示（自动拒绝）
  if (isAsync && !canShowPermissionPrompts) {
    toolPermissionContext = {
      ...toolPermissionContext,
      shouldAvoidPermissionPrompts: true
    }
  }
}

finally {
  await mcpCleanup()                           // 清理 Agent 专属 MCP 服务器
  clearSessionHooks(rootSetAppState, agentId)   // 清理会话钩子
  cleanupAgentTracking(agentId)                 // 清理 prompt cache 追踪
  agentToolUseContext.readFileState.clear()      // 释放文件缓存
  initialMessages.length = 0                     // 释放消息数组
  unregisterPerfettoAgent(agentId)              // 释放 Perfetto 追踪条目
  clearAgentTranscriptSubdir(agentId)           // 释放 transcript 子目录映射

  // 释放 todos 条目，防止内存泄漏
  rootSetAppState(prev => {
    if (!(agentId in prev.todos)) return prev
    const { [agentId]: _removed, ...todos } = prev.todos
    return { ...prev, todos }
  })

  // 杀死后台 shell 任务，防止僵尸进程
  killShellTasksForAgent(agentId, getAppState, rootSetAppState)
}

┌─────────────────────────────────────────────────────┐
│           拓扑一：星形（Agent 派生）                   │
│                                                       │
│              ┌──────────┐                             │
│              │  主 Agent │                             │
│              └──┬───┬───┘                             │
│            ┌────┘   └────┐                            │
│     ┌──────▼──┐    ┌──────▼──┐                        │
│     │ Explore  │    │ General │                        │
│     │ (只读)   │    │ Purpose │                        │
│     └─────────┘    └─────────┘                        │
│     同步返回结果    同步返回结果                         │
└─────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────┐
│         拓扑二：星形+异步（Coordinator 模式）          │
│                                                       │
│             ┌─────────────┐                           │
│             │ Coordinator │                            │
│             └──┬───┬───┬──┘                           │
│           ┌────┘   │   └────┐                         │
│    ┌──────▼──┐ ┌───▼────┐ ┌─▼────────┐               │
│    │Worker-1 │ │Worker-2│ │ Worker-3  │               │
│    │(研究)   │ │(研究)  │ │(实现)     │               │
│    └────┬────┘ └───┬────┘ └────┬──────┘               │
│         │          │           │                      │
│    <task-notification> 异步通知回 Coordinator           │
└─────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────┐
│            拓扑三：网状（Swarm 架构）                   │
│                                                       │
│    ┌──────────┐    Mailbox     ┌──────────┐          │
│    │  Leader   │◄─────────────►│Teammate-1│          │
│    │(team-lead)│               │(researcher)          │
│    └──┬───┬───┘               └──────────┘           │
│       │   │       Mailbox     ┌──────────┐           │
│       │   └──────────────────►│Teammate-2│           │
│       │                       │(implementer)          │
│       │       Mailbox         └─────┬────┘           │
│       └──────────────────┐          │                │
│                    ┌─────▼────┐     │ Mailbox         │
│                    │Teammate-3│◄────┘                │
│                    │(verifier) │                       │
│                    └──────────┘                       │
│    各 Agent 独立进程，通过文件 Mailbox 通信             │
└─────────────────────────────────────────────────────┘