怎么说呢，

《Claude Code 源码解析系列》第2章｜ReAct 主循环

上一篇我们把 Claude Code 拆成了几层：Model API 负责判断。QueryEngine 负责推进主循环，Tools 负责接触真实工程环境，Context / State 负责让任务不断线。说起来，

这一篇开始往里钻。先看最主要的一层：query.ts 怎么把一次模型调用 成一轮可以持续行动的 Agent Run。

使用者痛点①的观点是。一句话就想得到完整答案，却被模型一次性答不出来。说起来，

案例：

帮我看看这个项目为什么测试失败。并把它修好，老实说，

模型本身不会读文件、跑命令或维护任务状态。现在的问题变成：

Claude Code 怎么让模型在一个受控循环里边判断、边行动、边吸收结果，直到任务真的推进下去？

这就是 ReAct 要解决的问题。

使用者痛点②的观点是，担心工具执行后不透明、权限被忽略。

"模型会不会直接跑 shell 命令？"

ReAct 闭环的主要概念

Reason → Act → Observe → Reason

• Reason: 根据当前上下文判断接下来要做什么；
• Act: 生成工具调用意图；
• Observe: 将工具执行结果写回 messages;
• Reason: 基于新事实继续判断。说起来，

为什么主循环不能只调一次 Model API？

"为什么不是一次问完就行？"

package.json 里脚本怎么写？启动命令报了什么错，相关源码在哪？ 话说回来，改完之后测试过吗？”这些事实不在模型参数里需要多轮交互获取。

简单案例与复杂案例对比
模型直接生成答案，完事。

使用者痛点③：多轮交互导致耗时长、体验差。

重现真实故障排查流程的必要性：

• A -> B -> C 的顺序是“先假设。再取证，再修正”，;按理说，
• A 是模型初始猜测；B 是工具执行收集信息，C 是下一轮推理。，
• This loop mimics production troubleshooting steps.

ReAct 并非“模型自己动手”，而是“模型提意图”

关键误区： "模型会读文件或输入命令吗?" 它只能输出意图，例如 "读取 package.json" 或 "运行 npm test". 切换到实际操作的是外层程序.

分工表格
角色 功能	职责说明
Model	判断接下来干什么
Tools / QueryEngine	执行意图、记录结果并回填消息流
QueryEngine	维持会话级状态与权限控制。确保安全可恢复

至于使用者痛点④，对“权限/审计/错误恢复”的缺失感到担忧。话说回来，"如果工具返回错误怎么办？"

query.ts 的状态机：主要不是函数，而是 State 对象

• 'messages' - 模型可见上下文；
• 'toolUseContext' - 当前可用工具列表与输入 schema；
• 'turnCount' - 已跑轮次用于防止无限循环；
• 'shouldAutoCompact' - 上下文膨胀时触发压缩；
• 'aborted' - 外部中断信号。

  . messages: Agent 的短期工作记忆

  • Mimics a live ledger: 使用者输入 → 模型判断 → 工具调用 → 工具结果 → 程序摘要 ...;
  • If omitted,each round starts from scratch—model loses context.

  . toolUseContext: 这一轮能用哪些「手脚」

  • The tool environment is more than a list—it defines schemas,permissions。and how results are transformed into messages.

  . : 多轮程序标识

  • The system explicitly acknowledges that tasks require multiple turns.

  . : 上下文膨胀治理

  • This flag ensures long-running agents don't exceed token limits or lose focus.

  . : 安全中断

  • An agent must gracefully stop if user cancels or a tool fails.

。

---