模型调用：在课程协议和 Provider API 之间转换

#你将得到什么

第 04 章写出的 ScriptedModel 接收 AgentContext，返回 ModelEvent。真实模型也要接到 这个位置上。不过，它在进程外面：消息要先写成 HTTP 请求，回复则以 SSE 字节流的 形式回来。

这一章跟随一次完整的模型调用。发送方向从一条课程消息开始，经过 Provider 请求， 最后进入 fetch；返回方向从网络字节开始，经过 SSE 和一组较小的 ProviderChunk， 最后回到前几章已经使用过的 ModelEvent。

AgentContext → ProviderRequest → HTTP
ModelEvent   ← ProviderChunk   ← SSE

这里会出现两个新名字。adapter 负责课程协议与 Provider 语义之间的转换； transport 负责 HTTP、SSE 和外部 JSON。写完以后，ScriptedModel 与真实模型都能 通过同一个 Model.stream() 交给上层使用。

本章只讨论模型边界的转换。工具参数怎样验证、工具怎样执行，留到第 06 章。实现会 修改 packages/pi-course/src/types.ts 和 packages/pi-course/src/provider-adapter.ts。

#先建立全景

先看发送方向。课程内部的一条 user message 是一个带 content block 的对象：

{
  role: "user",
  content: [{ type: "text", text: "读取 README.md" }],
  timestamp: 1,
}

OpenAI-compatible API 接收的同一条消息更扁平：

{ role: "user", content: "读取 README.md" }

toProviderMessages() 读取前一个对象，写出后一个对象。system prompt、assistant 的 工具调用和 tool result 也在这里转换。完成转换后，它们和模型名一起组成 ProviderRequest。

返回方向多两层。下面是一条真实 SSE data 的形状：

data: {"choices":[{"delta":{"content":"正在读取"}}]}

transport 先从字节流中取出完整的 data:，解析 JSON，并检查课程实际用到的字段。 上面的 payload 会变成一个较小的对象：

{ type: "text", delta: "正在读取" }

这个对象叫 ProviderChunk。adapter 不再接触 choices[0].delta.content 之类的外部 字段；它只根据 ProviderChunk 累积回复，并发出课程中的 text_delta、 toolcall_delta、done 或 error。

AgentContext
    │  toProviderMessages()
    ▼
ProviderRequest
    │  transport.stream()
    ▼
raw SSE ──→ ProviderChunk ──→ ModelEvent ──→ AssistantMessage
           transport          adapter

ProviderChunk 是两段代码之间的接缝：

export type ProviderChunk =
  | { type: "text"; delta: string }
  | {
      type: "tool";
      index: number;
      id?: string;
      name?: string;
      argumentsDelta?: string;
    }
  | {
      type: "finish";
      reason: "stop" | "length" | "tool_calls";
      usage?: Partial<Usage>;
    };

真实 transport 和测试使用的 fixedTransport() 都实现同一个接口：

export interface ProviderTransport {
  stream(
    request: ProviderRequest,
    options: { signal?: AbortSignal },
  ): AsyncIterable<ProviderChunk>;
}

因此 adapter 可以先在离线数组上写完。网络解析接好以后，它处理的仍是同样三个 chunk 分支。

{ type: "tool", index: 0, argumentsDelta: '{"path":' }
{ type: "tool", index: 0, argumentsDelta: '"README.md"}' }

#把消息写成 Provider 请求

模型请求还需要知道本轮可以调用哪些工具。ToolDefinition 保存工具名称、说明和 交给模型的 JSON Schema：

export interface ToolDefinition {
  name: string;
  description: string;
  parameters: Record<string, unknown>;
}

export interface AgentContext {
  systemPrompt?: string;
  messages: AgentMessage[];
  tools?: ToolDefinition[];
}

这里的 schema 只会进入模型请求。第 06 章会为它配上运行时验证器。

看一份稍完整的 context：

const context: AgentContext = {
  systemPrompt: "回答要简洁。",
  messages: [
    userMessage("读取 README.md"),
    assistantMessage([
      {
        type: "toolCall",
        id: "call-1",
        name: "read",
        arguments: { path: "README.md" },
        rawArguments: '{"path":"README.md"}',
      },
    ], "toolUse"),
    {
      role: "toolResult",
      toolCallId: "call-1",
      toolName: "read",
      content: [text("# Project")],
      isError: false,
      timestamp: 1,
    },
  ],
};

toProviderMessages(context) 写出的数组是：

[
  { role: "system", content: "回答要简洁。" },
  { role: "user", content: "读取 README.md" },
  {
    role: "assistant",
    content: null,
    tool_calls: [{
      id: "call-1",
      type: "function",
      function: {
        name: "read",
        arguments: '{"path":"README.md"}',
      },
    }],
  },
  {
    role: "tool",
    tool_call_id: "call-1",
    name: "read",
    content: "# Project",
  },
]

四种 role 在这个例子里都出现了。system prompt 变成第一条 system message；user 的 text block 合并成字符串；assistant 的工具调用进入 tool_calls；课程中的 toolResult 则写成 Provider 的 role: "tool"，并继续使用原来的 call id。

工具参数优先采用 rawArguments：

arguments:
  call.rawArguments ?? JSON.stringify(call.arguments ?? {})

rawArguments 保存 Provider 原先给出的字符序列。重新序列化一个已经解析过的对象， 可能改变空格或字段顺序，也无法表示被截断的原文。只有没有原文时，才从 arguments 生成 JSON。

toProviderTools() 做另一项转换，把每个 ToolDefinition 包进 Provider 所需的 { type: "function", function: ... }。没有工具时返回 undefined，请求体也就不会 带一个空数组。这两个转换都是纯函数；传入的 context 在调用后保持原样。

npm run build -w @pi/course
node --test --test-name-pattern="出站转换" \
  packages/pi-course/dist/test/05-*.test.js

#从 ProviderChunk 读回模型回复

发送方向处理的是完整对象。返回方向是一段会逐渐长出来的回复。先看只有文本的情况：

[
  { type: "text", delta: "正在" },
  { type: "text", delta: "读取" },
  { type: "finish", reason: "stop", usage: { output: 2 } },
]

adapter 依次发出 start、两个 text_delta 和 done。第一个 delta 之后，partial 中 的文本是“正在”；第二个 delta 之后，它变成“正在读取”。每个事件保存的是该时刻 已经形成的完整 partial，而非最后一个字符串片段。

工具调用也会分段到达，而且文本与多个工具可能交错：

tool index 4   {"path":
text           先读
tool index 2   {"query":
tool index 4   "README.md"}
text           ，再查
tool index 2   "pi"}
finish         tool_calls

Provider 的 index 只负责把后续片段送回同一个工具。canonical content 则按照内容 第一次出现的先后排列：

content[0] = tool index 4
content[1] = text
content[2] = tool index 2

第一次遇到工具 4 时，adapter 为它建立一个 ToolBuffer，把当时的 content.length 记为 contentIndex。以后再收到 index 4，只更新这个 buffer 和 content[0]。工具 2 同样保留自己的 buffer，但它第一次出现得更晚，所以占据 content[2]。

一次 stream() 需要保存这些值：

这些值属于一次请求，写在 stream() 内。每次 delta 先更新对应槽位，再用 structuredClone(content) 留下事件快照。后来的字符不会反过来改变已经发出的 partial。

finish 决定工具参数怎样收尾。tool_calls 表示 Provider 已经完成工具调用，此时 adapter 解析完整 JSON，并发出 toolcall_end。length 表示输出被截断；参数原文会 留下来，stop reason 也保持 length，后续 Agent Loop 不会执行它。

transport 抛出的异常会沿用当前 content 生成 error message。取消对应 aborted，其他异常对应 error。终态事件与 stream.result() 使用同一条最终消息。

npm run build -w @pi/course
node --test --test-name-pattern="normalized transport" \
  packages/pi-course/dist/test/05-*.test.js

到这里，adapter 已经可以完全离线运行。余下工作是让网络响应产生同样的 ProviderChunk。

#从 SSE 字节流读出 ProviderChunk

fetch 返回 ReadableStream<Uint8Array>。一次 reader.read() 只表示“这次读到了 一些字节”，它不对应一条 SSE event。下面这条 data 甚至可能从 JSON 字符串中间被 切成两次网络读取：

data: {"choices":[{"delta":{"content":"正在
读取"}}]}

transport 维护一个字符串 buffer。新字节由带 { stream: true } 的 TextDecoder 解码并追加进去；每读到一个换行，才取出一行；空行出现时，此前收集的 data: 行构成一条完整 SSE payload。

网络字节块            没有协议含义
    ↓ TextDecoder
文本行                 识别 data:
    ↓ 空行结束一组 data
SSE payload 字符串
    ↓ JSON.parse + 字段检查
ProviderChunk

JSON.parse 的结果从 unknown 开始。课程只读取下列字段：

• 顶层 choices 数组；
• choice.delta.content；
• choice.delta.tool_calls 及其中的 index、id、name、arguments；
• finish_reason；
• usage 中的三个 token 数。

每走一层都检查实际类型。tool index 和 token 数还必须是非负安全整数。普通流只接受 一个 choice；空 choices 留给尾随 usage。其他字段即使存在，也不会因此进入课程 协议。

finish_reason 与 usage 可能来自不同 payload。transport 读到结束原因后先记住它， 继续等待尾随 usage；遇到 [DONE] 或输入结束，再合成唯一的 finish chunk。整个流 没有出现结束原因时，adapter 会用已经积累的 partial 形成 error 终态。

读取前后都检查 abort signal。reader 在 finally 中取消并释放 lock，所以正常结束、 解析异常和取消会走过同一个资源清理位置。

npm run build -w @pi/course
node --test --test-name-pattern="SSE" \
  packages/pi-course/dist/test/05-*.test.js

#发出 HTTP 请求

transport 最后需要写出完整的 fetch 选项。base URL 去掉末尾斜杠后，加上 /chat/completions：

{
  method: "POST",
  headers: {
    Accept: "text/event-stream",
    Authorization: `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    ...request,
    stream: true,
    stream_options: { include_usage: true },
  }),
  signal,
}

API key 由 transport 配置持有。请求发出时，它进入 Authorization header；body、 AgentContext 和 canonical message 中都没有这项数据。底层 fetch 的异常文本可能 包含认证信息，因此 transport 在错误离开这一层之前，把 key 替换成 [redacted]。 AbortError 保持原来的名称，adapter 才能识别取消。

课程测试注入离线 fetch，直接记录 URL、header、body 和 signal。它不会调用真实 Provider，也不需要 API key 或网络费用。

npm run build -w @pi/course
node --test --test-name-pattern="fetch transport" \
  packages/pi-course/dist/test/05-*.test.js
node --test packages/pi-course/dist/test/05-*.test.js

#故意把它弄坏

这一节是完成实现后的诊断实验。把工具的 contentIndex 临时改成 Provider 给出的 chunk.index：

contentIndex: chunk.index

测试数据中的工具 index 按 4、2 到达，中间还有文本。改动以后，第一个 toolcall_delta 会指向 content[4]，而当时真正创建的工具槽位是 content[0]。

#本章验收

npm run build -w @pi/course
node --test packages/pi-course/dist/test/05-*.test.js

#可选迁移练习

#小结

一次真实模型调用现在可以从头读到尾。AgentContext 先变成 Provider 的消息和工具 定义；transport 发出 HTTP 请求，从 SSE 中读出经过检查的 ProviderChunk；adapter 再把这些 chunk 累积成 ModelEvent 与最终 AssistantMessage。

第 04 章的离线模型和这一章的真实模型因此共享 Model.stream()。上层代码不需要 读取 Provider 的 URL、header、choices 或 SSE。下一章会继续处理模型已经提出的 工具调用。