接口 —— 先造一条能回放的模型,再接真的
E02 结束后,loop.ts 还是硬绑 createMockProvider()。mock 有个天花板:它只会
按三条规则说话,你没法用它验证「流式解析对不对」「工具参数分片拼没拼上」。
这一章把 provider 抽成真接口,然后写两份实现:
fixture:把一段回复录成文本,离线回放。零凭据、零网络、可进测试。openai:一个 POST,读 SSE,边读边翻译成同样形状的 chunk。
三个问题:
- 回放要录什么?录原始 SSE,还是录我们自己的 chunk?
- 网络给来的是字节流,不是一个事件一个事件——怎么把它切成完整事件?
- 没有 API key 时,怎么证明真模型那段代码是对的?
runAgent | | provider.stream(messages, tools, signal) v ProviderChunk: text / toolCall / done ^ ^ | | mock(三条规则) fixture(回放) / openai(SSE)一、本章终点:先跑起来
cd examples/mini-agentnode src/demo-model.tsfixtures/openai-basic.jsonl text 你好 text ,这是一份录好的回复。 done stopfixtures/openai-tool.jsonl toolCall read {"path":"README.md"} done toolUse你好,这是一份录好的回复。turns=1 stop=stop四段输出对应四件事:两条带子被读成了 chunk、带子里的 toolCall 带着参数、同一份
loop.ts 直接吃下了 fixture、整轮只跑一次就 stop。
| 文件 | 行数 | 本章变化 |
|---|---|---|
src/provider/fixture.ts |
42 | 重写:从「解析 SSE」改成「重放 chunk」 |
src/provider/openai.ts |
159 | 新增:真模型 |
src/demo-model.ts |
40 | 新增:本章入口 |
| 合计 | 684 | E02 的 443 + 本章 241 |
另有两类不计入行数链的配角:fixtures/ 下两条录好的带子(共 5 行),和
test/openai.test.ts(47 行,离线测 SSE)。行数链只计 src/,下同。
二、先定录制格式,再写解析器
第一版我录的是原始 SSE,一行一个 data: {...}。写了两条带子之后发现一个硬
约束:书里的代码块每行不能超过 80 列。 而 OpenAI 的 tool_calls delta 长这样
(真实录制,一行):
data: {"choices":[{"delta":{"tool_calls":[{"index":0,"id":"call_9",... "function":{"name":"read","arguments":"{\"path\":\"README.md\"}"}}]}}]}一行 158 列。压不进书里,也就压不进「看教程就能复现」这条原则。
于是我换了分工:回放不负责解析方言,只负责重放 chunk。 带子里存的就是
ProviderChunk,一行一条;SSE 的方言只在 openai.ts 里出现一次。两个直接好处:
- 带子可读、可手写、长度可控,坏一行报行号;
- 回放器不依赖任何 provider 细节,将来接 Anthropic 也不用改它。
代价是:fixture 不能替 openai.ts 测 SSE 解析。那就用一个本地 http 服务器来测
(第七节),比录制更可靠。
三、两条带子
<!-- file: examples/mini-agent/fixtures/openai-basic.jsonl -->
{"type":"text","text":"你好"}{"type":"text","text":",这是一份录好的回复。"}{"type":"done","stopReason":"stop"}<!-- file: examples/mini-agent/fixtures/openai-tool.jsonl -->
{"type":"toolCall","id":"call_9","name":"read","args":{"path":"README.md"}}{"type":"done","stopReason":"toolUse"}三行到两行,形状就是 E01 定义的 ProviderChunk。没有新格式,所以回放器不需要
任何映射表——这也是「先把契约定死」的回报。
四、回放器:42 行,三个判断
<!-- file: examples/mini-agent/src/provider/fixture.ts -->
import { readFileSync } from "node:fs";import type { Provider, ProviderChunk } from "../types.ts";/** * 把录好的一段回复重放成 chunk。 * 文件格式:一行一个 chunk(JSON),空行和 # 开头的行忽略。 */export function createFixtureProvider(file: string): Provider { const chunks = loadChunks(file); if (chunks.at(-1)?.type !== "done") { throw new Error(`${file} 最后一行必须是 done`); } return { name: "fixture", async *stream() { for (const chunk of chunks) yield chunk; }, };}export function loadChunks(file: string): ProviderChunk[] { const raw = readFileSync(file, "utf8"); const chunks: ProviderChunk[] = []; const lines = raw.split(/\r?\n/); for (let i = 0; i < lines.length; i += 1) { const line = lines[i].trim(); if (!line || line.startsWith("#")) continue; let chunk: ProviderChunk; try { chunk = JSON.parse(line) as ProviderChunk; } catch { const head = line.slice(0, 40); throw new Error(`${file}:${i + 1} 不是 JSON:${head}`); } if (!["text", "toolCall", "done"].includes(chunk.type)) { throw new Error(`${file}:${i + 1} 未知 chunk 类型`); } chunks.push(chunk); } return chunks;}判断一:带子必须有一条 done 结尾。 少了它不会报错——我删掉最后一行试了,
循环照样给出一个「正常」的结果:
node tmp-nodone.tsturns=1 stop=stop看着没问题,但这句 stop 是 loop.ts 里的初始值,不是模型报的原因。真模型
如果是被 length 截断,你也会记成 stop,然后去查一个不存在的问题。所以
回放器在创建时就拦:
ERR: fixtures/tmp-bad.jsonl 最后一行必须是 done判断二:坏行报行号。 带子是手写的,截断、少个引号都常见:
ERR: fixtures/tmp-bad2.jsonl:2 不是 JSON:not-json第 2 行——有这个数字,修法就只有一种;没有它,你只能打开文件数。
判断三:未知类型要拦。 JSON.parse 只保证是合法 JSON,不保证是合法 chunk。
{"type":"thought"} 能过 parse,但下游 loop.ts 的 if/else 会把它当 done
分支吞掉(那个 else 就是给 done 用的)。所以这里先拦一道。
stream() 是 async * 但内部没有 await——它是异步可迭代协议的要求,不是
为了异步而异步。yield 让调用方用 for await 拉,和真网络流完全同形。
五、真模型:159 行,一个 POST
<!-- file: examples/mini-agent/src/provider/openai.ts -->
import type { Message, Provider, ProviderChunk, StopReason, Tool,} from "../types.ts";export interface OpenAIOptions { baseUrl?: string; apiKey?: string; model?: string;}/** tool_calls 分片暂存:id 只来一次,name 与 args 可能来好几段。 */interface PendingCall { id: string; name: string; args: string;}function wireMessages(messages: Message[]) { return messages.map((message) => { if (message.role === "system" || message.role === "user") { return { role: message.role, content: message.content }; } if (message.role === "assistant") { const text = message.content .filter((block) => block.type === "text") .map((block) => block.text) .join(""); const calls = message.content .filter((block) => block.type === "toolCall") .map((block) => ({ id: block.id, type: "function", function: { name: block.name, arguments: JSON.stringify(block.args), }, })); if (calls.length > 0) { return { role: "assistant", content: text || null, tool_calls: calls }; } return { role: "assistant", content: text }; } return { role: "tool", tool_call_id: message.toolCallId, content: message.content, }; });}function mapReason(reason: string | null | undefined): StopReason { if (reason === "tool_calls") return "toolUse"; if (reason === "length") return "length"; return "stop";}/** 真模型:只有一个 POST,流式读 SSE,边读边翻译成 chunk。 */export function createOpenAIProvider(options: OpenAIOptions = {}): Provider { const env = process.env.OPENAI_BASE_URL ?? ""; const baseUrl = (options.baseUrl ?? env).replace(/\/$/, ""); const apiKey = options.apiKey ?? process.env.OPENAI_API_KEY ?? ""; const model = options.model ?? process.env.OPENAI_MODEL ?? "gpt-4o-mini"; return { name: "openai", async *stream(messages, tools, signal) { if (!baseUrl || !apiKey) { throw new Error("缺 OPENAI_BASE_URL 或 OPENAI_API_KEY"); } const response = await fetch(`${baseUrl}/chat/completions`, { method: "POST", signal, headers: { "content-type": "application/json", authorization: `Bearer ${apiKey}`, }, body: JSON.stringify({ model, stream: true, messages: wireMessages(messages), tools: tools.map((tool) => ({ type: "function", function: { name: tool.name, description: tool.description, parameters: tool.parameters, }, })), }), }); if (!response.ok || !response.body) { const body = await response.text(); throw new Error(`HTTP ${response.status}: ${body.slice(0, 200)}`); } const reader = response.body.getReader(); const decoder = new TextDecoder(); const pending = new Map<number, PendingCall>(); let buffer = ""; while (true) { const { done, value } = await reader.read(); if (done) break; buffer += decoder.decode(value, { stream: true }); const parts = buffer.split("\n\n"); buffer = parts.pop() ?? ""; for (const part of parts) { for (const line of part.split("\n")) { const data = line.startsWith("data:") ? line.slice(5).trim() : ""; if (!data || data === "[DONE]") continue; const event = JSON.parse(data); const choice = event.choices?.[0]; if (!choice) continue; const delta = choice.delta ?? {}; if (delta.content) { yield { type: "text", text: delta.content } as ProviderChunk; } for (const call of delta.tool_calls ?? []) { const index = call.index ?? 0; const slot = pending.get(index) ?? { id: "", name: "", args: "" }; if (call.id) slot.id = call.id; if (call.function?.name) slot.name += call.function.name; if (call.function?.arguments) { slot.args += call.function.arguments; } pending.set(index, slot); } if (choice.finish_reason) { for (const [index, slot] of pending) { let args: Record<string, unknown> = {}; try { args = JSON.parse(slot.args) as Record<string, unknown>; } catch { args = { _raw: slot.args }; } yield { type: "toolCall", id: slot.id || `call_${index}`, name: slot.name, args, } as ProviderChunk; } pending.clear(); const stopReason = mapReason(choice.finish_reason); yield { type: "done", stopReason } as ProviderChunk; } } } } }, };}export type { Tool };五段,逐个说。
第一段:wireMessages——出站翻译。 我们要发给模型的只有四种消息,但形状
不等于 OpenAI 的形状:
assistant在我的模型里是content: ContentBlock[],OpenAI 要的是content: string | null加一个并列的tool_calls数组。所以 text 块join(""),toolCall 块折成{id, type, function:{name, arguments}}。arguments必须是字符串,不是对象。所以这里JSON.stringify(block.args)。 反过来入库时再JSON.parse——来回一趟,就是「对象 ↔ 字符串」的边界。content: text || null:只要带了 tool_calls,text 允许为空,但不能是空字符串 (部分严格实现会 400)。tool消息的字段名是tool_call_id,不是我们的toolCallId。
第二段:一个 POST,stream: true。 没有 SDK、没有重试、没有 base64 图片、
没有 prompt cache 字段。signal 直接透传,取消就断。
第三段:错误要带状态码和响应体前 200 字符。 !response.ok 时如果只抛
HTTP 401,你会去猜是 key 错了还是模型名错了;带上 body 前 200 字符,通常
第一句就写着原因。
第四段:SSE 的切分。 这是最容易写错的地方。reader.read() 给你的是任意
长度的字节块,一个事件可能被劈成两半,也可能两个事件挤在一块。所以:
buffer += decoder.decode(value, { stream: true });const parts = buffer.split("\n\n");buffer = parts.pop() ?? "";split("\n\n") 是 SSE 的事件分隔;parts.pop() 取回的最后一段是不完整的,
必须留到下一次。decoder.decode(value, { stream: true }) 里的 stream: true
也是同一个道理:一个多字节汉字可能被劈在两个字节块之间。
第五段:tool_calls 分片。 真模型发工具调用时是一个片段一个片段来的:
{"index":0,"id":"call_9","function":{"name":"read","arguments":"{\"pa"}}{"index":0,"function":{"arguments":"th\":\"README.md\"}"}}id 只来一次,name 和 arguments 会 += 累加。所以 pending 是按 index
索引的暂存表。等 finish_reason 出现,再一次性 yield 成完整的 toolCall。
args 解析失败时我塞 {_raw: slot.args} 而不是抛错——因为「模型给了坏 JSON」
是模型的问题,应该作为一条 tool 结果(或一次可观测的失败)回到循环里,而不是
让整个进程崩。
六、跑一遍
<!-- file: examples/mini-agent/src/demo-model.ts -->
/** * E03 的终点:同一份 loop.ts,换一个 provider 就换了一种「模型」。 * 运行:cd examples/mini-agent && node src/demo-model.ts */import { loadChunks, createFixtureProvider } from "./provider/fixture.ts";import { runAgent } from "./loop.ts";import { toLlm } from "./messages.ts";const basic = "fixtures/openai-basic.jsonl";const tool = "fixtures/openai-tool.jsonl";function describe(file: string): void { console.log(`\n${file}`); for (const chunk of loadChunks(file)) { if (chunk.type === "text") { console.log(` text ${chunk.text}`); } else if (chunk.type === "toolCall") { const args = JSON.stringify(chunk.args); console.log(` toolCall ${chunk.name} ${args}`); } else { console.log(` done ${chunk.stopReason}`); } }}describe(basic);describe(tool);/* 同一个循环,provider 换成回放:一行代码都不用改 */const result = await runAgent({ provider: createFixtureProvider(basic), tools: [], messages: [{ role: "user", content: "你好" }], maxTurns: 2, project: toLlm, emit: (event) => { if (event.type === "text_delta") process.stdout.write(event.text); },});console.log(`\nturns=${result.turns} stop=${result.stopReason}`);输出里的 turns=1 值得停一下:带子只有一条 done,第二轮没有新 chunk,循环
在第一次就判定「没有 toolCall → 停」。这是 provider 的职责边界:它只负责
把一轮回复吐干净,轮次由循环决定。
七、真模型那段,不联网也能测
fixture 不碰 SSE,那 openai.ts 谁来测?起一个本地 http 服务器,假装自己是
OpenAI,而且故意把一个事件劈成两半:
<!-- file: examples/mini-agent/test/openai.test.ts -->
import test from "node:test";import assert from "node:assert/strict";import { createServer } from "node:http";import { createOpenAIProvider } from "../src/provider/openai.ts";import type { ProviderChunk } from "../src/types.ts";test("openai 解析 SSE:一个事件被劈成两半也能拼回来", async () => { const lines = [ 'data: {"choices":[{"delta":{"content":"你"}}]}\n\n', 'data: {"choices":[{"delta":{"content":"好"}}]}\n\n', 'data: {"choices":[{"delta":{},"finish_reason":"stop"}]}\n\n', "data: [DONE]\n\n", ]; const server = createServer(async (_req, res) => { res.writeHead(200, { "content-type": "text/event-stream" }); /* 故意把第一个事件从中间切开,分两次 write; 中间等 20ms,否则两个 write 会被合成一个网络块,测不到切割 */ res.write(lines[0].slice(0, 20)); await new Promise((resolve) => setTimeout(resolve, 20)); res.write(lines[0].slice(20)); for (const line of lines.slice(1)) res.write(line); res.end(); }); await new Promise<void>((resolve) => server.listen(0, resolve)); const port = (server.address() as { port: number }).port; const provider = createOpenAIProvider({ baseUrl: `http://127.0.0.1:${port}`, apiKey: "test", model: "test", }); const chunks: ProviderChunk[] = []; const messages = [{ role: "user" as const, content: "hi" }]; try { for await (const chunk of provider.stream(messages, [])) { chunks.push(chunk); } } finally { /* 即使断言前就抛错,也要关服务器:否则测试会卡在不退出的状态 */ server.close(); } assert.deepEqual( chunks.map((chunk) => chunk.type), ["text", "text", "done"], );});真实结果:
✔ openai 解析 SSE:一个事件被劈成两半也能拼回来 (50.3555ms)ℹ tests 1ℹ pass 1ℹ fail 0这个测试写了三版,前两版都是「能过但测不到东西」,三处坑都值得记:
第一坑:两次 res.write ≠ 两个网络块。 TCP 会把相邻的小写合在一起,
所以第一版「劈两半」的测试,实际收到的是一个完整事件——我把 openai.ts 的
buffer 复位注释掉,它照样绿。加了 await setTimeout(20) 之后才真劈开。
测试如果不是红的,它可能什么都没测。
第二坑:拆掉那行会怎么死。 把 buffer = parts.pop() ?? "" 删掉,重跑:
SyntaxError: Unterminated string in JSON at position 14 at Object.stream (.../src/provider/openai.ts:114:32)半截事件被 JSON.parse,报的是「字符串没完」——它不是「缺少复位」这种话,
所以你得自己把行号映射回那两行切割逻辑。
第三坑:失败后测试不退出。 第一版没有 try/finally,抛错时 server.close()
被跳过,端口句柄悬着,node --test 卡到超时。测试代码也要管资源:finally
里关掉的不是服务器,是「失败时要能看见失败」。
顺手把回放器的测试也补齐(test/provider.test.ts,37 行)——它只断言类型序列
和参数,不依赖网络。
八、没配凭据的样子
node src/cli.ts --openai "hi"Error: 缺 OPENAI_BASE_URL 或 OPENAI_API_KEY at Object.stream (.../src/provider/openai.ts:72:15) at runAgent (.../src/loop.ts:48:22)栈直接打穿了整个进程。这是故意的:loop.ts 目前不接 provider 的错误,
cli.ts 也还没写 try/catch。要不要现在补?不补——这一层需要一个 error 事件
和一次收尾(agent_end 得发两次吗?工具还没跑完时怎么收?),E08 写 CLI 时一起
处理。现在你只需要知道:provider 抛错 = 进程崩,不是「模型回答失败」。
九、代码地图
| 文件 | 关键符号 | 下一章怎么用 |
|---|---|---|
src/provider/fixture.ts |
loadChunks() / createFixtureProvider() |
E06 会话回放会再用它 |
src/provider/openai.ts |
wireMessages() / createOpenAIProvider() |
E04 加工具后,tools 数组直接进来 |
src/demo-model.ts |
describe() |
E08 并进 CLI 的 --fixture |
fixtures/*.jsonl |
— | 手写或录制,坏行报行号 |
tools: [] 这件事在下一章就变了。openai.ts 里那段
tools.map(...) 已经是完整实现:E04 只要把工具塞进 runAgent,模型就能看见
它们的名字、描述和参数 schema。接口先立住的好处就在这里——加能力不用回头
改协议。
自检
buffer.split("\n\n")之后为什么必须parts.pop(),而不是丢掉最后一段?- 带子里没有
done会怎样?错误在哪一层被拦住? - provider 抛错时,
loop.ts的emit会发出哪些事件?为什么这不是 bug?
参考答案:
第 1 题:split 的最后一段可能是不完整事件(网络块边界正好落在事件中间)。
留到下一轮和新的字节拼起来,才可能凑成完整事件。丢掉它就等于丢掉模型的半句话,
而且不报错。
第 2 题:不会报错。实测 turns=1 stop=stop,一切看起来正常。危险就在这里:
那个 stop 是循环里的初始值,不是模型报的原因。真模型被 length 截断时,你
也会看到 stop,然后去查一个不存在的问题。所以错误要在最早能识别的那一层报,
并且报得像它真正的原因。
第 3 题:agent_start、turn_start 已发,agent_end 不会发——异常直接
穿透 runAgent。这不是 bug,是「谁负责兜底」还没定:宿主(CLI / TUI)知道怎么
告诉用户,库不该擅自吞掉异常。E08 的 CLI 会 catch 它、打一行人话、退出码 1。
十、与 Pi 的对照(可选)
Pi 的 provider 在 packages/ai/,一个 OpenAI Chat Completions 适配器就有
1,594 行(src/api/openai-completions.ts),而你刚写的是 159 行。它多出来
的是:
src/api/openai-completions.ts:542的for await (const chunk of ...)之外, 还有 reasoning 明细、prompt cache、usage 计费、九家 provider 的字段兼容;:640起处理delta.tool_calls,参数用src/utils/streaming-json.ts的ToolCallArgumentsStream做增量解析——比 我们的「拼成整串再JSON.parse」更早发现坏 JSON;src/providers/openai.ts只有 34 行,因为它只列模型清单。
结构同构:一个 POST,一个循环,一套分片。你现在这 159 行是删掉所有兼容性之后 的骨架,出问题时知道该往哪个方向加。
十一、下一章
现在 tools: [],模型永远只能说话。E04 把工具接回来:注册表、参数校验、并发
执行,以及一个真问题——两个工具同时写同一个文件,谁先写?
E04 结束时,node src/demo-tools.ts 会打印出一份「谁在等谁」的依赖图。