叫出八种消息角色
读出 AgentMessage 的八种角色以及它们背后的 SystemMessage 声明,包括 1.0.4 版类型里没有的那个 replace 字段。
Pi 在 SDK 状态、生命周期事件、RPC 响应和持久化的会话条目中使用 AgentMessage 联合——一个类型横跨四个面。在 1.0.4 上,编码智能体给它扩展了四种角色,而应用可以通过声明合并添加更多。下面的声明复现了 ch26-message-types/declared.ts 导出的类型;assert-equal.ts 用两种方式对着真实导出检查那些复现。
八种角色
| 角色 | 它做什么用 |
|---|---|
system |
提示词与工具状态;后面的系统消息给它打补丁 |
user |
一条提示词:一个字符串,或一个文本/图片块数组 |
assistant |
内容块、usage、stopReason、三重的模型身份 |
toolResult |
一个工具的结果,通过 toolCallId 与它的调用相连 |
bashExecution |
一条直接的 shell 命令——不是一次 LLM 工具结果 |
custom |
一条扩展上下文消息,被转换成一条用户消息 |
branchSummary |
一条 branch_summary 条目在上下文中变成的那个摘要 |
compactionSummary |
一条 compaction 条目在上下文中变成的那个摘要 |
带着那条告诫的声明
SystemMessage 是带着本书最著名的不一致的那个角色,所以它是值得展示的那一个。下面是被声明的复现的一个片段——一份声明,不是可执行代码:
export interface SystemMessage {
role: "system";
content: string | TextContent[];
sections?: Record<string, string | null>;
toolsAdded?: Tool[];
toolsRemoved?: ToolReference[];
timestamp: number;
}declared.ts 确实在一个 namespace 内部写下这些行,而 assert-equal.ts 证明每一个都与导出的类型相互可赋值,并具有同一组键。sections 是一个具名映射,其中 null 值移除一个节,而 toolsAdded / toolsRemoved 在不重新声明的情况下给工具集打补丁。
本章记录的那个不一致: message-types.md 里的散文在 SystemMessage 上列出了 replace?: boolean,并把它描述为丢弃更早的状态,但导出的 1.0.4 声明没有 replace 字段,而已交付的 JavaScript 里也没有任何代码读取它。本书的规则是声明优先,所以上面的界面略去了它——它已被上游报告为 earendil-works/pi#10462,框定方式是一个问题而不是一个 bug。
机制与局限
有文档记载: 这个联合、各角色字段以及那个四面的陈述,都是导出的 1.0.4 类型,由 assert-equal.ts 在编译期验证(声明可赋值性、证据台账中的声明范围)。有两条局限即使单从类型本身也带得过来:stopReason: "pending" 是一个只在流式传输中存在的状态,Pi 不会把它持久化进会话 JSONL,所以同一个类型确实在不同面上携带不同的值;而条目上的时间戳是 ISO 8601,嵌套的消息时间戳是 Unix 毫秒——同一个字段名,两种格式。已观察: 这里没有任何东西运行模型——声明检查是本章唯一的一行证据,而类型里的那个 SystemMessage 没有说出一个真实模型如何产生这些角色。
完整源码与测试 。
Understand this example
Copy this prompt into your AI tool. No code runs here.
Apply this example
Copy this prompt into your AI tool. No code runs here.