2 · 会话层：QueryEngine

这一章讲「一场对话」这个东西在程序里是怎么被表示和管理的。

2.1 它解决什么问题

大语言模型没有记忆 —— 每次调用都要把全部历史重发一遍。所以必须有个东西持有这场对话的所有状态，在用户的每一次提问之间保持存活。

这就是 QueryEngine（查询引擎）。源码里的类注释说得很清楚：

2.2 它持有哪些状态

export class QueryEngine {
  private config: QueryEngineConfig       // 不变的配置（工具、命令、模型等）
  private mutableMessages: Message[]      // ★ 完整的消息历史，会一直增长
  private abortController: AbortController // 中止开关，贯穿整条调用链
  private permissionDenials: SDKPermissionDenial[]  // 被拒绝过的操作记录
  private totalUsage: NonNullableUsage    // 累计 token 用量
  private hasHandledOrphanedPermission = false
  private readFileState: FileStateCache   // ★ 读过哪些文件、什么版本

  // 下面两个是"轮次内追踪"，每轮开头清空
  private discoveredSkillNames = new Set<string>()   // 本轮发现了哪些技能
  private loadedNestedMemoryPaths = new Set<string>() // 本轮加载了哪些记忆文件
}

claude-code/src/QueryEngine.ts

其中两个字段值得单独说

readFileState（文件读取状态缓存）记录「模型读过哪些文件、读的是哪个版本」。它有三个用途：

1. 防止重复注入。记忆系统预取到一个文件时，如果模型自己已经读过它，就不再作为「记忆」注入一遍。
2. 检测文件被外部修改。模型读过 a.ts，后来用户在编辑器里改了它，那么模型手里的内容就过期了。系统会检测到并注入一条提示。
3. 编辑前的安全检查。模型要改一个它从没读过的文件时，工具会拒绝并要求它先读 —— 因为盲改极易出错。

abortController（中止控制器）是那个「取消开关」。它被传递到每一个工具调用、每一个网络请求。用户按 Ctrl+C 时拉一下，整条链路都能感知到。第 3 章会讲它的正确处理姿势。

2.3 一次 submitMessage 的完整流程

submitMessage() 是这个类的核心方法。它是一个异步生成器 —— 也就是说它不是「算完再返回」，而是一边算一边往外吐消息，调用方可以实时消费。

async *submitMessage(
  prompt: string | ContentBlockParam[],
  options?: { uuid?: string; isMeta?: boolean },
): AsyncGenerator<SDKMessage, void, unknown>

（async * 是 JavaScript 的异步生成器语法。yield 一个值就等于「先把这个吐出去，调用方拿到之后我再继续」。这是流式界面能实时更新的基础。）

完整流程：

2.4 用户消息为什么必须先落盘

第 ⑤ 步有一段很长的注释，讲的是一个真实的线上问题：

翻译成人话：用户发出消息后、模型还没回复的那几秒钟里，如果程序被杀掉，这次对话就彻底找不回来了。因为落盘的时机在模型回复之后。

修复方式是把落盘提前到「用户消息被接受」的那一刻。但这里又冒出一个性能权衡：

if (persistSession && messagesFromUserInput.length > 0) {
  const transcriptPromise = recordTranscript(messages)
  if (isBareMode()) {
    void transcriptPromise          // ★ 极简模式：发射后不管，不等它写完
  } else {
    await transcriptPromise         // 正常模式：等写完再继续
    ...
  }
}

注释解释了为什么极简模式要特殊处理：

2.5 消费主循环输出：一个大 switch

进入主循环后，QueryEngine 用一个 for await 循环消费主循环吐出的每一条消息，按类型分别处理：

为什么模型消息要「发射后不管」，而用户消息要同步等待

这一段涉及一个精巧的机制，值得展开：

而 progress（进度）消息要「立刻落盘」，也有专门的注释：

2.6 压缩分界点：主动释放内存

当主循环发出「压缩分界点」消息时，QueryEngine 做一件很重要的事：

if (message.subtype === 'compact_boundary' && message.compactMetadata) {
  // 分界点之前的消息已经被摘要替代了，可以释放给垃圾回收器
  const mutableBoundaryIdx = this.mutableMessages.length - 1
  if (mutableBoundaryIdx > 0) {
    this.mutableMessages.splice(0, mutableBoundaryIdx)   // ★ 直接从数组里删掉
  }
  const localBoundaryIdx = messages.length - 1
  if (localBoundaryIdx > 0) {
    messages.splice(0, localBoundaryIdx)
  }
  yield { type:'system', subtype:'compact_boundary', ... }
}

注释：「Release pre-compaction messages for GC. query.ts already uses getMessagesAfterCompactBoundary() internally, so only post-boundary messages are needed going forward.」（把压缩前的消息释放给垃圾回收。主循环内部已经只用分界点之后的消息了，所以往后只需要保留这些。）

为什么要专门做这件事？因为一场长会话的消息历史可能有几百 MB。压缩之后前面那些消息在逻辑上已经没用了，但只要数组还引用着它们，垃圾回收器就不会回收 —— 内存会一直涨到进程被系统杀掉。

但落盘要在释放之前完成

而且顺序不能错。在删除之前，有一段专门的落盘逻辑：

if (persistSession && message.type === 'system' &&
    message.subtype === 'compact_boundary') {
  const tailUuid = message.compactMetadata?.preservedSegment?.tailUuid
  if (tailUuid) {
    const tailIdx = this.mutableMessages.findLastIndex(m => m.uuid === tailUuid)
    if (tailIdx !== -1) {
      await recordTranscript(this.mutableMessages.slice(0, tailIdx + 1))
    }
  }
}

注释解释了不这么做的后果：「If the SDK subprocess restarts before then (claude-desktop kills between turns), tailUuid points to a never-written message → applyPreservedSegmentRelinks fails its tail→head walk → returns without pruning → resume loads full pre-compact history.」

译：如果子进程在那之前重启（桌面应用会在轮次之间杀进程），保留段的尾节点就指向了一条从未被写入的消息 → 重新串联函数的「从尾到头」遍历失败 → 直接返回不做裁剪 → 于是恢复时会加载完整的压缩前历史。

症状是：用户压缩过的会话，恢复之后又变回了压缩前的样子，上下文立刻爆掉。

2.7 三种退出结果

submitMessage 最终会发出一个 result 消息，标明这次轮次是怎么结束的：

最后那个错误类型带了一个专门的诊断前缀

errors: (() => {
  const all = getInMemoryErrors()
  const start = errorLogWatermark ? all.lastIndexOf(errorLogWatermark) + 1 : 0
  return [
    // ★ 诊断前缀：直接说明"判定失败"的那三个条件各自是什么值
    `[ede_diagnostic] result_type=${edeResultType} ` +
    `last_content_type=${edeLastContentType} stop_reason=${lastStopReason}`,
    ...all.slice(start).map(_ => _.error),
  ]
})()

而且错误列表是按轮次范围截取的 —— 用了一个「水位标记」：

// 用引用而不是下标作为水位标记，这样 error_during_execution 的 errors 数组
// 是轮次范围内的。用长度下标会在 100 条环形缓冲区发生位移时失效 —— 下标会滑走。
// 如果这条标记本身被轮换出去了，lastIndexOf 返回 -1，就包含全部（安全兜底）。
const errorLogWatermark = getInMemoryErrors().at(-1)

2.8 ask()：一次性调用的便捷封装

文件末尾还导出了一个 ask() 函数，是 QueryEngine 的一次性封装 —— 创建实例、跑一轮、把文件缓存交还给调用方：

export async function* ask({...}) {
  const engine = new QueryEngine({
    ...,
    readFileCache: cloneFileStateCache(getReadFileCache()),   // ★ 传入的是克隆
  })
  try {
    yield* engine.submitMessage(prompt, { uuid: promptUuid, isMeta })
  } finally {
    setReadFileCache(engine.getReadFileState())   // ★ 无论如何都要交还
  }
}

两个细节：

• 传入的文件缓存是克隆的。这样这次调用对缓存的修改不会立刻影响外部 —— 直到最后显式交还。
• finally 块保证交还。即使中间抛异常、被中断，「模型读过哪些文件」这个信息也不会丢。丢了会导致下一轮重复注入记忆或者误判文件新鲜度。