查询引擎
这是整个 Claude Code 最核心的代码。如果你只看一个文件，看 query.ts。1200+ 行的 while 循环，每一轮都是一次完整的 AI 交互。
双文件架构
查询引擎分成两个文件，职责不同：
- QueryEngine.ts（~1000 行）— 会话管理器，维护消息列表、token 统计、会话生命周期
- query.ts（~1200 行）— 核心查询循环，每一轮的具体逻辑
查询循环的 11 步
query.ts 的核心是一个 while 循环。每一轮迭代包含：
第 1-4 步：上下文压缩
1. Snip 压缩 — 标记过期内容（feature-gated）
2. 微压缩 — 工具结果级别的精简
3. 上下文折叠 — 折叠不重要的历史（feature-gated）
4. 自动压缩 — 上下文过大时触发完整压缩为什么需要 4 种压缩？因为 AI 的上下文窗口是有限的（200K token），而一次复杂的编程任务可能产生大量工具调用结果。不压缩的话，几轮下来就把上下文撑爆了。
4 种压缩的粒度不同：snip 最轻量（打个标记），自动压缩最重（调 AI 做摘要）。系统会根据当前上下文使用率选择合适的策略。
第 5 步：Token 预算
typescript
// BudgetTracker 计算本轮可用 token
const budget = calculateBudget({
contextWindow: 200_000,
currentUsage: messages.tokenCount,
compressionThreshold: 0.7 // 70% 时触发压缩
})预算系统会在 70%-95% 的范围内动态调整，既要给 AI 足够的输出空间，又不能浪费上下文。
第 6 步：API 调用
带着裁剪后的消息和 token 预算，调用 Claude API。流式返回。
第 7 步：流式工具执行
AI 响应中如果包含工具调用，边接收边执行。支持并发——多个工具调用可以同时跑。
第 8 步：回填工具结果
工具执行完毕，结果拼入消息列表，作为下一轮循环的输入。
第 9-11 步：收尾检查
9. 阻塞限制检查 — 是否触及 API 限流
10. 错误恢复 — 4 级恢复机制
11. 停止钩子检查 — 是否该结束循环错误恢复机制
4 级递进恢复，从轻到重：
| 级别 | 策略 | 触发条件 |
|---|---|---|
| 1 | 反应式压缩 | 上下文超限 |
| 2 | 上下文折叠排空 | 压缩后仍超限 |
| 3 | 最大输出 token 恢复 | 输出被截断 |
| 4 | 媒体错误恢复 | 图片/文件处理失败 |
这种递进式设计很有经验——先试最小代价的修复，不行再升级。不会一上来就用最激进的策略。
Token 预算系统
BudgetTracker 负责精细化管理上下文窗口：
- 压缩触发阈值：上下文使用 70% 时开始压缩
- 强制压缩阈值：95% 时强制执行
- 输出预留：始终为 AI 响应保留足够空间
- 缓存感知：prompt cache 命中的 token 成本更低
循环终止条件
while 循环什么时候停？
- AI 没有返回工具调用（纯文本响应）
- 达到最大轮次限制（
--max-turns） - 停止钩子返回 true
- 遇到不可恢复的错误
- 用户手动中断（Ctrl+C）