深度拆解 Claude Code 源码系列(二):查询引擎 —— 对话的精密编排器

编者：这是系列文章的第二章。在第一章中，我们了解了 Claude Code 的整体架构。本章将深入最核心的模块 —— QueryEngine，理解它是如何编排与 AI 的完整对话生命周期的。

引子：为什么需要 QueryEngine？

在第一章中，我们提到了 Claude Code 的核心循环：

用户输入 → QueryEngine → query.ts → API → 工具调用 → ... → 响应

但你有没有想过这样一个问题：为什么不能直接调用 `query.ts`，而需要一个 `QueryEngine` 来包装它？

毕竟，query.ts已经能完成 API 调用、流式响应处理、工具执行这些核心功能了。再加一层 QueryEngine，是不是多此一举？

要回答这个问题，让我们先想象一个场景：

你和 Claude Code 进行了一场长达 30 分钟的对话。期间它：

读取了 15 个文件

执行了 8 次 Bash 命令

调用了 3 次 MCP 工具

修改了 5 个文件

现在，消息历史已经接近 200K tokens —— 快要触及 API 的上下文窗口限制了。

这时候，如果你再输入一条消息，系统需要做以下几件事：

压缩消息历史—— 将旧对话总结为摘要，保留关键信息
追踪文件状态—— 记录哪些文件被修改了，用于 Git 归因
管理 Token 预算—— 确保这次调用不会超出你的成本上限
处理权限审批—— 如果 Claude 要调用新工具，需要你的批准
持久化转录—— 将对话保存到本地，以便下次恢复
模型切换—— 如果用户通过斜杠命令切换了模型，需要应用新设置

这些职责，每一个都不简单。而query.ts的核心职责只是单次 API 调用—— 它不应该关心压缩、预算、归因这些事。

这就是 QueryEngine 存在的意义。

QueryEngine 是对话的"指挥官"。它负责：

管理整个对话的生命周期（从用户输入到最终响应）
维护跨轮次的状态（消息历史、文件缓存、使用统计）
触发压缩、预算检查、归因记录等横切关注点
为不同的调用方（REPL、SDK、Headless 模式）提供统一的接口

如果没有 QueryEngine，这些逻辑就会散落在 REPL、SDK、Headless 各个调用方中，造成大量重复代码和不一致行为。

所以，QueryEngine 的本质是一个"关注点分离"的设计模式。query.ts专注于 API 调用，QueryEngine 专注于对话编排。

在这一章中，我们将深入 QueryEngine 的 1366 行代码，理解它是如何精密地编排每一次对话的。

第一部分：QueryEngine 的角色定位

1.1 QueryEngine 是什么？

让我们从代码开始：

这段注释揭示了 QueryEngine 的三个关键设计决策：

一个 QueryEngine 对应一次对话

不是每个请求创建一个新的 QueryEngine，而是整个对话生命周期共享一个实例。这意味着：

消息历史在轮次之间持久化
文件状态缓存在轮次之间保留
TOKEN 使用统计累计

submitMessage 启动一轮新对话

每次调用submitMessage()都是一轮新的对话（turn）。一轮对话可能包含多次 API 调用（因为工具调用会循环）。

状态跨轮次持久化

mutableMessages、readFileState、totalUsage等状态在轮次之间保留。这是与query.ts的关键区别 ——query.ts是无状态的，每次调用都是独立的。

1.2 配置系统

QueryEngine 的构造函数接收一个 QueryEngineConfig 对象：

30 多个配置项，涵盖了 QueryEngine 需要的所有外部环境信息。

这种配置对象的设计有几个好处：

参数分组清晰—— 环境、权限、状态、文件、模型等配置按类别组织
可选参数灵活—— 大部分参数都是可选的，有合理的默认值
函数式状态更新——setAppState接收一个更新函数，而不是直接修改状态，这符合不可变状态的最佳实践

1.3 QueryEngine 的状态管理

QueryEngine 内部维护了多个状态变量：

这些状态变量揭示了 QueryEngine 的职责范围：

消息历史—— 核心状态，每轮对话都会累积
Token 使用—— 跨轮次累计，用于成本追踪
权限拒绝—— 用于向 SDK 报告用户拒绝了多少次工具调用
文件状态—— 缓存文件读取结果，避免重复 IO
技能发现—— 追踪本轮对话发现了哪些新技能

1.4 QueryEngine 的调用方

QueryEngine 不是独立运行的，它被多个调用方使用：

QueryEngine 通过 AsyncGenerator 接口为所有调用方提供统一的输出格式。

调用方消费submitMessage()返回的异步生成器：

这种设计让 QueryEngine 不需要关心调用方的具体实现，只需要按照协议 yield 消息即可。

在下一部分中，我们将深入submitMessage方法，理解一轮对话的完整生命周期。

第二部分：消息流转的完整生命周期

submitMessage是 QueryEngine 的核心方法，也是整个对话生命的周期的起点。

这个方法有800+ 行代码，涵盖了从用户输入到最终响应的每一个步骤。让我们一步步拆解。

2.1 submitMessage 的整体流程

submitMessage是一个AsyncGenerator函数。这意味着它不是一次性返回结果，而是逐步 yield 消息给调用方。

这种设计的好处是：

流式输出—— 调用方可以在对话进行中就渲染部分结果
中断支持—— 调用方可以随时停止生成
进度反馈—— 每个关键步骤都可以 yield 进度消息

让我们用一张流程图来展示整体流程：

这张图展示了从用户输入到最终结果的完整路径。接下来我们会深入每个关键步骤。

2.2 第一阶段：初始化与配置解构

submitMessage的第一步是解构配置并重置状态：

关键操作解释：

`discoveredSkillNames.clear()`—— 清空技能发现记录。每轮对话都要重新开始追踪发现的技能，避免跨轮次累积。
`permissionDenials = []`—— 重置权限拒绝记录。这个数组用于向 SDK 报告用户拒绝了多少次工具调用。
`setCwd(cwd)`—— 设置当前工作目录。这是 Shell 工具执行时需要的上下文。
`persistSession`—— 检查是否需要持久化会话。如果用户禁用了会话持久化（CLAUDE_CODE_DISABLE_SESSION_PERSISTENCE），则不保存转录。
`startTime`—— 记录开始时间，用于最终计算总耗时。

2.3 第二阶段：包装 canUseTool

接下来，QueryEngine 包装了canUseTool函数：

为什么要包装？

原始的canUseTool只负责权限检查。QueryEngine 需要额外追踪权限拒绝记录，以便最终结果中报告给 SDK 调用方。

这是一种装饰器模式—— 在不修改原始函数的情况下，添加额外的行为。

2.4 第三阶段：构建系统提示

系统提示是 Claude 行为的"灵魂"。QueryEngine 通过fetchSystemPromptParts()构建系统提示：

系统提示的组成：

最终的系统提示由三部分拼接而成：

这种分层设计让系统提示可以灵活组合：

默认系统提示—— Claude Code 的核心行为定义
自定义系统提示—— 用户通过/custom-prompt命令覆盖
内存机制提示—— 告诉 Claude 如何使用记忆文件
追加系统提示—— 用户通过配置附加的提示词

2.5 第四阶段：处理用户输入

接下来，QueryEngine 调用processUserInput()处理用户的输入：

processUserInput()负责：

1.解析斜杠命令—— 如/model、/compact、/force-snip等

2.处理附件—— 用户附加的文件、图片等

3.验证输入—— 检查输入格式、长度等

4.提取参数—— 如模型切换、工具允许列表等

关键标志：`shouldQuery`

如果用户输入只是一个斜杠命令（如/model sonnet），而不需要查询 API，shouldQuery会是false。这时 QueryEngine 直接返回命令结果，不进入 API 调用循环。

2.6 第五阶段：持久化转录

在进入 API 调用循环之前，QueryEngine 先保存用户消息到转录文件：

为什么要在 API 调用之前保存？

注释给出了原因：

如果进程在 API 响应之前被杀死（例如用户在发送后几秒内点击 Stop），转录中只会留下队列操作条目；`getLastSessionLog` 会过滤掉这些，返回 null，`--resume` 会失败并提示"No conversation found"。现在写入可以让转录从用户消息被接受的时刻起可恢复，即使 API 响应永远不到达。

这是一个容错设计—— 确保即使系统崩溃，用户的消息也不会丢失。

2.7 第六阶段：进入 query() 循环

最后，QueryEngine 进入query()循环：

这个for await循环是对话的核心。query()是一个 AsyncGenerator，它会：

发送 API 请求
流式接收响应
如果需要工具调用，执行工具并将结果作为用户消息发回
重复直到 API 返回纯文本响应

QueryEngine 在这个循环中的职责：

追加消息到mutableMessages
持久化转录
yield 消息给调用方
追踪轮次、Token 使用、权限拒绝等

2.8 消息类型处理

在循环中，QueryEngine 处理多种消息类型：

每种消息类型都有特定的处理逻辑，确保状态正确更新。

2.9 最终结果消息

当query()循环完成后，QueryEngine yield 一个result消息：

这个result消息是对话的最终输出，包含了完整的统计信息。SDK 调用方可以根据这些信息显示报告或进行计费。

在下一部分中，我们将深入 Claude Code 最复杂的机制之一 —— 上下文压缩（Compaction）。

第三部分：上下文压缩机制 —— 如何在有限窗口中保持记忆

如果你曾经用过 ChatGPT 或其他 LLM 产品，你可能遇到过这样的情况：

对话进行到后来，AI 开始"遗忘"前面说过的话。这不是 AI 变笨了，而是因为它达到了上下文窗口的限制。

对于 Claude Code 这种可能需要长时间对话的工具来说，这个问题更加突出。想象一下：

你让 Claude 分析一个大型项目

它读取了 50 个文件，执行了 20 次命令，消息历史已经超过 150K tokens，但模型的上下文窗口只有 200K tokens。

这时候，Claude Code 有两个选择：

1.停止对话—— 告诉用户"上下文满了，无法继续"

2.压缩上下文—— 将旧消息总结为摘要，腾出空间继续对话

显然，第2个选择更好。但这不是一个简单的任务。

3.1 压缩的挑战

压缩对话消息面临着几个核心挑战：

1. 保留关键信息

不是所有消息都同等重要。工具调用的结果（如文件内容）可能比 Claude 的闲聊更有价值。压缩需要智能地判断哪些信息值得保留。

2. 保持对话连贯性

压缩后，Claude 需要知道对话被压缩了。否则它会困惑为什么突然"失去"了部分记忆。

3. 控制成本

压缩本身也需要调用 API（让 Claude 总结旧对话）。如果压缩太频繁，成本会很高。

4. 处理失败

压缩可能失败（API 错误、超时等）。系统需要有重试机制和降级策略。

Claude Code 的压缩系统通过多种压缩策略组合来应对这些挑战。

3.2 压缩策略的层次

Claude Code 实现了4 种压缩策略，各有不同的触发条件和处理方式：

让我们逐一理解这些策略。

3.3 自动压缩（Auto Compact）

autoCompact是最主要的压缩策略。它基于 Token 阈值自动触发。

核心参数：

有效上下文窗口计算：

触发条件：

自动压缩在以下情况触发：
当前消息 Token 数 > 有效上下文窗口 - 缓冲区 Token

缓冲区 Token 根据模型大小动态调整：

为什么需要这么大的缓冲区？

因为一轮对话可能产生大量 Token
Claude 的输出可能达到 8K-32K Token
工具调用结果（如文件读取）可能达到 20K+ Token
如果缓冲区太小，可能在检查时还有空间，但实际执行时就超限了。

3.4 压缩的核心流程

压缩的核心流程在compact.ts中实现：

关键步骤解释：

Step 1: 压缩前 Hooks

在压缩之前，系统会执行一些预处理：

保存文件状态快照
记录压缩前的 Token 统计
通知外部系统（如遥测）

Step 2: 构建压缩提示

压缩提示告诉 Claude 如何总结对话：

你是一个 AI 助手。以下是一个开发者与 AI 的对话历史。

请将对话总结为简洁的摘要，保留以下信息：

关键决策和结论
代码修改和文件操作
待完成的任务
对话历史：[... 消息列表 ...]

Step 3: 调用 API

压缩需要调用一次 API，让 Claude 总结对话。这会产生额外的成本，但通常比继续对话导致的错误更便宜。

Step 4: 构建压缩后消息

压缩后的消息历史由两部分组成：

[System: 对话被压缩。摘要：...]← 压缩边界消息
[最近的消息保留]← 保留的原始消息

压缩边界消息告诉 Claude 对话被压缩了，并提供了摘要。这类似于给 Claude 一个"记忆断点"。

Step 5 & 6: 压缩后 Hooks 和清理

压缩完成后：

更新内部状态
标记压缩边界
清理临时消息
记录压缩统计

3.5 压缩缓冲区的演进

让我们用一张图来展示不同模型的压缩缓冲区策略：

为什么要根据模型大小调整缓冲区？

因为大模型的单轮输出可能更大：

小模型（如 Haiku）：输出 ~4K Token
中型模型（如 Sonnet）：输出 ~8K Token
大模型（如 Opus）：输出 ~32K Token

如果缓冲区太小，大模型可能在检查时还有空间，但输出后就超限了。

3.6 Snip 压缩：快速裁剪

snipCompact是一种更轻量的压缩策略。它不是总结整个对话，而是"裁剪"掉最旧的消息。

Snip 的工作原理：

1. 找到对话中的"自然断点"（如工具调用完成、任务完成）

2. 裁剪断点之前的消息

3. 插入一个压缩边界消息

Snip 比 Auto Compact 更快，因为它不需要调用 API 总结。但它丢失的信息也更多 —— 没有摘要，只有裁剪。

3.7 微压缩（Micro Compact）

microCompact是单轮压缩。它只压缩最近一轮对话中的工具结果。

例如：

微压缩的好处是只影响工具结果，不影响对话历史。这对于包含大量文件读取的对话特别有用。

3.8 响应式压缩（Reactive Compact）

reactiveCompact是基于内容重要性的压缩策略。它不是基于 Token 阈值，而是基于内容的重要性决定哪些消息值得保留。

响应式压缩的优先级：

3.9 压缩失败处理

压缩可能失败。例如：

API 返回错误
超时
提示仍然太长（prompt_too_long）

Claude Code 的压缩系统有一个断路器模式：

// 连续失败超过 3 次后停止尝试

const MAX_CONSECUTIVE_AUTOCOMPACT_FAILURES = 3

为什么是 3 次？

注释给出了原因：

2026-03-10 数据分析：1,279 个会话有 50+ 次连续失败（最多 3,272 次），每天浪费约 250K API 调用。

如果没有断路器，系统可能会无限重试压缩，浪费大量 API 调用。

失败后的降级策略：

第一次失败：重试压缩
第二次失败：尝试不同的压缩策略（如从 Auto Compact 降级到 Snip Compact）
第三次失败：停止压缩，继续对话（可能最终会因为上下文超限而报错）

3.10 压缩边界消息

压缩完成后，系统会插入一个SystemCompactBoundaryMessage：

这个消息告诉 Claude（和调用方）：

对话被压缩了
压缩的类型是什么
Token 数变化
哪些消息被保留了

Claude 收到这个消息后，会知道自己的对话历史被压缩了，并且可以从compact_metadata中了解压缩的细节。

在下一部分中，我们将了解工具调用的编排机制 —— Claude 如何连续调用多个工具。

第四部分：工具调用的编排 —— 从单个调用到循环执行

在第一章中，我们提到了 Claude Code 的核心循环：

用户输入 → API → tool_use → 执行工具 → 结果作为用户消息 → API → ...

这个循环是 Claude Code 最强大的功能之一。它让 Claude 可以连续调用多个工具，直到完成用户的请求。

但你可能不知道的是，工具调用的编排比看起来复杂得多。

4.1 工具调用的生命周期

让我们追踪一次工具调用的完整路径：

这个流程涉及多个模块的协作：

query.ts—— 检测工具调用，触发权限检查
canUseTool—— 检查权限
工具实现—— 执行实际操作
QueryEngine—— 追踪权限拒绝，记录统计

4.2 权限检查的层次

Claude Code 的权限系统有多个层次：

1. 权限模式（Permission Mode）

用户在会话开始时选择一个权限模式：

2. 工具级别的权限

某些工具可能有特殊的权限规则：

文件读取工具：通常自动批准
文件写入工具：需要批准
Shell 命令：需要批准
MCP 工具：取决于配置

3. 用户规则（Always Allow Rules）

用户可以配置某些工具或命令自动批准：

/permission always-allow BashTool "npm test"

这告诉系统：npm test命令不需要批准。

4.3 QueryEngine 中的权限追踪

QueryEngine 通过包装canUseTool来追踪权限拒绝：

为什么需要追踪权限拒绝？

主要有两个原因：

SDK 报告—— SDK 调用方需要知道有多少次工具调用被拒绝了
统计分析—— 了解哪些工具最常被拒绝，帮助改进用户体验

最终结果消息中包含权限拒绝列表：

4.4 工具执行的细节

工具执行在query.ts中的runTools函数中处理：

工具编排的关键点：

1. 并行执行

如果 Claude 在一次响应中调用多个工具，这些工具可以并行执行：

2. 超时处理

工具执行有超时限制。如果工具执行时间过长，系统会中止执行并返回错误。

3. 错误恢复

如果工具执行失败，系统会返回错误消息，让 Claude 决定如何处理。

第五部分：Token 预算与成本控制

在使用 AI 编程助手时，成本是一个重要的考虑因素。Claude Code 提供了多层成本控制机制。

5.1 预算配置

QueryEngine 支持多种预算配置：

最大轮数（maxTurns）

限制一轮对话中的 API 调用次数。例如：

这可以防止 Claude 无限循环调用工具。

最大成本（maxBudgetUsd）

限制一轮对话的总成本。例如：

当成本达到限制时，系统会停止对话并返回结果。

5.2 Token 使用追踪

QueryEngine 追踪每轮对话的 Token 使用：

totalUsage在每次 API 响应后更新：

Token 使用的组成：

5.3 成本计算

成本根据模型的定价计算：

5.4 预算检查

在每轮 API 调用之前，系统会检查预算：

这种预测性的预算检查可以防止意外的高成本。

在下一部分中，我们将了解文件历史与归因系统。

第六部分：文件历史与归因系统 —— 追踪每一次代码修改

如果你在使用 Claude Code 修改代码，你可能会有这样的疑问：

"哪些文件被 Claude 修改了？"

这个问题对于代码审查、Git 归因、会话恢复都很重要。Claude Code 通过文件历史快照系统来回答这个问题。

6.1 文件状态缓存

QueryEngine 维护一个文件读取状态缓存：

FileStateCache记录了：

·哪些文件被读取过
·读取时的内容
·读取的时间点

这个缓存有两个作用：

1.避免重复 IO—— 如果文件已经被读取过且没有变化，直接返回缓存

2.归因追踪—— 记录哪些文件被 Claude 操作过

6.2 文件历史快照

当用户发送消息时，系统会创建文件历史快照：

这个快照记录了：

消息的 UUID
消息发送时的文件状态
哪些文件在本次会话中被修改

6.3 Git 归因

QueryEngine 还支持 Git 提交归因：

AttributionState追踪：

哪些代码行是 Claude 修改的
修改的时间
相关的会话消息

这使得 Claude Code 可以在 Git 提交中标注"AI 辅助贡献"。

6.4 会话恢复

文件历史和归因信息最终被保存到转录文件中：

转录文件包含完整的消息历史、文件快照和归因信息。这使得用户可以通过--resume命令恢复之前的会话

总结与预告

本章回顾

在这一章中，我们深入了 QueryEngine 的 1366 行代码，理解了它是如何精密地编排每一次对话的：

1. QueryEngine 的角色定位

作为"对话指挥官"，QueryEngine 负责管理整个对话生命周期，而不关心具体的 API 调用细节。这种关注点分离的设计让query.ts和 QueryEngine 各司其职。

2. 消息流转的完整生命周期

submitMessage方法涵盖了从初始化、系统提示构建、用户输入处理、持久化转录到 query() 循环的完整流程。每一步都有明确的职责和容错设计。

3. 上下文压缩机制

Claude Code 实现了 4 种压缩策略（Auto Compact、Snip Compact、Micro Compact、Reactive Compact），通过动态缓冲区和断路器模式应对各种场景。这是一个复杂的系统，但设计非常优雅。

4. 工具调用的编排

权限检查、并行执行、超时处理、错误恢复 —— 工具调用的编排比看起来复杂得多。

5. Token 预算与成本控制

多层预算配置、Token 使用追踪、成本预测检查，让成本可控。

6. 文件历史与归因系统

文件快照、Git 归因、会话恢复，让每一次操作都有迹可循。

这些设计你可以借鉴什么？

AsyncGenerator 流式输出—— 让调用方可以在进行中就消费结果
装饰器模式—— 在不修改原始函数的情况下添加额外行为
多层压缩策略—— 根据不同场景选择不同压缩方式
断路器模式—— 防止无限重试导致的资源浪费
预测性预算检查—— 在操作前预测成本，而不是事后才发现超限

下一章预告

在理解了查询引擎之后，下一章我们将深入消息系统 —— 理解 Claude Code 如何定义和组织消息类型、如何在不同类型的消息之间转换、以及消息如何在 API 格式和内部格式之间适配。

如果你对"消息"这个看似简单实则复杂的系统感兴趣，下一章会给你带来全新的视角。