【Claude Code源码剖析】11-任务与多 Agent 系统

Claude Code 支持后台任务、子 Agent、团队协作等多种并行执行模式。

---

一、任务类型

// Task.ts
type TaskType =
  | 'local_bash'            // 本地 Shell 命令 (后台运行)
  | 'local_agent'           // 本地子 Agent
  | 'remote_agent'          // 远程 Agent
  | 'in_process_teammate'   // 进程内队友 Agent
  | 'local_workflow'        // 本地工作流
  | 'monitor_mcp'           // MCP 监控任务
  | 'dream'                 // Dream 模式 (自动思考)

type TaskStatus =
  | 'pending'    // 等待启动
  | 'running'    // 运行中
  | 'completed'  // 完成
  | 'failed'     // 失败
  | 'killed'     // 被终止

---

二、Task ID 设计

// 安全的 Task ID 生成
const TASK_ID_PREFIXES: Record<string, string> = {
  local_bash: 'b',             // b + 8字符 → bash 任务
  local_agent: 'a',            // a + 8字符 → agent 任务
  remote_agent: 'r',           // r + 8字符 → 远程 agent
  in_process_teammate: 't',    // t + 8字符 → 队友
  local_workflow: 'w',         // w + 8字符 → 工作流
  monitor_mcp: 'm',            // m + 8字符 → 监控
  dream: 'd',                  // d + 8字符 → dream
};

// 使用 crypto.randomBytes 生成，抵抗 symlink 攻击
// 36^8 ≈ 2.8 万亿种组合
export function generateTaskId(type: TaskType): string {
  const prefix = getTaskIdPrefix(type);
  const bytes = randomBytes(8);
  let id = prefix;
  for (let i = 0; i < 8; i++) {
    id += TASK_ID_ALPHABET[bytes[i]! % TASK_ID_ALPHABET.length];
  }
  return id;  // 例如: "b3k9m2x1p"
}

---

三、Agent 系统

3.1 AgentTool — 子 Agent 派生

主 Agent (REPL)
    │
    ├─ AgentTool("分析这个 bug")
    │   │
    │   └─ 子 Agent 1 (独立上下文)
    │       ├─ FileRead → 读取相关文件
    │       ├─ Grep → 搜索错误模式
    │       └─ 返回分析结果给主 Agent
    │
    ├─ AgentTool("写单元测试")
    │   │
    │   └─ 子 Agent 2 (独立上下文)
    │       ├─ FileRead → 读取被测代码
    │       ├─ FileWrite → 创建测试文件
    │       ├─ BashTool → 运行测试
    │       └─ 返回测试结果
    │
    └─ 主 Agent 综合所有子 Agent 结果

3.2 Agent 定义

// tools/AgentTool/loadAgentsDir.ts
type AgentDefinition = {
  name: string;
  slug: string;
  description: string;
  prompt: string;            // Agent 的专属系统 prompt
  model?: string;            // 使用特定模型
  tools?: string[];          // 允许使用的工具列表
  mcpServers?: McpServerConfig[];  // Agent 专属 MCP 服务器
  maxTokens?: number;
  isBuiltIn: boolean;
};

// 内置 Agent (tools/AgentTool/built-in/)
// 用户自定义 Agent (.claude/agents/*.md)

3.3 Agent 执行隔离

// utils/forkedAgent.ts
export function createSubagentContext(parentContext: ToolUseContext) {
  return {
    // ✅ 共享: 权限上下文、MCP 客户端、文件系统
    toolPermissionContext: parentContext.toolPermissionContext,
    mcpClients: parentContext.options.mcpClients,

    // ❌ 独立: 消息历史、文件缓存、abort 控制
    messages: [],  // 空消息历史 (干净上下文)
    readFileCache: createFileStateCacheWithSizeLimit(),
    abortController: new AbortController(),

    // ❌ 受限: 可用工具列表
    tools: resolveAgentTools(agentDefinition, parentContext.options.tools),
  };
}

---

四、Coordinator 模式

// coordinator/coordinatorMode.ts (370 行)
// "协调者模式"：主 Agent 只负责分配任务，不亲自执行

export function isCoordinatorMode(): boolean {
  return isEnvTruthy(process.env.CLAUDE_CODE_COORDINATOR_MODE);
}

// 协调者模式下：
// - 主 Agent 的可用工具限制为: Agent创建/删除/消息发送
// - 子 Worker Agent 拥有完整工具集
// - 主 Agent 专注于任务分解和协调

Coordinator 用户上下文

export function getCoordinatorUserContext(
  mcpClients,
  scratchpadDir,
): { [k: string]: string } {
  // 告诉协调者：
  // 1. Worker 可用的工具列表
  // 2. MCP 服务器列表
  // 3. Scratchpad 目录 (跨 Agent 共享文件)
}

---

五、Agent Swarms (团队模式)

// utils/agentSwarmsEnabled.ts
// Agent Swarm = 多个 Agent 并行协作

// 架构:
// Leader Agent (主)
//   ├─ Worker Agent 1 (独立目录/worktree)
//   ├─ Worker Agent 2
//   └─ Worker Agent 3
//
// 通过 Mailbox 机制通信:
// utils/mailbox.ts — Agent 间消息传递
// utils/swarm/leaderPermissionBridge.ts — 权限委托
// utils/swarm/permissionSync.ts — 权限同步

Worktree 模式

// utils/worktree.ts
// 每个 Worker Agent 在独立的 git worktree 中工作
// 避免文件冲突

async function createAgentWorktree(agentId: string): Promise<string> {
  // git worktree add /tmp/claude-worktree-{agentId} -b agent/{agentId}
  // 返回 worktree 路径
}

async function removeAgentWorktree(agentId: string): Promise<void> {
  // git worktree remove /tmp/claude-worktree-{agentId}
}

---

六、后台任务管理

6.1 Shell 任务

// tasks/LocalShellTask/
// 长时间运行的 shell 命令（如 npm run dev、docker compose up）

export function spawnShellTask(input: LocalShellSpawnInput): TaskHandle {
  // 1. spawn 子进程
  // 2. 输出重定向到文件 (outputFile)
  // 3. 注册到 AppState.tasks
  // 4. 返回 TaskHandle (用于查询/终止)
}

// 前景/背景切换:
export function backgroundExistingForegroundTask(taskId: string): void;
export function registerForeground(taskId: string): void;
export function unregisterForeground(taskId: string): void;

6.2 任务输出读取

// tools/TaskOutputTool/
// 读取后台任务的输出

// 使用偏移量避免重复读取:
type TaskState = {
  outputFile: string;    // 输出文件路径
  outputOffset: number;  // 上次读取到的位置
};

// 读取新输出:
function readTaskOutput(task: TaskState): string {
  const content = readFromOffset(task.outputFile, task.outputOffset);
  task.outputOffset += content.length;
  return content;
}

---

七、Task Status 状态机

pending → running → completed
                  → failed
                  → killed

任何状态 → killed (外部终止)

export function isTerminalTaskStatus(status: TaskStatus): boolean {
  return status === 'completed' || status === 'failed' || status === 'killed';
}
// 终态任务不会再转换状态
// 用于: 防止向已死 Agent 注入消息、清理资源

---

八、In-Process Teammate

// tasks/InProcessTeammateTask/
// 进程内的队友 Agent (不 spawn 新进程)

// 优势: 低延迟，共享进程内状态
// 劣势: 共享 Node.js 事件循环，可能相互阻塞

export function injectUserMessageToTeammate(
  agentId: AgentId,
  message: string,
): void {
  // 向进程内队友发送消息
  // 队友在下一个事件循环 tick 处理
}

---

九、任务工具集成

工具	功能
TaskCreateTool	创建新任务 (bash/agent)
TaskGetTool	获取任务状态和输出
TaskUpdateTool	更新任务描述/状态
TaskListTool	列出所有任务
TaskStopTool	终止任务
TaskOutputTool	读取任务输出
TodoWriteTool	管理 TODO 列表