Claude code源码精读之复杂任务处理机制分析
·
复杂任务处理机制分析
概述
Claude Code 通过 多层编排体系 处理复杂任务，核心机制包括：
| 层级 | 机制 | 核心职责 |
|---|---|---|
| 基础层 | QueryEngine + queryLoop | 多轮对话、工具调用循环、上下文压缩 |
| 规划层 | Plan Mode（进入/退出规划模式） | 先设计方案，再执行编码 |
| 任务层 | Task System V2（创建/更新/列表/认领） | 任务拆分、状态追踪、依赖管理 |
| Agent 层 | AgentTool（同步/异步子 Agent 派生） | 并行执行子任务、隔离上下文 |
| 协作层 | Coordinator Mode / Agent Swarms | 多 Agent 协作编排、团队通信 |
一、基础层：QueryEngine 多轮对话引擎
1.1 架构概览
用户输入
↓
QueryEngine.submitMessage() [src/QueryEngine.ts:217]
↓ 处理用户输入、记录 session、更新 mutableMessages
queryLoop() [src/query.ts:392]
↓ while(true) 循环
├── 构建 API 请求（system prompt + messages + tools）
├── 调用模型 API (callModel)
├── 收到响应 → 如果包含 tool_use → 执行工具 → 追加结果 → continue
└── 如果没有 tool_use → 返回 Terminal(reason: 'completed')
1.2 关键文件
| 文件 | 行数 | 职责 |
|---|---|---|
src/QueryEngine.ts |
1366 | 会话级编排器：消息管理、压缩触发、文件快照、属性追踪 |
src/query.ts |
2043 | 核心 API 交互循环：请求构建、流式处理、工具调用分发 |
1.3 多轮对话管理
mutableMessages（QueryEngine.ts:194）：跨轮次共享的消息数组submitMessage()方法每次处理一个用户轮次，将新消息追加到mutableMessages- Turn 计数：QueryEngine 内部
turnCount（line 769）和 queryLoop 内部state.turnCount（query.ts:428）双重追踪
1.4 上下文压缩（Compaction）
当上下文接近模型窗口限制时，系统自动触发多层压缩：
queryLoop 每次迭代
├── Snip Compact（HISTORY_SNIP feature flag）
│ └── 移除/摘要个别工具结果块，无需 LLM 调用
├── Micro Compact
│ └── 轻量级压缩，在 autoCompact 之前执行
└── Auto Compact（核心）
├── 检查 token 数是否超过阈值（context window - output reserve - buffer）
├── 调用 compactConversation() → LLM 摘要整个对话
└── 生成压缩边界消息 → 旧消息可被 GC 释放
关键文件：
src/services/compact/autoCompact.ts— 自动压缩触发器src/services/compact/compact.ts— 压缩核心实现src/services/compact/microCompact.ts— 微压缩src/services/compact/prompt.ts— 压缩 prompt 构建src/services/compact/sessionMemoryCompact.ts— 会话记忆压缩
预测性压缩（query.ts:837-873）：在实际超过窗口之前，预估本轮增长量，提前触发压缩。
二、规划层：Plan Mode（规划模式）
2.1 核心流程
用户提出复杂需求
↓
模型自主判断 → 调用 EnterPlanModeTool
↓ 进入只读探索阶段
├── 探索代码库结构
├── 识别关键模式
├── 设计实现方案
└── 制定分步计划
↓
调用 ExitPlanModeV2Tool → 呈现计划给用户批准
↓ 用户批准后
进入实施阶段 → 使用 AgentTool/TaskCreateTool 分配工作
↓
调用 VerifyPlanExecutionTool → 自检所有步骤是否完成
2.2 关键工具
| 工具 | 文件 | 职责 |
|---|---|---|
| EnterPlanModeTool | packages/builtin-tools/src/tools/EnterPlanModeTool/ |
进入规划模式，模型变为只读探索 |
| ExitPlanModeV2Tool | packages/builtin-tools/src/tools/ExitPlanModeV2Tool/ |
呈现计划、请求批准、退出规划模式 |
| VerifyPlanExecutionTool | packages/builtin-tools/src/tools/VerifyPlanExecutionTool/ |
执行后自检：确认所有步骤已完成 |
2.3 设计要点
- 只读约束：规划模式下模型不能写文件、不能执行命令
- 用户批准门控：ExitPlanModeV2Tool 需要用户确认计划后才能进入编码阶段
- Agent 限制：EnterPlanModeTool 明确禁止在子 Agent 上下文中调用（
if (context.agentId) throw ...） - Swarm 集成：当 Agent Swarms 启用时，ExitPlanModeV2Tool 会在输出中提示模型使用
TeamCreate并行化工作 - 队友审批流：当 Teammate 处于
plan_mode_required模式时，ExitPlanModeV2Tool 通过 Mailbox 向 Team Lead 发送审批请求
三、任务层：Task System V2
3.1 核心机制
Task System 是所有多 Agent 协作的底层基础设施，提供共享任务列表 + 状态管理 + 依赖追踪：
TaskCreateTool → 创建任务（pending 状态）
↓
Agent/Teammate 认领 → TaskUpdateTool(status: "in_progress")
↓
执行工作...
↓
完成 → TaskUpdateTool(status: "completed") → 触发 TaskCompleted Hook
↓ 依赖此任务的其他任务自动解锁
3.2 任务工具集
| 工具 | 文件 | 职责 |
|---|---|---|
| TaskCreateTool | packages/builtin-tools/src/tools/TaskCreateTool/ |
创建新任务到共享任务列表 |
| TaskUpdateTool | packages/builtin-tools/src/tools/TaskUpdateTool/ |
更新状态/负责人/阻塞关系 |
| TaskListTool | packages/builtin-tools/src/tools/TaskListTool/ |
列出所有任务（含状态、负责人、阻塞信息） |
| TaskGetTool | packages/builtin-tools/src/tools/TaskGetTool/ |
获取单个任务详情 |
| TaskStopTool | packages/builtin-tools/src/tools/TaskStopTool/ |
停止运行中的后台任务 |
| TaskOutputTool | packages/builtin-tools/src/tools/TaskOutputTool/ |
读取后台任务的输出 |
3.3 任务类型
7 种任务类型定义在 src/tasks/types.ts：
| 类型 | 运行位置 | 适用场景 |
|---|---|---|
| LocalAgentTask | 本地子进程 | 标准子 Agent 任务 |
| LocalShellTask | 本地 shell | 后台 shell 命令 |
| InProcessTeammateTask | 同进程内 | 轻量级进程内队友 |
| RemoteAgentTask | 远程服务器 | 分布式 Agent（CCR） |
| DreamTask | 后台静默 | 后台自主整理记忆 |
| LocalWorkflowTask | 本地 | 工作流编排 |
| MonitorMcpTask | 本地 | MCP 监控任务 |
3.4 核心特性
- 任务依赖（Blocking）：通过
addBlocks/addBlockedBy参数建立任务间依赖，被阻塞的任务在依赖完成前无法开始 - Hook 系统：
TaskCreated— 新任务创建时触发（可用于自动分配）TaskCompleted— 任务完成时触发（结果通知、依赖解锁）TeammateIdle— Teammate 空闲时触发（Lead 重新分配）
- 验证提醒（TaskUpdateTool:326-349）：当主 Agent 完成了 3+ 个任务中的最后一个，且无任务提及 "verif" 时，自动提醒派生验证 Agent
- 持久化：任务状态通过文件系统存储（
~/.claude/tasks/{team-name}/），进程重启可恢复
四、Agent 层：AgentTool 子 Agent 派生
4.1 核心流程
AgentTool（packages/builtin-tools/src/tools/AgentTool/AgentTool.tsx，1609 行）是子 Agent 派生的统一入口。
派生路径路由
AgentTool.call()
├── 有 teamName + name → spawnTeammate()（Swarm 多 Agent）
├── 无 subagent_type + forkGate → FORK_AGENT（共享父级 system prompt）
└── 有 subagent_type → 查找 agent definition → 标准子 Agent
同步 vs 异步执行
AgentTool 执行决策（line 709-716）
├── 同步（默认）：阻塞等待子 Agent 完成
│ └── 支持自动后台化：太长时自动转入后台
└── 异步（满足以下任一条件）：
├── run_in_background === true
├── agent definition 强制 background
├── Coordinator Mode
├── Fork 子 Agent
└── Proactive Mode 激活
4.2 同步执行细节
- 创建
AbortController和SubagentContext - 调用
runAgent()→ 返回异步迭代器 - 逐条处理消息：追踪进度、转发 bash 进度到父 SDK
- 支持 自动后台化：
backgroundPromise竞态，执行太长时自动转后台 - 完成后
finalizeAgentTool()+ 清理 worktree
4.3 异步执行细节
- 通过
registerAsyncAgent()在 AppState 中注册任务 - 注册名称到
agentNameRegistry（用于SendMessage路由） - 包装在
runWithAgentContext()中执行 - Fire-and-forget：父 Agent 立即返回
{ status: 'async_launched' } - 异步 Agent 完成后通过
<task-notification>XML 通知父 Agent
4.4 关键约束
- 工具过滤：子 Agent 的工具集根据类型过滤（例如 Coordinator Worker 只能使用 Bash + Read + Edit）
- 递归防护：子 Agent 不能递归创建新的子 Agent（Fork 子 Agent 有显式守卫）
- 上下文隔离：每个子 Agent 有独立的上下文窗口，不共享父 Agent 的对话历史
- 权限委托：子 Agent 的权限由父 Agent 预设，Swarm 模式下通过 Mailbox 路由到 Team Lead
五、协作层：Coordinator Mode 与 Agent Swarms
5.1 两种模式的架构对比
| 维度 | Coordinator Mode | Agent Swarms |
|---|---|---|
| 门控 | feature('COORDINATOR_MODE') + 环境变量 |
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 |
| 拓扑 | 星型：Coordinator 居中，Worker 外围 | 星型+P2P 混合：Team Lead 协调 + Teammate 间直接通信 |
| 角色 | 明确分工：Coordinator 编排、Worker 执行 | Team Lead 协调 + Teammate 自主认领任务 |
| 通信 | <task-notification> 定向通知 |
Mailbox 消息系统（message/broadcast） |
| 任务分配 | Coordinator 显式分配给指定 Worker | 共享任务列表 + 竞争认领 |
5.2 Coordinator Mode（协调者模式）
核心设计
- Coordinator 的工具集被精简为 4 个：Agent（启动 Worker）、SendMessage（向已有 Worker 发指令）、TaskStop（停止 Worker）、subscribe_pr_activity
- Coordinator 不能写代码、读文件、执行命令 — 只负责理解需求、分配任务、综合结果
- Worker 的工具通过
getCoordinatorUserContext()动态注入到 System Prompt
核心约束：先理解，再分配
反模式（禁止）:
"Based on your findings, fix the auth bug"
→ 把理解的责任推给 Worker
正确做法:
"Fix the null pointer in src/auth/validate.ts:42.
The user field on Session (src/auth/types.ts:15) is undefined
when sessions expire. Add a null check before user.id access."
→ Coordinator 自己理解问题，给出精确指令
通信协议
Worker 完成后，Coordinator 收到 XML 格式通知：
<task-notification>
<task-id>agent-a1b</task-id>
<status>completed|failed|killed</status>
<summary>Agent "Investigate auth bug" completed</summary>
<result>Found null pointer in src/auth/validate.ts:42...</result>
<usage>
<total_tokens>N</total_tokens>
<tool_uses>N</tool_uses>
<duration_ms>N</duration_ms>
</usage>
</task-notification>
Scratchpad 共享知识库
- Worker 可以自由读写 Scratchpad 目录（无需权限审批）
- Worker A 的研究结果写入 Scratchpad → Worker B 直接读取
- 实现跨 Worker 知识传递，无需经过 Coordinator 中转
5.3 Agent Swarms（蜂群模式）
架构组件
┌─────────────┐ ┌──────────────────┐
│ Team Lead │────▶│ Shared Task List │
│ (主会话) │ │ (文件锁保护) │
└─────────────┘ └──────────────────┘
│ │
│ ┌───────┴───────┐
│ │ │ │
▼ ▼ ▼ ▼
┌──────────┐ ┌──────────┐ ┌──────────┐
│Teammate A│ │Teammate B│ │Teammate C│
│独立上下文 │◀──│ Mailbox │──▶│独立上下文 │
└──────────┘ └──────────┘ └──────────┘
- Team Lead：创建团队、分配任务、综合结果
- Teammate：独立 Claude Code 实例，各自拥有独立的上下文窗口
- Task List：共享任务列表，Teammate 竞争认领和完成
- Mailbox：消息系统，支持 Teammate 间直接通信
任务认领与竞争
Teammate A 发现 task #3 是 pending
Teammate B 同时发现 task #3 是 pending
↓ 两者同时尝试 TaskUpdate(task #3, {status: "in_progress"})
文件锁保证原子性：
- 第一个写入者获得 owner 锁定
- 第二个写入者收到 already_claimed 错误
↓
获得任务的 teammate 执行工作
↓
完成后 TaskUpdate(task #3, {status: "completed"})
→ 依赖此任务的其他任务自动解锁
→ tool_result 提示 "Call TaskList to find your next task"
Mailbox 消息系统
| 模式 | 作用 | 场景 |
|---|---|---|
| message | 定向发送给指定 Teammate | 传递具体指令、请求协作 |
| broadcast | 广播给所有 Teammate | 全局通知、状态同步 |
关键特性：
- 自动投递到目标 Teammate 的对话上下文
- TeammateIdle Hook：Teammate 空闲时自动通知 Team Lead
- 直接通信：Teammate 间可直接通信，无需经过 Lead 中转
生命周期管理
Teammate 异常退出
↓
unassignTeammateTasks()
→ 扫描任务列表，找到 owner === teammateName 的未完成任务
→ 重置为 pending + owner=undefined
↓
Team Lead 感知：
1. 任务状态变化（pending 重置）
2. Mailbox 空闲通知（TeammateIdle hook）
↓
Team Lead 重新分配任务或创建新 Teammate
限制
- 不支持嵌套团队（Teammate 不能再创建子团队）
- 每 session 一个团队
- Team Lead 创建后不可更换
- in-process Teammate 进程重启后状态丢失
详细可见往期文章。
5.4 Hook 事件系统
Agent Teams 提供三个关键 Hook 事件：
| Hook | 触发时机 | 典型用途 |
|---|---|---|
| TaskCreated | 新任务添加到任务列表时 | 自动分配、优先级排序 |
| TaskCompleted | 任务标记为完成时 | 结果通知、依赖解锁 |
| TeammateIdle | Teammate 完成所有任务进入空闲时 | Lead 重新分配、动态扩缩容 |
5.5 场景选择指南
| 场景 | 推荐模式 | 原因 |
|---|---|---|
| "重构认证系统，需要多模块协调" | Coordinator | 需要集中决策，Worker 间有依赖 |
| "修复 10 个独立的 lint 警告" | Agent Teams | 任务独立，Teammate 可完全并行 |
| "研究方案 A 和方案 B，然后选一个实现" | Coordinator | 先并行研究，再集中决策 |
| "在大仓库中搜索所有 TODO 并分类" | Agent Teams | 无依赖，各自领任务即可 |
六、完整工作流示例
6.1 典型复杂任务处理流程
用户: "重构用户认证模块"
↓
【规划层】模型判断任务复杂 → 调用 EnterPlanModeTool
↓ 只读探索阶段
1. 分析 src/auth/ 目录结构
2. 识别依赖模块和接口
3. 制定重构计划（5 个子任务）
↓
【规划层】调用 ExitPlanModeV2Tool → 呈现计划给用户
↓ 用户批准
【基础层】QueryEngine 开始执行
↓
【协作层 - Agent Swarms】
├── TeamCreate → 创建团队
├── TaskCreate × 5 → 拆分为 5 个独立任务
├── AgentTool × 3 → 派生 3 个 Teammate
│ ├── Teammate A 认领 task #1、#3
│ ├── Teammate B 认领 task #2、#4
│ └── Teammate C 认领 task #5
│ ↓ 各项并行执行
│ ↓ Teammate 间通过 Mailbox 协调接口变更
└── Team Lead 监控进度、综合结果
↓
【基础层】VerifyPlanExecutionTool → 自检
↓
所有任务完成 → 返回用户最终结果
6.2 上下文压缩介入时机
任务执行过程中
↓ token 消耗持续增长
Micro Compact → 移除冗余工具输出
↓
预测性检测 → 预估本回合增长会超过窗口
↓
Auto Compact → LLM 摘要对话 → 释放旧消息
↓
继续执行后续任务（使用压缩后的上下文）
七、关键文件索引
核心引擎
| 文件 | 说明 |
|---|---|
src/QueryEngine.ts |
会话级编排器 |
src/query.ts |
API 交互核心循环 |
src/query/transitions.ts |
查询状态转换 |
src/query/loopHelpers.ts |
循环辅助函数 |
上下文压缩
| 文件 | 说明 |
|---|---|
src/services/compact/autoCompact.ts |
自动压缩触发 |
src/services/compact/compact.ts |
压缩核心实现 |
src/services/compact/microCompact.ts |
微压缩 |
src/services/compact/prompt.ts |
压缩 prompt |
src/services/compact/sessionMemoryCompact.ts |
会话记忆压缩 |
规划模式
| 文件 | 说明 |
|---|---|
packages/builtin-tools/src/tools/EnterPlanModeTool/ |
进入规划模式 |
packages/builtin-tools/src/tools/ExitPlanModeV2Tool/ |
退出规划模式 |
packages/builtin-tools/src/tools/VerifyPlanExecutionTool/ |
验证计划执行 |
任务系统
| 文件 | 说明 |
|---|---|
packages/builtin-tools/src/tools/TaskCreateTool/ |
创建任务 |
packages/builtin-tools/src/tools/TaskUpdateTool/ |
更新任务 |
packages/builtin-tools/src/tools/TaskListTool/ |
列出任务 |
packages/builtin-tools/src/tools/TaskGetTool/ |
获取任务 |
packages/builtin-tools/src/tools/TaskStopTool/ |
停止任务 |
packages/builtin-tools/src/tools/TaskOutputTool/ |
读取任务输出 |
src/utils/tasks.js |
任务 CRUD 核心 |
src/tasks/types.ts |
任务类型定义 |
Agent 系统
| 文件 | 说明 |
|---|---|
packages/builtin-tools/src/tools/AgentTool/AgentTool.tsx |
Agent 派生核心 |
src/utils/forkedAgent.ts |
Fork Agent 实现 |
packages/builtin-tools/src/tools/TeamCreateTool/ |
创建团队 |
packages/builtin-tools/src/tools/TeamDeleteTool/ |
删除团队 |
packages/builtin-tools/src/tools/SendMessageTool/ |
Agent 间消息 |
协作模式
| 文件 | 说明 |
|---|---|
src/coordinator/coordinatorMode.ts |
Coordinator Mode 核心 |
src/utils/agentSwarmsEnabled.ts |
Swarm 模式开关 |
packages/swarm/ |
Swarm 解耦模块 |
docs/agent/coordinator-and-swarm.mdx |
协作模式文档 |
八、总结
Claude Code 的复杂任务处理是一个分层递进的体系：
- 基础层（QueryEngine）提供了稳定可靠的多轮对话引擎和智能上下文压缩，是所有复杂任务的执行基础
- 规划层（Plan Mode）在编码前引入"先想后做"的设计阶段，降低大型任务的返工率
- 任务层（Task System V2）提供细粒度的任务拆分、状态追踪和依赖管理，是并行化的前提
- Agent 层（AgentTool）实现子 Agent 派生与上下文隔离，使并行执行成为可能
- 协作层（Coordinator/Swarms）提供两种互补的多 Agent 编排模式，分别适用于集中决策和自主协作场景
五层设计相互配合，形成从"单 Agent 顺序执行"到"多 Agent 蜂群协作"的完整能力谱系。
更多推荐
8
0- 0
已为社区贡献8条内容
所有评论(0)