一次请求的七步装配 —— 1,132 行里发生了什么
Q04 讲到 Conversation 决定「再问一次模型」,它只做一件事:
发布 llm.request。
从这条事件到真正发出去的 HTTP 请求之间,横着一个
packages/core/src/event-bus/llm/request-preparation.ts(1,132 行)。
本章把它拆成七步,每一步回答一个具体问题。
一、LlmHandler 只有四个方法
packages/core/src/event-bus/llm-handler.ts 共 312 行,
类本身只有四个方法(:54-142):
| 方法 | 行 | 职责 |
|---|---|---|
register() |
:54-58 |
只订阅 llm.request 一个事件 |
handle() |
:61-71 |
取 state、校 round,然后 void 启动 |
runRound() |
:73-112 |
装配 → 推理 → 结算,三行调用 |
settle() |
:114-142 |
写 round.modelResult,发布 llm.settled |
runRound 的骨架非常短(:73-112):
private async runRound(state: QueryState, round: QueryRound): Promise<void> { const ctx: LlmRoundContext = { state, round, signal: state.control.abort.signal, emit: (output) => emitOutput(this.bus, state, output), }; const preparation = await prepareRequest(ctx); if (preparation.kind === 'stopped') { this.settle(state, round, { ...emptyResult(preparation.prepared), outcome: 'failed', failure: preparation.failure, error: preparation.error, }); return; } const inference = await runInference( ctx, preparation.request, (block, responseId, assistantMessageUuid) => publishFor( this.bus, state, 'llm.tool_use', { block, responseId, assistantMessageUuid }, round.roundId, ), ); this.settle( state, round, assembleModelResult( ctx, preparation.prepared, preparation.request, inference, ), );}三个动词:准备、推理、结算。这跟 Q03 讲的「handler 只做一件事」一致—— LlmHandler 不决定继续还是收工,只管把这一轮跑完然后广播结果。
注意 handle() 里用的是 void this.runRound(...)(:67),
故意不 await。事件总线的订阅者回调不能阻塞发布方,
出错时通过 bus.reportFailure('llm', event, error) 转成 handler.failed 事件。
二、prepareRequest:36 行门面,四个分支
prepareRequest(:209-244)只做前置处理,真正的装配交给 assembleRequest:
export async function prepareRequest( ctx: LlmRoundContext,): Promise<PreparationResult> { const { state, round, signal } = ctx; const { input } = state; const options = input.params; const work: PreparationWork = { runtime: state.runtime, model: state.model, sessionContextReason: state.sessionContextReason, }; if (!work.model) await selectInitialModel(ctx, work); if (round.reason === 'reactive_compact') { const recovered = await runReactiveCompact(ctx, work); if (!recovered) { return { kind: 'stopped', failure: 'reactive_compact_failed', prepared: preparedFrom(ctx, work), error: round.cause, }; } } if (round.reason === 'tool_results' && options.attachmentCtx) { await injectInterTurnAttachments(ctx, work, options.attachmentCtx); } if (signal.aborted) { return { kind: 'stopped', failure: 'aborted_before_request', prepared: preparedFrom(ctx, work), }; } return assembleRequest(ctx, work);}四个分支的顺序有讲究:
- 没选过模型就先选 ——
selectInitialModel只在第一次请求时跑; - 反应式压缩优先 —— 它是上一轮
prompt_too_long的补救,必须先于一切; - 工具返回后补附件 —— 只有
reason === 'tool_results'才注入回合间附件; - 最后查中止 —— 前面几步都是
await,期间用户可能已经取消。
kind 只有两个值:stopped 与 ready。
所有「不该发了」的情况都收敛成 stopped + 一个 LlmFailureKind,
由 LlmHandler 统一转成 outcome: 'failed' 结算。
三、七步装配
assembleRequest(:669-1010,342 行)是整个内核最长的一个函数。
按执行顺序切成七步:
| # | 步骤 | 做什么 | 行 |
|---|---|---|---|
| 1 | 输出上限重选 | maxOutputTokensOverride 变了就重选模型 |
:686-711 |
| 2 | 环境消息 | 注入环境上下文(getEnvironmentMessages) |
:723-733 |
| 3 | 待发回合物化 | requestMessages.prepare() 把 pending 拆成消息 |
:739-743 |
| 4 | 钩子补注入 | 抽干异步钩子上下文与迟到的附件 | :748-775 |
| 5 | 压缩 | compressionPipeline.compress() |
:799-925 |
| 6 | 会话上下文 | 注入 session context(含 git 快照) | :930-946 |
| 7 | 编号与容量 | 分配 modelRequestId、查上下文上限 |
:948-999 |
第 5 步是唯一会替换整个历史的步骤。压缩成功后要重放全部消息
(:891),让消费端能重建可见会话;然后重新装配一次会话:
work.runtime = createContinuationState( work.runtime, { messages: nextMessages }, { reason: 'next_turn' },);// 历史已经替换,不复用压缩前的 usage 或投影结果。latestUsage = undefined;conversation = prepareConversation();所以 prepareConversation 在 assembleRequest 里一共被调用 3 次:
一次初装、一次压缩后、一次会话上下文注入后。
每次都重算 token 数——因为每次的输入都不一样。
四、消息拼装:三段拼一
prepareRequestConversation(packages/core/src/event-bus/llm/request-preparation-helpers.ts:33-86)
负责把历史变成「能发给模型的消息数组」。
普通路径(非 fork)只有三行核心(:63-67):
runtimeMessages = [...prefixMessages, ...history, ...pendingTurnMessages];// Prefix and history are normalized together so adjacent user messages merge// identically in the parent request and every cache-sharing fork. The prefix// is ephemeral and never stored in conversation history.messages = normalizeMessagesForAPI(runtimeMessages, projectionOptions);三段含义:
| 段 | 来源 | 是否入历史 |
|---|---|---|
prefixMessages |
startupMemoryPrefix(启动记忆) |
否,临时 |
history |
getRequestBaseHistory(state, pendingTurnMessages) |
是 |
pendingTurnMessages |
本回合尚未落盘的用户消息 | 请求后落盘 |
注释里那句「Prefix and history are normalized together」是关键。 如果把 prefix 单独归一化再拼接,相邻的两条 user 消息合并逻辑 会跟父请求不一致——而 fork 出来的子请求要共享 prompt 缓存, 前缀差一个字节,缓存就全失效。
所以这里强制先拼再归一化。代价是 runtimeMessages 保留全量,
token 计数要基于它而不是 messages 算——countRequestTokens 同时收两者(:70-78)。
五、工具清单怎么来
getToolSchemas(packages/core/src/event-bus/llm/request-preparation.ts:162-173)只有 12 行:
export function getToolSchemas( state: QueryState, modelKey: string,): ModelStreamTool[] { return ( state.input.params.toolRegistry?.getSchema(modelKey, { // The CLI intentionally has no model allowlist for this prompt behavior. // `--bare` is the only minimal mode and never enters a // tool-bearing query. preReadLineDropped: state.input.params.preReadLineDropped !== false, }) ?? [] );}两点值得注意:
- 按模型取 schema:
getSchema(modelKey, ...)而不是无参。 不同模型支持的工具集可能不同(比如某些模型不支持并行调用); - 没有工具就返回空数组,不是
undefined。 空数组在协议层表示「这个请求不带工具」, 而undefined会被某些 provider 当成「用默认工具」。
preReadLineDropped 这个参数控制一个降级行为:
把工具描述里的首行去掉。这是为小上下文模型准备的——
工具描述的首行通常是长句说明,占用不少 token。
六、推理:一个回调撑起流式
runInference(packages/core/src/event-bus/llm/inference-round.ts:47-238,192 行)
负责真正调用模型。它的签名有个特点——第三个参数是回调:
export async function runInference( ctx: LlmRoundContext, assembled: AssembledRequest, dispatchToolUse: ToolUseDispatcher,): Promise<InferenceResult> {dispatchToolUse 在模型流出 tool_use 块的那一刻被调用,
LlmHandler 传进去的实现就是「发布 llm.tool_use 事件」:
(block, responseId, assistantMessageUuid) => publishFor( this.bus, state, 'llm.tool_use', { block, responseId, assistantMessageUuid }, round.roundId, ),这条链路让工具可以在模型还没说完时就开始执行。
ToolHandler 订阅 llm.tool_use(Q03 讲过),收到就去跑工具,
不必等 llm.settled。并行工具调用的加速就来自这里。
llm.settled 与 llm.tool_use 的分工:
| 事件 | 时机 | 消费者用它做什么 |
|---|---|---|
llm.tool_use |
流中出现工具块时 | Tool 立刻开跑 |
llm.settled |
整个响应结束 | Conversation 决定下一步 |
七、结算:把流结果拍扁成快照
assembleModelResult 把「流式过程」压成「一份可判定的事实」。
它调的两个函数在 packages/core/src/event-bus/llm/result-assembly.ts:
extractToolUseBlocks(:27-38,12 行):
export function extractToolUseBlocks( message: ModelMessage, config?: Config, capturedMcpIdentities?: Map<string, McpInfo>,): ModelToolUseBlock[] { return message.blocks.flatMap((block) => { if (block.type !== 'tool_use') return []; const tool = normalizeModelToolUseBlock(block); captureMcpToolIdentity(tool, config, capturedMcpIdentities); return [tool]; });}splitAssistantMessage(:41-106)做另一件事:把一个 ModelMessage
按块拆成多条 AssistantMessage。
为什么拆?因为历史存储是按块索引的。
一个响应里有 2 段文本 + 3 个工具调用,就要拆成 5 条记录,
每条带自己的 index。最后一块才承载 stopReason 和 usage(:74-75):
const blockMessage: ModelMessage = { ...message, stopReason: isLastBlock ? message.stopReason : undefined, usage: isLastBlock ? message.usage : undefined, blocks: [normalizeModelBlockForHistory(block)],};否则 5 条记录每条都带一份 usage,累计起来就是 5 倍。
结算函数 settle() 还有个双保险(packages/core/src/event-bus/llm-handler.ts:114-117):
private settle(state: QueryState, round: QueryRound, result: ModelResult) { if (this.store.get(state.input.queryId) !== state) return; if (state.round !== round || round.modelResult) return; round.modelResult = result;两个 if:state 已销毁(查询结束)、round 已换或已有结果,都直接丢弃。
llm.settled 因此永远只会发一次。
八、失败分类:八种,一个函数
classifyRequestFailure(packages/core/src/event-bus/llm-handler.ts:159-170)
把异常映射成 LlmFailureKind(8 种):
function classifyRequestFailure( signal: AbortSignal, error: unknown,): LlmFailureKind { const isAbort = signal.aborted || error?.name === 'AbortError'; if (isAbort) { return 'aborted'; } if (isPromptTooLongError(error)) return 'ptl'; if (getErrorStatus(error) === 406) return 'refusal_406'; return 'transport';}这里只判四种,另外四种(aborted_before_request / context_limit /
reactive_compact_failed / max_tokens_escalatable)由
prepareRequest 或结果装配阶段直接给出。
顺序很重要:先判 signal.aborted,再判错误类型。
用户取消时异常常常是 AbortError,但也可能是网络层抛的 TypeError;
只要信号是中止状态,一律归为 aborted,不被错误类型带偏。
406 这个状态码硬编码在这里——它表示模型拒绝回答(内容安全)。
单独分出一个 refusal_406 而不是并进 transport,
因为两者的处理完全不同:transport 可以重试,refusal 必须直接收工。
九、工程暗坑
1. prepareConversation 的返回值必须重新赋给 conversation
assembleRequest 里三次调用都写成 conversation = prepareConversation(...)。
如果只 await 不赋值,压缩后仍然用旧的历史发请求——
压缩等于白做,下一个请求立刻又 prompt_too_long。
2. 压缩后 latestUsage 必须置 undefined
源码注释写得很直白(:915):
// 历史已经替换,不复用压缩前的 usage 或投影结果。latestUsage = undefined;latestUsage 是用来估算 token 的。压缩前的 usage 对应的是旧历史,
拿它当新历史的基线,估算值会偏大,导致连续误触发压缩。
3. yieldToEventLoop() 之后必须重查中止
:992-999 这段:
await yieldToEventLoop();if (signal.aborted) { return { kind: 'stopped', failure: 'aborted_before_request', prepared: preparedFrom(ctx, work, baseExtra), };}yieldToEventLoop 把控制权交回微任务队列,让消费端读完准备阶段的消息。
这一让,用户就可能在此时点下取消。所以让出前后各查一次
(前面 :237 一次、这里一次),中间那段窗口不能漏。
4. 工具 schema 为空数组不等于「没工具」
getToolSchemas 的 ?? [] 会让「registry 返回 undefined」和
「registry 明确返回空」变成同一个值。
Q04 里 needsToolSettlement 判的是 toolExecutor !== undefined,
不是 schema 非空——这个设计上是对的(有执行器就可能要结算),
但如果你的自定义 provider 需要区分两者,得自己加标志。
5. splitAssistantMessage 的 includeEmpty 控制空响应
响应为空时(:57-69),includeEmpty: true 会造一条空 AssistantMessage,
false 则返回空数组。
中断场景必须 true——否则历史里什么都没有,
下一轮模型看不到「上次被打断了」。
十、本章源码索引
| 文件 | 行数 | 本章用到的位置 |
|---|---|---|
packages/core/src/event-bus/llm-handler.ts |
311 | :54-58 register,:61-71 handle |
:73-112 runRound,:114-142 settle,:159-170 失败分类 |
||
packages/core/src/event-bus/llm/request-preparation.ts |
1,132 | :209-244 prepareRequest |
:162-173 getToolSchemas,:669-1010 assembleRequest |
||
packages/core/src/event-bus/llm/request-preparation-helpers.ts |
200 | :33-86 prepareRequestConversation |
packages/core/src/event-bus/llm/inference-round.ts |
238 | :47-238 runInference |
packages/core/src/event-bus/llm/result-assembly.ts |
126 | :27-38 extractToolUseBlocks |
:41-106 splitAssistantMessage |
||
packages/core/src/event-bus/llm/inference.ts |
142 | :104- toTurnStepResult |
十一、自己动手验证
node qw-examples/check/05-request-prep.mjs预期输出:
llm subscribes: 1methods: 4prepare kinds: kind: 'ready',kind: 'stopped'prepareConversation calls: 3prepareRequest span: 36 start line 209LlmFailureKind: 8tokenCount inputs: 9 311 event-bus/llm-handler.ts 1132 event-bus/llm/request-preparation.ts 200 event-bus/llm/request-preparation-helpers.ts 142 event-bus/llm/inference.ts 238 event-bus/llm/inference-round.ts 126 event-bus/llm/result-assembly.ts改一处试试:把 prepareRequestConversation 里的
messages = normalizeMessagesForAPI(runtimeMessages, ...) 改成两次归一化——
先 normalizeMessagesForAPI(prefixMessages) 再拼 history。
跑一次 fork 子代理,观察 prompt 缓存命中率:会从接近 100% 掉到很低。
这就是注释里那句「prefix and history are normalized together」的代价。
十二、下一步
本章的「消息」始终是个黑箱——我们知道有三段拼起来,
但不知道 Message 这个类型里到底有什么。
下一章 Q06 拆 packages/core/src/protocol/ 这一层:
一份内部消息如何投影成三家 provider 的格式,以及为什么投影层要独立存在。
本章读完你应该能回答: ①
llm.request到 HTTP 请求之间有几个阶段? ——prepareRequest前置四分支 +assembleRequest七步。 ② 为什么prepareConversation要调三次? ——初装、压缩后、会话上下文注入后,输入都变了。 ③ 工具为什么能在模型说完之前开跑? ——llm.tool_use是流中事件,不等llm.settled。 ④ 一个响应为什么要拆成多条AssistantMessage? ——按块索引存储,最后一块才带stopReason与usage。 ⑤ 用户取消时为什么不会被误判成网络错误? ——先判signal.aborted,再看错误类型。