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

⚠️ 学习声明：本文档基于 Claude Code 2.1.88 源码分析整理，仅供个人学习研究使用，不做任何商业用途。

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 列表

---

十一、多 Agent 系统的学术基础

11.1 为什么需要多 Agent？

单 Agent 的局限性：

瓶颈	表现	多 Agent 解法
上下文窗口	一个 Agent 只能关注一个任务	每个子 Agent 有独立窗口
专注度	大任务中的子任务容易被忽略	每个子 Agent 专注一个子任务
工具冲突	并行工具调用可能相互干扰	隔离的工具执行环境
权限边界	一个 Agent 拥有全部权限	子 Agent 可被限制权限

11.2 学术文献中的多 Agent 模式

论文	核心模式	CC 对应
AutoGen (Wu et al., 2023)	Agent 间对话协调	Swarm 的 Agent 通信
ChatDev (Qian et al., 2024)	角色模拟（CEO+CTO+程序员）	Task 的角色分工
MetaGPT (Hong et al., 2024)	SOP 驱动的 Agent 流程	Plan Mode + Task

11.3 三种多 Agent 架构

1. 层次式（Hierarchical）
   主 Agent → 分配子任务 → 子 Agent → 回传结果
   CC 实现: Task

2. 对等式（Peer-to-Peer）
   Agent A ⇔ Agent B（通过 Mailbox 通信）
   CC 实现: Swarm + Mailbox

3. 混合式（Hybrid）
   主 Agent 协调 + 子 Agent 间可直接通信
   CC 实现: InProcessTeammate + Mailbox

---

十二、Task 系统：层次式多 Agent

12.1 Task 的生命周期

Task 创建
  │
  ├─ CREATED ──→ RUNNING ──→ COMPLETED
  │                │
  │                ├─ FAILED (工具执行失败)
  │                ├─ ABORTED (用户中断)
  │                └─ TIMEOUT (超时)
  │
  └─ 父 Agent 轮询 Task 状态（循环或 callback）

12.2 Task 的代理模式（Delegation）

// 主 Agent 将子任务委派给子 Agent
const task = await createTask({
  description: "Refactor UserService to use dependency injection",
  context: "See src/services/UserService.ts (450 lines)",
  tools: [FileReadTool, FileEditTool, GrepTool],  // 受限的工具集
  maxTurns: 10,  // 有限的 turn 数
});

// 主 Agent 可以并行委派多个子任务
const [task1, task2] = await Promise.all([
  createTask({ description: "Add unit tests for UserService" }),
  createTask({ description: "Update UserController to use new UserService" }),
]);

12.3 子 Agent 的上下文隔离

每个子 Agent 拥有独立的：

• System Prompt（包含子任务的专用指令）
• Messages 历史（不包含主 Agent 的对话）
• 工具集（主 Agent 可限制子 Agent 能使用的工具）
• 权限模式（子 Agent 可被授予更低或更高的信任级别）

---

十三、Swarm 系统：对等式多 Agent

13.1 Swarm 的设计目标

• 自动并行化：将可以并行的工作自动分配给多个 Agent
• 容错性：单个 Agent 失败不影响其他 Agent
• 弹性伸缩：Agent 数量可根据工作负载动态调整

13.2 Swarm 架构

       ┌─────────────┐
       │  Swarm      │
       │ Coordinator │  ← 协调者（通常是主 Agent）
       └──┬──┬──┬───┘
          │  │  │
   ┌──────┘  │  └──────┐
   ▼         ▼         ▼
Agent 1   Agent 2   Agent 3
(Task A)  (Task B)  (Task C)
   │         │         │
   └────┬────┴────┬────┘
        ▼         ▼
     Mailbox   Mailbox
        │         │
        └────┬────┘
             ▼
       Coordinator

13.3 权限同步

Swarm 中的 Agent 通常继承主 Agent 的权限模式，但可通过 leaderPermissionBridge 实现细粒度控制：

// 子 Agent 请求权限 → 转发给主 Agent
// 主 Agent 批准/拒绝 → 同步给子 Agent
class LeaderPermissionBridge {
  async requestPermission(childAgentId: string, tool: Tool, input: any): Promise<boolean> {
    // 将子 Agent 的权限请求转发给用户
    const decision = await askUser({
      message: `Agent ${childAgentId} wants to use ${tool.name}`,
      details: JSON.stringify(input),
    });
    return decision === 'allow';
  }
}

---

十四、Mailbox：Agent 间通信

14.1 Mailbox 的设计

Mailbox 是 Agent 间异步通信的通道，灵感来自 Erlang/OTP 的 Actor 模型：

interface Mailbox {
  // 发送消息到另一个 Agent
  send(toAgentId: string, message: AgentMessage): Promise<void>;

  // 检查本 Agent 的收件箱
  receive(): Promise<AgentMessage[]>;

  // 清空收件箱
  clear(): void;
}

interface AgentMessage {
  from: string;     // 发送者 Agent ID
  to: string;       // 接收者 Agent ID
  type: 'result' | 'query' | 'notification';
  content: string;
  timestamp: number;
}

14.2 通信模式

1. 通知（Notification）— 单向，无响应
   Agent A → Mailbox → Agent B
   "Task X is done, here are the results"

2. 查询（Query）— 请求-响应
   Agent A → Mailbox → Agent B → Mailbox → Agent A
   "What's the return type of UserService.findById()?"

3. 广播（Broadcast）— 一对多
   Coordinator → Mailbox → [Agent 1, Agent 2, Agent 3]
   "All agents: the API schema changed, adjust your code"

14.3 与 Actor 模型的对比

维度	Erlang Actor	CC Mailbox
隔离性	进程级隔离	上下文级隔离
消息传递	异步 by default	异步 + 可选的同步等待
监督树	OTP Supervisor	Swarm Coordinator
故障处理	Let it crash	任务级重试

---

涉及源文件

• tools/AgentTool/loadAgentsDir.ts
• utils/agentSwarmsEnabled.ts
• utils/forkedAgent.ts
• utils/mailbox.ts
• utils/swarm/leaderPermissionBridge.ts
• utils/swarm/permissionSync.ts
• utils/worktree.ts