给 Agent 一套自己的消息格式

#你将得到什么

上一章的 EventStream<T,R> 已经知道事件怎么到达，却不知道 T 和 R 具体是什么。如果把某家 SDK 的 chunk 直接传进 Agent，换模型服务、保存会话和 调用工具时，每一层都会依赖那家 SDK。

本章给 Agent 定义一套自己的消息格式。这里把它叫作 canonical message： 它是系统认可、可以保存和重放的统一消息。你会新增 packages/pi-course/src/types.ts，并修改 packages/pi-course/src/event-stream.ts，让上一章的通用流变成 EventStream<ModelEvent, AssistantMessage>。

本章不变量是：

Provider payload、界面文字和 canonical message 分属三层。只有 canonical message 能成为 Agent 长期保存的事实。

需要重新开始时，用 npm run practice -w @pi/course -- 03 <新目录> 创建新练习。 不要修改注入测试，也不要为了适配后续 provider 样例而扭曲本章的消息结构。

#先建立全景

同一个用户意图，在不同边界有不同表示：

终端输入："读取 README"
        ↓  UI 构造
UserMessage { role: "user", content: [{ type: "text", text: "读取 README" }] }
        ↓  provider adapter 翻译
某家 API 的 { role: "user", content: "读取 README" }

中间那层才是 Agent 自己保存的消息。UI 从中取出适合显示的内容，adapter 把它 翻译成某家 API 的格式。若 session 直接保存 API payload，换 provider 就要迁移 历史数据；若只保存终端文字，tool call 的 id 和参数会直接丢失。

#Content block 保存有顺序的语义

课程先实现文本和工具调用两种 block。它们共享 type 判别字段，却只携带各自合法的数据：

export interface TextContent {
  type: "text";
  text: string;
}

export interface ToolCall {
  type: "toolCall";
  id: string;
  name: string;
  arguments: unknown;
  rawArguments?: string;
}

export type AssistantContent = TextContent | ToolCall;

产生 toolUse 终态前，toolcall_end 会把完整 JSON 写入 arguments。 第 05 章会处理 provider 分段发送的字符串。若输出因 length 被截断，系统保留 未完成的 rawArguments，但绝不能执行。第 06 章才会按工具 schema 验证参数。 JSON 能解析，只说明格式完整，不说明参数可以执行。

#三种消息承担不同所有权

消息联合不使用大量可选字段，而是让角色决定合法内容：

export type StopReason =
  | "stop"
  | "length"
  | "toolUse"
  | "error"
  | "aborted";

export interface UserMessage {
  role: "user";
  content: TextContent[];
  timestamp: number;
}

export interface AssistantMessage {
  role: "assistant";
  content: AssistantContent[];
  provider: string;
  model: string;
  usage: { input: number; output: number; totalTokens: number };
  stopReason: StopReason;
  errorMessage?: string;
  timestamp: number;
}

export interface ToolResultMessage {
  role: "toolResult";
  toolCallId: string;
  toolName: string;
  content: TextContent[];
  details?: unknown;
  isError: boolean;
  timestamp: number;
}

export type AgentMessage =
  | UserMessage
  | AssistantMessage
  | ToolResultMessage;

toolResult 是独立角色。它记录环境对某个 call 的返回，不属于用户，也不是模型 自己说的话。error 和 aborted 仍保存在最终 AssistantMessage 里。这样一次 失败调用也能保留已经生成的文本、usage 和错误说明。

Usage 也属于协议，而不只是日志。input 描述本次 context 的消耗，output 描述生成量，totalTokens 给上层预算与诊断一个统一基线。课程先不计算价格和缓存命中，但仍要求三者是数字字段，因为第 11 章会根据预算重建 context。若 adapter 没拿到可信 usage，应使用明确的缺省策略并保留诊断，不能从文本长度假装得到精确 token 数。

可以把最终消息看成一次模型调用的提交记录：

stop       完成回答，可以结束
toolUse    产生完整调用，交给工具层
length     输出被截断，保留事实但禁止执行调用
error      调用失败，保留 partial 与错误说明
aborted    用户取消，保留 partial 与取消事实

stop、toolUse 和 length 通过 done 事件结束；error 和 aborted 通过 error 事件结束。两类终态最终都能由 result() 取得。事件名表示流走了 哪条路径，message 的 stop reason 表示模型为什么结束。两者必须匹配。当前聚焦 测试只观察 error + error；其他组合会在后续模型与 adapter 测试中逐步补齐。

textOf() 是有损投影，不能用于重新构造 message。它适合搜索摘要与终端显示；保存和重放必须使用原始 block 数组。函数名和返回类型应让这种损失显而易见，避免调用者把便利函数误当序列化协议。

#Context 是本次请求的输入视图

AgentContext 不是整个 session。它只包含本次模型决策需要的 system prompt 与消息序列：

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

const nextContext: AgentContext = {
  systemPrompt: previous.systemPrompt,
  messages: [...previous.messages, newUserMessage],
};

用新数组构造下一状态，能让测试比较请求前后的事实。第 10 章会把 session 建成追加式事件树，第 11 章再从历史投影 context；本章不做裁剪，也不把 context 持久化成唯一真相。

消息保留 timestamp，但不加入随机 message id。时间由 canonical message 构造器在边界生成，fixture 可显式给定或在断言中归一化；provider 不应另造一套时间字段。到了会话层，稳定 entry id 将由拥有追加责任的组件生成。先明确所有权，再添加元数据，才能避免恢复时出现两个时钟或无法配对的 id。

上一章的流现在可以有准确终态：

export type ModelEvent =
  | { type: "start"; partial: AssistantMessage }
  | { type: "text_delta"; contentIndex: number; delta: string; partial: AssistantMessage }
  | { type: "toolcall_delta"; contentIndex: number; delta: string; partial: AssistantMessage }
  | { type: "toolcall_end"; contentIndex: number; toolCall: ToolCall; partial: AssistantMessage }
  | { type: "done"; reason: "stop" | "length" | "toolUse"; message: AssistantMessage }
  | { type: "error"; reason: "error" | "aborted"; error: AssistantMessage };

done 与 error 都是流终态，EventStream.result() 对两者都 resolve 最终 assistant message。调用者不必猜测 provider 是在首字节前还是中途失败。

#故意把它弄坏

如果为了“方便打印”把 tool result 改成 assistant 文本：

// 错误：环境事实失去了 call 的配对键
const fakeResult = assistantMessage(
  [{ type: "text", text: "README 内容是……" }],
  "stop",
);

后续 provider 无法知道这段内容回答哪个调用，并行工具更会立刻产生歧义。

#本章验收

#可选迁移练习

#小结

Agent 现在有了自己的消息格式。Content block 保留内容类型和顺序；user、 assistant、toolResult 三种角色各自记录不同来源的事实；stop reason 决定下一步 控制动作；context 只是一次模型请求要看到的消息。数据和时间都有了稳定接口， 下一章才能写一个行为完全可预测的模型。