1. 从一次「卡住」的对话说起QueryEngine 与 queryLoop 到底在干什么如果你把 Claude Code 当成一个黑盒输入一句话它读文件、改代码、跑命令最后给你一段总结——看起来就是「一问一答」。但真正跑起来你会发现一次提问背后可能藏着十几轮模型调用模型先说要读某个文件框架执行读取把结果塞回去模型再决定改哪一行框架执行写入再塞回去……直到模型说「我完成了」。这套机制的核心检索词就是Claude Code QueryEngine 与 queryLoop 源码解析。QueryEngine 是会话层的外壳负责「这一通对话」的状态queryLoop 是执行层的状态机负责「这一次查询」内部的循环。两者通过 async generator 串起来形成一条可背压的流。它适合谁适合已经用过 Claude Code、想搞清楚「为什么我的对话会突然压缩」「为什么工具调用顺序和我预期不一样」「为什么有时候报 prompt_too_long 但重试又好了」的开发者。你不需要通读全部源码只要抓住几个关键函数和数据流就能在本地对照定位。我先说结论对话不是一次 API 就结束而是一个长寿命、有状态、可并行、可压缩、可中断的管线。产品交互像一问一答运行时却是多轮循环。理解这个矛盾后面所有代码就都顺了。这一章我会带你走完用户输入 → 会话层预处理 → queryLoop 迭代 → 模型流式响应 → 工具回注 → 终止判断。每一步都给可复制的配置片段和验证方法让你能在本地跑起来对照。2. 前置准备用 TaoToken 接入 Claude Code 并拿到可调试的环境在对照源码之前你得先有一个能跑起来的 Claude Code 环境否则光看代码很难验证「工具回注到底发生在哪一步」。这里我用 TaoToken 作为接入层它的 API 地址是https://taotoken.net/api兼容 Anthropic 的接口格式配置起来比较直接。第一步去控制台创建一个 API Key。打开https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentconsole登录后在 API Keys 页面新建一个密钥复制出来备用。注意密钥只显示一次丢了就重新建。第二步配置 Claude Code 的环境变量。Claude Code 读取ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY两个变量。你可以在 shell 里临时导出也可以写进配置文件。我建议写进~/.claude/settings.json这样每次启动都生效{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的密钥, ANTHROPIC_MODEL: claude-sonnet-4-20250514 } }如果你用的是 Claude Code 的 CLI也可以直接在启动时指定export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEYsk-你的密钥 claude第三步确认模型 ID。不同版本的 Claude Code 默认模型可能不同你可以在settings.json里显式写死ANTHROPIC_MODEL避免它去请求一个你账号没权限的模型。常见的可用 ID 包括claude-sonnet-4-20250514、claude-opus-4-20250514等具体以你账号实际可用的为准。注意Base URL 后面不要加/v1Claude Code 会自己拼接路径。如果你写成https://taotoken.net/api/v1请求会变成/v1/v1/messages直接 404。配置好之后跑一个最小验证claude -p 用一句话说明什么是 async generator如果能看到正常回复说明接入层通了。接下来我们才能安心去看源码里的 queryLoop 是怎么驱动这条链路的。3. 可复制配置把 QueryEngine 与 queryLoop 的关键参数落到本地要对照源码调试光能跑还不够你得让 Claude Code 输出足够多的中间信息。这一节我给你一份可复制的配置包含环境变量、settings.json 片段以及几个能触发不同代码路径的测试用例。先看完整的~/.claude/settings.json{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的密钥, ANTHROPIC_MODEL: claude-sonnet-4-20250514, CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY: 10, MAX_THINKING_TOKENS: 8000 }, permissions: { allow: [ Read, Glob, Grep ], ask: [ Bash, Write, Edit ] } }这里有几个参数直接对应源码里的行为。CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY对应getMaxToolUseConcurrency()默认 10控制并发批的大小。permissions.allow里的只读工具会被标记为 concurrency safe可以并行执行ask里的写操作会串行并且触发权限弹窗。如果你想观察工具回注的顺序可以故意把并发调低{ env: { CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY: 1 } }这样所有工具调用都会串行你能在输出里清楚看到「模型输出 tool_use → 工具执行 → tool_result 回注 → 模型继续」的完整节奏。再给你一个能触发 AutoCompact 的测试用例。AutoCompact 的触发线由AUTOCOMPACT_BUFFER_TOKENS 13000等常量控制当上下文接近窗口上限时自动摘要。你可以让 Claude Code 读一个大文件claude -p 读取 src/query.ts 并总结 queryLoop 的状态机结构如果文件足够大你会看到它先读文件然后可能触发压缩再继续分析。这个过程在源码里对应deps.autocompact调用autoCompactIfNeeded。还有一个能触发 Stop Hooks 的场景。Stop Hooks 在无 tool_use 时执行你可以配置一个 Stop 命令{ hooks: { Stop: [ { matcher: , hooks: [ { type: command, command: echo stop hook fired /tmp/claude-stop.log } ] } ] } }跑一次普通对话然后检查/tmp/claude-stop.log如果里面有内容说明handleStopHooks走到了executeStopHooks。这能帮你确认「模型说完了」之后框架还做了什么。提示调试时建议把ANTHROPIC_LOG或 Claude Code 的 verbose 模式打开能看到更多请求级信息。具体变量名以你使用的版本为准。4. 验证请求从用户输入到模型响应与工具回注的完整闭环配置好了现在我们来实际跑一遍对照源码看数据流。这一节我会用一个具体任务把「用户输入 → 会话层 → queryLoop → 模型 → 工具 → 回注」每一步都标出来。任务让 Claude Code 读取一个文件统计其中的函数数量然后写一个总结。claude -p 读取 src/query.ts统计里面有多少个 export function然后告诉我第一步用户输入进入会话层。在源码里这对应QueryEngine.submitMessage()。它会做几件事包装canUseTool、拼 System Prompt、处理斜杠命令。如果输入是普通文本shouldQuery为 true就进入for await (x of query({...}))。第二步query()外壳调用yield* queryLoop(params, consumedCommandUuids)。queryLoop 是真正的状态机它维护一个State对象包含messages、toolUseContext、turnCount、transition等字段。每次迭代顶部解构 statecontinue 前整体重新赋值。第三步消息窗口处理。getMessagesAfterCompactBoundary(messages)去掉压缩边界之前的内容applyToolResultBudget处理超大工具结果。然后进入deps.callModel传入messagesForQuery、systemPrompt、tools、signal等。第四步模型流式返回。模型看到任务后决定调用 Read 工具。它输出的 assistant 消息里包含一个tool_useblock内容是{ name: Read, input: { file_path: src/query.ts } }。第五步工具编排。queryLoop 检测到有 tool_use调用runTools或StreamingToolExecutor。partitionToolCalls把连续且isConcurrencySafe为真的调用合成一批。Read 是只读工具通常被标记为并发安全所以可以和其他只读操作并行。第六步工具执行并回注。Read 工具读取文件内容构造一个tool_resultblock以user 消息的形式追加到消息列表。这是 API 约束工具结果必须作为 user 角色回传。源码里由createUserMessage等函数构造。第七步模型继续。模型收到 tool_result 后看到文件内容开始统计 export function 数量。如果文件很大可能触发 microcompact 或 autocompact。如果统计完成模型输出最终文本没有 tool_use进入 Stop Hooks。第八步终止。handleStopHooks执行用户配置的 Stop 命令返回{ blockingErrors, preventContinuation }。如果没有阻塞错误queryLoop 返回 terminalquery()补发notifyCommandLifecycle会话层把内部 Message 规范化为 SDKMessageyield 给调用方。你可以用这个命令观察每一步的耗时time claude -p 读取 src/query.ts统计 export function 数量如果工具回注正常你会看到总耗时明显大于单次模型调用因为中间多了文件读取和可能的压缩。实测下来一个中等大小的文件完整闭环大概在 5 到 15 秒之间取决于模型响应速度和工具执行时间。注意如果你看到tool_use_id不匹配的报错通常是流式降级时 tombstone 没处理好。源码里onStreamingFallback触发后会discard()并重建 StreamingToolExecutor避免 tool_use 和 tool_result 错位。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth这一节我整理了几个在对照源码调试时最容易撞上的报错每个都给出原因和排查路径。这些报错在 queryLoop 的不同阶段触发理解它们能帮你快速定位问题出在会话层还是执行层。401 Unauthorized。这个最常见出现在deps.callModel发起请求时。原因通常是 API Key 无效或 Base URL 配错。检查ANTHROPIC_API_KEY是否以sk-开头ANTHROPIC_BASE_URL是否是https://taotoken.net/api不带/v1。如果你用的是 settings.json确认 JSON 格式没写错特别是逗号和引号。可以用curl直接测curl -X POST https://taotoken.net/api/v1/messages \ -H x-api-key: sk-你的密钥 \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d {model:claude-sonnet-4-20250514,max_tokens:100,messages:[{role:user,content:hi}]}如果 curl 通了但 Claude Code 报 401说明是 Claude Code 读取配置的路径不对检查它实际加载的是哪个 settings 文件。local proxy failed。这个报错说明 Claude Code 尝试走本地代理但连接失败。检查你的环境变量里有没有HTTP_PROXY、HTTPS_PROXY之类的设置如果有先 unset 掉。另外确认没有其他程序占用 Claude Code 期望的本地端口。这个错误和网络环境有关排查时优先看环境变量。reading choices 相关报错。这通常出现在模型返回的响应格式不符合预期时比如流式 chunk 解析失败。源码里deps.callModel返回的是 async iterable如果某个 chunk 的choices字段为空或结构异常解析就会出错。排查方法是打开 verbose 日志看原始响应。如果频繁出现可能是模型 ID 不匹配换一个确认可用的模型试试。OAuth 相关报错。如果你用的是需要 OAuth 的接入方式报错通常和 token 过期或 scope 不足有关。检查你的认证流程是否完整token 是否刷新。如果同时配了 API Key 和 OAuth确认优先级避免冲突。还有一个容易忽略的prompt_too_long。这个不是配置错误而是上下文真的超了。源码里 queryLoop 会先尝试压缩microcompact、autocompact如果压缩后还是超才会把错误暴露给上层。如果你看到这个报错说明压缩策略没救回来可以考虑手动/clear或减少单次任务的文件量。提示排查时按「会话层 → 执行层 → 模型层」的顺序定位。401 和 OAuth 在模型层local proxy failed 在会话层reading choices 在流式解析层prompt_too_long 在执行层的压缩逻辑。6. 继续深入用 TaoToken 的 Coding Plan 长期跑 Agent 任务把 QueryEngine 和 queryLoop 的链路搞清楚之后你会发现 Claude Code 真正强大的地方在于它能长时间跑 Agent 任务读代码、改代码、跑测试、修错误循环几十轮。这种场景对 API 的稳定性和成本控制要求比较高。如果你打算长期用 Claude Code 做编码或 Agent 任务可以看看 TaoToken 的 Coding Plan。它针对高频调用做了优化适合这种多轮循环的场景。入口在这里https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentcoding-plan。另外如果你想单独验证某个模型的行为比如确认claude-sonnet-4-20250514在工具调用上的表现可以用模型对话页面直接测https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentchat。接入文档在https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentdoc里面有完整的参数说明和示例。回到源码本身我建议你按这个顺序读先看query.ts顶部的State类型和queryLoop的 while 循环骨架再看deps.callModel的调用点然后看runTools和StreamingToolExecutor的分支最后看QueryEngine.submitMessage怎么把这一切包起来。每读一段就用上面给的命令跑一次观察实际行为。这样比从头到尾通读高效得多。最后留一个实用技巧在settings.json里把CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY设成 1然后跑一个需要读多个文件的任务。你会看到工具调用严格串行每个 tool_result 回注后才发起下一个。这个观察能帮你直观理解「工具回注」在循环里的位置——它不是一个附加步骤而是驱动下一轮迭代的必要输入。