Claude code源码精读之复杂任务处理机制分析

十正

395人浏览 · 2026-06-12 16:58:41

十正 · 2026-06-12 16:58:41 发布

复杂任务处理机制分析

概述

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 蜂群协作"的完整能力谱系。

亚马逊云科技技术品牌专区

更多推荐

open-code-review Codex 插件教程：对话式调用评审技能指南

本文是一份面向新手的 **open-code-review Codex 插件教程**，教你在 Codex 中通过对话式方式调用 open-code-review 的 AI 代码评审技能。open-code-review 是阿里巴巴开源的 AI 代码评审工具，采用"确定性流水线 + LLM Agent"混合架构，内置多语言评审规则（NPE、线程安全、XSS、SQL 注入等），可在 Codex 里用一

亚马逊云科技技术品牌专区

OBS Studio 完整指南：免费开源录屏与直播软件从零上手

想做一场像模像样的直播，或者把屏幕内容录成教程视频，但一想到商用软件的订阅费就有些犹豫？其实你不需要花一分钱。OBS Studio 是一款免费开源的直播与录屏软件，支持 Windows、macOS 和 Linux，采集、混音、编码、推流、录制，一条流水线全包了。## 先搞清楚 OBS Studio 是什么OBS Studio 是一个"场景化"的采集合成工具：你把摄像头、窗口、浏览器、图片、

亚马逊云科技技术品牌专区

如何用MediaCrawler爬取小红书抖音数据？7大平台爬虫从安装到实战完整指南

MediaCrawler 是一个支持小红书、抖音、快手、B站、微博、百度贴吧、知乎的开源自媒体数据采集工具。它能按关键词、按帖子、按创作者主页三种方式抓取笔记/视频内容、评论甚至二级评论，并把结果存成 JSON、CSV、Excel 或数据库。适合做市场调研、竞品监控、内容选题的运营人员，以及想要现成爬虫框架而不想从零写 JS 逆向的开发者。## 从一次"手动抄数据"说起想象这个场景：你负责

亚马逊云科技技术品牌专区

所有评论(0)

查看更多评论

十正

@skypig555

已为社区贡献11条内容

Claude code源码精读之复杂任务处理机制分析

十正

复杂任务处理机制分析

概述

一、基础层：QueryEngine 多轮对话引擎

1.1 架构概览

1.2 关键文件

1.3 多轮对话管理

1.4 上下文压缩（Compaction）

二、规划层：Plan Mode（规划模式）

2.1 核心流程

2.2 关键工具

2.3 设计要点

三、任务层：Task System V2

3.1 核心机制

3.2 任务工具集

3.3 任务类型

3.4 核心特性

四、Agent 层：AgentTool 子 Agent 派生

4.1 核心流程

派生路径路由

同步 vs 异步执行

4.2 同步执行细节

4.3 异步执行细节

4.4 关键约束

五、协作层：Coordinator Mode 与 Agent Swarms

5.1 两种模式的架构对比

5.2 Coordinator Mode（协调者模式）

核心设计

核心约束：先理解，再分配

通信协议

Scratchpad 共享知识库

5.3 Agent Swarms（蜂群模式）

架构组件

任务认领与竞争

Mailbox 消息系统

生命周期管理

限制

5.4 Hook 事件系统

5.5 场景选择指南

六、完整工作流示例

6.1 典型复杂任务处理流程

6.2 上下文压缩介入时机

七、关键文件索引

核心引擎

上下文压缩

规划模式

任务系统

Agent 系统

协作模式

八、总结

所有评论(0)

温馨提示：您尚未绑定手机号

十正