消息类型
AgentMessage 覆盖的八种角色、它们共用的内容块,以及哪些字段才是权威的——包括那个会绊倒每个人的时间戳类型。
你写一个渲染工具结果的扩展。它在流式事件上能用,在保存下来的会话上失败,而在模型请求上又以另一种方式失败。这三个面用的是同一批类型——但并不是同一批值,而其中有一个字段尤其不是它的名字所暗示的那样。
本章就是对这些形状本身的参考。
一个联合类型,四个面
“Pi 在 SDK 状态、生命周期事件、RPC 响应和持久化的会话消息条目中使用 AgentMessage 值。”
四个面,一个类型。这就是为什么一条在流式传输时渲染正确的消息在磁盘上有可能是错的:流式的那份值是暂定的,持久化的那份是最终的。
在编码智能体里,这个联合类型等价于:
type AgentMessage =
| SystemMessage
| UserMessage
| AssistantMessage
| ToolResultMessage
| BashExecutionMessage
| CustomMessage
| BranchSummaryMessage
| CompactionSummaryMessage;
“编码智能体包给 AgentMessage 扩展了四种角色。“四个——BashExecutionMessage、CustomMessage、BranchSummaryMessage、CompactionSummaryMessage。另外四个来自基础包。
还有一条告诫,针对任何从别人的宿主那里消费消息的代码:“应用可以通过 TypeScript 声明合并来添加角色,所以消费者在从一个被增强的宿主接受消息时,应当容忍未知的自定义角色。”
从转录记录到请求
第三部分的每一章讲的都是这四个面中的一个。它们不可互换,而它们之间的投影正是意外藏身之处。
flowchart TD
E["持久化的会话条目<br/>JSONL,每个分支,耐久"] --> A["活动分支<br/>直到活动叶子的那些条目"]
A --> X["投影出的对话<br/>已应用压缩,已应用编辑"]
X --> C["请求投影<br/>transformContext、convertToLlm"]
C --> P["provider 请求<br/>模型收到了什么"]
X -.-> S["session.get_messages<br/>第 27 章"]
P -.-> O["在测试中观察<br/>第 18 章"]
Q["context 条目:被存储,在转录记录中可见,<br/>但不会被发送给模型"] -.-> E
把那些虚线边读作观察这件事的两种方式。get_messages 展示的是投影,也就是第三个方框——而不是第四个。而一条 context 条目被存储、可见,却从不被发送,那是第 5 章的 appendEntry(),也是一个读者可以对一条消息持有的、真正的第四种东西。
最后那条箭头是产生 bug 的那一条。实线路径上的一切都能在压缩后存留;provider 以上那些虚线边上的东西,没有一个是模型真正看到的。
时间戳陷阱
把这部分读两遍,因为在读取会话的代码里,这是最常见的一种 bug。
错误:“条目的 timestamp 和消息的 timestamp 是同一个字段。”
正确:“消息时间戳是以毫秒为单位的 Unix 时间戳。它们与会话条目上的 ISO 8601 时间戳不同。”
{"type":"message","id":"a1b2c3d4","parentId":"prev1234","timestamp":"2024-12-03T14:00:01.000Z","message":{"role":"user","content":"Hello","timestamp":1733234401000}}
条目的 timestamp 是 "2024-12-03T14:00:01.000Z"。消息里嵌套的 timestamp 是 1733234401000。同一个瞬间,两种表示,同一个字段名。拿错的那一个去排序,你会得到 NaN,或者一个看着没问题、直到它出问题为止的顺序。
内容块
四个块,其中两个带着你绝不该去解释的字段:
interface TextContent { type: "text"; text: string; textSignature?: string; }
interface ImageContent { type: "image"; data: string; mimeType: string; }
interface ThinkingContent { type: "thinking"; thinking: string; thinkingSignature?: string; redacted?: boolean; }
interface ToolCall { type: "toolCall"; id: string; name: string; arguments: Record<string, any>; thoughtSignature?: string; namespace?: string; }
ImageContent.data 是 base64 编码的。ToolCall.namespace “为一个 OpenAI Responses 命名空间标识动态加载的或带命名空间的工具。”
文档对那几个签名字段的说明异乎寻常地清楚,而其中的理由要紧。关于 textSignature:“包含 provider 特定的消息元数据。把它当作不透明的。“关于思考:“思考签名包含 provider 特定的重放数据。把它们当作不透明的。”
不透明意味着原样往返传递它,绝不在它上面做分支判断。被删节的思考块是具体情况:“一个被删节的块可以没有任何可见的思考文本,同时在 thinkingSignature 里保留一份加密过的载荷。“所以一个空的 thinking 字符串并不表示什么都没有发生。
用量(Usage)
interface Usage {
input: number; output: number; cacheRead: number; cacheWrite: number;
cacheWrite1h?: number; reasoning?: number; totalTokens: number;
cost: { input: number; output: number; cacheRead: number; cacheWrite: number; total: number; };
}
有两条规则会让你免于算出一个错误的合计。“当 reasoning 存在时,它已经被包含在 output 里;不要重复相加。“而”cacheWrite1h 是以一小时保留期写入的 cacheWrite 的子集。”
所以 reasoning 是 output 的一个明细项,而不是它的附加项,而 cacheWrite1h 是 cacheWrite 的一个子集。两者都可以安全地展示;没有一个可以安全地相加。
“助手消息总是包含用量。当工具执行了嵌套的模型工作时,工具结果可以包含用量。”
SystemMessage
interface SystemMessage {
role: "system";
content: string | TextContent[];
sections?: Record<string, string | null>;
toolsAdded?: Tool[];
toolsRemoved?: ToolReference[];
timestamp: number;
}
这是唯一一个不是关于这段对话的某一条事实的角色。message-types.md说:“领头的那条系统消息声明初始的提示词与工具。后面的系统消息可以追加指令、替换或移除具名的提示词节,以及添加或移除工具。按顺序重放它们就能得出当前的状态。”
一个类型里装着两套机制:sections 是一个具名映射,其中 null 值移除一个节,而 toolsAdded 和 toolsRemoved 在不重新声明整套工具集的情况下给它打补丁。
**一个散文描述了、而声明里没有的字段。**在 message-types.md 里,SystemMessage 的列表包含 replace?: boolean,而正文说一条带 replace: true 的消息会丢弃更早的状态并建立一条新基线。pi-ai 中导出的 1.0.4 版 SystemMessage 声明没有 replace 字段,而在已交付的 JavaScript 里搜索那段重放逻辑,没有找到任何读取它的代码。本书的规则是声明优先,所以上面的界面略去了它,而本书中没有任何东西依赖它。如果你需要知道在你所用的版本上能否做一次完整重置,请去查声明并测试它,而不是查散文。这个不一致已被上游报告为 earendil-works/pi#10462,它的框定方式是一个问题(预期 API 缺失,还是文档已过时),而不是一个 bug。
那个实际后果是:你无法从单独一条系统消息里读出当前的提示词。你要按顺序把它们全部重放一遍。session-format.md 确认"不存在单独的提示词状态条目。”
{"type":"message","id":"a0b1c2d3","parentId":null,"timestamp":"2024-12-03T14:00:00.000Z","message":{"role":"system","content":"","sections":{"preamble":"You are an expert coding assistant...","tools":"<tools>\n- read: ...\n</tools>","cwd":"/project"},"toolsAdded":[{"name":"read","description":"...","parameters":{}}],"timestamp":1733234400000}}
“在系统消息存在之前创建的会话没有领头的那条系统消息;第一次请求把当前提示词声明为一条更晚的系统消息,它以同样的方式被重放。“一个假定条目一是提示词的解析器,会在旧会话上出错。
UserMessage
interface UserMessage {
role: "user";
content: string | (TextContent | ImageContent)[];
timestamp: number;
}
那个"字符串或数组"的联合不是表面功夫——它是你被给到的数据的形状,而不是一个选择。一条带图片的用户消息是一个数组;一条普通的提示词往往是一个裸字符串。
AssistantMessage
最重的类型,也是拥有最多不可互换字段的那一个。
interface AssistantMessage {
role: "assistant";
content: (TextContent | ThinkingContent | ToolCall)[];
api: string;
provider: string;
model: string;
responseModel?: string;
responseId?: string;
providerThinkingLevel?: string;
thinkingLevel?: ModelThinkingLevel;
diagnostics?: AssistantMessageDiagnostic[];
usage: Usage;
stopReason: "pending" | "stop" | "length" | "toolUse" | "error" | "aborted" | "deferred";
deferred?: DeferredHandle;
errorMessage?: string;
rawStopReason?: string;
endTurn?: boolean;
timestamp: number;
}
模型身份是三重的。model 是被请求的那个;responseModel “在与被请求的模型不同时,记录一个具体的 provider 响应模型。“如果你在按模型统计花费,responseModel 就是那个告诉你实际是谁回答了问题的字段。
stopReason 有七个值,其中两个表示响应尚未结束。"pending" 是"用于助手消息在流式传输期间的部分状态”,而"Pi 不会把 "pending" 助手消息持久化进会话 JSONL”——所以一个把自己看到的东西持久化下来的渲染器,会写出一个读取方没有为之准备好的值。"deferred" 表示 provider 还没有回答,而 deferred 携带一个 DeferredHandle,其中带有 provider、modelId、api、id、可选的 expiresAt、pollAfterMs 和用于取回它的 data。剩下五个是终局的 stopReason:"stop"、"length"、"toolUse",以及失败的那一对 "error" 和 "aborted"。
rawStopReason 和 diagnostics “保留 provider 或运行时的细节”——同样是不透明的,同样值得记录、同样不值得在它上面做分支判断。endTurn 是那个表示模型认为这一轮已结束的字段。
"length" 值得注意,因为它的后果超出这条消息本身。compaction.md:“一次 provider 的上下文溢出错误,或一个提前出现的最终 stopReason: "length",可以选择使用一次压缩并重试的恢复尝试。”
ToolResultMessage
interface ToolResultMessage<TDetails = JsonValue> {
role: "toolResult";
toolCallId: string;
toolName: string;
content: (TextContent | ImageContent)[];
details?: TDetails;
usage?: Usage;
nestedCalls?: NestedToolCalls;
isError: boolean;
timestamp: number;
}
toolCallId 是回到那个 ToolCall 的连接键。details 是工具特定的,而当状态应当跟随活动分支时,它就是扩展状态该去的地方——extensions.md 在它的状态表里把它列为"跟随活动分支的工具状态。”
这里的 usage 是特殊的:它"报告由该工具执行的嵌套模型工作,并计入整场会话的统计,但它不是主要模型调用用量的一部分。“所以当你为计费而汇总用量时,把它算进去。当你展示"上下文中的 token 数"时,不要——它从来就不在上下文里。
isError 是一个字段,不是异常。extensions.md:“从 execute() 抛出以产生一个失败的工具结果”,而对于那种你既想要一个错误又想要数据的场景,“返回带 isError: true 的结果,而不是抛出:模型看到一个错误,而脚本仍然收到 structuredContent。”
编码智能体的那四个角色
BashExecutionMessage——“由直接的 shell 命令创建,包括 RPC 的 bash 命令。它不是一次 LLM 工具结果。“它的字段是 command、output、exitCode、cancelled、truncated、可选的 fullOutputPath、可选的 excludeFromContext,以及一个时间戳。
其中两个要紧。excludeFromContext 是一个真正的开关——“除非 excludeFromContext 为真,否则 Pi 会在下一次模型请求之前把这条消息转换成用户角色的文本。“而 truncated 加 fullOutputPath 意味着 output 未必是完整的东西。第 9 章的 !! 前缀是同一个想法的面向用户的形式。
CustomMessage——“当一个扩展发送一条上下文消息时创建。“它携带 customType、一个 content 联合、一个 display 布尔值、可选的 details,以及一个时间戳。“Pi 会为模型请求把它的内容转换成一条用户消息。display 控制终端渲染;details 不会发送给模型。”
所以 display: false 对用户不可见、对模型在场——这与第 19 章的 custom 条目类型正好相反,那一个对模型不可见、而可由一个条目渲染器渲染。
BranchSummaryMessage 携带一个 summary 和一个类型为 string | null 的 fromId。CompactionSummaryMessage 携带一个 summary 和一个 tokensBefore。两者都是 Pi 生成的,而没有一个是由你写的任何东西构造出来的:它们存在的目的,是让一个 compaction 或 branch_summary 条目能变成模型上下文里的一条消息——也就是 session-format.md 描述为 compaction → “完整的系统检查点,后接 compactionSummary",以及 branch_summary → branchSummary 的那个转换步骤。
把角色映射到条目
这个转换值得直白地说出来,因为正是它,四个面才彼此有别:
| 会话条目 | 模型收到的消息 |
|---|---|
message |
被存储的那个 AgentMessage |
compaction |
系统检查点,然后是 compactionSummary |
branch_summary |
branchSummary |
custom_message |
CustomMessage |
context_edit |
它自己什么也没有 |
usage、custom |
什么也没有 |
context_edit 是会误导人的那一行:没有自己的消息,因为它修改的是另一个条目的贡献。usage 和 custom 什么也不贡献——这就是为什么你两者都需要才能从会话文件计费,而两者都不需要就能重建那段对话。
照着这些定义写一个处理器
三条从这些定义推出的规则。在读字段之前先按 role 收窄——一条 AssistantMessage 没有 content 字符串。把 stopReason 的 "pending" 当作一个实现状态,而不是一个被持久化的状态。而要有意识地在 model 或 responseModel 上做分支判断,因为它们回答的是不同的问题。
上面这些类型就是契约。下一章往下拆一层,因为同一个 AgentMessage 值在变成一个只追加文件里的一行那一刻起,就不再是同一样东西了——在那里,压缩与上下文编辑决定模型实际收到什么。