Example

叫出八种消息角色

读出 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.