Pi Agent 源码级教程
M06

消息系统 —— 四种给模型看,八种给系统记

6,782 字 · 含 170 行代码 · 约 32 分钟

M05 里工具执行完了,产出变成一条 ToolResultMessage。它进了 transcript,然后在下一轮被发给模型。

问题来了:用户在 TUI 里敲 !ls -la,这条 bash 执行记录是什么消息?它不是用户说的话,也不是模型说的话,更不是工具调用结果。可是它必须留在 transcript 里——下次打开会话还能看到"我当时跑了什么"。

Pi 的答案是:给系统记的消息比给模型看的多四种。

这一章讲这四种,以及它们和那四种之间那道转换闸门。


一、给模型看的只有四种

Message 的定义只有一行(packages/ai/src/types.ts:659):

ts
export type Message =	SystemMessage | UserMessage | AssistantMessage | ToolResultMessage;

四种。这是所有 provider 都能表达的最小公约数——M04 讲过的十种方言,翻译的对象就是这个联合类型。

1.1 字段对照

四种消息的字段数差得很远,值得摆在一起看:

消息 字段数 必有字段 独有字段
UserMessage 2 content timestamp —
SystemMessage 5 content timestamp sections toolsAdded toolsRemoved
ToolResultMessage 9 toolCallId toolName content isError timestamp details usage nestedCalls durationMs
AssistantMessage 17 content api provider model usage stopReason timestamp 见下

AssistantMessage(:585-616)是唯一一个"必须记录是谁回答的"的消息:

ts
export interface AssistantMessage {	role: "assistant";	content: (TextContent | ThinkingContent | ToolCall)[];	api: Api;	provider: ProviderId;	model: string;	responseModel?: string;	responseId?: string;	providerThinkingLevel?: string;	thinkingLevel?: ModelThinkingLevel;	diagnostics?: AssistantMessageDiagnostic[];	usage: Usage;	stopReason: StopReason;	deferred?: DeferredHandle;	errorMessage?: string;	rawStopReason?: string;	endTurn?: boolean;	timestamp: number;	durationMs?: number;}

UserMessage 只有两个字段,AssistantMessage 有十七个。为什么?因为用户说的东西只需要读,模型说的话需要被记账:花了多少钱(usage)、用的哪个模型(provider + model)、为什么停下来(stopReason)、花了多久(durationMs)。

M10 讲会话恢复时会发现,正是这十七个字段让"重放一次历史对话"变成可能——你不仅知道模型说了什么,还知道它当时是怎么说的。

1.2 content 是唯一形状各异的字段

四种消息里,除 content 之外的字段都长得规矩。content 却四种形状:

消息 content 类型 图片 thinking
system string | TextContent[] 否 否
user string | (Text | Image)[] 是 否
assistant (Text | Think | ToolCall)[] 否 是
toolResult (Text | Image)[] 是 否

三条规律:

一,只有 user 和 toolResult 能带图片。 因为"看图"是输入能力: 用户发截图,工具回传渲染结果(M05 的 read 读图片文件就靠这个)。 而 assistant 不能产出图片块——模型生成图像走的是另一套接口 (KnownImageApi,ai/src/types.ts:78),不在对话流里。

二,只有 assistant 能带 ThinkingContent 和 ToolCall。 这是"模型说过什么"独有的两种形状:思考过程、结构化的调用请求。 其余三种消息没有理由出现它们。

三,assistant 和 toolResult 不接受裸 string。 user 和 system 可以,因为它们常常"整条就是一段话"。 而 assistant 的 content 是一串事件——可能同时有一条思考、一段文字、 一个工具调用,必须结构化才能记账(usage 按块分摊、durationMs 对齐)。

同一件事在不同消息里用不同形状表达,是能力边界直接映射进了类型。

1.3 三个"本来不该在这里"的字段

AssistantMessage 里有三个字段很可疑:

  • diagnostics:Redacted provider/runtime diagnostics for failures and recoveries.
  • rawStopReason:provider 原始停止原因,没做归一化
  • endTurn:Preserved for debugging and does not currently affect agent control flow.

三个都是调试用途,都在注释里明说了。为什么允许它们存在?

因为线上问题的排查现场只有 transcript。如果 stopReason 归一化成 "error" 就丢了原始值,你永远查不出"到底是限流还是内容审核"。把原始值留在消息里,是最便宜的可观测性。

endTurn 那条注释里的 does not currently affect agent control flow 更值得记:它说明这个字段曾经想过参与控制流,后来退出了。留着是为了不破坏已有 transcript 的兼容性。

1.4 sections 里别用整数键

SystemMessage.sections 的注释藏着一句警告(ai/src/types.ts:565-571):

Named, ordered prompt sections rendered verbatim after content. ... Avoid integer-like names; JSON objects reorder those.

sections 是 Record<string, string | null>,注释里写着 ordered—— 顺序有语义,因为提示词是顺序读的。但 JS 对象的键顺序不是插入顺序:

  • 整数样式的键("0"、"12")被引擎排到最前,并按数值升序
  • 其余字符串键保持插入顺序

所以 {"b":.., "0":.., "a":..} 渲染出来是 0, b, a。 编号成 "1" "2" "3" 恰好躲过,但 "10" 会排到 "2" 前面。

null 的语义也值得一提:它不是"置空",是删除这一节。 后面一条 system 消息可以把前面声明的一节整个摘掉,不必重发全文。 这跟 toolsRemoved 是同一个思路——后续消息只描述增量。

1.5 一条消息,两个消费者

ToolResultMessage(:640-657)里有三个字段明确注明不发给模型:

ts
usage?: Usage;                  // 不进主 LLM 上下文记账nestedCalls?: NestedToolCalls;  // 只进会话记录,不发给模型durationMs?: number;
  • usage 是工具自己花掉的 token——比如一个内部调模型做总结的工具
  • nestedCalls 是工具内部又发起了哪些工具调用(codemode 场景)
  • durationMs 是执行耗时,给 UI 和分析用

三个字段指向同一个事实:一条消息同时服务多个消费者。 模型只读 content 和 isError;会话记录(M10)读 usage、 nestedCalls、durationMs;TUI 读 details 里的渲染数据。

字段按消费者分区,所以"消息"不是"发给模型的东西", 而是"关于这次工具调用,我记下的全部"。


二、给系统记的还有四种

coding-agent/src/core/messages.ts(196 行)定义了四种额外消息。它们不在 Message 里,全在 AgentMessage 里。

2.1 bashExecution:! 命令的记录

ts
export interface BashExecutionMessage {	role: "bashExecution";	command: string;	output: string;	exitCode: number | undefined;	cancelled: boolean;	truncated: boolean;	fullOutputPath?: string;	timestamp: number;	/** If true, this message is excluded from LLM context (!! prefix) */	excludeFromContext?: boolean;}

字段几乎和 BashToolOutput(M05 的 bash 结构化输出)一一对应。区别在于它是用户主动跑的,不是模型要跑的。

! 和 !! 的区别就是一个布尔:!ls 会进上下文让模型知道,!!ls 只显示给人看。

为什么不复用 UserMessage 塞一段文本?因为 output 可能有几十 MB(被截断后还留着 fullOutputPath)。如果一开始就转成文本,那"折叠展开完整输出"这个 UI 功能就没法做了。原始字段留着,转文本推迟到最后一刻。

2.2 custom:扩展的注入口

ts
export interface CustomMessage<T = unknown> {	role: "custom";	customType: string;	content: string | (TextContent | ImageContent)[];	display: boolean;	details?: T;	timestamp: number;}

customType 是扩展自己的命名空间(比如 "todo-reminder"),details 是任意挂载数据。

display 这个字段值得单独说:它控制是否在 TUI 里显示,和是否发给模型完全无关。一个 display: false 的 custom 消息会静默进入上下文,用户看不见。

这是个双刃剑:扩展可以用它注入"系统提醒"而不污染界面,也可以用它偷偷塞东西。所以扩展机制天然需要信任——M07 会讲扩展是怎么被加载和隔离的。

2.3 branchSummary:分叉回退的凭证

ts
export interface BranchSummaryMessage {	role: "branchSummary";	summary: string;	fromId: string | null;	timestamp: number;}

场景:你在第 20 轮发现走错路了,回退到第 8 轮重开。但第 9 到 20 轮发生过的事不能凭空消失——模型如果完全不知道"之前试过 A 方案失败了",就会再试一次。

branchSummary 就是那条"我从哪来"的记录:fromId 指向被放弃的分叉点,summary 是那段历史的摘要。它被插回上下文时用一对标签包起来(messages.ts:19-24):

text
The following is a summary of a branch that this conversation came back from:<summary>...摘要内容...</summary>

为什么要标签?因为要让它长得不像对话。模型看到 <summary> 包着的东西,就知道这是"关于历史的元信息",不是"用户在跟我说话"。

2.4 compactionSummary:压缩后的替身

ts
export interface CompactionSummaryMessage {	role: "compactionSummary";	summary: string;	tokensBefore: number;	timestamp: number;}

和 branchSummary 几乎一样,多一个 tokensBefore——压缩前的 token 数。这个数字是压缩效果的唯一证据:你能算出"从 150,000 压到 8,000",也能在它压得不够时报警。

两者的区别是语义:branchSummary 是"这段历史被放弃了",compactionSummary 是"这段历史被浓缩了"。同样是摘要,一个向前看,一个向后看。 所以它们是两个类型,不是同一个类型加个 kind 字段。

2.5 三类来源,三种信任等级

四条自定义消息看着平级,按"谁产生的"分却是三层:

消息 产生者 可信吗
bashExecution 用户敲 ! 高(人操作)
custom 扩展 中(需审计)
branchSummary 系统自动 高(内部写)
compactionSummary 系统自动 高(内部写)
  • bashExecution 的每个字段都来自一次真实进程(output、exitCode)
  • custom 是唯一允许外部代码任意注入的通道, customType 就是它的自报家门
  • 两条 summary 由系统自己拼,前缀是导出的常量(:11-24),格式可控

这个分级解释了 custom 为什么独独带 display 和 details: 它必须能被渲染成"看起来像插件的东西",用户才有机会发现异常。 bashExecution 不需要——它本来就在等宽输出区里,长得就像终端。

权限不同,UI 待遇就不该相同。


三、超集是怎么做到不侵入的

这是本章技术上最漂亮的一处。

3.1 空接口 + 声明合并

agent/src/types.ts:365-374:

ts
export interface CustomAgentMessages {	// Empty by default - apps extend via declaration merging}export type AgentMessage =	Message | CustomAgentMessages[keyof CustomAgentMessages];

CustomAgentMessages 是空接口。所以默认情况下:

text
AgentMessage = Message | never = Message

never 在联合类型里会消失。默认等于没有扩展,零成本。

两个语法点如果生疏:X[keyof X] 叫「索引访问类型」,意思是"把 X 里每个属性的值取出来,拼成一个联合";never 混进联合里会自动消失。二者在附录 B 的 §2.2 和 §三 符号表各有一行。

然后 coding-agent 在 messages.ts:70-77 往里加字段:

ts
declare module "@earendil-works/pi-agent-core" {	interface CustomAgentMessages {		bashExecution: BashExecutionMessage;		custom: CustomMessage;		branchSummary: BranchSummaryMessage;		compactionSummary: CompactionSummaryMessage;	}}

这是 TypeScript 的声明合并(declaration merging):同名接口在多个地方声明,字段会合并。加完之后,全仓库的 AgentMessage 立刻变成八种。

写法本身只有五行,但第一次看到很难不起疑——"这不就是重复定义吗?"附录 B §2.8 把它当独立语法拆过一遍。

3.2 为什么这个设计值得学

关键在于:agent 包完全不知道 coding-agent 有哪些消息类型。

agent 包的 types.ts 里没有 bashExecution 这个词。它只提供"一个可被扩充的插槽",coding-agent 往里塞。编译产物里也没有循环依赖。

对比一下常见的替代方案:

方案 问题
agent 包里直接定义八种消息 agent 得认识"bash 执行"这种业务概念,抽象被污染
用 Record<string, unknown> 兜 丢掉全部类型安全,m.role 变成 string
泛型参数 AgentMessage<TExtra> 每传一层都要带上类型参数,传染性极强

声明合并的代价是隐式的:你看到一个 AgentMessage 的 switch,里面却有 case "bashExecution",而在当前文件里搜不到这个类型的定义。新手会困惑"这个 role 到底哪来的"。

这也解释了为什么 messages.ts 开头要有那段文件注释(:1-6)——它是在补声明合并丢掉的可发现性。

3.3 代价:穷尽检查必须写

convertToLlm 的 switch 末尾有这几行(:189-193):

ts
default:	// biome-ignore lint/correctness/noSwitchDeclarations: fine	const _exhaustiveCheck: never = m;	return undefined;

never 类型在这里当编译器用:如果某个 case 没写,m 就不是 never,这一行编译报错。

声明合并让"加类型"变容易了,所以"加完忘改转换器"就成了主要风险。 穷尽检查是唯一能拦住它的东西。注释里那个 biome-ignore 说明这是在"让 linter 闭嘴换类型安全"——值得的交易。

3.4 声明合并是"编译单元级"的

这点容易误解:CustomAgentMessages 不是全局共享的, 合并结果取决于当前程序包含了哪些文件。

text
只编 agent 包             → AgentMessage = 4 种编 agent + coding-agent  → AgentMessage = 8 种

messages.ts:70 那句 declare module 要进入编译图才生效。 如果某个测试文件没 import 到它,里面的 AgentMessage 还是四个成员, 写 case "bashExecution" 直接报错。

三个实际后果:

  1. 不要在 agent 包的单元测试里断言八种消息—— 那个包看不到自定义类型
  2. agent 包的代码不该 switch 自定义 role——编译不过, 除非加 default 兜底
  3. 类型只在"看到那个 import"的地方变宽,所以声明合并的入口文件 必须唯一:coding-agent 里就是 core/messages.ts

顺带解释一个怪现象:agent 包和 coding-agent 里都写着 AgentMessage,在编辑器里点进去是同一个定义,但悬停时看到的展开结果 可能不一样。不是 IDE 抽风,是两处看到的合并结果不同。

3.5 非法 details 让它编译不过

ToolResultMessage 还带一个条件类型(ai/src/types.ts:640):

ts
export type ToolResultMessage<TDetails = JsonValue> =	IsJsonCompatible<TDetails> extends true ? { ... } : never;

details 不是随便挂的。判定分三层(:491-537):

  1. IsJsonCompatible<T>——递归走一遍,函数、undefined、 Symbol 之类都判 false
  2. InvalidJsonKeys<T>——反向找出哪个键不合法, 报错信息能指到具体字段
  3. never——不合规时整个 ToolResultMessage 变成 never, 任何赋值都编译失败

为什么值得写六十行类型体操?因为 details 的唯一归宿是 jsonl 文件(M10)。 塞一个 Date 进去,落盘时静默变成字符串;塞一个 Map 进去,直接变 {}。 错误在落盘那一刻才暴露,而那时类型信息已经找不回来了。

JsonRepresentation<T>(:527-537)是配套的另一半:它把内存类型映射成 "落盘之后的形态",让读取方知道会拿到什么。


四、convertToLlm:那道转换闸门

4.1 四条 case,一种产物

完整函数(messages.ts:148-196)不长。四条自定义消息的处理:

ts
switch (m.role) {	case "bashExecution":		if (m.excludeFromContext) return undefined;		return {			role: "user",			content: [{ type: "text", text: bashExecutionToText(m) }],			timestamp: m.timestamp,		};	case "custom":		return { role: "user", content, timestamp: m.timestamp };	case "branchSummary":		return { role: "user", content: [{			type: "text",			text: BRANCH_SUMMARY_PREFIX + m.summary + BRANCH_SUMMARY_SUFFIX,		}], timestamp: m.timestamp };	case "compactionSummary":		// 同上,用 COMPACTION_SUMMARY_PREFIX/SUFFIX 包裹

四条,全部变成 role: "user"。

这是整章最反直觉的一点。为什么不变成 system?不新增一个 role?

因为 role 的集合是协议层决定的,不是 Pi 决定的。M04 那十个 api 里,有的只认 user / assistant / system / tool。你造一个新 role,十家都得改。

而 user 是所有 provider 都必有的、语义最宽的槽位:"这是外部给模型的一段输入"。摘要、bash 记录、扩展通知,本质都是"外部输入"。

4.2 bash 记录变成什么样

bashExecutionToText(:82-98)的产物:

text
Ran `ls -la`

total 24 drwxr-xr-x 5 user staff 160 Nov 2 10:00 . ...

text
Command exited with code 1

三段可选尾巴:(command cancelled)、Command exited with code N、[Output truncated. Full output: /tmp/...]。

注意它把命令原文用反引号包起来、输出用三反引号围栏——这是在模仿 markdown 代码块。模型在训练数据里见过海量这种格式,它会把围栏里的内容当"命令输出"而不是"用户的话"。

格式不是装饰,是提示。

4.3 默认实现是"丢",不是"转"

agent/src/agent.ts:39-47:

ts
function defaultConvertToLlm(messages: AgentMessage[]): Message[] {	return messages.filter(		(message) =>			message.role === "system" ||			message.role === "user" ||			message.role === "assistant" ||			message.role === "toolResult",	);}

没用配置时,convertToLlm 是纯过滤——四种认识的留下,其他全丢。

而 coding-agent 显式传入了自己的版本(sdk.ts:411)。

默认丢、显式转:一个不认识的类型,默认行为应该是"不要发给外部服务", 而不是"试着塞过去"。安全默认值 + 显式覆盖,是所有"往外发数据"的接口都该有的姿态。

4.4 闸门只有一个,入口有八处

convertToLlm 在 coding-agent 里被调用八次,分布在六个文件:

位置 用途
sdk.ts:298 包一层 convertToLlmWithBlockImages
agent-session.ts:597 :838 估算 token 前先降级
agent-session.ts:1021 发请求前
compaction.ts:721 :1076 压缩前的准备
branch-summarization.ts:326 分叉摘要
bug-report.ts:339 生成 bug 报告

看第四类就明白为什么这么多:压缩本身也是一次模型调用。 M09 会讲,压缩是"把历史摘要成一段话",那个摘要请求同样得把历史降级成 Message[] 才能发给 provider。所以这不是"主循环的门",而是 "所有要把对话发给模型的地方的门"。

compaction/utils.ts:109 有一行注释把这个约束写死了:

Call convertToLlm() first to handle custom message types.

serializeConversation 的签名是 Message[] → string—— 它不接受 AgentMessage[]。签名本身就是约束: 想直接把八种消息喂进去,编译不过。


五、两阶段管道

convertToLlm 不是唯一的转换点。agent-loop.ts:403-406 是两行:

ts
const llmMessages = await config.convertToLlm(messages);const llmContext = normalizeContext({ messages: llmMessages });

前面还有一道(AgentLoopConfig.transformContext),完整链条是三级:

text
AgentMessage[]        八种,超集   ↓ transformContext    AgentMessage → AgentMessage(可选)AgentMessage[]   ↓ convertToLlm        AgentMessage → Message(必选)Message[]             四种,子集   ↓ normalizeContext    Message → TranscriptContext(M04)TranscriptContext

5.1 为什么不能合成一步

transformContext 的契约(agent/src/types.ts:224-232)写的是:

Use this for operations that work at the AgentMessage level: context window management (pruning old messages), injecting context from external sources. Contract: must not throw or reject.

两个阶段的输入输出类型不同,所以职责不同:

transformContext convertToLlm
输入输出 AgentMessage[] → AgentMessage[] AgentMessage[] → Message[]
能不能看见自定义消息 能 能(但要丢掉)
典型用途 剪枝、注入、压缩(M08/M09) 降级、过滤
是否必须 可选 必须

如果合成一步,压缩就没法工作了——压缩要产出一条 compactionSummary(自定义类型),但那个函数如果只能输出 Message,就吐不出自定义消息。

"在超集里改造,在边界处降级"——分开两步,是因为中间会有"半成品仍是超集"的阶段。

5.2 顺序不能换

transformContext 先跑。这意味着压缩、剪枝这些操作都在完整信息上做——包括 bashExecution 的原始 output、compactionSummary 的 tokensBefore。

换过来会怎样?先降级成 Message,那 bashExecution 已经变成一段文本了,压缩时想按"这条命令输出多长"做决策就没了原始数据。

信息只减不增,所以减之前要把该做的事做完。

5.3 还有第三次降级:变成纯文本

convertToLlm 之后,压缩路径上还有一道更狠的降级:

text
AgentMessage[]   八种   ↓ convertToLlmMessage[]        四种   ↓ serializeConversationstring           "[User]: ...\n[Assistant]: ..."

serializeConversation(utils.ts:120)把每条消息拼成 [User]: ... / [Assistant]: ... 的流水账。注释写明了目的(:107-108):

This prevents the model from treating it as a conversation to continue.

为什么非要打散成文本? 如果摘要请求原样保留对话结构,模型很可能 "接着最后一句往下说",而不是"总结这段对话"。把 role 结构抹掉、 换成带方括号的流水账,模型就只把它当素材看。

同一段注释还交代了 thinking 为什么被丢掉(:114-118):

replayed thinking is often not part of the model's live context ... Including it can make the summarization request larger than the context it summarizes.

这句话点出一个隐蔽的失败模式:摘要请求比被摘要的内容还大。 一份塞满 thinking 的 transcript,重发一遍的成本可能超过原上下文窗口。

三次降级,每次丢的东西不同:第一次丢"自定义语义", 第二次丢"对话结构",第三次连"块结构"都不要了。 每降一级,目标就窄一点,但每一步都还够用。


六、过滤:三个独立开关

"这条消息要不要给模型看"和"要不要给人看"是两个问题。Pi 把它们拆成三个互不相干的开关:

开关 作用范围 谁控制 例子
excludeFromContext 不进 LLM 单条消息 !!cmd
display 不在 TUI 显示 单条消息 扩展的静默通知
blockImages 图片块被剥掉 全局设置 隐私/带宽场景

6.1 excludeFromContext 走的是丢弃,不是标记

ts
case "bashExecution":	// Skip messages excluded from context (!! prefix)	if (m.excludeFromContext) return undefined;

注意它返回 undefined,然后末尾 .filter((m) => m !== undefined) 把它滤掉。消息从数组里消失了,不是被标记为隐藏。

这有后果:发给模型的消息序列里,!!ls 那一轮完全不存在。模型看到的上下文是连续的,它会以为是"用户还没说话"。

这个语义是对的——!! 的用途就是"我跑个命令看看,别让模型知道我在看什么"。

6.2 blockImages 是第二道过滤

sdk.ts:296-302 包了一层:

ts
const convertToLlmWithBlockImages = (messages: AgentMessage[]) => {	const converted = convertToLlm(messages);	// Check setting dynamically so mid-session changes take effect	if (!settingsManager.getBlockImages()) return converted;	// ... 把 image 块剥掉,换成文本注释};

注释里那句 Check setting dynamically so mid-session changes take effect 是重点:这个开关在每次转换时重新读,不是启动时快照。 用户中途开了"屏蔽图片",下一条请求立刻生效。

6.3 display 与上下文无关

CustomMessage.display 只影响渲染。一个 display: false 的消息照样进 convertToLlm,照样变成 user 消息发给模型。

所以"扩展能不能偷偷影响模型"的答案是:能,而且这是设计允许的。 display 只是让用户看不见,不是让模型看不见。

这也解释了为什么扩展机制要有信任边界——custom 消息是一条完全开放的注入通道。

6.4 为什么不合并成一个枚举

三个开关看着可以合成一个字段,比如 visibility: "both" | "ui-only" | ...。 没合是因为作用域不同:前两个是单条消息的属性,第三个是全局设置。 把全局设置塞进每条消息就得在写入时快照——而 blockImages 明确要求 "中途改立刻生效"。

短命的状态不要存进长命的数据里。 设置存进 jsonl,就永远追不上它的下一次变化。


七、完整数据流

把这一路串起来,从用户敲下 !ls 到模型收到请求:

text
用户敲 !ls   ↓ 执行(M05 的 bash 工具复用同一套 shell 逻辑)BashExecutionMessage           role: "bashExecution"   ↓ 存进 transcript(M10 的 jsonl)AgentMessage[]                 八种混排   ↓ transformContext          剪枝/压缩(可选)AgentMessage[]   ↓ convertToLlm              四条 case + filterMessage[]                      四种   ↓ normalizeContext          systemPrompt/tools 折进首条(M04)TranscriptContext   ↓ stream / streamSimple     十种方言翻译(M04)provider 请求

每一步都在减少信息:八种变四种,excludeFromContext 的直接消失,details 这种只给 UI 用的字段在转换时被丢掉。

而反方向——把 provider 的响应存回 transcript——每一步都在增加信息:AssistantMessage 带上 usage、provider、durationMs。

存的时候尽量多,发的时候尽量少。 这句话可以概括整个消息系统。

7.1 反方向:一次响应怎么变回消息

以 api/anthropic-messages.ts 为例,一边收 SSE 事件一边往 output 里填:

字段 来源 行号
api provider model 请求入参(响应里没有) :590-591
stopReason 初值 硬编码 "pending" :601
rawStopReason delta.stop_reason 原样 :842
stopReason mapStopReason() 归一化 :843
responseId event.message.id :705
responseModel 仅当不等于请求值时 :709

两个细节值得看:

一,api/provider/model 是回填的。 响应体里没有"我是被谁请求的", 这三项必须由翻译器从请求上下文里写进去。所以身份字段是请求侧的承诺, 不是响应侧的事实。

二,responseModel 只在不一样时才写(:709)。用户请求 claude-sonnet-4,provider 悄悄换成带日期的快照版,这时才记一笔; 相同就留空,省字节。而 :711-716 会拿这个实际模型名去查 fallback 定价—— 降级往往也意味着换价。

mapStopReason(:1660-1682)就是归一化的全部内容:

provider 原文 stopReason
end_turn stop
max_tokens length
tool_use toolUse
refusal error + "sensitive"

stop_sequence 那一支的注释写着 We don't supply stop sequences, so this should never happen——收到一个"不可能发生"的值也照样映射, 不抛错。这是"失败也是消息"的又一处落地。


八、暗坑:最后一条必须是 user 或 toolResult

agent-loop.ts:74-79 有一段直白的警告:

Important: The last message in context must convert to a user or toolResult message via convertToLlm. If it doesn't, the LLM provider will reject the request. This cannot be validated here since convertToLlm is only called once per turn.

这是 agentLoopContinue(重试入口)的注释。三个事实:

  1. provider 要求最后一条是 user 或 toolResult(不能让模型接着自己的话往下说)
  2. 这个要求在转换之后才成立
  3. 转换每轮只调用一次,所以"调完之后又追加了消息"这种情况没人检查

真实事故长这样:某处在转换之后往 context 里 push 了一条 AssistantMessage,请求发出去,provider 报 400: last message must have role user。

校验放在了错误的层级。 类型系统只知道"这是 Message",不知道"最后一条有 role 要求"。

那该放哪里?两个看上去可行的位置都不好:

  • 放进 normalizeContext——它是所有路径的必经之地,能统一兜底。 但这等于把一个 provider 的契约写进内核
  • 放进 transformContext 的契约——那里已经写着 must not throw, 放不下硬校验

Pi 选了第三个:写进文档注释,让调用方自己保证。 这不是偷懒,是承认这个约束跨越了两个模块: convertToLlm 在 coding-agent,normalizeContext 在 ai 包, 两头都不知道对方的全部处境。

遇到同样情况时,先把约束写在最靠近真相的地方,比发明一个假的校验点强。


九、自己动手验证

环境:v1.4.0 / node v24.12.0 / Windows 24H2。每条判据都是这一版实跑的输出。

实验 1:数一数 Message 有几个成员。

bash
# 在仓库根目录执行cd packages/ai/srcsed -n '659p' types.ts

一行,四个。

实验 2:确认默认是"空超集"。

bash
sed -n '365,374p' ../../agent/src/types.ts

CustomAgentMessages 空接口 + never 在联合里消失。

实验 3:找出声明合并。

bash
cd ../../coding-agent/src/coregrep -n -A 8 "declare module" messages.ts

四个字段,全部挂在 CustomAgentMessages 上。

实验 4:看默认转换器丢什么。

bash
cd ../../agent/srcsed -n '39,47p' agent.ts

四个 role 白名单,其余全丢。

实验 5:数调用点。

bash
cd ../../coding-agent/srcgrep -rn "convertToLlm(" --include=*.ts | wc -l
powershell
cd ../../coding-agent/src(Get-ChildItem -Recurse -Filter *.ts |  Select-String -Pattern 'convertToLlm\(').Count

十行命中 = 八处调用 + 一处定义(messages.ts:148)+ 一处注释 (compaction/utils.ts:109)。六个文件,见 §4.4 的表。

实验 6:验证穷尽检查。

把 messages.ts 里 case "branchSummary" 那一支注释掉再编译,会报:

text
Type 'BranchSummaryMessage' is not assignable to type 'never'

这就是那个 _exhaustiveCheck 在工作。

实验 7:看归一化的兜底。

bash
cd ../../ai/src/apised -n '1674,1684p' anthropic-messages.ts

refusal 变 error 并带上 "sensitive";stop_sequence 那支坦然写着 "这永远不会发生",但照样 return { stopReason: "stop" }。 一个不会发生的分支也必须有返回值,否则类型检查过不去。

实验 8:改一处试试——把 !! 找回来。

  • 改哪里 messages.ts:154-156,删掉这三行:
ts
if (m.excludeFromContext) {  return undefined;}
  • 预期 拿一条 excludeFromContext: true 的 bashExecution 消息 跑 convertToLlm,本机实测:转换后条数由 0 变 1。
  • 连带 !! 前缀的语义就是「跑了但别进上下文」,删掉它等于取消这条规则。 影响在 M09:被排除的消息一旦进了上下文,压缩时的 token 计数会多算, 压缩触发点提前。
  • 回滚 把三行加回去。

跑法:两行脚本导入 convertToLlm,造一条带 excludeFromContext: true 的假消息,打印 convertToLlm([m]).length。用 M01 §8.2 那条 --import 命令执行。


十、工程暗坑

1. AgentMessage 的 switch 里出现"查不到来源"的 case。

声明合并导致的。搜类型名搜不到定义是正常的——去 declare module 那块找。给新同事讲这一章时,这一条要提前说。

2. 加了自定义消息类型,忘了改 convertToLlm。

后果分两种:写了穷尽检查 → 编译报错(好事);没写 → 消息被 default 分支静默丢弃,模型永远看不到,而且没有任何日志。

3. display: false 不等于不进上下文。

它只影响 UI。想不进上下文,用 excludeFromContext。两个名字长得不像,容易搞混。

4. excludeFromContext 是删除不是标记。

!!ls 之后模型看到的是一段"无间隙"的对话。如果你的扩展依赖"消息索引"做对齐,删除会打乱索引。

5. 摘要消息的标签不能省。

<summary> 是给模型看的语义信号。省掉标签就是一段普通文本,模型会以为"用户刚跟我说了一段总结",可能顺着往下编。M09 会看到压缩后模型"接着摘要继续总结"的经典故障。

6. 别把 details 当存储用。

ToolResultMessage.details 的注释是 JsonRepresentation——它要能 JSON 序列化,因为 M10 会把它写进 jsonl。塞一个 Date 或 Map 进去,落盘时会变成字符串或者直接丢。好在 §3.4 那个条件类型会在编译期拦住大部分情况。

7. exitCode 的 null 幽灵。

类型写的是 number | undefined(messages.ts:33),但 bashExecutionToText 判的是 !== null && !== undefined(:91)。 防御 null 是历史遗留——从 jsonl 读回的旧记录里可能真有 null。 类型收窄了,实现不敢收窄,这种不一致要留着。

8. 两个时钟。

AssistantMessage.timestamp 是请求开始的时间(:608 注释), durationMs 用 monotonic clock 量,不是 Date.now() 相减。 原因:系统时间会被 NTP 校时、夏令时、用户手改往回拨, 用墙钟算耗时会算出负数。记时刻用墙钟,量间隔用单调钟。


十一、三个可以带走的方法

方法一:超集用"空接口 + 声明合并"扩展,不要用泛型。

泛型参数会沿着调用链传染——AgentMessage<T> 传到第十层,中间每个函数都要带 <T>。声明合并是全局的:加一次,全仓库生效,签名不变。

代价是可发现性变差,用文件头注释和穷尽检查补。

方法二:降级时全部落到最宽的槽位。

四种自定义消息全变 role: "user"。不是懒,是"role 的集合由协议决定,不由你决定"。

设计自己的转换层时,先问:下游系统认识哪几种类型? 那是硬约束,你的语义要往里挤,不是反过来。

方法三:默认安全,显式放开。

默认 convertToLlm 是过滤器(丢掉不认识的),默认 CustomAgentMessages 是空的。两个默认值都选择"什么都不做"。

一个往外部系统发数据的接口,默认应该不发。 想发就显式传一个函数进去——传的那一刻,调用方就知道自己在放开什么。

两个默认值叠加,结果是"什么都没发生"。而这恰好是最难的默认值: 一个什么都不做的接口,必须能被静态检查证明"确实什么都没做"—— 空接口 + filter,两个都可以用类型和逻辑看完。


本章小结

  1. 给模型的只有四种 role;给系统记的有八种。
  2. 多出的四种靠空接口 + 声明合并,不改 agent 包。
  3. convertToLlm 是唯一闸门,默认行为是"过滤"。
  4. 降级全部落到 role: "user",因为 role 集合由协议定。
  5. 发给模型的最后一条必须是 user 或 toolResult。

概念回顾

术语 一句话 在哪
超集 8 种对 4 种,多的四种只给系统记 §三
声明合并 空接口 + declare module,不传染泛型 §三
闸门 convertToLlm,唯一出口 §四
三开关 显示 / 排除上下文 / 转换,三件不同的事 §六
两时钟 记时刻用墙钟,量间隔用单调钟 §十 坑 8

练习

练习 1(读):§八 说最后一条必须是 user 或 toolResult。 如果 transcript 停在一条 assistant 上,哪些下游会先报错? → 回 §五 的"两阶段管道"找它在哪里被兜住。

练习 2(改):给 CustomAgentMessages 加一种消息,只写声明、 不写 convertToLlm 分支。预期:default 分支静默丢弃,模型永远看不到; 回滚:删掉那条声明,编译即恢复。

常见误区

  1. 你会以为 display: false 就不进上下文;实际是 它只影响 UI; 证据 §十 坑 3。
  2. 你会以为 加消息类型要改 agent 包;实际是 声明合并就够了; 证据 §三。
  3. 你会以为 convertToLlm 默认会尽力转换;实际是 默认当过滤器; 证据 §4.3。

读完自检

三条,能不能不看稿说出来?

自检 一句话答案 不会就去
给模型看的有几种?给系统记的有几种? 4 种 / 8 种;多出来的 4 种靠一道闸门降级 §一、§二
加消息类型为什么不用改 agent 包? 空接口 + 声明合并,AgentMessage 从 4 变 8 §三
那道转换闸门默认干什么? 默认是过滤器——丢掉不认识的,不是硬转 §4.3

下一步

消息有了,工具有了,循环有了。但这些东西怎么跟外面说话?

用户按了 Esc,循环怎么知道要停?工具跑了 3 秒,进度怎么到 UI?扩展想在"工具调用之前"插一脚,它挂在哪?

下一章打开事件系统。

想亲手写那道「八种收窄成四种」的闸门?Part E 的 E02 用 33 行造了同构的一道,还演示了忘改 case 时怎么当场炸。


本章源码索引

文件 行数 本章用到的位置
packages/ai/src/types.ts 918 SystemMessage :561-577、UserMessage :579-583、AssistantMessage :585-616、ToolResultMessage :640-657、Message :659
packages/agent/src/types.ts — CustomAgentMessages :365-367、AgentMessage :374、transformContext 契约 :224-232
packages/agent/src/agent.ts — defaultConvertToLlm :39-47、convertToLlm 挂载 :200 :242
packages/agent/src/agent-loop.ts 960 两阶段 :403-406、最后一条约束 :74-79
packages/coding-agent/src/core/messages.ts 197 四条 case :151-193、声明合并 :70-77、bashExecutionToText :82-98
packages/coding-agent/src/core/sdk.ts — convertToLlmWithBlockImages :296-302、传入 :411
packages/coding-agent/src/core/compaction/compaction.ts — 摘要前转换 :721 :1076
packages/coding-agent/src/core/compaction/utils.ts 164 Message[] 约束 :109、serializeConversation :120、thinking 取舍 :114-118
packages/ai/src/api/anthropic-messages.ts 1,687 字段回填 :590-601、responseId :705、responseModel :709、rawStopReason :842、mapStopReason :1660-1682