Pi Agent 源码级教程
E03

接口 —— 先造一条能回放的模型,再接真的

2,515 字 · 含 334 行代码 · 约 14 分钟

E02 结束后,loop.ts 还是硬绑 createMockProvider()。mock 有个天花板:它只会 按三条规则说话,你没法用它验证「流式解析对不对」「工具参数分片拼没拼上」。

这一章把 provider 抽成真接口,然后写两份实现:

  • fixture:把一段回复录成文本,离线回放。零凭据、零网络、可进测试。
  • openai:一个 POST,读 SSE,边读边翻译成同样形状的 chunk。

三个问题:

  1. 回放要录什么?录原始 SSE,还是录我们自己的 chunk?
  2. 网络给来的是字节流,不是一个事件一个事件——怎么把它切成完整事件?
  3. 没有 API key 时,怎么证明真模型那段代码是对的?
text
  runAgent     |     |  provider.stream(messages, tools, signal)     v  ProviderChunk: text / toolCall / done     ^                    ^     |                    |  mock(三条规则)      fixture(回放) / openai(SSE)

一、本章终点:先跑起来

bash
cd examples/mini-agentnode src/demo-model.ts
text
fixtures/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 长这样 (真实录制,一行):

text
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 -->

text
{"type":"text","text":"你好"}{"type":"text","text":",这是一份录好的回复。"}{"type":"done","stopReason":"stop"}

<!-- file: examples/mini-agent/fixtures/openai-tool.jsonl -->

text
{"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 -->

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 结尾。 少了它不会报错——我删掉最后一行试了, 循环照样给出一个「正常」的结果:

bash
node tmp-nodone.ts
text
turns=1 stop=stop

看着没问题,但这句 stop 是 loop.ts 里的初始值,不是模型报的原因。真模型 如果是被 length 截断,你也会记成 stop,然后去查一个不存在的问题。所以 回放器在创建时就拦:

text
ERR: fixtures/tmp-bad.jsonl 最后一行必须是 done

判断二:坏行报行号。 带子是手写的,截断、少个引号都常见:

text
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 -->

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() 给你的是任意 长度的字节块,一个事件可能被劈成两半,也可能两个事件挤在一块。所以:

ts
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 分片。 真模型发工具调用时是一个片段一个片段来的:

text
{"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 -->

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 -->

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"],  );});

真实结果:

text
✔ openai 解析 SSE:一个事件被劈成两半也能拼回来 (50.3555ms)ℹ tests 1ℹ pass 1ℹ fail 0

这个测试写了三版,前两版都是「能过但测不到东西」,三处坑都值得记:

第一坑:两次 res.write ≠ 两个网络块。 TCP 会把相邻的小写合在一起, 所以第一版「劈两半」的测试,实际收到的是一个完整事件——我把 openai.ts 的 buffer 复位注释掉,它照样绿。加了 await setTimeout(20) 之后才真劈开。 测试如果不是红的,它可能什么都没测。

第二坑:拆掉那行会怎么死。 把 buffer = parts.pop() ?? "" 删掉,重跑:

text
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 行)——它只断言类型序列 和参数,不依赖网络。


八、没配凭据的样子

bash
node src/cli.ts --openai "hi"
text
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。接口先立住的好处就在这里——加能力不用回头 改协议。

自检

  1. buffer.split("\n\n") 之后为什么必须 parts.pop(),而不是丢掉最后一段?
  2. 带子里没有 done 会怎样?错误在哪一层被拦住?
  3. 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 会打印出一份「谁在等谁」的依赖图。