消息系统 —— 四种给模型看,八种给系统记
M05 里工具执行完了,产出变成一条 ToolResultMessage。它进了 transcript,然后在下一轮被发给模型。
问题来了:用户在 TUI 里敲 !ls -la,这条 bash 执行记录是什么消息?它不是用户说的话,也不是模型说的话,更不是工具调用结果。可是它必须留在 transcript 里——下次打开会话还能看到"我当时跑了什么"。
Pi 的答案是:给系统记的消息比给模型看的多四种。
这一章讲这四种,以及它们和那四种之间那道转换闸门。
一、给模型看的只有四种
Message 的定义只有一行(packages/ai/src/types.ts:659):
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)是唯一一个"必须记录是谁回答的"的消息:
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)里有三个字段明确注明不发给模型:
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:! 命令的记录
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:扩展的注入口
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:分叉回退的凭证
export interface BranchSummaryMessage { role: "branchSummary"; summary: string; fromId: string | null; timestamp: number;}场景:你在第 20 轮发现走错路了,回退到第 8 轮重开。但第 9 到 20 轮发生过的事不能凭空消失——模型如果完全不知道"之前试过 A 方案失败了",就会再试一次。
branchSummary 就是那条"我从哪来"的记录:fromId 指向被放弃的分叉点,summary 是那段历史的摘要。它被插回上下文时用一对标签包起来(messages.ts:19-24):
The following is a summary of a branch that this conversation came back from:<summary>...摘要内容...</summary>为什么要标签?因为要让它长得不像对话。模型看到 <summary> 包着的东西,就知道这是"关于历史的元信息",不是"用户在跟我说话"。
2.4 compactionSummary:压缩后的替身
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:
export interface CustomAgentMessages { // Empty by default - apps extend via declaration merging}export type AgentMessage = Message | CustomAgentMessages[keyof CustomAgentMessages];CustomAgentMessages 是空接口。所以默认情况下:
AgentMessage = Message | never = Messagenever 在联合类型里会消失。默认等于没有扩展,零成本。
两个语法点如果生疏:X[keyof X] 叫「索引访问类型」,意思是"把 X 里每个属性的值取出来,拼成一个联合";never 混进联合里会自动消失。二者在附录 B 的 §2.2 和 §三 符号表各有一行。
然后 coding-agent 在 messages.ts:70-77 往里加字段:
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):
default: // biome-ignore lint/correctness/noSwitchDeclarations: fine const _exhaustiveCheck: never = m; return undefined;never 类型在这里当编译器用:如果某个 case 没写,m 就不是 never,这一行编译报错。
声明合并让"加类型"变容易了,所以"加完忘改转换器"就成了主要风险。 穷尽检查是唯一能拦住它的东西。注释里那个 biome-ignore 说明这是在"让 linter 闭嘴换类型安全"——值得的交易。
3.4 声明合并是"编译单元级"的
这点容易误解:CustomAgentMessages 不是全局共享的,
合并结果取决于当前程序包含了哪些文件。
只编 agent 包 → AgentMessage = 4 种编 agent + coding-agent → AgentMessage = 8 种messages.ts:70 那句 declare module 要进入编译图才生效。
如果某个测试文件没 import 到它,里面的 AgentMessage 还是四个成员,
写 case "bashExecution" 直接报错。
三个实际后果:
- 不要在
agent包的单元测试里断言八种消息—— 那个包看不到自定义类型 agent包的代码不该switch自定义 role——编译不过, 除非加default兜底- 类型只在"看到那个 import"的地方变宽,所以声明合并的入口文件
必须唯一:
coding-agent里就是core/messages.ts
顺带解释一个怪现象:agent 包和 coding-agent 里都写着
AgentMessage,在编辑器里点进去是同一个定义,但悬停时看到的展开结果
可能不一样。不是 IDE 抽风,是两处看到的合并结果不同。
3.5 非法 details 让它编译不过
ToolResultMessage 还带一个条件类型(ai/src/types.ts:640):
export type ToolResultMessage<TDetails = JsonValue> = IsJsonCompatible<TDetails> extends true ? { ... } : never;details 不是随便挂的。判定分三层(:491-537):
IsJsonCompatible<T>——递归走一遍,函数、undefined、Symbol之类都判falseInvalidJsonKeys<T>——反向找出哪个键不合法, 报错信息能指到具体字段never——不合规时整个ToolResultMessage变成never, 任何赋值都编译失败
为什么值得写六十行类型体操?因为 details 的唯一归宿是 jsonl 文件(M10)。
塞一个 Date 进去,落盘时静默变成字符串;塞一个 Map 进去,直接变 {}。
错误在落盘那一刻才暴露,而那时类型信息已经找不回来了。
JsonRepresentation<T>(:527-537)是配套的另一半:它把内存类型映射成
"落盘之后的形态",让读取方知道会拿到什么。
四、convertToLlm:那道转换闸门
4.1 四条 case,一种产物
完整函数(messages.ts:148-196)不长。四条自定义消息的处理:
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)的产物:
Ran `ls -la`total 24 drwxr-xr-x 5 user staff 160 Nov 2 10:00 . ...
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:
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 是两行:
const llmMessages = await config.convertToLlm(messages);const llmContext = normalizeContext({ messages: llmMessages });前面还有一道(AgentLoopConfig.transformContext),完整链条是三级:
AgentMessage[] 八种,超集 ↓ transformContext AgentMessage → AgentMessage(可选)AgentMessage[] ↓ convertToLlm AgentMessage → Message(必选)Message[] 四种,子集 ↓ normalizeContext Message → TranscriptContext(M04)TranscriptContext5.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 之后,压缩路径上还有一道更狠的降级:
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 走的是丢弃,不是标记
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 包了一层:
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 到模型收到请求:
用户敲 !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
userortoolResultmessage viaconvertToLlm. If it doesn't, the LLM provider will reject the request. This cannot be validated here sinceconvertToLlmis only called once per turn.
这是 agentLoopContinue(重试入口)的注释。三个事实:
- provider 要求最后一条是
user或toolResult(不能让模型接着自己的话往下说) - 这个要求在转换之后才成立
- 转换每轮只调用一次,所以"调完之后又追加了消息"这种情况没人检查
真实事故长这样:某处在转换之后往 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 有几个成员。
# 在仓库根目录执行cd packages/ai/srcsed -n '659p' types.ts一行,四个。
实验 2:确认默认是"空超集"。
sed -n '365,374p' ../../agent/src/types.tsCustomAgentMessages 空接口 + never 在联合里消失。
实验 3:找出声明合并。
cd ../../coding-agent/src/coregrep -n -A 8 "declare module" messages.ts四个字段,全部挂在 CustomAgentMessages 上。
实验 4:看默认转换器丢什么。
cd ../../agent/srcsed -n '39,47p' agent.ts四个 role 白名单,其余全丢。
实验 5:数调用点。
cd ../../coding-agent/srcgrep -rn "convertToLlm(" --include=*.ts | wc -lcd ../../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" 那一支注释掉再编译,会报:
Type 'BranchSummaryMessage' is not assignable to type 'never'这就是那个 _exhaustiveCheck 在工作。
实验 7:看归一化的兜底。
cd ../../ai/src/apised -n '1674,1684p' anthropic-messages.tsrefusal 变 error 并带上 "sensitive";stop_sequence 那支坦然写着
"这永远不会发生",但照样 return { stopReason: "stop" }。
一个不会发生的分支也必须有返回值,否则类型检查过不去。
实验 8:改一处试试——把 !! 找回来。
- 改哪里
messages.ts:154-156,删掉这三行:
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,两个都可以用类型和逻辑看完。
本章小结
- 给模型的只有四种 role;给系统记的有八种。
- 多出的四种靠空接口 + 声明合并,不改
agent包。 convertToLlm是唯一闸门,默认行为是"过滤"。- 降级全部落到
role: "user",因为 role 集合由协议定。 - 发给模型的最后一条必须是
user或toolResult。
概念回顾
| 术语 | 一句话 | 在哪 |
|---|---|---|
| 超集 | 8 种对 4 种,多的四种只给系统记 | §三 |
| 声明合并 | 空接口 + declare module,不传染泛型 |
§三 |
| 闸门 | convertToLlm,唯一出口 |
§四 |
| 三开关 | 显示 / 排除上下文 / 转换,三件不同的事 | §六 |
| 两时钟 | 记时刻用墙钟,量间隔用单调钟 | §十 坑 8 |
练习
练习 1(读):§八 说最后一条必须是 user 或 toolResult。
如果 transcript 停在一条 assistant 上,哪些下游会先报错?
→ 回 §五 的"两阶段管道"找它在哪里被兜住。
练习 2(改):给 CustomAgentMessages 加一种消息,只写声明、
不写 convertToLlm 分支。预期:default 分支静默丢弃,模型永远看不到;
回滚:删掉那条声明,编译即恢复。
常见误区
- 你会以为
display: false就不进上下文;实际是 它只影响 UI; 证据 §十 坑 3。 - 你会以为 加消息类型要改
agent包;实际是 声明合并就够了; 证据 §三。 - 你会以为
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 |