Claude Code 多 Agent 系统 — 实现原理

深入剖析多 Agent 编排的架构设计、生成流程、上下文传递和协作机制。

架构总览 · 生成流程 · 工具池系统 · 上下文传递 · Teams 内部机制 · 后台任务引擎 · DreamTask · Worktree 隔离 · 权限同步 · 生命周期数据流 · 源文件索引 · Feature Flags

实现架构总览

一、架构总览

Claude Code 的多 Agent 系统由以下核心模块组成：

5 大核心模块

模块	职责	关键文件
Agent Tool	主入口，路由分发，参数解析	`src/tools/AgentTool/AgentTool.tsx`
执行引擎	Agent 生命周期管理，查询循环	`src/tools/AgentTool/runAgent.ts`
上下文管理	系统提示词构建，缓存安全参数	`src/utils/forkedAgent.ts`
任务系统	状态追踪，进度更新，通知队列	`src/tasks/LocalAgentTask/`
Swarm 基础设施	团队管理，邮箱通信，权限同步	`src/utils/swarm/`

5 大 Agent 类别

┌─────────────────────────────────────────────────┐
│                  Agent Tool                      │
│              (入口 & 路由分发)                    │
├───────────┬───────────┬───────────┬─────────────┤
│  Subagent │  Fork     │ Teammate  │   Remote    │
│  (子代理)  │ (分叉)    │ (队友)    │   (远程)    │
│           │           │           │             │
│ 独立上下文 │ 继承上下文 │ 团队协作   │ CCR 环境   │
│ 按类型过滤 │ 缓存共享   │ 邮箱通信   │ 远程执行   │
│ 工具池     │ 字节一致   │ 权限同步   │ 轮询结果   │
└───────────┴───────────┴───────────┴─────────────┘
                        │
                  ┌─────┴─────┐
                  │ DreamTask │
                  │ (记忆整合)  │
                  │ 定时后台   │
                  └───────────┘

二、Agent 生成流程 — 四条路径

入口：`AgentTool.call()`

src/tools/AgentTool/AgentTool.tsx 中的 call() 函数是所有 Agent 生成的入口。根据输入参数，路由到四条不同的生成路径：

AgentTool.call(input)
  │
  ├─ team_name + name? ──────→ 路径1: spawnTeammate()
  │
  ├─ run_in_background?  ────→ 路径2: registerAsyncAgent()
  │     └─ agent.background?
  │
  ├─ 省略 subagent_type? ───→ 路径3: Fork (buildForkedMessages())
  │     └─ fork 实验开启?
  │
  └─ 默认 ───────────────────→ 路径4: runAgent() 同步执行

路径 1：Teammate 生成

触发条件：team_name 和 name 同时存在

入口函数：spawnTeammate() — src/tools/shared/spawnMultiAgent.ts

流程：

检测执行后端（tmux / iTerm2 / in-process）
为队友生成唯一 agentId：formatAgentId(name, teamName)
分配颜色（从预定义调色板）
创建执行环境：
- in-process：通过 spawnInProcessTeammate() 在同进程中启动
- tmux：通过 TmuxBackend 创建新 pane
- iTerm2：通过 ITerm2Backend 创建新窗口
写入 TeamFile 成员列表
返回 TeammateSpawnedOutput（包含 pane ID、agent ID 等）

In-Process 队友的隔离：

typescript

// src/utils/swarm/spawnInProcess.ts
export async function spawnInProcessTeammate(config, context) {
  // 1. 独立的 AbortController（不随 leader 中断）
  const abortController = new AbortController()
  
  // 2. AsyncLocalStorage 上下文隔离
  runWithTeammateContext(teammateContext, async () => {
    // 3. 独立的任务状态
    // 4. 独立的消息循环
    // 5. 共享的权限管道（通过 mailbox）
  })
}

路径 2：异步 Subagent

触发条件：run_in_background=true 或 Agent 定义中 background: true

流程：

registerAsyncAgent()
  │
  ├─ 创建 LocalAgentTask（status: 'running'）
  ├─ 注册到 agentNameRegistry（如有 name）
  ├─ 创建输出文件符号链接
  ├─ 创建 AbortController（链接到父代理）
  ├─ 发射 SDK event: task_started
  │
  └─ void runAsyncAgentLifecycle()  ← 异步分离执行
       │
       ├─ 创建 ProgressTracker
       ├─ 遍历 makeStream() 生成器
       │   ├─ 追加消息到 agentMessages[]
       │   ├─ 更新进度（tokens、tools、activities）
       │   └─ 发射 SDK progress events
       │
       └─ 完成时：
           ├─ finalizeAgentTool()（提取结果）
           ├─ completeAgentTask()（标记完成）
           ├─ 清理 worktree（如有隔离）
           └─ enqueuePendingNotification()（通知主代理）

关键实现：src/tools/AgentTool/agentToolUtils.ts — runAsyncAgentLifecycle()

路径 3：Fork Subagent

触发条件：省略 subagent_type 且 Fork 实验开启

核心优化：通过字节级一致的 API 请求前缀，实现 prompt cache 命中。

Fork 缓存优化

流程：

buildForkedMessages(directive, assistantMessage)
  │
  ├─ 保留父代理完整的 assistant message（所有 tool_use 块）
  ├─ 构建 user message：
  │   ├─ 对每个 tool_use 创建占位 tool_result（字节一致）
  │   └─ 追加 per-child directive（唯一差异部分）
  │
  └─ 结果：字节级一致的 API 前缀 → prompt cache 命中！

Fork 子代理的行为约束（通过 FORK_BOILERPLATE_TAG 注入）：

1. 你是分叉的工作进程，不是主代理
2. 不要对话、提问或建议后续步骤
3. 直接使用工具（Bash、Read、Write 等）
4. 如修改文件，在报告前提交更改
5. 工具调用之间不要输出文本
6. 严格限制在指令范围内
7. 报告控制在 500 词以内
8. 响应必须以 "Scope:" 开头

防递归保护：isInForkChild() 检测是否在 fork 子进程中，防止嵌套 fork。

路径 4：同步 Subagent

触发条件：默认路径（无 team_name、无 background、非 fork）

流程：

runAgent(promptMessages, toolUseContext, options)
  │
  ├─ 解析 Agent 定义（getSystemPrompt、tools、permissions）
  ├─ 构建系统提示词（buildEffectiveSystemPrompt）
  ├─ 创建隔离的 ToolUseContext（createSubagentContext）
  ├─ 启动查询循环（query() async generator）
  │   ├─ 发送 API 请求
  │   ├─ 处理流式事件
  │   ├─ 执行工具调用
  │   └─ 累积消息和 usage
  │
  └─ 返回 AgentToolResult
       ├─ content: 最后 assistant 消息的文本
       ├─ totalToolUseCount
       ├─ totalDurationMs
       └─ totalTokens

三、工具池系统 — 三层过滤

工具池系统

第一层：全局禁止

ALL_AGENT_DISALLOWED_TOOLS — 对所有 Agent 禁止的工具：

工具	禁止原因
TaskOutput	仅主代理可读取任务输出
ExitPlanMode	仅主代理可退出计划模式
EnterPlanMode	仅主代理可进入计划模式
AskUserQuestion	子代理不应直接问用户
TaskStop	仅主代理可终止任务
Agent	防止递归生成（Ant 内部例外）

第二层：Agent 类型过滤

filterToolsForAgent() — 基于 Agent 类型的工具过滤：

typescript

// src/tools/AgentTool/agentToolUtils.ts
function filterToolsForAgent(tools, agentDef) {
  // 1. 移除 ALL_AGENT_DISALLOWED_TOOLS
  // 2. 如果非内置 Agent，额外移除 CUSTOM_AGENT_DISALLOWED_TOOLS
  // 3. 如果是异步 Agent，限制为 ASYNC_AGENT_ALLOWED_TOOLS
  // 4. MCP 工具始终允许
}

ASYNC_AGENT_ALLOWED_TOOLS（15 个）：

Read, WebSearch, TodoWrite, Grep, WebFetch, Glob,
Bash/PowerShell, FileEdit, FileWrite, NotebookEdit,
Skill, SyntheticOutput, ToolSearch, EnterWorktree, ExitWorktree

第三层：Agent 定义过滤

resolveAgentTools() — 基于 Agent 定义的工具解析：

typescript

function resolveAgentTools(agentDef, availableTools) {
  if (tools === ['*'] || undefined)  → 通配符，全部允许
  if (tools === ['Read', 'Grep'])    → 仅允许列表中的工具
  if (disallowedTools === ['Agent']) → 从可用工具中减去
}

过滤流程图：

所有可用工具
  │
  ├─ 减去 ALL_AGENT_DISALLOWED_TOOLS ──→ 通用禁止
  │
  ├─ 非内置？减去 CUSTOM_AGENT_DISALLOWED_TOOLS ──→ 自定义限制
  │
  ├─ 异步？限制为 ASYNC_AGENT_ALLOWED_TOOLS ──→ 异步白名单
  │
  ├─ 有 tools 列表？取交集 ──→ Agent 白名单
  │
  ├─ 有 disallowedTools？取差集 ──→ Agent 黑名单
  │
  └─ 最终工具池

四、上下文传递机制

上下文传递

CacheSafeParams — 缓存安全参数

typescript

// src/utils/forkedAgent.ts
export type CacheSafeParams = {
  systemPrompt: SystemPrompt       // 系统提示词
  userContext: { [k: string]: string }  // 目录结构、CLAUDE.md 等
  systemContext: { [k: string]: string } // git status、环境信息
  toolUseContext: ToolUseContext    // 工具配置、模型、选项
  forkContextMessages: Message[]   // Fork 上下文消息（用于缓存共享）
}

缓存共享原理：

Fork Agent 通过保持 API 请求前缀字节级一致来复用 prompt cache：

┌─────────────────────────────────────────┐
│         共享前缀（字节一致）              │
│  ┌──────────────────────────────────┐   │
│  │ System Prompt                    │   │
│  │ User Context                     │   │
│  │ System Context                   │   │
│  │ Tool Use Context                 │   │
│  │ 对话历史 Messages                │   │
│  │ Assistant Message (all tool_use) │   │
│  │ User Message (placeholder results│)  │
│  └──────────────────────────────────┘   │
├─────────────────────────────────────────┤
│  唯一差异：per-child directive text      │
└─────────────────────────────────────────┘

系统提示词构建

buildEffectiveSystemPrompt() — src/utils/systemPrompt.ts

优先级链（从高到低）：

Override System Prompt     ← 最高优先级，完全替换
  ↓
Coordinator System Prompt  ← 协调器模式专用
  ↓
Agent System Prompt        ← agentDefinition.getSystemPrompt()
  ↓                          - proactive 模式：追加到默认
  ↓                          - 其他：替换默认
Custom System Prompt       ← --system-prompt 参数
  ↓
Default System Prompt      ← Claude Code 标准提示词
  ↓
Append System Prompt       ← 追加到末尾

Agent 特有的系统提示词增强：

typescript

// src/tools/AgentTool/runAgent.ts
function getAgentSystemPrompt(agentDef, toolUseContext) {
  let prompt = agentDef.getSystemPrompt({ toolUseContext })
  prompt = enhanceSystemPromptWithEnvDetails(prompt)
  // 添加：工作目录、启用工具列表、模型信息、环境变量
  return prompt
}

SubagentContext — 子代理上下文隔离

typescript

// src/utils/forkedAgent.ts
export type SubagentContextOverrides = {
  options?: ToolUseContext['options']           // 自定义工具、模型
  agentId?: AgentId                            // 子代理 ID
  agentType?: string                           // Agent 类型
  messages?: Message[]                         // 自定义消息历史
  readFileState?: ToolUseContext['readFileState'] // 文件读取缓存
  abortController?: AbortController            // 中止控制器

  // 显式 opt-in 共享（默认隔离）
  shareSetAppState?: boolean                   // 共享 AppState 写入
  shareSetResponseLength?: boolean             // 共享响应长度度量
  shareAbortController?: boolean               // 共享中止控制器

  // 实验性注入
  criticalSystemReminder_EXPERIMENTAL?: string // 每轮重新注入的提醒
  contentReplacementState?: ContentReplacementState
}

隔离 vs 共享：

资源	默认	说明
readFileState	克隆	文件读取缓存独立
messages	新建	消息历史独立
abortController	新建（链接父）	父取消时子也取消
setAppState	No-op	默认不影响父状态
contentReplacementState	克隆	内容替换状态独立

模型解析

getAgentModel() — src/utils/model/agent.ts

优先级链：

CLAUDE_CODE_SUBAGENT_MODEL 环境变量  ← 最高
  ↓
Agent({ model: 'opus' }) 参数       ← 工具指定
  ↓
agentDefinition.model               ← Agent 定义
  ↓
'inherit'                           ← 继承父代理模型

五、Agent Teams 内部机制

TeamFile 结构

typescript

// 存储路径：~/.claude/teams/{team_name}/config.json
{
  name: string                        // 团队名称
  description?: string                // 团队描述
  createdAt: number                   // 创建时间戳
  leadAgentId: string                 // Team Lead 的 Agent ID
  leadSessionId?: string              // Lead 的会话 UUID
  hiddenPaneIds?: string[]            // UI 中隐藏的 pane
  teamAllowedPaths?: TeamAllowedPath[] // 团队级共享权限
  members: Array<{
    agentId: string                   // 成员 Agent ID
    name: string                      // 显示名称
    agentType?: string                // 角色类型
    model?: string                    // 使用的模型
    prompt?: string                   // 初始任务
    color?: string                    // UI 颜色
    planModeRequired?: boolean        // 是否需要 plan 审批
    joinedAt: number                  // 加入时间
    tmuxPaneId: string                // 终端 pane ID
    cwd: string                       // 工作目录
    worktreePath?: string             // Worktree 路径
    sessionId?: string                // 会话 ID
    subscriptions: string[]           // 消息订阅
    backendType?: 'tmux'|'iterm2'|'in-process'
    isActive?: boolean                // false=空闲, true/undefined=活跃
    mode?: PermissionMode             // 当前权限模式
  }>
}

邮箱系统

Teams 邮箱系统

存储路径：~/.claude/teams/{team_name}/inboxes/{agent_name}.json

typescript

// src/utils/teammateMailbox.ts
type TeammateMessage = {
  from: string        // 发送者名称
  text: string        // 消息内容（纯文本或 JSON）
  timestamp: string   // ISO 时间戳
  read: boolean       // 是否已读
  color?: string      // 发送者颜色
  summary?: string    // 5-10 词摘要
}

并发安全：使用 proper-lockfile 文件锁，10 次重试，5-100ms 指数退避。

消息类型：

消息	格式	用途
纯文本	`string`	普通对话消息
shutdown_request	`{ type, reason }`	请求队友关停
shutdown_response	`{ type, request_id, approve }`	批准/拒绝关停
plan_approval_response	`{ type, request_id, approve }`	审批 plan
permission_request	`{ type, toolName, path }`	权限请求
idle_notification	特殊格式	空闲通知

收件箱轮询

typescript

// src/hooks/useInboxPoller.ts
// 轮询间隔：1000ms

useEffect(() => {
  const interval = setInterval(async () => {
    const messages = await readUnreadMessages(agentName, teamName)
    
    for (const msg of messages) {
      if (isShutdownRequest(msg.text)) {
        // 处理关停请求
      } else if (isPlanApprovalResponse(msg.text)) {
        // 处理 plan 审批
      } else if (isPermissionRequest(msg.text)) {
        // 路由到权限系统
      } else {
        // 纯文本消息 → 提交为新对话轮
        onSubmitMessage(formatted)
      }
    }
  }, INBOX_POLL_INTERVAL_MS)
}, [])

消息处理状态：

状态	说明
`pending`	新收到，等待处理
`processing`	正在处理（权限请求等）
`processed`	已处理完毕

消息路由

SendMessage({ to, message })
  │
  ├─ to === "*" → 广播
  │   └─ 遍历所有队友，逐个写入 mailbox
  │
  ├─ agentNameRegistry.has(to) → in-process 子代理
  │   └─ 通过 AppState pending messages 队列路由
  │
  ├─ teamFile.members.find(to) → 进程级队友
  │   └─ writeToMailbox(to, message, teamName)
  │
  ├─ to.startsWith("bridge:") → 远程会话
  │   └─ postInterClaudeMessage(sessionId, message)
  │
  └─ to.startsWith("uds:") → Unix Domain Socket
      └─ sendToUdsSocket(socketPath, message)

六、后台任务引擎

后台任务引擎

LocalAgentTask 状态机

typescript

// src/tasks/LocalAgentTask/LocalAgentTask.tsx
type LocalAgentTaskState = {
  type: 'local_agent'
  agentId: AgentId                // 唯一标识
  status: 'running' | 'completed' | 'failed' | 'killed'
  isBackgrounded: boolean         // 前台 vs 后台
  
  progress: {
    latestInputTokens: number     // 最新输入 tokens
    cumulativeOutputTokens: number // 累计输出 tokens
    toolUseCount: number          // 工具使用次数
    recentActivities: ToolActivity[] // 最近 5 个活动
    lastActivity: number          // 最后活动时间戳
  }
  
  result?: AgentToolResult        // 最终结果
  abortController: AbortController // 中止控制器
  retain: boolean                 // UI 保持标志
  evictAfter?: number             // 延迟清除时间戳
}

状态转换：

              ┌──────────────────────────┐
              │                          │
  register    │    ┌──── killed ←── abort()
    │         │    │
    ▼         │    │
 running ─────┼────┼──── completed ← finalizeAgentTool()
              │    │
              │    └──── failed ← error / timeout
              │
              └──── evict ← notified && endTime > grace

进度追踪

typescript

// ProgressTracker
function updateProgressFromMessage(tracker, message) {
  // 1. 累积输入 tokens（取最新值）
  tracker.latestInputTokens = message.usage?.input_tokens
  
  // 2. 累加输出 tokens
  tracker.cumulativeOutputTokens += message.usage?.output_tokens
  
  // 3. 统计工具使用
  tracker.toolUseCount += countToolUses(message)
  
  // 4. 维护最近活动（循环缓冲区，max 5）
  tracker.recentActivities = [...activities].slice(-5)
}

通知系统

typescript

// src/utils/messageQueueManager.ts
function enqueuePendingNotification(taskId, result) {
  // 1. 原子设置 notified 标志（防重复）
  if (task.notified) return
  task.notified = true
  
  // 2. 格式化 XML 通知
  const notification = `
    <task-notification>
      <task-id>${taskId}</task-id>
      <status>${status}</status>
      <summary>${summary}</summary>
      <output-file>${outputPath}</output-file>
    </task-notification>
  `
  
  // 3. 入队等待主代理消费
  pendingNotifications.push(notification)
}

输出管理

存储路径：~/.claude/temp/{sessionId}/tasks/{taskId}.output

参数	值
最大容量	5GB / 文件
循环缓冲区	1000 行
轮询间隔	1 秒
终态保持时间	3 秒（任务面板 30 秒）
写入方式	队列异步写入，防内存堆积
安全措施	O_NOFOLLOW 防符号链接攻击

七、DreamTask — 自动记忆整合

DreamTask 是特殊的后台 Agent，用于跨会话记忆整合。

触发条件

typescript

// src/services/autoDream/autoDream.ts
function executeAutoDream() {
  // 四重门控：
  if (hoursSinceLastConsolidation < minHours) return  // 时间门：默认 24h
  if (sessionsSinceLastConsolidation < minSessions) return // 会话门：默认 5 次
  if (otherProcessConsolidating) return               // 锁门：互斥
  if (timeSinceLastScan < 10min) return               // 扫描节流：10 分钟
}

DreamTask 状态

typescript

type DreamTaskState = {
  type: 'dream'
  phase: 'starting' | 'updating'  // updating = 已开始编辑文件
  sessionsReviewing: number       // 正在审查的会话数
  filesTouched: string[]          // 编辑过的文件路径
  turns: DreamTurn[]              // 对话轮次记录
}

八、Worktree 隔离实现

创建流程

typescript

// src/utils/worktree.ts
async function createAgentWorktree(slug) {
  // 1. 校验 slug（防目录逃逸攻击）
  validateWorktreeSlug(slug)
  
  // 2. 创建 git worktree
  git worktree add {path} -b {branch}
  
  // 3. 符号链接大目录（节省磁盘）
  symlink(node_modules, worktree/node_modules)
  
  // 4. 应用 sparse-checkout（如配置）
  if (sparseCheckoutPaths) {
    git sparse-checkout set {paths}
  }
  
  // 5. 返回 WorktreeSession
  return { worktreePath, worktreeBranch, headCommit }
}

清理机制

Agent 完成后自动检测是否有改动（hasWorktreeChanges()）
有改动：返回 worktree 路径和分支名给用户
无改动：自动删除 worktree（removeAgentWorktree()）
异常退出：通过 registerTeamForSessionCleanup() 确保清理

九、权限同步机制

团队级权限

typescript

type TeamAllowedPath = {
  path: string        // 绝对目录路径
  toolName: string    // 适用的工具（如 "Edit", "Write"）
  addedBy: string     // 添加者名称
  addedAt: number     // 添加时间
}

队友启动时，自动继承团队级权限规则。

Bubble 模式

Fork Agent 使用 bubble 权限模式 — 权限提示冒泡到父代理终端：

Fork Agent 需要权限
  │
  └─ bubble 模式 → 权限请求发送到父代理
       │
       └─ 父代理的 ToolUseConfirm 对话框显示
            │
            ├─ 用户批准 → 结果回传给 Fork Agent
            └─ 用户拒绝 → Fork Agent 收到拒绝

In-Process 队友权限

队友需要权限
  │
  ├─ 有 UI bridge → 直接显示在 Leader 的确认对话框
  │     └─ 带 worker badge 标识来源
  │
  └─ 无 UI bridge → 通过 mailbox 排队
        └─ Leader 的 useSwarmPermissionPoller 处理

十、Agent 生命周期完整数据流

1. 用户触发 Agent Tool
   │
2. AgentTool.call() 路由分发
   │
3. 解析 Agent 定义
   ├─ 查找 Agent 类型（内置 > 插件 > 用户 > 项目）
   ├─ 加载系统提示词
   ├─ 解析工具池（三层过滤）
   └─ 确定权限模式和模型
   │
4. 创建隔离上下文
   ├─ createSubagentContext()（克隆 readFileState）
   ├─ 生成 agentId
   ├─ 创建 AbortController
   └─ 可选：创建 worktree
   │
5. 注册任务状态
   ├─ registerAsyncAgent() 或 registerAgentForeground()
   ├─ 发射 SDK event: task_started
   └─ Perfetto trace 注册
   │
6. 执行查询循环
   ├─ query() async generator
   │   ├─ 构建 API 请求（含 CacheSafeParams）
   │   ├─ 流式处理响应
   │   ├─ 执行工具调用
   │   └─ 累积 usage 指标
   ├─ 更新进度（ProgressTracker）
   └─ 记录 transcript
   │
7. 完成处理
   ├─ finalizeAgentTool()（提取结果文本）
   ├─ completeAgentTask()（标记完成）
   ├─ 清理资源
   │   ├─ 释放文件状态缓存
   │   ├─ 关闭 MCP 连接
   │   └─ 删除 worktree（如有）
   ├─ enqueuePendingNotification()（通知主代理）
   └─ 发射 SDK event: task_completed
   │
8. 主代理消费结果
   ├─ 同步：直接获取 AgentToolResult
   └─ 异步：收到 <task-notification> 后处理

十一、关键源文件索引

Agent Tool 核心

文件	职责
`src/tools/AgentTool/AgentTool.tsx`	主工具实现，路由分发
`src/tools/AgentTool/runAgent.ts`	执行引擎，查询循环
`src/tools/AgentTool/agentToolUtils.ts`	工具池解析，结果终结
`src/tools/AgentTool/forkSubagent.ts`	Fork 语义，消息继承
`src/tools/AgentTool/loadAgentsDir.ts`	Agent 定义类型，解析加载
`src/tools/AgentTool/builtInAgents.ts`	内置 Agent 注册表
`src/tools/AgentTool/prompt.ts`	Agent 工具 schema 和文档
`src/tools/AgentTool/agentMemory.ts`	Agent 持久记忆

Swarm 基础设施

文件	职责
`src/tools/TeamCreateTool/TeamCreateTool.ts`	团队创建
`src/tools/TeamDeleteTool/TeamDeleteTool.ts`	团队清理
`src/tools/SendMessageTool/SendMessageTool.ts`	代理间通信
`src/tools/shared/spawnMultiAgent.ts`	队友生成入口
`src/utils/swarm/spawnInProcess.ts`	进程内队友生成
`src/utils/swarm/teamHelpers.ts`	团队文件读写
`src/utils/swarm/constants.ts`	常量定义
`src/utils/swarm/teammateInit.ts`	队友初始化
`src/utils/swarm/permissionSync.ts`	权限同步
`src/utils/teammate.ts`	队友身份解析
`src/utils/teammateMailbox.ts`	邮箱消息队列
`src/utils/teamDiscovery.ts`	团队发现
`src/hooks/useInboxPoller.ts`	收件箱轮询

上下文管理

文件	职责
`src/utils/forkedAgent.ts`	缓存安全参数，子代理上下文
`src/utils/systemPrompt.ts`	系统提示词优先级构建
`src/utils/model/agent.ts`	Agent 模型解析
`src/utils/worktree.ts`	Git worktree 隔离

任务系统

文件	职责
`src/tasks/LocalAgentTask/LocalAgentTask.tsx`	本地 Agent 任务
`src/tasks/RemoteAgentTask/RemoteAgentTask.tsx`	远程 Agent 任务
`src/tasks/InProcessTeammateTask/`	进程内队友任务
`src/tasks/DreamTask/DreamTask.ts`	记忆整合任务
`src/utils/task/framework.ts`	任务注册、状态更新
`src/utils/task/diskOutput.ts`	任务输出文件管理
`src/utils/messageQueueManager.ts`	通知队列

协调器

文件	职责
`src/coordinator/coordinatorMode.ts`	协调器模式配置

十二、Feature Flags

Flag	控制内容
`FORK_SUBAGENT`	启用 Fork 路径（省略 subagent_type）
`BUILTIN_EXPLORE_PLAN_AGENTS`	启用 Explore/Plan Agent
`VERIFICATION_AGENT`	启用 verification Agent
`COORDINATOR_MODE`	启用协调器模式
`KAIROS`	启用 cwd 参数
`tengu_auto_background_agents`	120 秒后自动后台化
`tengu_slim_subagent_claudemd`	只读 Agent 省略 CLAUDE.md
`tengu_agent_list_attach`	Agent 列表通过 attachment 注入

Claude Code 多 Agent 系统 — 实现原理 ​

一、架构总览 ​

5 大核心模块 ​

5 大 Agent 类别 ​

二、Agent 生成流程 — 四条路径 ​

入口：AgentTool.call() ​

路径 1：Teammate 生成 ​

路径 2：异步 Subagent ​

路径 3：Fork Subagent ​

路径 4：同步 Subagent ​

三、工具池系统 — 三层过滤 ​

第一层：全局禁止 ​

第二层：Agent 类型过滤 ​

第三层：Agent 定义过滤 ​

四、上下文传递机制 ​

CacheSafeParams — 缓存安全参数 ​

系统提示词构建 ​

SubagentContext — 子代理上下文隔离 ​

模型解析 ​

五、Agent Teams 内部机制 ​

TeamFile 结构 ​

邮箱系统 ​

收件箱轮询 ​

消息路由 ​

六、后台任务引擎 ​

LocalAgentTask 状态机 ​

进度追踪 ​

通知系统 ​

输出管理 ​

七、DreamTask — 自动记忆整合 ​

触发条件 ​

DreamTask 状态 ​

八、Worktree 隔离实现 ​

创建流程 ​

清理机制 ​

九、权限同步机制 ​

团队级权限 ​

Bubble 模式 ​

In-Process 队友权限 ​

十、Agent 生命周期完整数据流 ​

十一、关键源文件索引 ​

Agent Tool 核心 ​

Swarm 基础设施 ​

上下文管理 ​

任务系统 ​

协调器 ​

十二、Feature Flags ​

Claude Code 多 Agent 系统 — 实现原理

一、架构总览

5 大核心模块

5 大 Agent 类别

二、Agent 生成流程 — 四条路径

入口：`AgentTool.call()`

路径 1：Teammate 生成

路径 2：异步 Subagent

路径 3：Fork Subagent

路径 4：同步 Subagent

三、工具池系统 — 三层过滤

第一层：全局禁止

第二层：Agent 类型过滤

第三层：Agent 定义过滤

四、上下文传递机制

CacheSafeParams — 缓存安全参数

系统提示词构建

SubagentContext — 子代理上下文隔离

模型解析

五、Agent Teams 内部机制

TeamFile 结构

邮箱系统

收件箱轮询

消息路由

六、后台任务引擎

LocalAgentTask 状态机

进度追踪

通知系统

输出管理

七、DreamTask — 自动记忆整合

触发条件

DreamTask 状态

八、Worktree 隔离实现

创建流程

清理机制

九、权限同步机制

团队级权限

Bubble 模式

In-Process 队友权限

十、Agent 生命周期完整数据流

十一、关键源文件索引

Agent Tool 核心

Swarm 基础设施

上下文管理

任务系统

协调器

十二、Feature Flags