深入理解 pi/第 06 章
两个 Message,一个边界
第 1 章提过这两种类型,这一章讲它们为什么必须分开。
export type AgentMessage = Message | CustomAgentMessages[keyof CustomAgentMessages];
export type Message = SystemMessage | UserMessage | AssistantMessage | ToolResultMessage;
| 类型 | 形状 | 语义 | 为什么这样做 |
|---|---|---|---|
Message |
封闭四元组 | 所有模型 API 都认的四种角色 | 线上协议就是这四种,多一种都没有意义 |
AgentMessage |
开放(申明合并) | 会话记忆里的任意东西 | 扩展可以注册自己的消息类型,内核不必知道 |
CustomAgentMessages 是一个由扩展「声明合并」(declaration merging)扩充的接口。
于是出现了这个局面:内核代码里出现的类型是开放的,但真正发出去的形状是封闭的——两者之间必须有一次显式转换。
这次转换就是 convertToLlm。它的函数签名本身就说明了责任:
convertToLlm: (messages: AgentMessage[]) => Message[] | Promise<Message[]>;
Message 是封闭的,
任何自定义消息类型都必须提供一个「怎么变成四元组之一」的答案,否则代码根本编译不过。
编译器替你把「不许发明新的线上角色」这条规则守住了。
agent/types.ts:374(开放)· ai/types.ts:659(封闭)
StreamFn:不许抛错
这是 pi 类型系统里最强的一条契约,而且它写在注释里:
/** * Contract: * - Must not throw or return a rejected promise for request/model/runtime failures. * - Must return an AssistantMessageEventStream. * - Failures must be encoded in the returned stream via protocol events and a * final AssistantMessage with stopReason "error" or "aborted" and errorMessage. */ export type StreamFn = ( model: Model<Api>, context: TranscriptContext, options?: SimpleStreamOptions, ) => AssistantMessageEventStream | Promise<AssistantMessageEventStream>;
「不许抛错」听起来是个软约束,但它的实现支撑在另一处:StopReason 里有两个专门为此存在的取值。
export type StopReason = "pending" | "stop" | "length" | "toolUse" | "error" | "aborted" | "deferred";
| 取值 | 含义 | 谁会处理它 |
|---|---|---|
stop | 正常说完 | L2 检查有没有工具调用 |
length | 撞到输出上限 | 需要「续写」逻辑 |
toolUse | 要调工具 | 进 L3 执行 |
error | 请求失败 | 带 errorMessage 返回给 L2,L2 直接结束,L1 决定要不要重试 |
aborted | 被取消 | 同上,但走取消路径 |
pending | 占位(流式未完成) | 内部状态 |
deferred | 延后 | 特殊分支 |
为什么「错误变成数据」比抛异常好?因为这个错误需要被写进 transcript:
stopReason: "error"error 正常收尾,L1 从历史里读到这条失败并决定重试。失败也是一条真实发生过的事件。agent/types.ts:27-38(不抛错契约)· ai/types.ts:489(StopReason)
配对完整性:为什么它不需要运行时检查
「每个 toolCall 必须有对应的 toolResult」——这是所有 agent 框架最头疼的不变量。 pi 基本不用运行时校验,因为它在结构上就不可能出现。
推理链条是这样:
ToolResultMessage 只能由内核产生AssistantMessage,其中的 toolCall 是内容块,不是消息。模型无法自己「插入工具结果」。executedToolBatch 产出结果后立刻 append,不会隔圈。所以「调用」和「结果」在 transcript 里永远相邻且成对。isError: true 的结果——结果一定存在。stopReason: "length")时可能出现「调用被截半」——pi 在这里合成一条配对错误结果,而不是留下空洞。
第 ③ 和第 ④ 合起来,就是「配对完整」的全部保证。它不靠一个 validateTranscript(),
而是靠让每个可能出错的环节都返回一个合法结果。
agent-loop.ts:488(截断时合成配对)· :818(永不 reject 契约)
ToolDefinition:一个工具要回答的 8 个问题
工具的类型定义本身就是一份规范。一个工具必须声明的事情,恰好是模型和框架各自需要的:
| 字段 | 给谁 | 回答什么问题 |
|---|---|---|
name / label | 模型 / UI | 它叫什么 |
description | 模型 | 什么时候该用它 |
parameters(TypeBox schema) | 模型 + 校验 | 参数长什么样 |
constrainedSampling | provider | 能不能约束解码 |
prepareArguments | 框架 | 畸形参数怎么修 |
execute | 框架 | 真正做什么 |
promptSnippet / promptGuidelines | 模型 | 在系统提示里怎么介绍它 |
renderShell | UI | 输出怎么渲染 |
注意 parameters 用的是 TypeBox(Type.Object),它同时提供两样东西:
TypeScript 类型(编译期)和 JSON Schema(运行时、发给 provider)。一份声明,三处使用。
const readSchema = Type.Object({ path: Type.String({ description: "Path to the file to read (relative or absolute)" }), offset: Type.Optional(Type.Number({ description: "Line number to start reading from (1-indexed)" })), limit: Type.Optional(Type.Number({ description: "Maximum number of lines to read" })), });
这里还有个容易忽略的细节:description 是给模型看的提示词,不是给人看的文档。
所以它写的是「(1-indexed)」「(optional, no default timeout)」这种防止误用的话,而不是「读取文件」这种废话。
类型做了四件运行时不用做的事
| # | 不变量 | 靠什么保证 | 省掉了什么 |
|---|---|---|---|
| 1 | 线上只有 4 种角色 | Message 封闭联合 |
不用在发送前校验角色合法性 |
| 2 | 失败不会中断循环 | StreamFn 契约 + stopReason |
不用在每层 try/catch |
| 3 | 调用与结果成对 | 工具永不 reject + 截断时合成 | 不用全量扫描轨迹找孤儿调用 |
| 4 | 工具声明完整 | ToolDefinition 必填字段 |
不用在注册时做字段检查 |
六章讲完。回头看,pi 的「极简」不在于代码少——而在于它把复杂度放在了边界上: 两个 Message 类型之间、一次模型请求的前后、一个工具的入参和出参之间。 每一处边界都有明确的类型或契约,所以内部可以很小。
这也解释了为什么内核 6 个文件 2,541 行就能跑一个完整 agent:不是省略了功能,是把功能压进了契约里。