Agent / Subagent / Swarm 解析：ClaudeCode源码深度解读

Claude Code 的多智能体系统由三个递进层级构成单次 Subagent轻量委托→Fork Subagent上下文克隆分身→Swarm / Team多进程协作群。它们共享同一个runAgent()核心但在隔离策略、通信方式和生命周期上各有不同。1. 三种模式一览特性普通 SubagentFork SubagentSwarm Teammate触发方式Agent(subagent_typeX)Agent()不带subagent_typeAgent(nameX, team_nameY)上下文继承空 / 只从 prompt 开始完整克隆父对话 工具结果独立进程仅通过 mailbox 通信运行位置父进程内sync/async父进程内后台异步子进程tmux/iTerm2或 in-processAbortControllersync: 共享父的; async: 独立独立独立不受领导者中断影响权限提示async: 自动拒绝; sync: 气泡到父bubble → 气泡到父终端通过 permissionSync 文件路由通信机制返回值 / Generator yield父 context 注入 返回值文件信箱mailboxsidechain 转录✅✅✅门控条件默认启用feature(FORK_SUBAGENT)isAgentSwarmsEnabled()2. Subagent普通子代理2.1 实体runAgent()异步生成器src/tools/AgentTool/runAgent.ts的核心是一个AsyncGenerator外部通过for await消费其输出消息实现流式透传。关键设计决策parent → AgentTool.call() ├── 构建 agentToolUseContext独立 AppState 视图 ├── resolveAgentTools() ← 按定义过滤工具集 ├── getAgentSystemPrompt() ← 专属系统提示词 ├── createSubagentContext() ← 上下文隔离 └── runAgent() → query() ← 流式游历 API 轮次 ↓ yield messages → agentToolUtils.runAsyncAgentLifecycle()权限模式继承规则优先级从高到低bypassPermissions/acceptEdits/auto— 父级总是赢子代理不可覆盖agentDefinition.permissionMode— 定义文件中的声明isAsynctrue→shouldAvoidPermissionPromptstrue不弹 UIcanShowPermissionPromptstrue→awaitAutomatedChecksBeforeDialogtrue先等自动化检查Claude.md 裁剪优化Explore / Plan 等只读代理默认剥除claudeMd省 ~5-15 Gtok/week和gitStatus节省上下文通过 GrowthBook 门控tengu_slim_subagent_claudemd。2.2 工具集解析resolveAgentTools()agentDefinition.tools: [*] → 继承父工具集 agentDefinition.tools: [Bash,Edit] → 精确子集 agentDefinition.tools: [!Bash] → 排除模式 useExactToolstrue → 完全跳过过滤fork 路径专用allowedTools参数在作用域上替换父级 session 权限保留 cliArg 层避免父级许可泄漏给子代理。2.3 生命周期 finally 清理runAgent()的finally块确保即使抛出 AbortError 也执行MCP 服务器关闭mcpCleanup()Session hooks 清理clearSessionHooks()Prompt cache 追踪状态清理文件状态缓存释放readFileState.clear()Todos 孤立条目删除后台 Bash 进程杀死killShellTasksForAgent()Perfetto trace 注销3. Fork Subagent分叉子代理3.1 设计理念Fork 是上下文克隆模式子代理不是从空白对话开始而是继承父对话的完整消息历史。核心思路是最大化利用父代理的prompt cache——子代理与父代理共享相同的 API 请求前缀命中缓存的概率极高。启用条件// 互斥约束不能与 coordinator 模式共用feature(FORK_SUBAGENT)!isCoordinatorMode()!isNonInteractiveSession()3.2 消息构建buildForkedMessages()父 AssistantMessage含所有 tool_use 块 ↓ clone [fullAssistantMessage] user 消息 [tool_result x N (全为 FORK_PLACEHOLDER)] ← 占位符让 API 认为工具已完成 text: fork_directive子任务说明/fork_directiveFORK_PLACEHOLDER_RESULT是固定字符串保证 cache 命中子代理看到的是已有工具结果和新指令。3.3useExactToolstrue稳定化Fork 模式传useExactToolstrue直接使用父工具池不经resolveAgentTools()过滤继承父的thinkingConfig思维链设置继承父的isNonInteractiveSession值目的让子代理的 API 请求前缀与父代理字节完全一致命中 server-side prompt cache3.4 递归 Fork 防护// 双重检查对抗 autocompact 改写消息后的 bypassif(toolUseContext.options.querySourceagent:builtin:${FORK_AGENT.agentType}||isInForkChild(toolUseContext.messages)){thrownewError(Fork is not available inside a forked worker.)}4. Swarm群集多代理4.1 架构概览Leader Processclaude REPL │ ├── TeamFile (.claude/teams/{team}/team.json) │ members: [{ agentId, agentName, color, backendType, paneId, ... }] │ ├── Mailbox (.claude/teams/{team}/inboxes/{agent_name}.json) │ 用于 peer DM、权限请求、shutdown、idle 通知 │ ├── Backend运行时自动选择 │ ├── tmux → 创建 tmux pane发 claude CLI 命令 │ ├── iterm2 → it2 split pane │ └── in-process → AsyncLocalStorage 隔离同进程运行 │ └── Leader Permission BridgeleaderPermissionBridge.ts module-level 全局 setter → 允许 in-process 队友使用 leader 的权限对话框4.2 后端选择策略registry.ts优先级从高到低tmux— 在 tmux 会话中且 tmux 可用iterm2— 在 iTerm2 中且it2CLI 已安装in-process— 兜底无终端分栏依赖选择结果在进程生命周期内固定缓存cachedBackend。4.3 TeamFile持久化团队状态路径~/.claude/teams/{team_name}/team.jsontypeTeamFile{leadAgentId:string// 唯一领导者members:TeamMember[]// 包含 paneId、backendType、agentIdhiddenPaneIds:PaneId[]// 支持 hide/showallowedPaths:TeamAllowedPath[]// 权限沙盒}写操作均通过lockfile序列化防止并发的多个 Claude 进程竞争写constLOCK_OPTIONS{retries:{retries:10,minTimeout:5,maxTimeout:100}}4.4 文件信箱Mailbox通信协议路径~/.claude/teams/{team}/inboxes/{agent_name}.json消息格式typeTeammateMessage{from:string// 发送者名称text:string// 消息内容timestamp:stringread:booleancolor?:string// 发送者颜色UI 显示用summary?:string// 5-10 字摘要预览用}消息类型teammateMailbox.ts消息类型方向用途peer_dm任意→任意SendMessageTool 的 DMpermission_requestworker→leader权限请求路由permission_responseleader→worker权限决策回传shutdown_requestleader→worker优雅关闭idle_notificationworker→leader完成通知sandbox_permission_request/responseworker↔leader沙盒权限写操作原子性通过lockfile包10 次重试 指数退避防止 N 个并发 Claude 进程同时写同一收件箱。4.5 权限同步机制permissionSync.tsWorker 遇到需要确认的工具调用 │ ├─ [in-process 路径] │ leader 的 ToolUseConfirm 队列内存 setter │ ← leaderPermissionBridge.getLeaderToolUseConfirmQueue() │ └─ [pane 路径] worker → writeToMailbox(leader, permission_request) │ leader 轮询检测 → UI 弹出确认对话框 │ leader → writeToMailbox(worker, permission_response) │ worker 轮询收到决策 → 继续 / 拒绝轮询间隔PERMISSION_POLL_INTERVAL_MS 500ms由useSwarmPermissionPollerhook 驱动。4.6 In-Process Teammate 隔离通过AsyncLocalStorage实现同进程内的上下文隔离spawnInProcessTeammate() ├── createAbortController() ← 独立中止不受领导者影响 ├── createTeammateContext() ← AsyncLocalStorage 上下文 ├── registerTask(taskState, setAppState) ← 在 AppState 中注册显示 └── startInProcessTeammate() ← runWithTeammateContext() 包裹 └── runAgent() 在隔离上下文中执行优点无需额外进程共享 API 连接和 MCP 服务器。缺点崩溃会影响主进程不支持从 in-process teammate 内部再派生后台代理限制“In-process teammates cannot spawn background agents”。5. Coordinator 模式COORDINATOR_MODE是另一套协调架构与 Fork 互斥CLAUDE_CODE_COORDINATOR_MODE1 → isCoordinatorMode() ├── getCoordinatorSystemPrompt() ← 专属系统提示词 ├── getCoordinatorUserContext() ← 专属用户上下文 ├── INTERNAL_WORKER_TOOLS ← 仅限内部工具集 └── 禁用 Fork subagent设计目标Coordinator 是轻量级调度者不直接执行工具而是向 worker 发任务与 Fork克隆并行策略相对。6. 通信流汇总┌─────────────────────────────────────────────────────────┐ │ Leader REPL │ │ ┌─────────────────────────────────────────────────┐ │ │ │ Mailbox Poller500ms 轮询 │ │ │ │ · 收取 peer_dm → 注入为 attachment 消息 │ │ │ │ · 收取 permission_request → 弹 UI 对话框 │ │ │ │ · 收取 idle_notification → Task 状态更新 │ │ │ └─────────────────────────────────────────────────┘ │ │ ↕ 内存信号 │ │ ┌──────────────────────────────────────────────────┐ │ │ │ In-Process TeammateAsyncLocalStorage 隔离 │ │ │ │ permission via leaderPermissionBridge (内存 fn) │ │ │ └──────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────┘ ↕ 文件 I/Omailbox lockfile ┌──────────────────────────────────────────────────────────┐ │ Pane Teammate独立进程 │ │ claude CLI 以环境变量指定 team/agent 信息 │ │ · CLAUDE_CODE_AGENT_ID / NAME / TEAM_NAME / COLOR │ │ · CLAUDE_CODE_LEADER_AGENT_ID │ └──────────────────────────────────────────────────────────┘7. 设计亮点7.1 Prompt Cache 最大化Fork 设计Fork 子代理通过useExactToolstrue 固定 placeholder result 确保 API 请求前缀与父代理字节完全一致最大化 server-side prompt cache 命中率。这是性能优化的核心。7.2 工具权限隔离allowedTools 替换语义parent session rules: [A, B, C] 子代理 allowedTools: [X, Y] → 子代理实际拥有: [cliArg rules, X, Y]父级 session 允许的工具不会自动泄漏给子代理必须显式传递。cliArg层SDK--allowedTools始终保留因为这是外部用户的显式意图。7.3 文件信箱 lockfile 并发安全多个 Claude 进程可同时写同一信箱通过lockfile的重试指数退避实现可靠串行化。比共享内存队列更健壮跨进程比数据库更轻量。7.4 Backend 抽象层TeammateExecutor接口interfaceTeammateExecutor{spawn(config:TeammateSpawnConfig):PromiseTeammateSpawnResultsendMessage(agentId,message):Promisevoidkill(agentId):Promisevoid}统一接口屏蔽 tmux / iTerm2 / in-process 差异注册模式registerTmuxBackend()避免循环依赖。7.5 sidechain 转录每个代理独立 JSONL每个子代理把消息写入subagents/{agentId}.jsonl支持会话恢复和调试查看且使用增量追加lastRecordedUuid游标不重写历史。7.6 Claude.md 精简读写代理分级优化只读代理Explore、Plan自动剥除 claudeMd 和 gitStatus节省大量 token。按agentDefinition.omitClaudeMd字段在代理定义文件中声明kill-switch 通过 GrowthBook 控制。8. 可直接复用的设计模式8.1 文件信箱Mailbox lockfile场景多进程 / 多 worker 异步通信且不想引入消息队列中间件。// 写序列化写带重试退避awaitlockfile.lock(path,opts)constmsgsJSON.parse(awaitreadFile(path))msgs.push(newMsg)awaitwriteFile(path,JSON.stringify(msgs))lockfile.unlock(path)// 读轮询 标记已读constmsgsreadMailbox(agentName)constunreadmsgs.filter(m!m.read)8.2 权限决策气泡bubble permission mode场景子任务需要弹 UI但希望对话框出现在主进程终端而非子进程。permissionMode: bubbleleaderPermissionBridgesetter 注册Pane 路径mailbox 双向路由8.3 AsyncLocalStorage 上下文隔离场景同进程并发运行多个租户每个租户有独立的 agentId、teamName、color 等上下文。constteammateContextnewAsyncLocalStorageTeammateContext()runWithTeammateContext(ctx,()runAgent(...))// 在任意调用深度取上下文getTeamName()→ teammateContext.getStore()?.teamName8.4 Generator 流式 终止信号asyncfunction*runAgent(...):AsyncGeneratorMessage{constcontrollerisAsync?newAbortController():parent.abortControllerforawait(constmsgofquery({signal:controller.signal})){yieldmsg// 流式透传}if(controller.signal.aborted)thrownewAbortError()}消费方调用break即可中止不需要手动清理——finally块统一清理。8.5 懒加载工具 SchemalazySchema()constinputSchemalazySchema(()z.object({...}))// 首次访问时才构建 Zod schema配合 feature() 门控避免在模块加载阶段就执行条件feature()检查build-time DCE 友好。8.6 Backend 注册模式避免循环依赖// registry.tsletTmuxBackendClass:(new()PaneBackend)|nullnullexportfunctionregisterTmuxBackend(cls:new()PaneBackend){TmuxBackendClasscls}// TmuxBackend.ts在模块末尾registerTmuxBackend(TmuxBackend)Backend 实现文件负责向 registry 注册自己registry 不直接 import 实现打破循环依赖。9. 源码索引职责文件Agent 工具入口src/tools/AgentTool/AgentTool.tsx子代理运行核心src/tools/AgentTool/runAgent.tsFork 消息构建src/tools/AgentTool/forkSubagent.tsTeamFile 锁src/utils/swarm/teamHelpers.ts权限同步src/utils/swarm/permissionSync.ts领导者权限桥src/utils/swarm/leaderPermissionBridge.tsIn-process 运行器src/utils/swarm/inProcessRunner.tsIn-process 生成src/utils/swarm/spawnInProcess.ts文件信箱src/utils/teammateMailbox.ts内存信箱src/utils/mailbox.ts后端接口src/utils/swarm/backends/types.ts后端注册表src/utils/swarm/backends/registry.tsSwarm 门控src/utils/agentSwarmsEnabled.tsCoordinator 模式src/coordinator/coordinatorMode.ts通信时序图agent-swarm-communication.puml