Pi Agent 源码级教程
M04

模型调用 —— 一行代码背后的十层翻译

9,082 字 · 含 470 行代码 · 约 45 分钟

M03 里有一行代码被我们跳过了:

ts
const stream = streamSimple(model, context, options);

一行。它背后是 packages/ai 的 28,581 行、206 个文件。

这一章拆这行。拆完你应该能回答五个问题:

  • 为什么必须有两层(stream / streamSimple)
  • 接入一个新模型要改几个文件
  • 一个"看起来正确"的错误处理写法错在哪
  • 缓存到底是默认开着还是默认关着
  • --model 那串字符是怎么变成一个 Model 对象的

正文里的代码块为贴合 80 列做过折行(原文件多为单行),语义不变。


零、读这章之前,你需要先知道一件事

流式与增量:模型不是等全部生成完再返回,而是一边生成一边把片段吐出来; 每次吐出的那一小段叫增量(delta),拼起来才是完整回答。

没有它会怎样:以为 stream() 返回的是一个字符串。它返回的是一串事件, text_delta 里的 delta 要你自己拼——不拼就只能看到一堆碎片。

本书哪里用到:§二 四个维度里的"返回形状";事件序列的完整体在 M07。


一、四个维度同时不一致

先说清楚要解决什么。

假设用户说了句"帮我读一下 main.ts"。在 Pi 内部它是一条统一消息:

ts
{ role: "user", content: "帮我读一下 main.ts", timestamp: 1748697600000 }

发给不同 provider,得翻译成四种样子:

text
Anthropic    { role: "user", content: [{ type: "text", text: "..." }] }OpenAI       { role: "user", content: "..." }Google       { role: "user", parts: [{ text: "..." }] }Bedrock      { role: "user", content: [{ text: "..." }] }

四种。差异点各不同:Anthropic 要数组加 type,Google 把 content 改名 parts,Bedrock 学 Anthropic 但不要 type。

纯文本是最简单的情况。真正的差异有四个维度:

维度 差在哪 一个例子
消息格式 字段名、结构、工具结果挂在哪 Anthropic 把工具结果塞进 user 消息,OpenAI 用独立 role: "tool"
流式传输 谁来解析字节流 Anthropic 返原始 SSE 要自己拆,OpenAI 的 SDK 直接给结构化 chunk
思考参数 怎么表达"多想想" Anthropic 给 token 预算,OpenAI 给努力程度,Google 给 thinkingConfig
缓存标记 怎么标记"这段没变" Anthropic 贴 cache_control,Bedrock 插独立 cachePoint 节点

四个维度乘以十个 API,就是这一层的全部工作量。

1.1 十个 api,不是一个数字

KnownApi(types.ts:64-74)正好十个取值。它们和翻译器文件是一一对应的:

api 翻译器 行数
openai-completions api/openai-completions.ts 1,729
openai-codex-responses api/openai-codex-responses.ts 1,720
anthropic-messages api/anthropic-messages.ts 1,687
bedrock-converse-stream api/bedrock-converse-stream.ts 1,462
mistral-conversations api/mistral-conversations.ts 925
google-vertex api/google-vertex.ts 562
google-generative-ai api/google-generative-ai.ts 466
pi-messages api/pi-messages.ts 466
openai-responses api/openai-responses.ts 454
azure-openai-responses api/azure-openai-responses.ts 256

十个体量差七倍。看两个极端:

  • openai-completions 最胖(1,729 行),因为它不是"一家"的协议,是一整个兼容圈(DeepSeek、Groq、Together、vLLM、Ollama……)的共同方言。同一份代码要兜住这些厂商各自的怪癖。
  • azure-openai-responses 最瘦(256 行),因为它几乎什么都不做——真正的活在共享层 openai-responses-shared.ts(892 行)里。Azure 只是改了鉴权和 URL。

所以"十个 api"不等于"十份独立工作量"。真实结构是:

text
独立实现    anthropic 1687   bedrock 1462   mistral 925            openai-completions 1729        codex 1720共享骨架    openai-responses 454  +  shared 892            google-generative-ai 466 + shared 575            google-vertex 562薄壳        azure 256 / pi-messages 466

十个翻译器合计 9,725 行,加上共享层 1,467 行,约 11,192 行——占整个 ai 包 28,581 行的 39%。将近四成代码只做一件事:把同一种意思翻译成十种方言。


二、分三层,但真正解耦的只有一条线

Pi 的切法:

text
第一层  入口        stream() / streamSimple()      查表 + 派活第二层  事件协议     AssistantMessageEvent(12 种)  约定输出第三层  翻译器        api/*.ts                     一种方言一个文件

类比国际翻译公司:前台查通讯录派活,翻译员各懂一门语言,但交付的报告必须用公司统一模板。前台不懂外语,翻译员不懂流程。

这个类比的要害是:第一层和第三层之间只靠第二层连接,互不知道对方存在。

但这里有一个比"三层"更重要的设计,藏在入口函数的第一行。

2.1 入口里藏了一个折叠动作

stream() 的骨架(compat.ts:252-267):

ts
export function stream<TApi extends Api>(	model: Model<TApi>,	context: Context,	options?: ProviderStreamOptions,): AssistantMessageEventStream {	const transcript = normalizeContext(context);            // ← 这一行	const builtinProvider = getBuiltinProviderForModel(model);	if (builtinProvider) {		// ... cloudflare 岔路,见 2.3		return builtinProvider.stream(model, transcript, ...);	}	const provider = resolveApiProvider(model.api);	return provider.stream(model, transcript, ...);}

normalizeContext 在 utils/transcript.ts:30-34,全文只有五行:

ts
export function normalizeContext(context: Context): TranscriptContext {	const initialMessage = createInitialSystemMessage(		context.systemPrompt,		context.tools,	);	const messages = initialMessage		? [initialMessage, ...context.messages]		: context.messages;	return { messages } as TranscriptContext;}

它把 Context(三个字段:systemPrompt、tools、messages)压成 TranscriptContext(一个字段:messages)。

系统提示词和工具定义被折进了首条消息。 再看 createInitialSystemMessage(transcript.ts:10-23):

ts
export function createInitialSystemMessage(	systemPrompt: string | undefined,	tools: Tool[] | undefined,): SystemMessage | undefined {	const hasSystemPrompt = systemPrompt !== undefined && systemPrompt.length > 0;	const hasTools = tools !== undefined && tools.length > 0;	if (!hasSystemPrompt && !hasTools) return undefined;	return {		role: "system",		content: systemPrompt ?? "",		...(hasTools ? { toolsAdded: tools } : {}),		timestamp: 0,	};}

注意 toolsAdded 这个名字。M03 第七节讲"变更即追加"时说过:工具集变化靠 system 消息的 toolsAdded / toolsRemoved 表达。这里就是那个字段的第一次写入。

两件事在这里合上了:

text
Context.tools  ──折进──→  messages[0].toolsAdded                                │                                ↓                        getCurrentTools(messages)  累加得出当前工具集

所以"工具集从 transcript 算出来"不是个精巧的算法,是因为源头就只有这一份数据。系统提示词同理——它不在别处,就在首条 system 消息的 content 里。

一个 Context 只有一种表示形式,就是 messages。 这是整个 ai 层最省事的一个决定:provider 只需要处理"一个消息数组",不需要知道 system prompt 和 tools 是独立概念。

顺带一个反直觉的地方:timestamp: 0。为什么不是 Date.now()?因为这条消息是推导出来的,不是"发生过的事件"。给它一个假时间戳才能保证同一次请求两次归一化产生字节完全相同的结果——2.2 和第七节的缓存都依赖这一点。

2.2 这条折叠有代价

代价是:首条 system 消息不能随便删。

压缩(M09)要扔掉老消息时,必须保住首条 system 消息,否则系统提示词和工具定义一起没了。你在 coding-agent 里看到的"压缩时总是保留开头"不是保守,是结构上的必须。

第二个代价是语义变窄:Context 上那个 systemPrompt 一旦折进去,就再也拿不回来了。想在请求途中"改一句系统提示词",唯一合法的做法是追加一条新的 system 消息(带 sections),而不是改第一条。M03 的"变更即追加"在 ai 层不是风格选择,是这个折叠逼出来的唯一解。

2.3 派活有两条路,还有一条岔路

stream() 里的 if (builtinProvider) 藏着三档优先级:

text
① builtin provider   compatModels.getProvider(provider) 里登记过的② registry           registerApiProvider() 现注册的(扩展、测试、faux)③ cloudflare 岔路     provider 名以 "cloudflare-" 开头且没有 key

判断函数 getBuiltinProviderForModel(compat.ts:238-242):

ts
function getBuiltinProviderForModel(model: Model<Api>) {	if (getApiProvider(model.api) !==		builtinApiProviderInstances.get(model.api)) return undefined;	const provider = compatModels.getProvider(model.provider);	const sameApi = provider?.getModels()		.some((candidate) => candidate.api === model.api);	return sameApi ? provider : undefined;}

第一行是身份比较,不是值比较。getApiProvider(model.api) 拿的是注册表里的当前实例,builtinApiProviderInstances 存的是内置实现。两者不等,说明有人用 registerApiProvider 覆盖了这个 api——此时必须让位,否则扩展就永远盖不掉内置实现。

这个设计在测试里很关键:providers/faux.ts(733 行)就是靠注册一个假 api 来让整个 Agent 循环在无网络环境下跑通。如果内置实现优先级硬编码在前,整套测试就没法做。

没有 builtin provider 时走 resolveApiProvider(:244-250):

ts
function resolveApiProvider(api: Api) {	const provider = getApiProvider(api);	if (!provider) {		throw new Error(`No API provider registered for api: ${api}`);	}	return provider;}

这是一个同步抛出——记下来,第四节要用。

第三条岔路是 Cloudflare:

ts
if (model.provider.startsWith("cloudflare-") &&	!hasResolvedCloudflareAuth(options)) {	return compatModels.stream(model, transcript, options);}

Cloudflare Workers AI 可以走 binding(进程内对象调用,根本没有 API key 的概念),这时不能走普通翻译器那条路。这类"平台特例"在任何多 provider 系统里都会长出来,Pi 的处理是只加一个 if,不污染抽象。

2.4 这个入口本身是临时的

看 compat.ts 的文件头注释(:1-11):

Temporary compatibility entrypoint preserving the old global pi-ai API surface... This module is deleted with the coding-agent ModelManager migration. New code uses createModels() and the provider factories.

也就是说,我们刚拆的 stream() 是一个兼容门面,v1.4.0 之后会被删掉。

那这一章还值得读吗?值得,因为新入口做的是同一件事。看 ModelsImpl.stream(models.ts:901-919):

ts
stream<TApi extends Api>(...): AssistantMessageEventStream {	const transcript = normalizeContext(context);          // ← 同一行	return lazyStream(model, async () => {		const provider = this.requireChatProvider(model);		const { requestModel, requestOptions } =			await this.applyAuth(model, options);		return provider.stream(requestModel, transcript, requestOptions);	}, observeModelRequest(model, options, false));}

normalizeContext 还在第一行。同一个折叠,写了两遍——这恰恰证明它是结构不变量,不是兼容层的偶然。

区别在两处,都很值得看:

  • 旧门面先解析 provider,再返回流;新入口把解析塞进 async () => {},先返回流。这个差异直接影响错误策略(见 5.3)。
  • 新入口多了一步 applyAuth:鉴权从"读环境变量"升级成了可插拔的凭据存储。

index.ts 开头的四行注释把整套分层写死了:

Core only, side-effect free: no generated catalogs, no provider factories, no api-registry, no OAuth implementations, no compat.

@earendil-works/pi-ai 是纯内核,provider 工厂在 /providers/*,api 实现在 /api/*,旧全局 API 在 /compat。一个包四个入口,靠子路径切开依赖性,而不是靠 tree-shaking 事后补救。


三、第二层:12 种事件

AssistantMessageEvent(types.ts:823-839)一共 12 个成员。下面这张表可以当查表用:

# type 额外字段 含义
1 start — 流建立,内容还没到
2 text_start contentIndex 一个文字块开始
3 text_delta contentIndex delta 推了一小段文字
4 text_end contentIndex content 文字块定稿
5 thinking_start contentIndex 思考块开始
6 thinking_delta contentIndex delta 推了一段思考
7 thinking_end contentIndex content 思考块定稿
8 toolcall_start contentIndex 工具调用开始
9 toolcall_delta contentIndex delta 推了一段 JSON
10 toolcall_end contentIndex toolCall 参数已可解析
11 done reason message 正常结束
12 error reason error 失败结束

除了 contentIndex 和 delta 这类差异字段,10 个事件还都带 partial(1 到 10 号),只有 done / error 不带——因为这两个不是"过程中的一帧",是终局。

不用记 12 个。记模式:三类内容 × 三步 + 两头。

text
start  text_start      → text_delta      → text_end  thinking_start  → thinking_delta  → thinking_end  toolcall_start  → toolcall_delta  → toolcall_enddone | error

为什么每类都是三步?因为流式。先声明"文字要开始了",然后逐字推,最后说"文字结束了"。

contentIndex 是这块内容在 content[] 数组里的下标。一轮回复可以同时有思考、文字、多个工具调用,靠这个下标区分。

3.1 done 的 reason 是四选一,不是三选一

ts
| { type: "done"; reason: ...; message: AssistantMessage }| { type: "error"; reason: ...; error: AssistantMessage };

那两个 ... 展开分别是:

ts
done   → Extract<StopReason, "stop" | "length" | "toolUse" | "deferred">error  → Extract<StopReason, "aborted" | "error">

大部分资料只写 stop / length / toolUse 三个。v1.4.0 有第四个:deferred——provider 说"这活儿长,我给你个句柄,你过一会儿再来取"。

这是 options.deferred 打开的能力(types.ts:381-382):

ts
/** Ask a capable provider to return a durable handle and *  continue the request asynchronously. */deferred?: boolean | { window?: "15m" | "1h" | "24h" };

deferred 不在 12 种事件里另开一个类型,它只是 done 的一个 reason 值。这选择省事:Agent 循环不认识"延迟",只看到"这轮结束,但没调用工具",于是正常收尾。内核那一侧 M03 §6.7 已讲,这里不再重复。

一个能力可以只用一个枚举值换进来。 这是加扩展时最便宜的位置——不动协议,不动消费方。

3.2 partial 不是快照

types.ts 在事件定义上方写了 16 行注释,其中最要命的一句:

partial is the shared live response-so-far helper, not an event-time snapshot.

它是"到目前为止的活响应",不是某一刻的快照。 也就是说,如果你把 event.partial 存进数组,之后所有元素都会变成最后一次的状态——因为它们是同一个对象。

M03 第八节讲过循环那边怎么处理(每次 { ...partialMessage } 浅拷一份)。这里补充另一半:为什么 provider 不直接给增量?

因为增量要求消费者维护状态机:"这是第几个 block、拼到第几个字符、thinking 和 text 交错怎么办"。全量快照把这些全免了——消费者只需要"覆盖"。

代价是每次事件都传一份完整消息,带宽略大。这是典型的用带宽换状态。

3.3 contentIndex 和"活引用"合起来会咬人

单看两条都没问题,合起来有个坑:你不可能只记下 partial 的一个片段。

ts
const textSoFar = new Map<number, string>();session.subscribe((e) => {	if (e.type === "text_delta") {		// 想"只存当前这块文字"——做不到,因为 partial 是整条消息		textSoFar.set(e.contentIndex, e.partial.content[e.contentIndex].text);	}});

这行看着对,其实读的是整条消息的第 N 个 block,不是"第 N 个 delta"。如果 partial 恰好在这一帧把后面的 block 也填了(某些 provider 会提前把工具调用参数塞进来),你读到的就不是你以为的那块。

正确姿势只有两个:要么整体浅拷贝({ ...e.partial }),要么只用 e.delta 自己拼。不要混用——delta 是增量,partial 是全量,混着读会出现"文字重复一遍"这种经典 bug。

3.4 流对象自己也有终局

前 12 种事件都是"给 for await 看的"。但流对象还有另一个出口,不走迭代器:result()。

实现在 utils/event-stream.ts,一共 135 行。核心是 EventStream<T, R> 里的两个队列和一段 push:

ts
push(event: T): void {	if (this.done) return;                        // ① 终局之后直接丢	if (this.isComplete(event)) {		this.done = true;		this.resolveFinalResult(this.extractResult(event));	}	const waiter = this.waiting.dequeue();        // ② 有人在等就直接给	if (waiter) waiter({ value: event, done: false });	else this.queue.enqueue(event);               // ③ 没人等就排队}

三个决定:终局之后 push 一律丢弃(provider 多发一个 done 不会炸);有消费者挂起时零延迟直送;没有就入队,等下次迭代来取。

迭代器那边正好是三种情况:

ts
while (true) {	if (this.queue.length > 0) yield this.queue.dequeue()!;	else if (this.done) return;	else yield await new Promise((r) => this.waiting.enqueue(r));}

AssistantMessageEventStream(:97-130)只是在这个骨架上加了计时:创建时记下 Date.now() 和 performance.now(),在 done / error / end 时给消息补一个 durationMs。跳过条件写得很细,其中一条值得注意——message.timestamp < this.#startedAt 时不计时,因为这条消息是别处产生的(比如 deferred 之后取回来的),不该算这个流的耗时。这一行是给延迟结果准备的。

最要紧的一点在构造函数里(:101-113):

ts
super(	(event) => event.type === "done" || event.type === "error",	(event) => event.type === "done" ? event.message : event.error,);

extractResult 对 error 事件返回的是 event.error,不是抛异常。而 complete() 就是 stream(...).result()(compat.ts:269-276)。于是:

ts
const msg = await complete(model, context);   // 失败也不抛if (msg.stopReason === "error") { /* 只有这里能知道 */ }

await complete() 在鉴权失败、网络断开时不会 reject,它返回一条 stopReason: "error" 的消息。 这是"失败也是消息"的最后一块拼图——不只是协议层这么约定,连"等最终结果"这个 API 都照着它实现。

想用异常流只有两条路:自己检查 stopReason,或者拿 streamSimple() 手动迭代。


四、第三层:四条契约

StreamFunction 的定义(types.ts:398-402)就三行,但上面有 8 行注释,是这套抽象真正的宪法:

ts
// Contract:// - Receives a normalized transcript: the system prompt and tools live in//   the leading system message, never on the context itself.// - Must return an AssistantMessageEventStream.// - Direct streamSimple() calls may throw synchronously when request auth is//   missing. Once a stream is returned, request/model/runtime failures should//   be encoded in that stream.// - Error termination must produce an AssistantMessage with stopReason//   "error" or "aborted" and errorMessage, emitted via the stream protocol.export type StreamFunction<	TApi extends Api = Api,	TOptions extends StreamOptions = StreamOptions,> = (	model: Model<TApi>,	context: TranscriptContext,	options?: TOptions,) => AssistantMessageEventStream;

四条,逐条看。

第一条:收的是 TranscriptContext,不是 Context。 参数名叫 context 但类型是 TranscriptContext——只有 messages 一个字段。配合 2.1 的折叠,这意味着翻译器永远不会看到"独立的 systemPrompt"。

第二条:必须返回流。 不是 Promise,不是字符串,是 AssistantMessageEventStream。

第三条最容易被读错:

Direct streamSimple() calls may throw synchronously when request auth is missing. Once a stream is returned, request/model/runtime failures should be encoded in that stream.

它说的是分界线,不是"永不抛出":

text
同步阶段(return 之前)        可以 throw    ← 鉴权缺失这类"根本无法开始"异步阶段(return 之后)        必须编码进流  ← 网络断、限流、模型崩

为什么这么分?因为同步抛出的错误调用方还没拿到流,只能 catch;而流已经返回之后,调用方已经在 for await 里了,再抛就没人接。分界线不是"错误类型",是"调用方手里有没有流"。

实证在 anthropic-messages.ts:959-961:

ts
if (!getAnthropicFederation(model, options?.apiKey, options?.headers,	options?.env)) {	assertRequestAuth(model.provider, options?.apiKey, options?.headers);}

这四行在函数体最前面,任何流对象创建之前。assertRequestAuth 抛了,调用方还能 catch。

M03 讲"永不抛出"时说的是 Agent 循环那一层——它对 streamSimple 的调用被包在 try 里,所以同步抛出也能被接住。到了流内部,就只剩编码一条路。

第四条:错误必须是一个完整的 AssistantMessage。 不是 { error: "网络超时" },是一个 stopReason: "error" 或 "aborted"、带 errorMessage 的助手消息,通过 { type: "error", reason, error } 事件发出。

这条是"失败也是消息"在协议层的落地:错误不是一个信号,是一条消息。

为什么值得这么费劲?因为 transcript 是唯一事实源。如果错误只是抛了个异常,就会被记成"这一轮没发生";而失败的一轮在语义上发生过——模型被调用了、花了钱、返回了东西(哪怕是空的)。把它记成消息,后续的压缩、成本统计、重放才有依据。


五、为什么要有 stream 和 streamSimple 两个

两个函数体几乎一样(compat.ts:252 和 :278),差别只在 options 类型:

stream() streamSimple()
options 类型 ProviderStreamOptions SimpleStreamOptions
思考等级 原样透传,翻译器自己解释 先 clampThinkingLevel 再翻译
采样参数 原样透传 按等级查 samplingParamsByThinkingLevel
maxTokens 原样透传 按当前上下文长度夹紧
谁在用 需要精确控制的调用方 Agent 循环

stream() 是机制,streamSimple() 是策略。Agent 循环选策略版,因为它不关心"模型到底支不支持 xhigh"。

5.1 buildBaseOptions 才是真正的适配器

streamSimple 多做的事集中在 api/simple-options.ts 的 buildBaseOptions(:36-66)。它把 6 个"简单选项"展开成 21 个字段:

ts
export function buildBaseOptions(	model: Model<Api>,	context: TranscriptContext,	options?: SimpleStreamOptions,	apiKey?: string,): StreamOptions {	const samplingParams = resolveSamplingParams(		model,		options?.reasoning ?? "off",		options?.samplingParams,	);	return {		temperature: options?.temperature,		samplingParams,		maxTokens: clampMaxTokensToContext(			model, context, options?.maxTokens ?? model.maxTokens),		signal: options?.signal,		// ... 还有 16 个字段:telemetry / apiKey / fetch / transport /		// cacheRetention / sessionId / headers / identity / onPayload /		// onResponse / timeoutMs / maxRetries / metadata / env ...	};}

两个细节值得停一下。

options?.reasoning ?? "off":思考等级在这个字段里,不叫 thinkingLevel。名字的差异有实际后果——你写 thinkingLevel: "high" 会被无视,因为根本没人读这个字段。

21 个字段里有 6 个是回调(onPayload / onResponse / onProviderStreamEvent / fetch / transport / signal)。这说明这一层不只做"参数翻译",还留了观测和替换的插口:想看真实发出的请求体用 onPayload,想自己接管网络用 fetch,想中途取消用 signal。M15 讲 telemetry 时会回到这里。

5.2 maxTokens 会被夹两次

clampMaxTokensToContext(simple-options.ts:18-22):

ts
export function clampMaxTokensToContext(	model: Model<Api>,	context: TranscriptContext,	maxTokens: number,): number {	if (model.contextWindow <= 0) return Math.max(MIN_MAX_TOKENS, maxTokens);	const available = model.contextWindow		- estimateContextTokens(context).tokens		- CONTEXT_SAFETY_TOKENS;	return Math.min(maxTokens, Math.max(MIN_MAX_TOKENS, available));}

CONTEXT_SAFETY_TOKENS = 4096,MIN_MAX_TOKENS = 1。

也就是说:输出上限不只受模型限制,还受"这段对话已经占了多长"限制。 上下文窗口 20 万,已经用了 19.8 万,你的 maxTokens 就被压到 200000 - 198000 - 4096,负数,最后取 1。

这还不是全部。Anthropic 那条路径会再夹一次(anthropic-messages.ts:987-1000):

ts
const adjusted = adjustMaxTokensForThinking(	base.maxTokens, model.maxTokens, options.reasoning,	options.thinkingBudgets,);const maxTokens = clampMaxTokensToContext(model, context, adjusted.maxTokens);// ...thinkingBudgetTokens: Math.min(	adjusted.thinkingBudget,	Math.max(0, maxTokens - 1024),),

顺序是:先按上下文夹 → 再加思考预算 → 再按上下文夹 → 最后给答案留 1024。

结果是一种优雅降级:上下文快满时,先被砍的不是请求,而是思考预算——maxTokens - 1024 变成 0,思考关掉,请求照发。

这解释了一个真实困惑:长会话到后面几轮,Agent 会明显"变笨"。不是模型退化,是思考预算被挤没了。你在 M09 里看到的"压缩要早做",根子在这里。

5.3 同一个契约,两种合规写法

回到 2.4 的差异:旧门面先 resolveApiProvider 再返回流,新入口先返回流再在 async 里解析 provider。

按第四节第三条契约,两者都合规:

旧门面 compat.stream 新入口 ModelsImpl.stream
provider 找不到 同步抛 No API provider... 进流,变成 error 事件
鉴权缺失 翻译器内 assertRequestAuth 同步抛 applyAuth 在 async 内,进流
调用方要写的代码 try 包住调用 + 包住循环 只需包住循环

新写法的调用方更省事,代价是错误发生的时刻不可预测——你拿到流不代表请求已经开始。这是一个典型取舍:把麻烦从调用方挪到实现方。

判断依据很简单:这个 API 会被多少不认识实现细节的人调用?越多,越应该"先返回流,错误进流"。


六、思考等级是七级,不是五级

大多数资料写五级或六级。实际定义在 providers/model-schema.ts:16-17:

ts
export const THINKING_LEVELS = [	"minimal", "low", "medium", "high", "xhigh", "max",] as const;export const MODEL_THINKING_LEVELS = ["off", ...THINKING_LEVELS] as const;

七个:off / minimal / low / medium / high / xhigh / max。

注意 ThinkingLevel 和 ModelThinkingLevel 是两个类型:前者不含 off("要思考"的六档),后者含("要不要思考"的七档)。这个区分很实用——thinkingBudgetForLevel(reasoningLevel: ThinkingLevel) 就不可能被传入 off。

text
off  minimal  low  medium  high  xhigh  max │      │      │     │       │      │      │不思考  └──────── 六档,由模型自己声明支持哪几档 ────────┘

多出来的 max 和 xhigh 是给"愿意为一次思考付更多 token"的模型用的。而"哪几档真的可用"由模型自己声明。

6.1 thinkingLevelMap 的值可以是 null

定义在 model-schema.ts:27:union([str(), nul()])——每个级别的映射值要么是字符串,要么是 null。

null 不是"没配置",是**"这个级别明确不支持"**。schema 的 description 里写得很清楚(:40):

null marks a level unsupported. Levels the model does not map use the provider's default value through high; xhigh and max are unsupported.

判断逻辑在 models.ts:1261-1270:

ts
export function getSupportedThinkingLevels<TApi extends Api>(	model: Model<TApi>,): ModelThinkingLevel[] {	if (!model.reasoning) return ["off"];	return EXTENDED_THINKING_LEVELS.filter((level) => {		const mapped = model.thinkingLevelMap?.[level];		if (mapped === null) return false;                    // 显式拒绝		if (level === "xhigh" || level === "max") return mapped !== undefined;		return true;                                          // 其余默认支持	});}

三态语义:

值 含义
undefined 没特别说,默认支持(xhigh / max 除外)
null 明确不支持
"high" 之类 映射到 provider 自己的档位名

undefined 和 null 在别的地方也这么用——M03 讲 mergeClientIdentity 时,attribution 字段的 undefined 是"我没意见"、null 是"明确不要"。同一个约定,两处独立使用。

xhigh / max 特殊对待的理由:这两档会显著增加成本,默认不开,必须模型显式声明。

6.2 clamp 的两个方向

clampThinkingLevel(models.ts:1272-1291)先向上找,再向下找:

ts
const availableLevels = getSupportedThinkingLevels(model);if (availableLevels.includes(level)) return level;const requestedIndex = EXTENDED_THINKING_LEVELS.indexOf(level);if (requestedIndex === -1) return availableLevels[0] ?? "off";for (let i = requestedIndex; i < EXTENDED_THINKING_LEVELS.length; i++) {	const candidate = EXTENDED_THINKING_LEVELS[i];	if (availableLevels.includes(candidate)) return candidate;   // 向上}for (let i = requestedIndex - 1; i >= 0; i--) {	const candidate = EXTENDED_THINKING_LEVELS[i];	if (availableLevels.includes(candidate)) return candidate;   // 向下}return availableLevels[0] ?? "off";

为什么先向上?因为思考更多通常比更少安全。请求 xhigh 但模型只到 high,降到 high 比降到 off 好——用户想要的是"想得深",不是"想得久"。

requestedIndex === -1 那行是给"运行时传了个不认识的字符串"兜底——ModelThinkingLevel 只是类型,JSON 配置里的值不归它管。

6.3 从等级到 token 预算

七级只是语义。落到 provider 上还有第二层翻译,而且不止一种:

text
自适应思考   forceAdaptiveThinking = true  → effort: "high"     (努力程度)预算思考     老模型                        → budget_tokens: 16384(token 数)推理模型     OpenAI o 系列                 → reasoning_effort     (努力程度)无思考       reasoning 为空                → thinkingEnabled: false

anthropic-messages.ts:974-983 里两种做法共存:

ts
// For models with adaptive thinking: use an effort level.// For older models: use budget-based thinking.if (model.compat?.forceAdaptiveThinking === true) {	const effort = mapThinkingLevelToEffort(model, options.reasoning);	return stream(model, context, { ...base, thinkingEnabled: true, effort });}

预算那张表在 simple-options.ts:71-76:

等级 默认预算(tokens) 备注
minimal 1,024
low 2,048
medium 8,192
high 16,384
xhigh 16,384 clampReasoning 折到 high
max 16,384 同上

xhigh / max 在 token 制里被 clampReasoning(:78-80)折成 high——因为预算制没有"更努力"这个维度,只有"更多 token"。同一个语义,在不同厂商那里能表达的粒度不同,这是 provider 抽象永远漏不掉的一层。

再加一条约束:MIN_ANSWER_TOKENS = 1024(:69)。当 maxTokens <= thinkingBudget 时,预算被压到 maxTokens - 1024,保证答案还有地方写。否则会出现"模型思考完,没配额输出"这种空回复。


七、缓存:三种语义,四种实现

Agent 对话是有状态的:第 50 轮会把前 49 轮全发一遍。缓存就是告诉服务端"这段没变,别重算"。

抽象只有三个值(model-schema.ts:19):

ts
export const CACHE_RETENTIONS = ["none", "short", "long"] as const;

但四家的"怎么标记"完全不同:

Provider short long 打在哪
Anthropic cache_control: { type: "ephemeral" } 加 ttl: "1h" system 块 + 最后一个 tool + 最后一条 user
Bedrock 插独立对象 { cachePoint: { type: DEFAULT } } 加 ttl: ONE_HOUR system 块后 + 最后一条消息后
OpenAI Responses 发 prompt_cache_key 加 prompt_cache_retention: "24h" 不打点,按 key 自动匹配前缀
OpenAI 兼容 照抄 Anthropic 的 cache_control 同上 同 Anthropic

四种思路,用一句话概括区别:

  • Anthropic 像贴便签:内容还是那些内容,附加一个"这段不变"的字段
  • Bedrock 像插路标:在消息流里插一个不含业务数据的独立对象
  • OpenAI 像报会员卡号:一个标记都不打,每次带个 key,后端自己算前缀重合
  • OpenAI 兼容厂商:直接抄便签协议

Anthropic 那条"三个位置"不是随便选的。实测代码(anthropic-messages.ts):system 块在 :1225 / :1232 / :1241(三条 system 消息各打一个),最后一条 user/system 在 :1526-1547(注释就写着 Add cache_control to the last user or system message to cache conversation history),最后一个 tool 在 :1655——而且是只给最后一个:

ts
...(cacheControl && index === tools.length - 1	? { cache_control: cacheControl }	: {}),

为什么只给最后一个 tool?因为缓存按前缀匹配:把标记放在第 N 个 tool 上,等于声明"前 N 个 tool 都不变"。标在中间是浪费——请求最多 4 个断点,要用在覆盖范围最大的位置。

7.1 默认是 "short",不是 "none"

这是最容易搞错的一条。anthropic-messages.ts:75-83:

ts
function resolveCacheRetention(	cacheRetention?: CacheRetention,	env?: ProviderEnv,): CacheRetention {	if (cacheRetention) return cacheRetention;	if (getProviderEnvValue("PI_CACHE_RETENTION", env) === "long") {		return "long";	}	return "short";}

调用方什么都不传时,结果是 "short"。也就是说 Anthropic 那条路上缓存默认是开的。

为什么会这样?因为不缓存纯亏:同一条系统提示词每轮重算一次,钱和延迟都翻倍。默认开是"防呆",none 是给调试和对比实验留的开关。

顺带一个成本细节(models.ts:1247-1253):1h 缓存写入按输入价的 2 倍计费。所以 long 不是无脑更省——短会话用 long 反而更贵。这是 CACHE_RETENTIONS 分三档而不是两档的原因。

7.2 这解释了 M03 的一个疑问

M03 说过:"每轮都重建 llmContext,为什么不会破坏缓存?"

答案在这一节:缓存命中靠内容字节前缀匹配,跟你是第几轮调用无关。 只要 system 和 tools 的字节没变、标记位置没变,后端就能命中。重建数组不是问题,改内容才是。

而 2.1 的 timestamp: 0 正是为了让"每轮重建"产生字节完全一致的 system 消息。如果那里写成 Date.now(),缓存命中率会归零——一个看起来无关紧要的假值,是整条缓存链的地基。


八、模型是哪来的:装配层

前七节都在 packages/ai 里。但 stream(model, context, options) 的第一个参数是 Model 对象——谁把它造出来的?

在 ai 包里搜 apiKey,只能搜到"从 options 里读"。它不读环境变量、不看 auth.json、更不认识命令行。ai 是无状态的翻译库:给一个 model 和一个 context,翻译成 HTTP。至于这个 model 是怎么挑出来的、凭据从哪来,它一概不管。

这一层在 packages/coding-agent/src/core/,三个文件,2,475 行:

文件 行数 回答的问题
model-resolver.ts 689 --model 那串字符 → 哪一个 Model
model-runtime.ts 1,049 provider 集合从哪来、凭据怎么找
provider-composer.ts 737 builtin / models.json / 扩展怎么叠成一个 Provider

三个文件对应三个动作:解析 → 装配 → 派活。一个一个看。

8.1 那串字符不是 id,是一条查询

--model 认三种写法:

text
claude-sonnet-4-5anthropic/claude-sonnet-4-5anthropic/claude-sonnet-4-5:high

第三种末尾的 :high 是第六节那七级思考里的一档。

要是按 : 一刀切就错了——网关的真模型 id 长这样:qwen/qwen3-coder:exacto、 zai/glm-5。切掉后半截,模型名就废了。所以请求参数里带了个开关 (model-resolver.ts:81-88):

ts
/** * A trailing `:<suffix>` is only considered when the full text matches * no model, since ids such as OpenRouter's `qwen/qwen3-coder:exacto` * contain colons. */thinkingSuffix: "none" | "strict" | "lenient";

顺序是:先拿整串去查表,查不到才剥后缀。剥下来的还得是合法思考等级 (splitThinkingSuffix,:120-125),否则后缀整个当 id 的一部分。

resolveCliModel(:450)第一件事很反直觉(:464-466):

ts
// Important: use *all* models here, not just models with pre-configured auth.// This allows "--api-key" to be used for first-time setup.const models = [...modelRuntime.getModels()];

取的是全部模型,不是"有凭据的那些"。原因在下一节。

8.2 五次判断,一条降级梯子

真正的算法在 selectReference(:235-265):

ts
const others = raw.filter((model) => model !== named);const candidates = named ? [named, ...others] : others;if (candidates.length === 0) return undefined;if (new Set(candidates.map((model) => model.provider)).size === 1)	return { status: "resolved", model: candidates[0] };if (named && usable(named.provider))	return { status: "resolved", model: named };const usableOthers = others.filter((model) => usable(model.provider));if (usableOthers.length === 1)	return { status: "resolved", model: usableOthers[0] };if (usableOthers.length === 0 && named)	return { status: "resolved", model: named };return { status: "ambiguous", candidates, usableCount: usableOthers.length };

六行判断,五档结果:

顺序 条件 结果
1 候选全来自同一个 provider 取第一个,不看凭据
2 命名了 provider,且它可用 命名者胜
3 其余候选中恰好一个可用 它胜
4 一个可用的都没有,但命名了 provider 命名者胜
5 以上都不成立 ambiguous + 候选列表

usable 只用来打破平局,不参与"能不能用"的判决。注释就写在函数头上 (:145-148):"usable only breaks ties between providers, so a unique match resolves even without credentials."

第 4 档正好回答了开篇那个问题:没配 key 为什么也能解析成功? 因为解析和 鉴权是两件事。解析只回答"你指的是哪一个",鉴权要到 prepareRequest 才发生 (8.6)。第一次配 key 的人正是靠这个顺序:先用 --model 加 --api-key 跑起来, key 才被存进去。

还有一个反向的细节(resolveCliModel,:490):

ts
inlineApiKey	? () => false	: (providerId) => modelRuntime.hasConfiguredAuth(providerId),

带了 --api-key 时,usable 恒为 false。因为这次 key 是打给用户选的那个 provider 的,已有凭据不该替用户做决定——三个 provider 都登录过时,静默选一个 和用户想指定的那个很可能不是同一个。

8.3 provider/ 只是提示,不是命名空间

anthropic/claude-opus-4-8 里的斜杠很容易被当成"路径"。但网关的模型 id 本身就带斜杠:zai/glm-5、moonshotai/kimi-k2.6、xiaomi/mimo-v2.6-pro。

所以那个前缀只是一条提示(:228-234,节选):

text
`provider/rest` is only a hint: the whole text may also be a model id onanother provider. The named provider wins when usable...An unusable named match is still preferred over unusable raw matches.

splitProviderPrefix(:127-143)还要处理一个更细的问题:provider id 自己 也带斜杠(URL 派生的 id 会这样)。它的解法是从长到短试:

ts
if (!prefix || (best && best.provider.length >= provider.length)) continue;

长的优先,短的才轮到。这和 8.2 是同一个思路:先试更具体的解释,再退到更宽的。

8.4 ModelRuntime 不是包装,是装配车间

class ModelRuntime implements Models(model-runtime.ts:174)。Models 是 ai 包的接口(ai/src/models.ts:258),ai 自己也有一份实现(ModelsImpl, :400)。两个实现,一个接口。

ModelRuntime 内部持有一个 ModelsImpl(:214),但它不是转发器——它的活 是把装配好的 provider 一个个塞进去。塞的动作在 recomposeProvider(:299-306):

ts
const provider = this.composeProvider(providerId);const entries = this.virtualModels.get(providerId)?.values() ?? [];const virtualModels = [...entries].map((entry) => entry.model);if (virtualModels.length > 0) {	this.models.setProvider(		withVirtualModels(providerId, provider, virtualModels),	);} else if (provider) {	this.models.setProvider(provider);} else {	this.models.deleteProvider(providerId);}

provider 从哪来?providerIds()(:288-296)把五个来源并成一个集合: builtin、原生扩展、models.json、扩展注册、虚拟模型。

单个 provider 怎么装?composeProvider(:309-325):

ts
const base = this.nativeExtensionProviders.get(providerId)	?? this.builtins.get(providerId);const extension = this.extensionProviders.get(providerId);if (!this.config.getProvider(providerId) && !extension) {	// No overlays: use the builtin untouched so its auth/login/stream	// behavior is exact.	this.compositionErrors.delete(providerId);	return base;}try {	const provider = composeModelProvider(		providerId,		base,		this.config,		extension,	);	this.compositionErrors.delete(providerId);	return provider;} catch (error) {	this.compositionErrors.set(providerId, String(error));	return base;}

三条路,第三条最值得记住:

  • 没有 overlay → 原样返回 builtin,连对象都不新建
  • 有 overlay → 走 composeModelProvider
  • 装配抛错 → 记进 compositionErrors,退回 builtin

第一句的注释值得逐字读:use the builtin untouched so its auth/login/stream behavior is exact。合成得一个个手动搬方法(fetchDeferred、cancelDeferred、 generateImages、classify 都是单独补上去的,:651-685),漏一个就少一个能力; 没改配置的人不该承担这个风险。

第三条是整层的性格:装配失败不崩,退化成内置 provider 并留一条诊断。 用户在 UI 里看到的是"这个 provider 有点问题",而不是白屏。

8.5 三层叠加、一次空校验、三重分派

composeModelProvider(provider-composer.ts:547)先把模型列表叠出来 (:560-580):

ts
const getAllModels = (): AnyModel[] => {	let models = applyExtension(		providerId,		applyModelsJson(providerId, getAllProviderModels(base), config),		currentExtension(),	);	// …OAuth 投影,只作用于 chat 模型	return models.map((model) => {		const override = config?.modelOverrides?.[model.id];		return override && isModelType(model, "chat")			? applyModelOverride(model, override)			: model;	});};

由内到外:builtin → models.json → 扩展,最后 modelOverrides。注释 (:558-559)说它是"最顶层的用户配置",而且只应用一次——所以它能在扩展 改写之后再压回去。

紧接着一行看起来像失误的代码(:582):

ts
// Validate eagerly so registration/reload reports structural errors// immediately.getAllModels();

调一次,扔掉结果。唯一作用是让叠加期的结构错误(比如扩展声明了 streamSimple 却没给 api,:540-542)在注册时立刻抛出,而不是等第一次请求。空调用当 校验,是"早失败"最便宜的写法。

然后是最硬的一条(:583-585):

ts
const apiKey = composeApiKeyAuth(providerId, base, config, extension);const oauth = composeOAuthAuth(providerId, base, config, extension);if (!apiKey && !oauth) {	throw new Error(		`Provider ${providerId}: no authentication method configured.`,	);}

装配层只关心"有没有一种鉴权方式",不关心 key 是否有效。有效性留给请求那一刻。

最后是派活,streamWith(:588-608):

ts
const streamWith = (	model: Model<Api>,	context: TranscriptContext,	options: StreamOptions | undefined,	simple: boolean,): AssistantMessageEventStream =>	lazyStream(model, async () => {		if (extension?.streamSimple && model.api === extension.api) {			return extension.streamSimple(				model,				context,				options as SimpleStreamOptions,			);		}		if (base && supportsBaseApi(model)) {			return simple				? base.streamSimple(model, context, options as SimpleStreamOptions)				: base.stream(model, context, options);		}		const api = getApiProvider(model.api);		if (!api) {			throw new Error(`No API provider registered for api: ${model.api}`);		}		return simple			? api.streamSimple(model, context, options as SimpleStreamOptions)			: api.stream(model, context, options);	});

三档优先级:扩展自带 > builtin 认识这个 api > 全局 api 注册表。第三档拿到的 就是第二节那个翻译器。

stream 和 streamSimple 在同一个函数里分流(:647-648),只差一个布尔。这就是 第五节"为什么要有两个入口"的落地方式:两条路,一套派活。

8.6 凭据不在装配时定死

每次调用前都过一遍 prepareRequest(model-runtime.ts:659-705):

ts
const provider = this.models.getProvider(model.provider);if (!provider) {	throw new ModelsError("provider", `Unknown provider: ${model.provider}`);}const resolution = await this.getAuth(model, {	apiKey: options?.apiKey,	env: options?.env,	signal: options?.signal,});if (!resolution) {	throw new ModelsError(		"auth",		`Provider is not configured: ${model.provider}`,	);}

三件事:找到 provider、拿到凭据、合出 header。

header 是三层(:686-690):

ts
let headers = mergeHeaders(	mergeHeaders(		getOpenCodeSessionHeaders(requestModel, sessionId),		resolution.auth.headers,	),	providerOptions.headers,);if (transformHeaders) headers = await transformHeaders(headers ?? {});

外层覆盖内层。mergeHeaders(:157-171)还专门做了大小写不敏感的去重——不然 X-Api-Key 和 x-api-key 会一起发出去,服务端取哪个看脾气。

为什么不在装配时把 key 定死?因为 OAuth token 会过期。getAuth 每次都检查 剩余有效期(minOAuthValidityMs 默认五分钟,:131-132),必要时先刷新再发请求。 装配回答"谁能来",鉴权回答"这次带什么证件"。

顺带一处容易读错的地方:streamSimple(:731)里还有一层虚拟模型的重路由 (:733-751)。虚拟模型(比如 radius)自己不是 provider,它要先选一次真模型 再递归回来,并且把预算夹到真模型的上限(:742-743):

ts
const maxTokens =	options?.maxTokens && limit > 0		? Math.min(options.maxTokens, limit)		: options?.maxTokens;

调用方是按虚拟模型算的预算,路由到真模型时必须重新夹一次。

8.7 从命令行到翻译器

一条链,五个层:

text
--model "openrouter/zai/glm-5:high"   |   +- main.ts:476               resolveCliModel   |    +- model-resolver.ts:149  resolveModelReference   |         +- :235  selectReference       整串先试   |         +- :127  splitProviderPrefix   "openrouter"   |         +- :120  splitThinkingSuffix   "high"   |   +- model-runtime.ts:450      getModels()  全部模型   |    +- :309  composeProvider   |         +- provider-composer.ts:547  composeModelProvider   |              +- applyExtension   |              +- applyModelsJson   |              +- modelOverrides   |   +- model-runtime.ts:731      streamSimple()   |    +- :659  prepareRequest   |         +- :446  getProvider   |         +- :558  getAuth          <- 凭据在这一步才取   |         +- :157  mergeHeaders   |   +- provider-composer.ts:648   provider.streamSimple        +- :588  streamWith   三重分派             +- (1) extension.streamSimple             +- (2) base.streamSimple             +- (3) api.streamSimple      <- 第二节的翻译器

对照第二节那张三层图,现在多了两层:解析在最上面,装配在中间。ai 包的 三层是"翻译内部的分工",这五层是"一次调用从命令行到 HTTP 的全过程"。

8.8 为什么这一层不放进 ai

一句话:ai 是函数,这层是对象。

ai 的 stream() 是纯函数式的:输入 model + context,输出事件流,中间不记任何 东西。装配层要记的东西很多:你登录过哪几个 provider、models.json 什么时候改的、 OAuth token 还剩几分钟、扩展注册了哪些实现。这些是状态,状态需要容器。

snapshot(model-runtime.ts:187-193)就是这个容器的只读投影:

ts
private snapshot: ModelRuntimeSnapshot = {	all: [],	available: [],	configuredProviders: new Set(),	storedProviders: new Set(),	auth: new Map(),};

all 和 available 的区别就是"有模型"和"能用"的区别——解析看前者,选择看 后者。resolveCliModel 取 getModels()(全部),findInitialModel 的第三 步取 getAvailableSnapshot()(:596-597)——两个函数用的是不同的池子,这不是 笔误,是两个不同的问题。


九、自己动手验证

环境:v1.4.0 / node v24.12.0 / Windows 24H2。每条判据都是这一版实跑的输出;发真请求的实验标 [需 key]。

Windows 用户没有 sed / grep 也没关系:把命令里的行号段拿去编辑器里跳转,结论一样。

实验 1:数一数 API 到底有几个。

bash
# 在仓库根目录执行cd packages/ai/srcsed -n '64,76p' types.ts

KnownApi 十个 + Api = KnownApi | (string & {})。最后那个 (string & {}) 很关键:允许任意字符串,所以扩展可以注册自己的 api id 而不改这个类型。这是 TypeScript 里"开放联合"的标准写法。

顺带看下面还有 KnownImageApi(1 个)和 KnownClassifierApi(4 个)——ai 包不只做对话,还做图像和分类。

实验 2:验证 12 个事件。

bash
sed -n '823,839p' types.ts

数 | { type: 开头的行,12 个。再数带 partial 的,10 个。

实验 3:看折叠发生在哪。

bash
sed -n '10,34p' utils/transcript.ts

二十四行,两个函数。createInitialSystemMessage 把 tools 折进 toolsAdded,normalizeContext 把它插到消息数组最前面。

实验 4:确认新入口做了同一件事。

bash
grep -n "normalizeContext" models.ts

三处::70 导入,:906 和 :930 各调用一次(stream 和 streamSimple)。旧门面 compat.ts 里另有两处(:257 / :283)。

实验 5:找一个模型的 thinkingLevelMap。

bash
grep -c "thinkingLevelMap" providers/anthropic.models.tsgrep -n "thinkingLevelMap" providers/anthropic.models.ts | head -3
powershell
(Select-String -Path providers/anthropic.models.ts `  -Pattern 'thinkingLevelMap').CountSelect-String -Path providers/anthropic.models.ts -Pattern 'thinkingLevelMap' |  Select-Object -First 3

更省事的办法:在 models.generated.ts 里搜 thinkingLevelMap,能直接看到几百个模型的声明,注意区分 null 和 "high"。

实验 6:确认错误的分界线。

bash
grep -n "assertRequestAuth\|throw new Error" \  api/anthropic-messages.ts | head -8
powershell
Select-String -Path api/anthropic-messages.ts `  -Pattern 'assertRequestAuth|throw new Error' | Select-Object -First 8

throw 都在流返回之前(建客户端、读配置、assertRequestAuth),异步失败则走 { type: "error" }。这就是契约第三条的实证。

实验 7:看默认缓存策略。

bash
sed -n '71,99p' api/anthropic-messages.ts

三行注释把优先级写完了:显式选项 > PI_CACHE_RETENTION 环境变量 > "short"。

实验 8:走一遍装配层。

bash
cd ../../coding-agent/srcsed -n '235,265p' core/model-resolver.ts

三十一行里,return { status: 出现五次:四次 resolved,一次 ambiguous。再 grep -n "usable(named.provider)" core/model-resolver.ts,命中 :260——命名 provider 胜出的那一档。

bash
grep -n "setProvider\|deleteProvider" core/model-runtime.ts

装配结果落地只有这两个方法(:302-304)。再往前一行,composeProvider 的 catch 分支(:321-324)会把错误塞进 compositionErrors 并 return base—— 这就是"装配失败静默降级"的出处。

bash
grep -n "supportsBaseApi\|getApiProvider" core/provider-composer.ts

两处都在 streamWith 里(:588-608),三档分派的分界线。

实验 9:改一处试试——把输出的天花板压到 1 个 token。

  • 改哪里 packages/ai/src/api/simple-options.ts:15,把安全边距改成天文数字:
ts
const CONTEXT_SAFETY_TOKENS = 4096;   // 改成 9999999
  • 预期 clampMaxTokensToContext(:18-22)算出 available = contextWindow - used - 9999999,永远是负数, Math.max(MIN_MAX_TOKENS, available) 取到 1。任何 maxTokens 都被压成 1。

  • 实测 基线(问「用一句话介绍你自己,不少于 30 个字」):

text
events      = end:system/-/0 | end:user/-/1 |              end:assistant/stop/1 | agent_end | agent_settledroles       = system,user,assistantusage.output= 46

agent_settled 是从哪冒出来的? 它不在 M03 那 10 种 AgentEvent 里(packages/agent/src/types.ts:528-551):它是 coding-agent 在会话层追加的事件,定义在 packages/coding-agent/src/core/agent-session.ts:216,aborted 字段说明这次是被中断还是自然结束。看到不认识的尾事件,先分清它是内核吐的还是宿主追加的。

改完同一个脚本(end:角色/stopReason/content块数):

text
events      = end:system/-/0 | end:user/-/1 |              end:assistant/length/1 | agent_end | agent_settledroles       = system,userentries     = model_change,thinking_level_change,              message,message,message,context_edit
  • 连带 这是全书最安静的一次失败:没有任何 error 事件, errorMessage 是空的。三个现象叠在一起:

    1. stopReason 从 stop 变成 length。
    2. subscribe 看得见那条 message_end,但 session.state.messages 里没有它——只剩 system,user。
    3. entries 里多了一条 context_edit。

    第 2、3 条是同一件事的两面。length 被 isRecoverableLength 判成 「可恢复的截断」(agent-session.ts:3089-3090),于是走溢出恢复。 注释写得很清楚(:3016-3017):

    Overflow with retry: a context-overflow error or recoverable length stop; remove the failed assistant message, compact, and retry the turn once.

    Pi 自己把那条消息删了。 删的方式不是物理删除,是追加一条 context_edit;投影时 replacement === null 就返回空数组 (session-manager.ts:519-523)。落盘的 entries 一条没少, 上下文里少了一条。

  • 回滚 改回 4096,usage.output 回到 46。

这条实验真正想说的是:§5.2 的「夹两次」不是理论。一个常量调错, 模型的输出上限就是 1,而系统从头到尾不报错——它把这当成上下文溢出, 删掉证据,继续往下走。


十、工程暗坑

1. partial 存数组会全部变成最后一次的状态。

ts
const frames = [];session.subscribe((e) => {	if (e.partial) frames.push(e.partial);   // ← 灾难});

所有元素指向同一个对象,最后全是终态。要存就存 { ...e.partial },或者只存 e.type 和 e.delta。

2. done 有四个 reason,不是三个。

stop / length / toolUse / deferred。只处理前三个,遇到 deferred 会走进 default 分支。如果 default 里是 throw,那你就在"模型要求延迟"时崩了。

3. 同步抛出的错误不在流里。

streamSimple() 可能在 return 之前抛(鉴权缺失)。如果你只 for await 不 try,这个错误会直接冒到顶层。必须用 try 包住调用本身,而不只是包住循环。

ts
try {	const stream = streamSimple(model, context, opts);   // 这里可能抛	for await (const event of stream) { /* ... */ }} catch (err) {	// 两处都能接住}

4. thinkingLevelMap 的 null 不等于"没配"。

if (model.thinkingLevelMap?.[level]) 这种写法会把 null 和 undefined 一起判掉。看起来没差,但你在做"这个级别支持吗"的判断时,两者含义相反。

5. 缓存标记位置不是越多越好。

Anthropic 每请求最多 4 个 cache_control。超了会报错。coding-agent 只打三处是有原因的——留一个余量给调用方。

6. 长会话的 maxTokens 会被压到 1。

clampMaxTokensToContext 的下限是 MIN_MAX_TOKENS = 1,不是"至少给几百"。所以别把返回 1 个 token 当成 bug 报,它是"上下文满了"的信号。真正的修法是压缩(M09),不是调大 maxTokens。

7. await complete() 不抛错。

complete() = stream().result(),而 result() 在 error 事件上 resolve 的是那条错误消息。所以 try/catch 包 await complete() 只能接住同步抛出(provider 未注册、鉴权缺失),接不住网络错误。想统一处理,就得看 stopReason。

8. (string & {}) 不是笔误。

Api = KnownApi | (string & {}) 如果写成 KnownApi | string,那 KnownApi 就被 string 吃掉了,类型补全全失效。string & {} 的写法保留了字面量补全,同时允许任意字符串。

9. 离线构建里,目录数据是快照。

nix/model-catalog.json 钉着一份 model catalog 的 revision。Nix 构建没有网络, 所以内置模型数据来自那个固定版本;运行时仍用 pi.dev 的新数据覆盖。 快照负责"同样的源码构建出同样的字节",覆盖负责"用户看到今天的模型表" ——缺一个就变成"复现不了"或"新模型用不上"。npm run build 会先刷新, npm run build:offline 不刷。


十一、三个可以带走的方法

方法一:用"折叠点"找设计的重心。

Context → TranscriptContext 的折叠只用一个二十四行的文件完成,但整个包的设计都围绕它:provider 只看 messages、工具集从 messages 算、压缩必须保住首条 system 消息、timestamp: 0 为了让字节可复现。

一个架构里真正重要的往往不是最大的文件,是数据类型转换发生的那几行。找到它,上下游就都通了。

方法二:契约里"能不能抛"要写清楚分界线。

StreamFunction 的注释不说"不抛异常",而说"返回流之前可以抛、之后必须编码"。这句话的价值在于它明确了一个边界条件,而不是给了一个口号。

写任何 API 的注释时,问自己一句:这个"可以/不可以"是从哪个时刻开始算的?

方法三:把"支持程度"编码成三种状态,不要两种。

thinkingLevelMap 用 undefined / null / "high" 表示"默认支持 / 明确不支持 / 映射到某档"。如果用布尔值,你就表达不了"没表态"和"明确反对"的区别。

这条在配置系统里通用:默认值、显式覆盖、显式禁用是三种状态,不是两种。


本章小结

  1. 三层里真正解耦的只有一条线:Context → TranscriptContext。
  2. provider 只看得到 messages,工具集也从 messages 里算出来。
  3. stream 做通用折叠,streamSimple 管各家方言。
  4. 思考等级七级;缓存三值,默认 "short",不是关。
  5. 契约只允许"返回流之前"抛,之后必须编码成事件。

概念回顾

术语 一句话 在哪
折叠点 Context 转成 TranscriptContext 的那几行 §二
十二种事件 七家 provider 归一后的流事件集合 §三
四条契约 "能不能抛 / 什么时候算完"这类边界 §四
三态 undefined / null / 值 = 未表态 / 不支持 / 指定 §六
装配层 --model 字符串变 Model 的五级梯子 §八

练习

练习 1(读):§二 说 timestamp: 0 是为了让字节可复现。 如果改成真实时间戳,哪一类功能会先坏?→ 回 §七 看缓存打点, 再回 §九 实验里对比两次请求的原始报文。

练习 2(改):把 utils/transcript.ts 折叠里的 timestamp: 0 改成沿用原消息的时间戳。预期:同一段对话两次运行,发给 provider 的 字节不再逐字相同,可重放性丢失;回滚:改回 0 即可。

常见误区

  1. 你会以为 三层是层层递进的能力;实际是 真正解耦的只有一条线; 证据 §二 二十四行的 transcript.ts。
  2. 你会以为 缓存默认关更省;实际是 默认 "short";证据 §7.1。
  3. 你会以为 "看起来正确"的错误处理是保险;实际是 它把"能不能抛" 的边界往后挪了;证据 §五、§十一 方法二。

读完自检

开头列了五个问题。答上四条就算过关(第三条排在下面最后一行)。

自检 一句话答案 不会就去
为什么必须有两层(stream / streamSimple)? 一层做通用折叠,一层管各家方言;两层之间只有一条线 §二
接入一个新模型要改几个文件? 落在已有 api 就只加一条目录条目;新 api 才写翻译器 §1.1、§八
缓存默认是开还是关? 默认 "short",不是 "none" §7.1
--model 那串字符怎么变成一个 Model? 它不是 id 是一条查询;查不到才剥后缀,五次判断逐级降级 §8.1、§8.2
"看起来正确"的错误处理错在哪? 把"能不能抛"的边界往后挪了;契约只允许返回流之前抛 §五、§十一

下一步

模型这层封好了:不管底下是谁,上面只看到 12 种事件。

但模型返回的是 toolCall——一个名字加一段 JSON。谁去执行?模型可能传错类型、可能要求删库、可能一次调八个。这些都在循环之外,但都在内核包里。

下一章打开工具系统。


本章源码索引

文件 行数 本章用到的位置
packages/ai/src/compat.ts 303 stream() :252-267、streamSimple() :278-293、派活 :238-250、env key :224-232
packages/ai/src/models.ts 1,301 ModelsImpl.stream :901-919、七级思考 :1259-1291、成本 :1247-1253
packages/ai/src/types.ts 918 KnownApi :64-76、StreamFunction :398-402、12 事件 :823-839
packages/ai/src/utils/transcript.ts 264 折叠 :10-34
packages/ai/src/utils/event-stream.ts 136 EventStream.push :40-56、计时 :97-130
packages/ai/src/providers/model-schema.ts 116 七级 :16-17、缓存三值 :19、null 语义 :27-42
packages/ai/src/api/simple-options.ts 110 夹上下文 :18-22、buildBaseOptions :36-66、预算 :69-109
packages/ai/src/api/anthropic-messages.ts 1,687 缓存策略 :75-99、思考预算 :985-1000、缓存打点 :1225 :1526-1547 :1655
packages/ai/src/index.ts 48 入口分层注释 :1-5
packages/coding-agent/src/core/model-resolver.ts 690 五档梯子 :235-265、后缀开关 :81-88、resolveCliModel :450-534
packages/coding-agent/src/core/model-runtime.ts 1,050 ModelRuntime :174、composeProvider :309-325、prepareRequest :659-705
packages/coding-agent/src/core/provider-composer.ts 738 三层叠加 :560-580、三重分派 :588-608