ScriptedModel：把模型行为写成可执行规格

#你将得到什么

前两章已经定义了消息和事件流，但还没有组件负责生产模型事件。如果现在直接连接 真实 LLM，网络、鉴权、费用、限流和随机输出会同时进入测试。测试失败时，你很难 判断究竟是 Agent 协议写错了，还是远端服务临时发生了变化。

本章处理一个新问题：如何构造一个遵守真实模型边界、行为又完全确定的事件生产者。 你将实现 ScriptedModel。它按轮读取预先写好的脚本，记录每次传入的 context， 并把成功、错误和预先取消都转换成统一的模型事件。

本章不变量是：

ScriptedModel 和真实 adapter 都满足同一个 Model.stream() 契约。上层代码 只消费模型事件，不需要判断当前接入的是脚本模型还是真实服务。

重新练习时，运行 npm run practice -w @pi/course -- 04 <新目录>。练习目录会 保留第 03 章实现，只移除本章的 scripted-model.ts，并注入第 04 章聚焦测试。

#先建立全景

ScriptedModel 是一种 test double，也就是专门替代外部依赖的测试实现。它和一个 随便返回 "hello" 的 mock 不同：脚本描述的是某一轮模型最终应产生什么消息， ScriptedModel 仍要按照真实协议生成中间事件和终态。

AgentContext
    │
    ▼
ScriptedModel.stream(context, { signal })
    ├─ 立即返回 AssistantMessageEventStream
    ├─ 保存 context 在调用时的快照
    └─ 在 microtask 中读取一个 ScriptedTurn
          TextContent → text_delta
          ToolCall    → toolcall_delta → toolcall_end
          正常消息    → done
          错误或取消  → error

microtask 是“当前同步代码结束后立刻执行”的小任务。stream() 先把流返回给调用者， 再由 microtask 发送事件。这样消费者可以先拿到流并开始等待；认证、模型运行或网络 阶段发生的失败，也能统一通过流内的 error 终态报告。

#先固定 Model 的唯一入口

第 03 章已经在 types.ts 中定义了 Model 和 ModelStream。本章不修改这些接口， 只实现它们：

export interface Model {
  stream(
    context: AgentContext,
    options?: { signal?: AbortSignal },
  ): ModelStream;
}

export interface ModelStream extends AsyncIterable<ModelEvent> {
  result(): Promise<AssistantMessage>;
}

脚本中的一个回合有两种写法。正常回合直接提供最终 AssistantMessage；错误回合 提供停止原因、错误说明和可选的部分文本：

export type ScriptedTurn =
  | AssistantMessage
  | {
      stopReason: "error" | "aborted";
      errorMessage: string;
      partialText?: string;
    };

ScriptedTurn 记录脚本预先规定的最终结果，不直接保存 ModelEvent[]。 ScriptedModel 仍要先发送 start，再按 content block 的顺序生成事件，最后根据 stop reason 发送 done 或 error。因此，测试验证的是事件生成边界，而非简单 回放一组预置事件。

#播放一个成功回合

先看第一项测试中的脚本。它包含一个 text block 和一个 tool call，所以完整事件 顺序应为：

start
text_delta
toolcall_delta
toolcall_end
done

start 携带空 content 的 partial message。处理每个 block 时，先把当前增量应用到 partial，再发送事件。这样 text_delta 的 partial 已经包含当前文本； toolcall_delta 的 partial 既保留前面的文本，也包含正在生成的 tool call； toolcall_end 再把完整参数写入同一位置。播放结束后，终态直接提交脚本中的最终 消息，不从事件文本重新拼装一次。

可以先写出类的外框：

export class ScriptedModel implements Model {
  readonly requests: AgentContext[] = [];
  private cursor = 0;

  constructor(private readonly turns: ScriptedTurn[]) {}

  stream(
    context: AgentContext,
    options: { signal?: AbortSignal } = {},
  ): AssistantMessageEventStream {
    const stream = new AssistantMessageEventStream();
    this.requests.push(structuredClone(context));
    const turn = this.turns[this.cursor++];

    queueMicrotask(() => {
      // 先处理不会播放的分支，再投影一个有效 turn。
    });
    return stream;
  }
}

第一阶段仍要让整个测试文件通过 TypeScript 编译。你可以先声明完整 ScriptedTurn 联合。在 microtask 内先判断三种暂不播放的情况：signal 已取消、 turn 不存在，或者 turn 没有 role 字段。前两项是失败入口，第三项代表显式错误 turn。遇到它们时，先临时抛出 "not implemented in lab 4.1"。通过这些判断后， TypeScript 也能确认剩下的 turn 就是 AssistantMessage。局部测试只提供正常 turn，不会执行临时分支。

#按轮消费，并把失败放回流里

同一个模型实例会被 Agent 多次调用。cursor 每次只前进一个 turn：

const model = new ScriptedModel([
  assistantMessage([
    text("我先读取文件。"),
    {
      type: "toolCall",
      id: "c1",
      name: "read",
      arguments: { path: "README.md" },
    },
  ], "toolUse"),
  assistantMessage([text("项目用于学习 Agent。")], "stop"),
]);

第一次调用产生工具请求，第二次调用给出最终回答。第 07 章会把这两个回合接入 Agent loop。本章只负责模型边界，不负责把上一轮消息写进下一轮 context。

脚本还必须能稳定表达失败：

{
  stopReason: "error",
  partialText: "正在",
  errorMessage: "rate limited",
}

这条 turn 应产生：

start
text_delta "正在"
error reason=error
result.stopReason = "error"
result.errorMessage = "rate limited"

result() 仍然 resolve 一条 canonical assistant message。上层因此可以同时读取 部分文本和错误说明。它不会把错误伪装成普通 stop，也不会迫使调用者额外处理 一个同步 throw 分支。

脚本耗尽时，ScriptedModel 自己构造 stopReason: "error" 的消息；播放开始前， 如果 signal 已处于 aborted 状态，就构造 stopReason: "aborted" 的消息。 这两个分支都只发送 error 终态，不发送 start，也不播放原 turn。所有分支都在 microtask 内完成，所以 stream() 始终先返回事件流。

#故意把它弄坏

一种常见错误是在脚本耗尽时，从 stream() 同步抛出异常：

stream(): ModelStream {
  throw new Error("script exhausted");
}

这样调用者还没拿到流，就被迫处理另一条失败通道。

#本章验收

#可选迁移练习

#小结

ScriptedModel 是模型协议的一种确定性实现。它把脚本 turn 转成真实事件，保存 请求发生时的 context，并让成功、错误、脚本耗尽和预取消走同一条流。Agent 上层 由此获得了稳定的测试基座。下一章接入真实 provider 时，只需证明 adapter 产生 相同的边界行为，无需另建一套模型接口。