第四章：沿 Claude Code 追踪一次文件修复

4.1 从入口分流到会话编排

entrypoints/cli.tsx 先处理特殊参数，再按需要动态导入较重模块。版本查询走短路径，其他入口可能启动完整 CLI 或专用功能。这说明启动成本与运行职责可以分层；不能因为某个参数瞬间返回，就断定完整交互路径也已验证。Claude Code 2.1.88 提取快照 · cli.tsx L31–45

在常规会话侧，QueryEngine 是重要定位点，而 query.ts 中的 queryLoop 推进模型与工具回路。前者与后者的关系应按实际调用追踪，不能把所有会话服务都理解成一次 HTTP 请求。Claude Code 2.1.88 提取快照 · QueryEngine.ts L182–196 Claude Code 2.1.88 提取快照 · query.ts L239–253

4.2 用读取任务标记消息流

设用户提出贯穿案例。系统先组织用户输入、系统上下文和可用工具，随后请求模型。模型若提出读取文件，程序拿到的是带工具身份和参数的调用。真正读取由工具执行服务处理，结果再次成为对话的一部分。

这里的轨迹是教学假设，不是本书执行官方客户端得到的记录。实际请求次数、选择哪种读取方式、是否并行，都由模型响应、配置和当前状态共同决定。本书关注的是每个动作怎样穿过固定边界。

queryLoop 是异步生成器，返回的不只是最终自然语言。类型签名包含流事件、请求开始、消息、替换相关条目与工具摘要等内容。调用方可以在任务完成前看到进度，但“能看到进度”不说明该动作的持久结果已经成立。Claude Code 2.1.88 提取快照 · query.ts L239–253

4.3 为什么需要独立工具执行器

StreamingToolExecutor 保存工具的状态、待交付进度、结果与上下文修改，并接收 canUseTool 这样的授权函数。把这些工作从主循环拆出，允许模型流与工具调度协作，同时让主循环不必亲自保存每个工具的全部运行状态。Claude Code 2.1.88 提取快照 · StreamingToolExecutor.ts L38–52 Claude Code 2.1.88 提取快照 · useCanUseTool.tsx L25–39

研究这个执行器时，特别注意取消原因。文件中区分用户中断、并行兄弟工具出错和流式回退等情况。它们都可能导致某项工具不再继续，但最终向模型和界面交付的含义不同。不能把“取消了一项任务”直接解释为“当前轮次整体失败”，也不能推断已经发生的写入被撤销。

4.4 大结果如何进入下一步

读取大文件或运行命令可能产生很大输出。applyToolResultBudget 在有替换状态时调用预算处理，并把新替换记录交给 transcript 写入路径。它展示了一个可迁移的思路：模型可见消息发生替换，应保留可追踪的记录。Claude Code 2.1.88 提取快照 · toolResultStorage.ts L922–936

这种处理与自动摘要不同。摘要试图保留含义；工具结果预算可以把原始结果外置，再提供预览与定位信息。若后续需要完整证据，应能根据引用重新读取，而不是只相信短预览足以支持一切结论。

4.5 从快照能借鉴什么

最值得借鉴的是职责拆分：会话编排、模型循环、执行器、权限决策和工具输出预算各有入口。你可以从这些入口观察数据怎样联动，却不能仅凭代码快照承诺每项分支都可构建或启用。源码使用构建开关与内部常量，这些条件属于运行结论的一部分。

练习：如果模型已显示“开始修复”，但工具结果未返回，你能确认文件已改变吗？不能。需要工具结果与实际文件状态；若进程此时中断，还必须考虑结果未知。这个问题会在日志与恢复章节再次出现。