Skip to content

10-query-engine.md

Latest commit

 

History

History
178 lines (131 loc) · 3.59 KB

10-query-engine.md

File metadata and controls

178 lines (131 loc) · 3.59 KB

10. Query Engine 教程

Query Engine 是 Claude Code 的系统心脏。真正把“用户输入”变成“多轮 agent 执行”的，是 QueryEngine 和 query.ts 这条主干。

1. 关键模块

  • src/QueryEngine.ts 会话级控制器
  • src/query.ts 回合执行循环
  • src/query/config.ts query 配置
  • src/query/tokenBudget.ts token budget 管理
  • src/query/stopHooks.ts 回合结束后的 stop hooks
  • src/services/compact/* compact 相关逻辑

2. 总体架构图

flowchart TB
    Submit[submitMessage]
    Engine[QueryEngine]
    Q[query.ts]
    API[Claude API]
    Tools[toolOrchestration]
    Compact[compact/reactive compact]
    Stop[stop hooks]
    Persist[session storage]

    Submit --> Engine
    Engine --> Q
    Q --> API
    API --> Tools
    Tools --> Q
    Q --> Compact
    Q --> Stop
    Engine --> Persist
Loading

3. QueryEngine 与 query.ts 的分工

3.1 QueryEngine

更偏会话级编排：

  • 持有 mutableMessages
  • 持有 readFileState
  • 累积 totalUsage
  • 管理 abort controller
  • 负责与 session storage、SDK 兼容层对接

3.2 query.ts

更偏单次 turn 的执行状态机：

  • 请求前上下文处理
  • 流式响应消费
  • tool_use 检测
  • tool_result 回填
  • compact/recovery
  • stop hook 执行

4. 核心流程

sequenceDiagram
    participant U as User
    participant E as QueryEngine
    participant Q as query.ts
    participant API as Claude API
    participant T as Tools

    U->>E: submitMessage(...)
    E->>Q: query(params)
    Q->>API: send request
    API-->>Q: stream assistant blocks
    Q->>Q: detect tool_use
    Q->>T: runTools(...)
    T-->>Q: tool_result
    Q->>API: continue next iteration
    Q-->>E: final messages / usage / events
Loading

5. 为什么说它是状态机

src/query.ts 中维护了显式状态：

  • messages
  • toolUseContext
  • autoCompactTracking
  • recovery count
  • transition reason
  • turn count

这意味着 Claude Code 每回合都可能进入不同分支：

  • 正常结束
  • 工具调用继续
  • prompt too long 恢复
  • max_output_tokens 恢复
  • auto compact
  • reactive compact
  • stop hooks

因此它绝不是一次 request-response 的轻量 wrapper。

6. Compact 在 Query Engine 中的位置

compact 不是离线工具，而是 query loop 的内建能力。

相关能力包括：

  • auto compact
  • reactive compact
  • micro compact
  • snip compact

它们的目的都是在不破坏会话连续性的前提下，把上下文压到可继续运行的范围内。

7. Tool Loop

query.ts 一旦收到 tool_use，不会直接结束，而是：

  1. 调用 runTools()
  2. 把结果封成 tool_result
  3. 追加回消息链
  4. 再次向模型发请求

这就是 Claude Code 变成 agent runtime 的核心闭环。

8. Stop Hooks

当一轮真正结束时，query/stopHooks.ts 会被触发，处理如：

  • 自动记忆提取
  • auto dream
  • 其它回合结束后动作

所以 stop hooks 是 query loop 的“尾插阶段”。

9. 核心源码入口

9.1 src/QueryEngine.ts

重点看：

  • QueryEngineConfig
  • submitMessage()
  • 内部会话状态字段

9.2 src/query.ts

重点看：

  • query()
  • queryLoop()
  • tool loop
  • compact / recovery 分支

10. 设计亮点

  • 会话级状态与回合级状态分离
  • 工具调用天然是多轮循环的一部分
  • compact、budget、hooks 都内建在主循环
  • 既能服务 REPL，也能服务 headless/SDK

11. 阅读建议

建议打开源码时同时对照：

  1. QueryEngine.ts
  2. query.ts
  3. services/tools/toolOrchestration.ts
  4. services/compact/*
  5. query/stopHooks.ts