Claude code执行过程解析

分层任务拆解与计划固化（/plan/task）

顶层拆分这事，说白了就是先把总目标拆成几个串行依赖的阶段——比如环境初始化→数据库层→接口层→前端→单元测试→上线校验，一个阶段一个阶段过，不能跳步。

每个阶段还得再切成更细粒度的任务切片，每个切片都对应一个独立的/task条目，而且必须附带清楚的可验收标准、依赖关系、用到的工具。光有清单还不够，得留风险预留：那些高风险步骤，比如大规模文件删除、数据库结构变更，中间必须插一个人工确认节点，防止脑子一热就动手。资源分配也要算清楚，每个子任务分配好 token 上限和最大工具调用轮数，别让单一步骤把整个上下文都吃光。

二、阶段 2：核心底层 —— 单 Agent 迭代执行循环（queryLoop 引擎）

所有长任务的最小执行单元，其实就是这个 queryLoop 引擎。它本质上是一个无限循环——只要还有工具调用、任务没完成，它就一直转。这是 Claude Code 的基础执行内核，底层是个异步生成器 AsyncGenerator，流式输出状态，不会卡住上层会话。

一轮完整的循环，走的是下面这 7 步标准流程：

上下文组装预处理 → 大模型推理决策 → 工具调用分发 → 权限安全校验 → 多工具并行执行 → 工具结果回写会话 → 判定终止/下一轮循环

上下文压缩这块，保留的内容必须精挑细选：总任务目标、项目核心架构、关键代码变更、验收标准，这些不能丢。其他边角料能省则省。

多层验收校验（防止半成品交付）

1. 自动化工具校验
   ：自动跑测试套件、Lint、构建脚本、数据库迁移脚本，验证功能能不能用；

2. 逻辑对抗校验 Agent
   ：专门针对产出代码、方案做反向漏洞推演，看看有没有坑；

3. 目标对齐校验
   ：对比原始需求，核查有没有遗漏子目标、偏离约束。校验失败直接回退到对应任务节点，调整方案重新迭代。

中断恢复机制（超长跨天任务核心能力）

1. 会话意外关闭或终端断开：自动保存当前 State（任务计划、压缩快照、已完成子任务）；
2. 重启会话后执行/state读取完整进度，从最近 Compact 断点续跑，不用从头再扫一遍项目；
3. Workflow 编排任务也支持断点续跑：已经完成的并行子 Agent 结果会缓存起来，不会重复执行。

一、queryLoop 核心定位与设计目标

1. 定位

queryLoop 是 Claude Code 所有代码自主执行的

，一个同步/异步的状态机循环引擎。甭管是简单的单文件修改，还是超大工程任务里的子智能体，底层全都复用这套循环逻辑。Dynamic Workflow 的 Subagent、普通对话代码模式、终端 Claude Code 插件，共享的是同一套 queryLoop 实现。

2. 核心设计目标（针对复杂长任务痛点）

1. 标准化工具调用生命周期，统一处理文件读写、Shell、Git、搜索、MCP 插件；
2. 内置多层上下文治理，持续抑制长会话 Token 膨胀和上下文腐烂；
3. 强容错：工具超时、报错、幻觉调用、上下文超限，都内置了重试或降级逻辑；
4. 可观测、可断点存储：每一轮状态固化，支持回滚、暂停、续跑；
5. 分层安全拦截，所有外部操作统一过权限网关。

3. 底层实现形态

工程层面是个

，流式吐出执行状态（思考日志、工具执行进度、压缩提示、报错），不会阻塞上层会话服务。全局只持有一个 SessionState 状态对象，所有轮次共享这份可变上下文。

二、queryLoop 全局依赖组件（循环前置底座）

循环启动之前，必须初始化全套依赖，缺一不可：

1. System Prompt 固定基座
   ：内置代码 Agent 行为约束、全部工具 Schema、输出格式规范、终止条件、安全红线。长任务模式会追加「分步规划、定期校验、主动压缩上下文」这种强制指令。

2. SessionState 全局状态存储
   ：循环的唯一数据源，字段包括：
   • messages：历史对话 + 工具输入输出消息列表
   • compactSnapshots：历史上下文压缩快照（断点）
   • taskPlan：顶层拆解的任务分阶段计划
   • toolCallBudget：本轮会话剩余工具调用轮数上限
   • fileCache：高频读取文件缓存（cache_control 驱动，减少重复读文件消耗 Token）
   • permissionAudit：文件 / Shell 操作授权记录
   • errorLog：工具执行失败栈，用于重试策略

3. ContextCompressor 分层压缩管线
   ：独立模块，循环每轮推理前自动执行 7 层裁剪，这是长任务稳定的核心。

4. ToolOrchestrator 工具调度器
   ：负责并行/串行工具分发、沙箱隔离、超时控制、结果序列化。

5. SecurityGateway 安全权限网关
   ：deny-first 拦截模型高危操作，区分自动放行、弹窗确认、直接阻断三类。

6. TerminationJudge 终止判定器
   ：输入模型输出内容，判断是否需要继续循环。

步骤 6：工具结果回写 SessionState 持久化

1. 将所有 tool_result 消息追加到全局 messages 列表，永久留存；
2. 更新 fileCache：本次读取的文件内容写入内存缓存，下一轮无需重复读取；
3. 更新 errorLog：记录失败工具、报错信息、重试次数；
4. 更新 toolCallBudget：扣除本轮消耗的工具调用配额，达到上限直接终止循环。

四、queryLoop 内置关键容错机制（长复杂任务专用）

1. 工具幻觉修复
   ：模型调用不存在的工具、参数缺失、参数类型错误时，tool orchestrator 返回明确格式化错误，写入 tool_result，下一轮模型会基于报错修正调用参数，不用人工介入。

2. 循环死锁熔断
   ：检测到连续 5 轮完全相同的工具调用（比如无限重复读同一个文件、重复执行同一个失败命令），触发熔断，自动执行一次全局 compact 并提醒用户任务陷入循环。

3. 断点快照自动保存
   ：每执行 10 轮循环自动生成一份 compactSnapshots 存入 SessionState；用户可通过 /rewind 回退到任意快照，从历史节点重新跑循环，适配跨天超长任务中断恢复。

4. 预算分级限流
   ：单会话全局工具轮数上限 + 单轮并行工具数量上限双重限制，防止无限制大规模扫描仓库消耗资源。

taskPlan 数据结构示例：

{
  "stages": [
    {
      "stageId": "scan_project",
      "title": "扫描项目目录",
      "completed": true,
      "acceptance": ["读取根目录文件树，梳理依赖"],
      "subTasks": []
    },
    {
      "stageId": "refactor_service",
      "title": "重构用户服务代码",
      "completed": false,
      "acceptance": ["修改User.ja va", "修复单元测试", "Lint无报错"],
      "subTasks": ["修改实体类", "重构接口", "执行测试"]
    }
  ]
}