Claude code 执行过程解析

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

顶层拆分：将总目标拆为串行依赖阶段（如环境初始化→数据库层→接口层→前端→单元测试→上线校验）；

细粒度任务切片：每个阶段拆独立/task条目，附带验收标准、依赖关系、所需工具；

• 风险预留：标记高风险步骤（大规模文件删除、数据库变更），插入人工确认节点；
• 资源分配：为每个子任务分配 token 上限、最大工具调用轮数，避免单步骤耗尽上下文。

二、阶段 2：核心底层 —— 单 Agent 迭代执行循环（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. 底层实现形态

工程层面是异步生成器 AsyncGenerator，流式吐出执行状态（思考日志、工具执行进度、压缩提示、报错），不会阻塞上层会话服务；全局持有唯一 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.java", "修复单元测试", "Lint无报错"],
      "subTasks": ["修改实体类", "重构接口", "执行测试"]
    }
  ]
}