Claude Code 多 Agent 架构深度分析：源码揭秘 Leader-Worker 全貌

2026 年 3 月 31 日，Anthropic 因一行遗漏的 .npmignore 配置，意外将 Claude Code v2.1.88 的完整源码打包进 npm 包。512,000 行 TypeScript、1,884 个文件，数小时内被镜像到 GitHub，并在社区引发了 AI 工具史上规模最大的一次架构"考古"。本文基于泄露源码中与多 Agent 相关的约 13,700 行核心代码，系统还原 Claude Code 的 Leader-Worker 编排架构——从 Agent 定义加载、三大执行后端选择，到文件邮箱通信、权限委托链，直到 Coordinator 自动编排模式与 Git Worktree 隔离设计，力求做到"知其然，更知其所以然"。

📌 核心参考：How we built our multi-agent research system（Anthropic Engineering Blog）

📌 适合人群：对 AI Agent 架构感兴趣的后端开发者、AI 应用工程师

# Claude Code 多Agent架构
## 为什么需要多Agent
- 单 Agent 上下文窗口瓶颈
- 并行执行提升吞吐量
- 专业化角色分工更精准
## 核心编排模型
- Leader-Worker 模式
- Team Mode 持久化协作
- Coordinator Mode 自动编排
## 三大执行后端
- InProcess（AsyncLocalStorage隔离）
- Tmux（终端分屏独立进程）
- iTerm2（Python自动化控制）
## 通信与隔离机制
- 文件邮箱（JSON + 文件锁）
- SendMessage 路由逻辑
- Git Worktree 文件隔离
## 安全与权限设计
- 权限始终由人类把控
- 多层工具过滤机制
- 优雅降级与容错

关于本文档 ​

本文系统解析 Claude Code 多 Agent 架构的设计全貌，所有分析均基于泄露源码中的实际函数、常量和类型定义，而非推测。无论你是要构建自己的多 Agent 系统，还是理解业界顶级 AI 编码工具的内部运作，都能从中获得第一手参考。

• ✅ Leader-Worker 架构的整体设计与两种编排模式（Team / Coordinator）
• ✅ AgentTool 的路由决策机制与 AgentDefinition 类型系统
• ✅ InProcess、Tmux、iTerm2 三大后端的实现原理与选择逻辑
• ✅ 文件邮箱通信协议与 SendMessage 的完整路由逻辑
• ✅ 权限委托链、Git Worktree 隔离与 Worker 完整生命周期

1. 为什么单 Agent 不够用？ ​

1.1 单 Agent 的上下文窗口瓶颈 ​

想象一下，你让一个员工同时负责市场调研、代码开发、测试验收和文档撰写。他会在各个任务之间频繁切换，大量注意力被"记住上下文"所消耗，真正用于思考的认知资源反而不足。大型语言模型的"上下文窗口"正是这种"工作记忆"的物理边界。

对于 Claude Code 要处理的真实任务——横跨多个文件的大型重构、跨模块的 Bug 修复、需要并行搜索代码库与文档的架构分析——单个 Agent 面临三个硬限制：

1.2 并行即压缩：多 Agent 的本质 ​

Anthropic 工程博客中有一句精辟的定义：

"搜索的本质是压缩——从海量数据库中提取洞见。子 Agent 通过并行搜索问题的不同维度并压缩最重要的内容，实现了这种压缩。"

这里的"子 Agent"不是比喻，而是真实运行的、拥有独立上下文窗口的 Claude 实例。每个子 Agent 只看到自己负责的那片信息空间，Leader 负责统筹这些压缩后的洞见，输出最终结论。这就是 Claude Code 选择 Leader-Worker 架构的根本动机。

2. 整体架构：Leader-Worker + 两种编排模式 ​

2.1 核心骨架一览 ​

Claude Code 的多 Agent 系统以 Leader-Worker 模型为骨架。Leader 负责接收用户请求、拆解任务、派遣 Worker；Worker 负责执行具体子任务，通过通信机制向 Leader 汇报。整个系统有三种执行后端（InProcess、Tmux、iTerm2）和两种编排模式（Team Mode、Coordinator Mode）。

2.2 两种编排模式的定位差异 ​

理解两种编排模式的区别，有助于知道什么场景下 Claude Code 如何"思考协作"。

3. Agent Tool：所有子 Agent 的统一入口 ​

src/tools/AgentTool/AgentTool.tsx（约 800 行）是整个多 Agent 系统的门卫，负责解析调用参数并路由到正确的执行路径。

3.1 AgentDefinition 类型系统 ​

每一个 Agent（无论内置还是自定义）都遵循同一套类型约束。这个设计让 Agent 系统具备良好的扩展性：

// src/tools/AgentTool/loadAgentsDir.ts
type AgentDefinition = {
  agentType: string           // 唯一标识，如 'Explore'、'verification'
  whenToUse: string           // 何时使用的描述（供 Leader 选型参考）
  tools: string[]             // 可用工具，['*'] 表示全部工具
  disallowedTools: string[]   // 明确禁用的工具列表
  model: string               // 模型选择，'haiku'|'sonnet'|'opus'|'inherit'
  permissionMode: string      // 权限模式，如 'plan'|'acceptEdits'
  maxTurns: number            // 最大对话轮次，防止 Agent 无限循环
  background: boolean         // 是否后台异步运行
  isolation: 'worktree'       // 文件系统隔离方式
  getSystemPrompt()           // 系统提示词生成函数
}

Agent 有三种来源，按以下优先级加载（后者覆盖前者）：

built-in < plugin < userSettings < projectSettings < flagSettings < policySettings

3.2 内置 Agent 类型全览 ​

源码中预置了 7 种内置 Agent，各自有严格的工具权限和模型配置：

3.3 路由决策树：call() 入口的四条分叉路 ​

AgentTool 收到调用后，按以下决策树将请求路由到不同的执行路径：

4. 三大执行后端：从同进程到终端分屏 ​

这是 Claude Code 架构中最有工程美感的部分——同一套 Agent 逻辑，可以运行在三种完全不同的物理环境中，且自动降级到最优可用方案。

4.1 InProcess 后端：零 IPC 开销的同进程隔离 ​

文件：src/utils/swarm/backends/InProcessBackend.ts（339 行）

InProcess 是最轻量的执行方式：所有 Worker 运行在同一个 Node.js 进程中，通过 AsyncLocalStorage 实现上下文隔离，无需任何进程间通信（IPC）。

// src/utils/teammateContext.ts（96 行）
// AsyncLocalStorage 实现进程内零开销隔离
const teammateContextStorage = new AsyncLocalStorage<TeammateContext>()

// 每个 Worker 运行在独立的 async 上下文中
function runWithTeammateContext(context: TeammateContext, fn: () => T): T {
  return teammateContextStorage.run(context, fn)
}

// 任何层级的函数都可以查询"我是哪个 Worker"
function isInProcessTeammate(): boolean {
  return teammateContextStorage.getStore() !== undefined
}

核心机制：AsyncLocalStorage 是 Node.js 的原生 API，它让同一个异步调用栈上的所有函数共享同一个"上下文存储"，而不同调用栈之间完全隔离。效果类似线程局部存储（Thread Local Storage），但适用于 JavaScript 的异步模型。

权限处理的特殊设计：InProcess Worker 的危险操作权限请求，通过 leaderPermissionBridge.ts 直接转发到 Leader 的 UI 对话框，无需文件邮箱中转——这是性能与安全之间的精巧平衡。

4.2 Tmux 后端：真正的独立进程分屏 ​

文件：src/utils/swarm/backends/TmuxBackend.ts（764 行）

每个 Worker 是一个独立的 claude CLI 进程，运行在 tmux 的独立 pane 中。这意味着每个 Worker 有自己的进程、内存空间和 Node.js 运行时——彻底的隔离，但也有 IPC 开销。

Tmux 后端支持两种布局：

【Leader 在 tmux 内】         【Leader 在 tmux 外】
┌──────────┬─────────┐       ┌─────────┬─────────┐
│          │Worker A │       │Worker A │Worker B │
│  Leader  ├─────────┤       ├─────────┼─────────┤
│  (30%)   │Worker B │       │Worker C │Worker D │
│          ├─────────┤       └─────────┴─────────┘
│          │Worker C │         tiled 布局
└──────────┴─────────┘         独立 session
  main-vertical 布局            claude-swarm-{pid}

几个值得关注的工程细节：

• acquirePaneCreationLock()：序列化并行 spawn 操作，防止多个 Worker 同时创建 pane 引发竞态条件
• 200ms 延迟：等待 shell 的 rc 文件（.bashrc、.zshrc）完成加载，确保 PATH 等环境变量可用
• hidePane()/showPane()：通过 break-pane/join-pane 实现 Worker 的视觉隐藏与恢复

4.3 iTerm2 后端：macOS 原生终端控制 ​

文件：src/utils/swarm/backends/ITermBackend.ts（370 行）

iTerm2 后端通过 it2 CLI（Python 自动化工具）控制 iTerm2 的分屏行为。

4.4 后端自动选择：优雅降级的瀑布逻辑 ​

src/utils/swarm/backends/registry.ts 的 detectAndGetBackend() 实现了一套"优雅降级"逻辑，自动选择当前环境中最合适的执行后端：

5. 核心通信机制：文件邮箱协议 ​

Claude Code 选择了一个看起来"朴素"但极为可靠的通信方案——基于 JSON 文件 + 文件锁的邮箱系统。

5.1 邮箱的物理结构 ​

每个 Agent 拥有一个专属的 JSON 邮箱文件：

~/.claude/teams/{team_name}/inboxes/{agent_name}.json

消息的数据结构非常简洁：

// src/utils/teammateMailbox.ts（1,183 行）
type TeammateMessage = {
  from: string       // 发送者名称
  text: string       // 消息正文
  timestamp: string  // ISO 时间戳
  read: boolean      // 是否已读（轮询时过滤未读）
  color?: string     // 发送者 UI 颜色（用于终端着色）
  summary?: string   // 5-10 字摘要（用于 Coordinator 跟踪进度）
}

5.2 核心操作：原子写入与文件锁 ​

proper-lockfile 的重试退避策略（5-100ms 随机抖动）可以有效避免多个 Worker 同时写入时的"惊群效应"——这是分布式系统的经典技巧，只不过在本地文件系统上实现。

5.3 结构化消息类型：不只是传文字 ​

邮箱不仅承载文本消息，还定义了一套完整的协议消息类型，用于 Agent 间的行为协调：

5.4 SendMessage Tool：智能消息路由 ​

src/tools/SendMessageTool/SendMessageTool.ts（917 行）是 Agent 主动发消息的唯一工具。它的路由逻辑根据接收者的类型和状态，选择不同的通道：

SendMessage.call() (line 741)
  ├── to: "bridge:<session-id>" → postInterClaudeMessage（跨机器 Remote Control）
  ├── to: "uds:<socket>"        → sendToUdsSocket（Unix Domain Socket 本地跨session）
  ├── to: "*"                   → 广播到所有团队成员邮箱
  └── to: "<agent-name>"       → 查 agentNameRegistry：
        ├── InProcess 运行中    → queuePendingMessage（内存队列，零文件 I/O）
        ├── InProcess 已停止    → resumeAgentBackground（自动唤醒！）
        └── Pane Agent         → writeToMailbox（文件邮箱）

这里有一个精妙的设计：Agent 的纯文本输出对其他 Agent 不可见——子 Agent 在终端打印的内容只给人类用户看，Agent 间的通信必须通过 SendMessage 显式发送。这个设计避免了消息的意外泄漏和误读。

6. 权限委托：无论多少层嵌套，人类始终掌控 ​

多 Agent 系统最大的安全风险是"权限漂移"——层层委托的过程中，权限可能被无限放大。Claude Code 用一套清晰的委托架构彻底解决了这个问题。

6.1 权限委托的完整流程 ​

src/utils/swarm/permissionSync.ts（928 行）定义了权限在 Leader 和 Worker 之间的传递规则：

6.2 多层工具过滤：白名单与黑名单并用 ​

filterToolsForAgent()（agentToolUtils.ts:70）为不同类型的 Agent 维护不同的工具过滤规则：

7. Worker 完整生命周期：诞生、执行、通信、终止 ​

7.1 Worker 诞生：InProcess vs Pane 的不同路径 ​

关键设计：InProcess Worker 的 AbortController 刻意不链接到 Leader 的 Controller。这意味着用户按下 Ctrl+C 中断 Leader 的当前查询时，Worker 不会被意外杀死——它们会继续完成自己的子任务。只有明确调用 killInProcessTeammate() 才会终止 Worker。

7.2 执行核心：query() 循环的递归复用 ​

src/tools/AgentTool/runAgent.ts（973 行）的 runAgent() 函数揭示了 Claude Code 最核心的设计理念：

runAgent() 完整执行流程:
  1. getAgentModel()         → 解析 Agent 的模型配置
  2. createSubagentContext() → 隔离的消息上下文（fork 父消息）
  3. initializeAgentMcpServers() → 初始化 Agent 专属的 MCP servers
  4. resolveAgentTools()     → 过滤并构建可用工具集
  5. 构建系统提示词          → Agent 角色提示 + 环境信息
  6. 注册 Perfetto 追踪      → 性能分析 hooks
  7. 调用 query()            ← 与主 REPL 完全相同的 agentic 循环！
  8. yield 消息流            → 将每条消息传回父 Agent
  9. 清理资源                → MCP servers、shell tasks、agent tracking

7.3 Worker 通信矩阵 ​

7.4 Worker 终止：三条退出路径 ​

8. Coordinator Mode：四阶段自动编排 ​

Coordinator Mode 是源码泄露中最引人注目的未发布功能之一，代表了 Anthropic 对"全自动多 Agent 编排"的完整答案。

8.1 激活方式与工具限制 ​

// src/coordinator/coordinatorMode.ts（369 行）
function isCoordinatorMode(): boolean {
  // 需要编译时 feature gate + 运行时环境变量双重激活
  return feature('COORDINATOR_MODE') && process.env.CLAUDE_CODE_COORDINATOR_MODE === '1'
}

Coordinator 被严格限制只能使用 3 个工具：

• Agent：派遣 Worker
• SendMessage：与 Worker 通信
• TaskStop：终止整个任务

这种"权力最小化"设计不是限制，而是职责边界的清晰界定——Coordinator 只负责编排决策，绝不直接操作文件系统或执行代码。

8.2 四阶段工作流 ​

9. Git Worktree 隔离：并行不冲突 ​

当多个 Worker 同时对同一个代码库进行修改时，最大的风险是文件冲突。Claude Code 通过 Git Worktree 机制从根本上消除了这个问题。

9.1 Worktree 创建流程 ​

Agent spawn 时设置 isolation='worktree'
  → 生成 slug: agent-{agentId 前8字符}
  → validateWorktreeSlug()   — 拒绝路径穿越攻击，限制64字符
  → 创建路径: .claude/worktrees/<slug>
  → 创建分支: worktree-<slug>
  → git worktree add -B worktree-<slug>
  → performPostCreationSetup():
      - 复制 settings.local.json（保留本地配置）
      - 配置 git hooks
      - 符号链接共享目录
      - 按 .worktreeinclude 复制 .gitignore 文件（如 .env、credentials）

9.2 Worktree 清理策略 ​

Agent 完成任务时，系统会检查 worktree 是否有实质性改动：

这套"按需保留"策略避免了两个极端：既不会因为自动清理而丢失 Agent 的实际成果，也不会让无用的 worktree 目录堆积占用磁盘空间。

10. Feature Gate 与未来路线图 ​

源码泄露中最令人兴奋的部分，是那些尚未发布、藏在 Feature Gate 后面的能力。

10.1 当前已发布的多 Agent 能力 ​

10.2 尚未发布的重量级功能 ​

11. 架构规模与设计理念 ​

11.1 代码规模分布 ​

11.2 六大核心设计理念 ​

1. query() 循环递归复用：子 Agent 使用与主 REPL 完全相同的 agentic 循环，天然具备任意深度嵌套的能力，整个系统的复杂性由一个递归实现支撑

2. AsyncLocalStorage 零开销隔离：InProcess 模式下，通过 Node.js 原生 API 实现上下文隔离，无需任何 IPC 机制，性能代价接近零

3. 文件邮箱统一通信：跨进程、跨后端使用同一套 JSON + 文件锁协议，牺牲极少的延迟换来零依赖、天然持久化和极强的可调试性

4. 权限始终由人类把控：无论多少层 Agent 嵌套，所有危险操作的最终裁决都路由到 Leader UI，用户意图永远优先于自动化效率

5. 优雅降级：后端选择遵循 iTerm2 → tmux → InProcess 的瀑布逻辑，在当前环境中自动选择最优可用方案，用户无需配置

6. Fire-and-forget 异步：后台 Agent 完成任务后，通过 <task-notification> XML 注入到父 Agent 的对话流，非侵入式、无需父 Agent 主动轮询

12. 总结 ​

参考资料 ​

核心文档 ​

相关论文 ​