TypeScript、测试与 ESM 生存集

#你将得到什么

序章让你看见了一条完整轨迹，但还不能判断代码中的 assistant_message 是否覆盖了所有情况。本章进入时，系统只会播放固定数据；本章完成后，你能读写后续课程反复使用的 tagged union、unknown 收窄、Promise、ESM 导入和 Node 内置测试。

我们只增加一种主要复杂性：让编译器和测试成为两种不同的证据。不会讲前端、DOM、装饰器或复杂泛型。你将在隔离练习目录中创建 packages/pi-course/src/survival/events.ts；聚焦测试已经注入，不需要改测试。你会先看到缺少模块，再分别观察遗漏事件分支时的编译错误和实现错误时的测试失败。

本章不变量是：

来自系统边界的数据先是 unknown；只有经过验证和穷尽分支后，才能进入 Agent 的强类型核心。

恢复起点时，不要在无 Git 历史的练习目录里寻找旧提交。保留当前目录作实验记录，再用 npm run practice -w @pi/course -- 01 <新目录> 从同一 parent 生成干净起点；不要修改注入的测试或 package-lock.json。

#先建立全景

Node、TypeScript、运行器和测试框架各自回答不同问题：

TypeScript 源码
  ├─ tsc --noEmit  → “这些值的静态形状能否成立？”
  ├─ tsc           → 编译为 Node 可执行的 ESM JavaScript
  └─ node --test   → “给定输入时，行为和顺序是否符合契约？”

类型检查通过，不代表事件顺序正确；测试通过，也不代表所有联合类型都被覆盖。因此每个 checkpoint 都会同时运行 typecheck 和聚焦测试。ESM 的职责更窄：它规定文件怎样通过 import 与 export 连接，让项目结构成为可追踪的依赖图。

#用 tagged union 表达互斥状态

Agent 事件不是一张塞满可选字段的表。started 没有结果，delta 必须有片段，finished 必须有终态。把互斥状态写成联合类型后，event.type 同时是数据和编译器的证明线索：

export type DemoEvent =
  | { type: "started"; requestId: string }
  | { type: "delta"; requestId: string; text: string }
  | { type: "finished"; requestId: string; reason: "stop" | "length" };

export function formatEvent(event: DemoEvent): string {
  switch (event.type) {
    case "started":
      return `start ${event.requestId}`;
    case "delta":
      return `delta ${event.requestId} ${event.text}`;
    case "finished":
      return `finish ${event.requestId} ${event.reason}`;
    default: {
      const unreachable: never = event;
      return unreachable;
    }
  }
}

若改成 { type: string; text?: string; reason?: string }，无效组合也会合法，例如 started 同时携带 reason。联合类型把“哪些状态可能存在”写进协议，而不是留给注释。

#把边界的 unknown 收窄

JSON.parse()、环境变量和网络响应不受 TypeScript 控制。把它们直接断言成内部类型，只是让编译器闭嘴。正确方向是：边界接受 unknown，验证最小必要字段，再返回强类型值。

export function readDelta(value: unknown): DemoEvent {
  if (
    typeof value === "object" &&
    value !== null &&
    "type" in value &&
    value.type === "delta" &&
    "requestId" in value &&
    typeof value.requestId === "string" &&
    "text" in value &&
    typeof value.text === "string"
  ) {
    return { type: "delta", requestId: value.requestId, text: value.text };
  }
  throw new Error("invalid delta event");
}

这里故意不引入 schema 库：第 06 章才系统处理工具参数。现在要掌握的是信任方向——外部数据不能凭一个 as DemoEvent 穿透边界。

#ESM 与测试让文件形成可执行契约

课程统一使用显式相对导入，测试从公共导出读取行为。一个最小测试同时固定输出与顺序：

import assert from "node:assert/strict";
import test from "node:test";
import { formatEvent, type DemoEvent } from "../src/survival/events.js";

test("formatEvent preserves event order", () => {
  const events: DemoEvent[] = [
    { type: "started", requestId: "r1" },
    { type: "delta", requestId: "r1", text: "Pi" },
    { type: "finished", requestId: "r1", reason: "stop" },
  ];
  assert.deepEqual(events.map(formatEvent), [
    "start r1",
    "delta r1 Pi",
    "finish r1 stop",
  ]);
});

运行结果应是稳定模式，而不是依赖机器耗时：

✔ tagged union 的完成态覆盖全部事件分支
tests 2
pass 2

#Promise 让“何时完成”进入类型

后续 Model.stream() 会同步返回一个可迭代对象，而最终消息通过 Promise 在未来完成。async/await 不是把异步代码变成同步代码，而是让依赖关系清楚地写出来。最容易误用的是 forEach(async ...)：外层不会等待内部回调，错误也可能脱离当前控制流。

// 明确顺序：后一项依赖前一项完成
for (const event of events) {
  await persist(event);
}

// 明确并发：同时启动，但等待全部结果
const results = await Promise.all(events.map((event) => persist(event)));

两段代码都可能返回按输入排列的结果，但副作用完成顺序不同。Agent 中的 provider delta 通常必须顺序处理；多个独立工具未来可以并发执行，却仍要按协议决定 transcript 的写入顺序。不要靠“这次日志碰巧有序”推断调度保证。

ESM 也在保护这种边界。公共文件只导出上层真正需要的类型和函数；在 NodeNext 配置下，TypeScript 源文件使用运行时会存在的 .js 相对路径。循环依赖往往说明所有权混乱：例如 types.ts 不应反向 import provider adapter，否则 canonical IR 已经知道了外部实现。遇到导入错误时先画依赖方向，不要急着改回 require() 或移除严格配置。

本课程不会用 any 或关闭 strict 换取短暂绿灯。若暂时不知道一个值的形状，就让它保持 unknown，把不确定性留在边界附近；这比让错误穿过五层调用后再爆炸更便宜。

#故意把它弄坏

下面的写法能让错误数据“看起来有类型”，却没有任何运行时证据：

const event = JSON.parse(raw) as DemoEvent;
console.log(formatEvent(event));

若 raw 是 {"type":"delta","text":42}，编译器不会替你检查数字。错误可能在更远处变成难以定位的字符串拼接或状态污染。

#本章验收

#可选迁移练习

#小结

我们没有“学完 TypeScript”，而是获得了构造 Agent 所需的生存集：用联合类型表示互斥状态，用 never 暴露遗漏，用 unknown 守住边界，用 ESM 连接模块，再让类型检查和行为测试提供不同证据。下一章只增加时间维度：事件如何逐个到达、怎样完成、又怎样取消。