深入理解 pi 06 / 06 目录 单页全本 学习手册 对比站

深入理解 pi/第 06 章

6.1

两个 Message,一个边界

第 1 章提过这两种类型,这一章讲它们为什么必须分开。

packages/agent/src/types.ts:374
export type AgentMessage = Message | CustomAgentMessages[keyof CustomAgentMessages];
packages/ai/src/types.ts:659
export type Message = SystemMessage | UserMessage | AssistantMessage | ToolResultMessage;
类型形状语义为什么这样做
Message 封闭四元组 所有模型 API 都认的四种角色 线上协议就是这四种,多一种都没有意义
AgentMessage 开放(申明合并) 会话记忆里的任意东西 扩展可以注册自己的消息类型,内核不必知道

CustomAgentMessages 是一个由扩展「声明合并」(declaration merging)扩充的接口。 于是出现了这个局面:内核代码里出现的类型是开放的,但真正发出去的形状是封闭的——两者之间必须有一次显式转换。

这次转换就是 convertToLlm。它的函数签名本身就说明了责任:

packages/agent/src/types.ts:222
convertToLlm: (messages: AgentMessage[]) => Message[] | Promise<Message[]>;
这是整篇最「类型驱动」的一处设计:因为 Message 是封闭的, 任何自定义消息类型都必须提供一个「怎么变成四元组之一」的答案,否则代码根本编译不过。 编译器替你把「不许发明新的线上角色」这条规则守住了。

agent/types.ts:374(开放)· ai/types.ts:659(封闭)

6.2

StreamFn:不许抛错

这是 pi 类型系统里最强的一条契约,而且它写在注释里:

packages/agent/src/types.ts:27-38
/**
 * 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 里有两个专门为此存在的取值。

packages/ai/src/types.ts:489
export type StopReason = "pending" | "stop" | "length" | "toolUse" | "error" | "aborted" | "deferred";
取值含义谁会处理它
stop正常说完L2 检查有没有工具调用
length撞到输出上限需要「续写」逻辑
toolUse要调工具进 L3 执行
error请求失败带 errorMessage 返回给 L2,L2 直接结束,L1 决定要不要重试
aborted被取消同上,但走取消路径
pending占位(流式未完成)内部状态
deferred延后特殊分支

为什么「错误变成数据」比抛异常好?因为这个错误需要被写进 transcript:

如果抛异常
调用栈直接弹出循环,这条 assistant 消息不存在——历史里少了一轮,下一轮模型会困惑「我明明调了工具,怎么没记录」。
如果编码成 stopReason: "error"
消息照常追加进 transcript(带错误信息),L2 看到 error 正常收尾,L1 从历史里读到这条失败并决定重试。失败也是一条真实发生过的事件。

agent/types.ts:27-38(不抛错契约)· ai/types.ts:489(StopReason)

6.3

配对完整性:为什么它不需要运行时检查

「每个 toolCall 必须有对应的 toolResult」——这是所有 agent 框架最头疼的不变量。 pi 基本不用运行时校验,因为它在结构上就不可能出现。

推理链条是这样:

① ToolResultMessage 只能由内核产生
模型输出的是 AssistantMessage,其中的 toolCall 是内容块,不是消息。模型无法自己「插入工具结果」。
② 内核在同一个循环体内成对写入
L3 里 executedToolBatch 产出结果后立刻 append,不会隔圈。所以「调用」和「结果」在 transcript 里永远相邻且成对。
③ 工具永不 reject,所以每条调用都必然产出结果
这是关键的一环:如果工具能抛错,那就会出现「调用了但没结果」。而它被规定为返回 isError: true 的结果——结果一定存在。
④ 唯一的破坏路径被显式修补
输出截断(stopReason: "length")时可能出现「调用被截半」——pi 在这里合成一条配对错误结果,而不是留下空洞。

第 ③ 和第 ④ 合起来,就是「配对完整」的全部保证。它不靠一个 validateTranscript(), 而是靠让每个可能出错的环节都返回一个合法结果。

对比一下另一种取向:如果框架选择「校验失败就拒绝/报错」,那它必须在每个边界上判断轨迹是否完整, 并且要有「轨迹坏了怎么办」的策略。pi 选择「不产生坏轨迹」,代价是错误处理必须写在每个工具里。 两种都能对,但后者更容易在长时运行中保持稳定。

agent-loop.ts:488(截断时合成配对)· :818(永不 reject 契约)

6.4

ToolDefinition:一个工具要回答的 8 个问题

工具的类型定义本身就是一份规范。一个工具必须声明的事情,恰好是模型和框架各自需要的:

字段给谁回答什么问题
name / label模型 / UI它叫什么
description模型什么时候该用它
parameters(TypeBox schema)模型 + 校验参数长什么样
constrainedSamplingprovider能不能约束解码
prepareArguments框架畸形参数怎么修
execute框架真正做什么
promptSnippet / promptGuidelines模型在系统提示里怎么介绍它
renderShellUI输出怎么渲染

注意 parameters 用的是 TypeBox(Type.Object),它同时提供两样东西: TypeScript 类型(编译期)和 JSON Schema(运行时、发给 provider)。一份声明,三处使用。

packages/coding-agent/src/core/tools/read.ts:14-18
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)」这种防止误用的话,而不是「读取文件」这种废话。

read.ts:14-18

6.5

类型做了四件运行时不用做的事

#不变量靠什么保证省掉了什么
1 线上只有 4 种角色 Message 封闭联合 不用在发送前校验角色合法性
2 失败不会中断循环 StreamFn 契约 + stopReason 不用在每层 try/catch
3 调用与结果成对 工具永不 reject + 截断时合成 不用全量扫描轨迹找孤儿调用
4 工具声明完整 ToolDefinition 必填字段 不用在注册时做字段检查

六章讲完。回头看,pi 的「极简」不在于代码少——而在于它把复杂度放在了边界上: 两个 Message 类型之间、一次模型请求的前后、一个工具的入参和出参之间。 每一处边界都有明确的类型或契约,所以内部可以很小。

这也解释了为什么内核 6 个文件 2,541 行就能跑一个完整 agent:不是省略了功能,是把功能压进了契约里。

本章学习记录

记录仅保存在当前浏览器。