【Harness Engineering】从Claude Code源码里扒出的真相： Query Loop循环才是智能体的命门，而不是模型！

模型调优与Prompt设计精细，工具集成完善，演示运行流畅，但在实际应用场景中常出现严重故障：

工具调用中断导致状态丢失；上下文累积引发"Prompt过长"崩溃；用户操作打断后缺乏事务回滚；任务未完成却被误判为结束...

这些问题的根源并非模型能力不足或Prompt设计不佳。

核心缺失在于系统缺乏稳定的"心跳机制"——Query Loop（查询循环）。

多数开发者过度关注模型和Prompt，却忽略Query Loop这一代理系统的"生命线"。它是区分演示原型与可落地系统的关键，Claude Code源码通过完备的状态管理与执行逻辑印证：代理系统的成熟度，取决于Query Loop的设计深度。

本文深度解析Claude Code的Query Loop实现，聚焦可复用的工程逻辑，规避智能体落地核心风险。

理解Query Loop：智能体系统的运行中枢

将智能体简单视为"一问一答"机制适用于基础聊天场景，但涉及多轮工具调用、中断处理、状态保存的复杂任务时，该逻辑必然失效。

例如执行"修改代码→Git提交→部署测试"任务时：若缺失Query Loop，系统可能遗漏关键步骤；工具调用失败后无法重试；用户操作中断导致修改记录不可追溯。

Query Loop作为智能体"心跳"，通过持续的状态维护确保任务有序推进。Claude Code在src/query.ts的241行实现queryLoop()函数，其核心逻辑远超简单try/catch封装——通过状态管理、输入治理、失败恢复等机制，保障执行流程有始有终。

关键认知：模型是智能体的"大脑"，Prompt是"行为准则"，而Query Loop是驱动执行落地的"心跳"。缺失稳定心跳，系统将丧失工程化基础。

Claude Code Query Loop的六大工程设计

1. 状态管理：系统运转的基石

代理系统必须坦然接受状态而非追求"无状态"。Claude Code在src/query.ts的203-217行显式声明关键状态：

• messages：会话历史记录
• toolUseContext：工具调用上下文
• turnCount：执行轮次计数
• pendingToolUseSummary：待处理工具摘要

这些状态通过State对象集中管理，确保每轮迭代时状态完整传递。这使系统能在故障后精准恢复执行，实现"下一步承接前序状态"的工程目标。

2. 执行前治理：输入净化的必经流程

Claude Code将80%核心逻辑置于模型调用前，通过src/query.ts:297起的治理流程：

1. 提前预取记忆数据与技能列表
2. 截取有效消息边界，过滤冗余内容
3. 应用工具结果预算控制上下文膨胀
4. 分层压缩：history snip→microcompact→context collapse→autocompact

该设计确立核心原则：上下文治理优先于模型推理。避免将杂乱输入直接交付模型导致的责任转嫁，保障系统运行可靠性。

3. 模型调用：心跳中的有序收缩

Claude Code采用流式消费模型输出（src/query.ts:652）。将响应解析为事件流：assistant文本、tool_use指令、token用量更新等。

系统在模型输出过程中并行执行三项操作：缓存对话内容、解析工具调用、调度工具执行。这使模型响应成为可操作的"事件链"而非终结结果，显著提升任务执行效率。

4. 中断处理：清晰的执行账本

通过src/query.ts:1011的中断管理机制：

• 消费残余模型输出生成synthetic tool_result，补全工具调用链
• 调用yieldMissingToolResultBlocks()明确标注中断状态

确保外部系统始终获得一致的执行轨迹，即便任务中断也要形成完整的"因果闭环"。这是保障系统可解释性与审计能力的基础。

5. 分层恢复：从故障到执行连续性

针对高频问题实施递进式恢复：

Prompt过长处理（src/query.ts:1065）：先尝试低成本context collapse，失败再触发reactive compact；

Token超限处理（src/query.ts:1185）：优先提升上限，次选生成元消息续接执行。核心理念：恢复流程是主路径的核心组件，而非模型失败的附带动作。

6. 多维停止机制：精准的状态判定

区别于单条件终止，Claude Code定义7种执行状态（src/query.ts:1062-1305）：

1. 待处理工具调用：进入新轮次执行
2. 无工具调用：触发停止钩子校验
3. 流式中断：执行账本补全流程
4. Prompt过长/Token超限：启动对应恢复流程
5. API错误：返回结构化错误信息

特别在停止钩子逻辑中加入防死循环设计，体现重试行为本身需被管理的工程智慧。

QueryEngine：会话生命周期管家

src/QueryEngine.ts定义会话核心管理器：

"QueryEngine拥有会话的查询生命周期与状态"。每个submitMessage()操作在持续状态中开启新轮次（src/QueryEngine.ts:180），通过queryLoop()与状态存储形成执行闭环（src/QueryEngine.ts:675），使Query Loop成为连接UI层与业务层的中枢。

可恢复执行循环：智能体工程化的核心

代理系统成功的关键在于维持可恢复的执行循环，而非模型或工具数量。Claude Code印证该原则：

• 显式State管理取代局部变量
• 运行时治理优先于模型推理
• 流式输出消费机制
• 中断后的执行账本补全
• 分层式故障恢复逻辑
• QueryEngine的生命周期管理

完善的Query Loop需满足五大条件：

1. 结构化跨轮状态管理
2. 主动式输入治理能力
3. 流式事件承接机制
4. 清晰的执行账本维护
5. 精准的执行状态判定

智能体工程化需回归基础：优先构建稳健的Query Loop，使系统具备有序执行、抗意外干扰与自主恢复能力。唯有如此，才能实现从演示原型到生产系统的质变。