TypeScript 泛型继承与函数式策略

在 pi-agent 的测试套件中，SimulatedResponseStream（原 MockAssistantStream）展示了如何利用 TypeScript 的泛型和构造函数回调来构建灵活的测试工具。

class SimulatedResponseStream extends EventStream<ModelStreamEvent, FinalMessage> {
  constructor() {
    // 调用父类构造函数，注入流处理策略
    super(
      // 策略 1: 定义流的终结条件 (Predicate)
      (evt) => evt.status === "completed" || evt.status === "failed",
      
      // 策略 2: 定义结果提取逻辑 (Mapper)
      (evt) => {
        if (evt.status === "completed") return evt.payload;
        if (evt.status === "failed") return evt.error;
        throw new Error("Unhandled stream event");
      }
    );
  }
}

核心概念解析

1. 泛型继承 (Generic Inheritance)

EventStream<ModelStreamEvent, FinalMessage> 接受两个类型参数：

• ModelStreamEvent: 定义了流中流转的每一个事件对象的结构。
• FinalMessage: 定义了当流结束时，最终生成的产出物类型。

2. 策略注入

这是一种典型的策略模式应用。EventStream 作为一个通用的流控制器，并不关心具体的业务逻辑。通过在 super() 中传入两个箭头函数，子类将"何时结束"和"如何取值"的逻辑外包给了父类。这种设计使得基类能够处理通用的流状态管理（如 Loading、Error、Done 状态切换），而具体的解析协议则由子类决定。

模拟对象 (Mocking) 的必要性

在单元测试中，我们不希望真实调用大模型的 API，因为这会导致测试变慢、成本增加且结果不可控。SimulatedResponseStream 的存在就是为了模拟真实流的行为。

// 测试环境中的典型用法
const mockStream = new SimulatedResponseStream();
queueMicrotask(() => {
  const fakeMessage = generateMockReply("Hello, this is a mock response.");
  mockStream.push({ status: "completed", payload: fakeMessage });
});

通过这种方式，测试代码可以精确控制模型返回的内容，从而验证 Agent 逻辑在各种边界情况（如网络中断、特定回复格式）下的表现。

助手消息的构造逻辑

在测试中，我们需要频繁构造 AssistantMessage。以下是一个生成模拟回复的工具函数：

function generateMockReply(textContent: string): AssistantResponse {
  return {
    role: "assistant", // 明确标识为助手角色
    content: [{ type: "text", text: textContent }],
    api: "openai-responses", // 指定解析协议
    provider: "openai",
    model: "test-environment",
    usage: {
      prompt: 0,
      completion: 0,
      total: 0,
    },
    finishReason: "stop",
    createdAt: Date.now(),
  };
}

API 协议标识：openai-responses

在 api 字段中出现的 "openai-responses" 并不直接代表数据来源，而是代表协议格式。OpenAI 提供了多种接口规范（如传统的 Chat Completions 和较新的 Responses API）。

字段名称	技术含义
role	消息归属。在测试中区分 user（用户输入）和 assistant（模型输出）。
api	数据协议类型。指示下游组件应采用哪种解析器来处理 content 或 usage 字段。
provider/model	元数据。在日志或统计中用于标识虚构的底层服务。

在 pi-agent 的架构设计中，这种明确的 API 协议标识使得系统具备了多模型适配能力。即使消息是模拟生成的，它也必须携带正确的协议头，以确保 Agent 的后续处理流水线（如长短期记忆存储、Token 计数器）能够正常运作。