第8章 查询引擎——LLM交互的心脏

第8章 查询引擎------LLM交互的心脏

引言

想象一辆汽车，它的核心是什么？是发动机。发动机将燃料转化为动力，驱动整辆车前进。在 Claude Code 这个 AI 编程助手中，QueryEngine 就是那个发动机------它将用户的输入转化为与 LLM 的交互，驱动整个对话系统运转。

本章将深入剖析 QueryEngine 的设计哲学和实现细节。你将看到：

• QueryEngine 如何管理对话状态
• 异步生成器如何优雅地处理流式响应
• Token 计量和预算控制如何防止成本失控
• AbortController 如何实现优雅的中断机制
• 会话持久化如何确保对话不丢失

概念讲解

查询引擎的本质

QueryEngine 是一个有状态的对象，它"拥有"整个对话的生命周期。每次调用 submitMessage() 都会开始一个新的轮次（turn），但状态（消息、文件缓存、使用量等）会在轮次之间持久化。

这就像一个厨师，他记住每个顾客的偏好，虽然每次服务都是新的订单，但累积的知识让他能提供更好的服务。

异步生成器的威力

QueryEngine 的核心方法 submitMessage() 是一个异步生成器（AsyncGenerator）。这是一个非常精妙的设计：

• 它可以逐步产生结果（流式响应）
• 它可以被外部中断（通过 AbortController）
• 它保持了内部状态的封装

异步生成器就像一个水龙头，你可以随时打开它获取数据，也可以随时关闭它停止流动。

状态管理的艺术

QueryEngine 维护多个核心状态：

• mutableMessages：对话历史
• totalUsage：Token 使用量统计
• abortController：中断控制器
• readFileState：文件读取缓存

这些状态的设计体现了单一职责原则和关注点分离的思想。

源码分析

QueryEngine 类定义

让我们从 QueryEngine 的类定义开始：

export class QueryEngine {
  private config: QueryEngineConfig
  private mutableMessages: Message[]
  private abortController: AbortController
  private permissionDenials: SDKPermissionDenial[]
  private totalUsage: NonNullableUsage
  private hasHandledOrphanedPermission = false
  private readFileState: FileStateCache
  private discoveredSkillNames = new Set<string>()
  private loadedNestedMemoryPaths = new Set<string>()

  constructor(config: QueryEngineConfig) {
    this.config = config
    this.mutableMessages = config.initialMessages ?? []
    this.abortController = config.abortController ?? createAbortController()
    this.permissionDenials = []
    this.readFileState = config.readFileCache
    this.totalUsage = EMPTY_USAGE
  }
}

设计要点分析：

1. 封装性 ：所有状态都是 private，外部无法直接修改
2. 可配置性 ：通过 QueryEngineConfig 传入所有依赖，便于测试和扩展
3. 默认值 ：initialMessages 和 abortController 提供了合理的默认值
4. 集合类型 ：使用 Set 来管理技能发现和内存路径，避免重复

submitMessage 方法签名

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

关键设计决策：

1. 灵活的输入 ：prompt 可以是字符串或内容块数组，支持简单和复杂场景
2. 可选元数据 ：uuid 用于追踪，isMeta 用于标记系统消息
3. 返回类型 ：AsyncGenerator<SDKMessage> 表示这是一个异步生成器，逐步产生 SDK 消息

配置解构与初始化

在 submitMessage 方法的开头，我们看到大量的配置解构：

const {
  cwd,
  commands,
  tools,
  mcpClients,
  verbose = false,
  thinkingConfig,
  maxTurns,
  maxBudgetUsd,
  taskBudget,
  canUseTool,
  customSystemPrompt,
  appendSystemPrompt,
  userSpecifiedModel,
  fallbackModel,
  jsonSchema,
  getAppState,
  setAppState,
  replayUserMessages = false,
  includePartialMessages = false,
  agents = [],
  setSDKStatus,
  orphanedPermission,
} = this.config

这种解构模式的优势：

• 显式依赖：所有依赖都清晰可见
• 默认值 ：如 verbose = false，replayUserMessages = false
• 类型安全：TypeScript 会检查解构的正确性

权限包装器

QueryEngine 使用了一个包装器来追踪权限拒绝：

const wrappedCanUseTool: CanUseToolFn = async (
  tool,
  input,
  toolUseContext,
  assistantMessage,
  toolUseID,
  forceDecision,
) => {
  const result = await canUseTool(
    tool,
    input,
    toolUseContext,
    assistantMessage,
    toolUseID,
    forceDecision,
  )

  // Track denials for SDK reporting
  if (result.behavior !== 'allow') {
    this.permissionDenials.push({
      tool_name: sdkCompatToolName(tool.name),
      tool_use_id: toolUseID,
      tool_input: input,
    })
  }

  return result
}

这是一个装饰器模式的经典应用：在不修改原始函数的情况下，添加了追踪功能。

系统提示词构建

QueryEngine 负责构建完整的系统提示词：

const {
  defaultSystemPrompt,
  userContext: baseUserContext,
  systemContext,
} = await fetchSystemPromptParts({
  tools,
  mainLoopModel: initialMainLoopModel,
  additionalWorkingDirectories: Array.from(
    initialAppState.toolPermissionContext.additionalWorkingDirectories.keys(),
  ),
  mcpClients,
  customSystemPrompt: customPrompt,
})

const userContext = {
  ...baseUserContext,
  ...getCoordinatorUserContext(
    mcpClients,
    isScratchpadEnabled() ? getScratchpadDir() : undefined,
  ),
}

const memoryMechanicsPrompt =
  customPrompt !== undefined && hasAutoMemPathOverride()
    ? await loadMemoryPrompt()
    : null

const systemPrompt = asSystemPrompt([
  ...(customPrompt !== undefined ? [customPrompt] : defaultSystemPrompt),
  ...(memoryMechanicsPrompt ? [memoryMechanicsPrompt] : []),
  ...(appendSystemPrompt ? [appendSystemPrompt] : []),
])

设计亮点：

1. 分层构建：基础提示词 + 用户上下文 + 内存机制 + 追加提示词
2. 条件加载 ：memoryMechanicsPrompt 只在需要时加载
3. 数组展开：使用展开运算符优雅地组合多个提示词部分

用户输入处理上下文

QueryEngine 创建了一个复杂的上下文对象来处理用户输入：

let processUserInputContext: ProcessUserInputContext = {
  messages: this.mutableMessages,
  setMessages: fn => {
    this.mutableMessages = fn(this.mutableMessages)
  },
  onChangeAPIKey: () => {},
  handleElicitation: this.config.handleElicitation,
  options: {
    commands,
    debug: false,
    tools,
    verbose,
    mainLoopModel: initialMainLoopModel,
    thinkingConfig: initialThinkingConfig,
    mcpClients,
    mcpResources: {},
    ideInstallationStatus: null,
    isNonInteractiveSession: true,
    customSystemPrompt,
    appendSystemPrompt,
    agentDefinitions: { activeAgents: agents, allAgents: [] },
    theme: resolveThemeSetting(getGlobalConfig().theme),
    maxBudgetUsd,
  },
  getAppState,
  setAppState,
  abortController: this.abortController,
  readFileState: this.readFileState,
  nestedMemoryAttachmentTriggers: new Set<string>(),
  loadedNestedMemoryPaths: this.loadedNestedMemoryPaths,
  dynamicSkillDirTriggers: new Set<string>(),
  discoveredSkillNames: this.discoveredSkillNames,
  setInProgressToolUseIDs: () => {},
  setResponseLength: () => {},
  updateFileHistoryState: (
    updater: (prev: FileHistoryState) => FileHistoryState,
  ) => {
    setAppState(prev => {
      const updated = updater(prev.fileHistory)
      if (updated === prev.fileHistory) return prev
      return { ...prev, fileHistory: updated }
    })
  },
  updateAttributionState: (
    updater: (prev: AttributionState) => AttributionState,
  ) => {
    setAppState(prev => {
      const updated = updater(prev.attribution)
      if (updated === prev.attribution) return prev
      return { ...prev, attribution: updated }
    })
  },
  setSDKStatus,
}

设计模式分析：

1. 依赖注入：所有依赖都通过参数传入
2. 不可变更新 ：updateFileHistoryState 和 updateAttributionState 使用函数式更新模式
3. 回调模式 ：setMessages 允许外部修改消息数组
4. 空函数默认值 ：onChangeAPIKey 等提供安全的默认实现

孤立权限处理

QueryEngine 处理孤立权限（orphaned permission）的逻辑非常优雅：

if (orphanedPermission && !this.hasHandledOrphanedPermission) {
  this.hasHandledOrphanedPermission = true
  for await (const message of handleOrphanedPermission(
    orphanedPermission,
    tools,
    this.mutableMessages,
    processUserInputContext,
  )) {
    yield message
  }
}

关键点：

1. 一次性处理 ：hasHandledOrphanedPermission 确保只处理一次
2. 流式 yield ：使用 for await 逐步产生消息
3. 状态传递 ：传递 tools、mutableMessages 和上下文

用户输入处理

QueryEngine 调用 processUserInput 来处理用户的输入：

const {
  messages: messagesFromUserInput,
  shouldQuery,
  allowedTools,
  model: modelFromUserInput,
  resultText,
} = await processUserInput({
  input: prompt,
  mode: 'prompt',
  setToolJSX: () => {},
  context: {
    ...processUserInputContext,
    messages: this.mutableMessages,
  },
  messages: this.mutableMessages,
  uuid: options?.uuid,
  isMeta: options?.isMeta,
  querySource: 'sdk',
})

返回值分析：

• messagesFromUserInput：处理后的消息（可能包含附件、斜杠命令结果等）
• shouldQuery：是否需要调用 LLM
• allowedTools：允许使用的工具列表
• modelFromUserInput：用户指定的模型
• resultText：处理结果文本

消息持久化

QueryEngine 在进入查询循环之前就持久化用户消息：

if (persistSession && messagesFromUserInput.length > 0) {
  const transcriptPromise = recordTranscript(messages)
  if (isBareMode()) {
    void transcriptPromise
  } else {
    await transcriptPromise
    if (
      isEnvTruthy(process.env.CLAUDE_CODE_EAGER_FLUSH) ||
      isEnvTruthy(process.env.CLAUDE_CODE_IS_COWORK)
    ) {
      await flushSessionStorage()
    }
  }
}

设计考虑：

1. 提前持久化：在 API 响应之前就保存，确保即使进程崩溃也不会丢失
2. 模式差异：bare 模式下不等待，其他模式等待并可能刷新
3. 环境变量控制：通过环境变量控制是否立即刷新

系统初始化消息

QueryEngine 产生一个系统初始化消息，包含所有配置信息：

yield buildSystemInitMessage({
  tools,
  mcpClients,
  model: mainLoopModel,
  permissionMode: initialAppState.toolPermissionContext.mode as PermissionMode,
  commands,
  agents,
  skills,
  plugins: enabledPlugins,
  fastMode: initialAppState.fastMode,
})

这个消息让 SDK 和客户端了解当前系统的完整状态。

局部命令输出处理

QueryEngine 特殊处理局部命令的输出：

for (const msg of messagesFromUserInput) {
  if (
    msg.type === 'user' &&
    typeof msg.message.content === 'string' &&
    (msg.message.content.includes(`<${LOCAL_COMMAND_STDOUT_TAG}>`) ||
      msg.message.content.includes(`<${LOCAL_COMMAND_STDERR_TAG}>`) ||
      msg.isCompactSummary)
  ) {
    yield {
      type: 'user',
      message: {
        ...msg.message,
        content: stripAnsi(msg.message.content),
      },
      session_id: getSessionId(),
      parent_tool_use_id: null,
      uuid: msg.uuid,
      timestamp: msg.timestamp,
      isReplay: !msg.isCompactSummary,
      isSynthetic: msg.isMeta || msg.isVisibleInTranscriptOnly,
    } as SDKUserMessageReplay
  }

  if (
    msg.type === 'system' &&
    msg.subtype === 'local_command' &&
    typeof msg.content === 'string' &&
    (msg.content.includes(`<${LOCAL_COMMAND_STDOUT_TAG}>`) ||
      msg.content.includes(`<${LOCAL_COMMAND_STDERR_TAG}>`))
  ) {
    yield localCommandOutputToSDKAssistantMessage(msg.content, msg.uuid)
  }

  if (msg.type === 'system' && msg.subtype === 'compact_boundary') {
    yield {
      type: 'system',
      subtype: 'compact_boundary' as const,
      // ... more fields
    }
  }
}

处理逻辑：

1. 用户消息：去除 ANSI 颜色代码，添加 SDK 元数据
2. 系统命令：转换为助手消息格式
3. 压缩边界：直接 yield 系统消息

设计启示

1. 异步生成器的优雅性

QueryEngine 使用异步生成器而不是回调或 Promise，带来了以下优势：

• 可读性：代码线性流动，易于理解
• 可中断性：外部可以随时中断生成过程
• 流式处理：逐步产生结果，不需要等待全部完成

async *submitMessage(...): AsyncGenerator<SDKMessage> {
  // 逐步产生消息
  yield buildSystemInitMessage(...)
  for (const msg of messages) {
    yield msg
  }
}

2. 状态封装与可变性

QueryEngine 使用私有字段和公共方法来封装状态：

export class QueryEngine {
  private mutableMessages: Message[]  // 私有可变状态
  
  async *submitMessage(...) {
    // 通过方法修改状态
    this.mutableMessages.push(...messagesFromUserInput)
  }
}

这种设计平衡了封装性和可变性：外部无法直接访问内部状态，但可以通过方法间接修改。

3. 依赖注入的威力

QueryEngine 通过构造函数接收所有依赖：

constructor(config: QueryEngineConfig) {
  this.config = config
  this.mutableMessages = config.initialMessages ?? []
  this.abortController = config.abortController ?? createAbortController()
  // ...
}

这使得 QueryEngine：

• 易于测试：可以注入 mock 依赖
• 易于扩展：可以通过配置改变行为
• 解耦合：不依赖具体的实现

4. 错误处理的层次性

QueryEngine 在多个层次处理错误：

1. 权限层 ：wrappedCanUseTool 追踪权限拒绝
2. 输入层 ：processUserInput 处理用户输入错误
3. API 层 ：query 函数处理 API 错误
4. 持久化层 ：recordTranscript 处理存储错误

每个层次专注于自己的职责，形成清晰的错误处理边界。

5. 性能优化的权衡

QueryEngine 在多个地方做出了性能权衡：

1. 提前持久化：牺牲一点延迟换取数据安全
2. 条件加载：只在需要时加载内存提示词
3. 异步处理：bare 模式下不等待持久化完成
4. 缓存复用 ：readFileState 跨轮次复用文件缓存

思考题

1. 设计题：如果需要支持多个并发用户输入，QueryEngine 的设计需要做哪些调整？

2. 优化题 ：在什么情况下，mutableMessages 应该改为不可变数据结构？优缺点是什么？

3. 扩展题：如何为 QueryEngine 添加插件系统，允许第三方扩展功能？

4. 测试题：如何为 QueryEngine 编写单元测试？需要 mock 哪些依赖？

5. 架构题 ：QueryEngine 和 query() 函数的职责如何划分？有没有更好的方式？

总结

QueryEngine 是 Claude Code 的心脏，它：

• 管理状态：维护对话历史、使用量、权限等核心状态
• 处理流式响应：使用异步生成器优雅地处理流式输出
• 控制成本：通过预算控制和 Token 计量防止成本失控
• 确保可靠性：通过提前持久化和中断机制保证数据不丢失
• 提供扩展点：通过配置和回调支持各种扩展场景

就像汽车的发动机一样，QueryEngine 将用户的输入（燃料）转化为与 LLM 的交互（动力），驱动整个 AI 编程助手运转。它的设计体现了软件工程中的诸多最佳实践：封装、依赖注入、异步处理、错误处理分层等。

理解 QueryEngine 的设计，你就能理解整个 Claude Code 系统的核心交互机制。