记忆 —— 第五种消息,和唯一一道闸
E01 收尾留了两个洞:types.ts 里 NoteMessage 定义了没人用,loop.ts 的
project 参数一直是空的。这一章把两个洞一起填上:消息从四种变五种,
但发给模型的永远只有四种。
三个问题:
- 系统自己记的消息,凭什么不能直接进 prompt?
- 忘改一个
case,凭什么当场炸,而不是悄悄污染历史? - 摘要变成 user 消息之后,为什么「放在哪」也能出事?
AgentMessage(5 种) system / user / assistant / tool / note | | toLlm() <- 唯一出口 v Message(4 种) system / user / assistant / tool | v provider一、本章终点:先跑起来
本章新增一个入口 src/demo-memory.ts。它的全部工作就在下面这 92 行里:造
一段带 note 的历史、投影一次、对比两种位置、再塞进循环跑一轮。
<!-- file: examples/mini-agent/src/demo-memory.ts -->
/** * E02 的终点:五种消息 → 四种消息,中间只有一道闸。 * 运行:cd examples/mini-agent && node src/demo-memory.ts */import { toLlm } from "./messages.ts";import { runAgent } from "./loop.ts";import { createMockProvider } from "./provider/mock.ts";import type { AgentMessage, Message, NoteMessage } from "./types.ts";/** 一段真会话:读文件、拿到结果、回话。四种老消息齐了。 */const history: AgentMessage[] = [ { role: "user", content: "读一下 README.md" }, { role: "assistant", content: [ { type: "text", text: "先看看文件。" }, { type: "toolCall", id: "call_1", name: "read", args: { path: "README.md" }, }, ], stopReason: "toolUse", }, { role: "tool", toolCallId: "call_1", toolName: "read", content: "# mini-agent", }, { role: "assistant", content: [{ type: "text", text: "(mock)读完了。" }], stopReason: "stop", },];/** 系统自己记的一条:要进上下文,但不是用户说的话。 */const note: NoteMessage = { role: "note", kind: "summary", text: "前 4 条已压缩:用户在问 README。", display: false, timestamp: 0,};function preview(message: Message): string { if (typeof message.content === "string") { return message.content.slice(0, 16); } const text = message.content.find((b) => b.type === "text"); return text ? text.text.slice(0, 16) : "(toolCall)";}function lastUser(messages: AgentMessage[]): string { const llm = toLlm(messages); const user = [...llm].reverse().find((m) => m.role === "user"); return user ? preview(user) : "(none)";}const projected = toLlm([...history, note]);console.log(`历史 ${history.length + 1} 条 → 模型 ${projected.length} 条`);for (const message of projected) { console.log(` ${message.role.padEnd(9)} ${preview(message)}`);}/* note 变成 user 之后,位置决定它是不是「用户刚说的话」 */const head = lastUser([note, ...history]);const tail = lastUser([...history, note]);console.log(`摘要放开头 → 最后一句 user: ${head}`);console.log(`摘要放末尾 → 最后一句 user: ${tail}`);/* 漏了一个角色时,闸门当场炸,不悄悄丢历史 */try { toLlm([{ role: "unknown" } as unknown as AgentMessage]);} catch (error) { console.log(`ERR: ${(error as Error).message}`);}/* 闸门接进循环:loop 的 project 参数就是这一处 */const result = await runAgent({ provider: createMockProvider(), tools: [], messages: [note, ...history], maxTurns: 2, project: toLlm, emit: (event) => { if (event.type === "text_delta") process.stdout.write(event.text); },});console.log(`\nturns=${result.turns} stop=${result.stopReason}`);跑:
cd examples/mini-agentnode src/demo-memory.ts历史 5 条 → 模型 5 条 user 读一下 README.md assistant 先看看文件。 tool # mini-agent assistant (mock)读完了。 user <note kind="summ摘要放开头 → 最后一句 user: 读一下 README.md摘要放末尾 → 最后一句 user: <note kind="summERR: unhandled: unknown(mock)读完了,文件已经在上下文里。turns=1 stop=stop四块分别是:投影表(第五种消息变成了 user)、位置对比、闸门报错、接进循环 跑一轮。
| 文件 | 行数 | 本章变化 |
|---|---|---|
src/types.ts |
106 | 不动(NoteMessage E01 就在) |
src/messages.ts |
33 | 新增,本章全部内容 |
src/demo-memory.ts |
92 | 新增,给本章一个能跑的终点 |
| 合计 | 443 | E01 的 318 + 本章 125 |
二、第五种消息:只给自己看
E01 的历史只有四种消息,正好等于模型能理解的四类角色。真实会话没这么干净:
- 用户按了 Ctrl+B,把一段 bash 输出塞进对话——不是他说的,也不是模型说的;
- 上下文快满了,你把前 20 条压成一段摘要——摘要得让模型看见,但它不是用户输入;
- 界面要显示「已压缩 12 条」,模型不需要知道这个提示。
硬塞进四种角色,模型就会以为「用户刚才说了这句话」。等它开始回答一句用户 根本没说过的话,你才发现历史被污染了。
所以第五种消息的形状是这样的:
<!-- file: examples/mini-agent/src/types.ts -->
/** 只给自己看的一种:display=false 时只进上下文,不上屏。 */export interface NoteMessage { role: "note"; kind: "summary" | "reminder"; text: string; display: boolean; timestamp: number;}export type AgentMessage = Message | NoteMessage;display 值得停一下,因为它常被读错。它管的不是「发不发」,而是
「上不上屏」。这两个问题必须分开:
- 一条压缩摘要:模型要看(否则不知道前文),用户未必要看(折叠成一行提示);
- 一条「已重试 2 次」的提醒:用户要看,模型不必看。
我把同一条 note 的 display 分别设成 false 和 true,投影结果一模一样:
display=false: [{"role":"user","content":"hi"}, {"role":"user","content":"<note kind=\"summary\">so far</note>"}]display=true : [{"role":"user","content":"hi"}, {"role":"user","content":"<note kind=\"summary\">so far</note>"}]same: truetoLlm 里根本没有读 display。这不是漏洞,是分工:投影层只回答「给模型
看什么」,界面层只回答「给用户看什么」。 一个字段背两个职责,迟早会有人
用错。
Pi 里对应的是 CustomMessage,字段名不同,思路一致:
export interface CustomMessage<T = unknown> { role: "custom"; customType: string; content: string | (TextContent | ImageContent)[]; display: boolean; details?: T; timestamp: number;}customType 相当于我们的 kind;display 一样只管上屏;details 是给界面
留的原始载荷(比如工具调用的入参),模型看不到。另外 Pi 的 bash 消息上有个
excludeFromContext(messages.ts:39),那是「连模型也不给」的开关——我们
这两种 note 都还没有这个需求,先不加。
三、写闸门:34 行,只干一件事
所有发给模型的消息,只经过这一个函数。全文如下:
<!-- file: examples/mini-agent/src/messages.ts -->
import type { AgentMessage, Message, NoteMessage } from "./types.ts";/** * 唯一出口:AgentMessage → Message。 * 多出来的 note 在这里翻译成 user 消息;缺一条 case 就抛错, * 所以「忘了一个角色」会在开发时立刻暴露,而不是悄悄丢历史。 */export function toLlm(messages: AgentMessage[]): Message[] { const out: Message[] = []; for (const message of messages) { switch (message.role) { case "system": case "user": case "assistant": case "tool": out.push(message); break; case "note": out.push({ role: "user", content: renderNote(message) }); break; default: { const unknown = message as { role?: string }; throw new Error(`unhandled: ${String(unknown.role)}`); } } } return out;}function renderNote(note: NoteMessage): string { return `<note kind="${note.kind}">${note.text}</note>`;}三段值得单独说。
第一段:四种老消息原样透传。 它们是 Message 的子集,不需要翻译,直接
push。注意这里没有做深拷贝——消息是不可变的,谁改写谁负责。
第二段:note 翻译成 user。 为什么不新增一个 note 角色发给 provider?
因为 provider 的方言是外部约束,不是你说了算。OpenAI 的 role 只有四种,
Anthropic 的 user 消息里能放 text 块,但没有「系统备注」这一档。所有 provider
都能表达的最小形式就是一条 user 消息。
代价是模型可能把它当成用户说的话。所以 note 的文本必须自带身份标签:
<note kind="summary">。Pi 的做法更啰嗦一点,压缩摘要前缀是整句话:
The conversation history before this point was compacted intothe following summary:一句话说清「这是摘要,不是用户说的」,比任何格式都管用。
第三段:default 抛错。 这是本章真正的重点。它不是为了处理未知角色,
而是为了在你将来加了第六种消息、却忘了改这里时,立刻炸掉。
四、位置:note 放末尾就变味
note 被翻译成 user 之后,它就和用户的话同一种形状了。于是「放哪」变成了
语义问题。上面那段真实输出里,同一段历史只改位置:
摘要放开头 → 最后一句 user: 读一下 README.md摘要放末尾 → 最后一句 user: <note kind="summ模型判断「用户现在想干什么」,看的就是最后一条 user。摘要放末尾,它就会 回答摘要。这不是理论风险,是所有 provider 的共同行为——最后一条 user 就是 当前轮次。
所以压缩摘要只有一种放法:替换历史开头,紧跟在 system 之后。 Pi 的
convertToLlm 里,compactionSummary 也翻译成 user,但它的前缀写的是
"the conversation history before this point was compacted",位置和语义
一起锁死。
五、类型擦除不替你兜底
你可能会想:AgentMessage 是联合类型,漏掉一个 case,TypeScript 会报错。
在有编译步骤的项目里确实会。但 Node 22.19 起直接跑 .ts 只做类型擦除,
不做类型检查。我写了一个五行文件:
const m = { role: "note" } as AgentMessage;const x: never = m;console.log("ran", typeof x);编辑器把第二行标成红色的类型错误,node tmp-never.ts 的输出是:
ran object一行错误都没报。所以「有没有漏角色」只能放在运行时判断:
ERR: unhandled: unknown这就是一张能用的网:开发时你会立刻看到它,而不是等模型答非所问。Pi 在同一
位置用了另一招——用 never 做编译期检查,同时兜底返回 undefined:
<!-- file: pi-main/pi-main/packages/coding-agent/src/core/messages.ts -->
case "system": case "user": case "assistant": case "toolResult": return m; default: // biome-ignore lint/correctness/noSwitchDeclarations: fine const _exhaustiveCheck: never = m; return undefined;它敢返回 undefined,是因为整个函数最后有一行
.filter((m) => m !== undefined):Pi 支持「这条消息不发」,我们需要的是
「每条消息都必须有归宿」。两种策略的分水岭是:你到底允不允许丢消息。
我们的答案是不允许,所以抛错。
六、接进循环:project 参数终于有人传了
E01 里这两行就在,只是没人用:
<!-- file: examples/mini-agent/src/loop.ts -->
/** 把 AgentMessage 投影成给模型看的 Message;E02 才传入。 */ project?: (messages: AgentMessage[]) => Message[]; const project = options.project ?? ((all: AgentMessage[]) => all as Message[]);默认值是恒等函数——所以 E01 的 demo.ts 一行不改也能跑。E02 只要把它换成
toLlm,整个循环就自动「只看四种消息」了。本章那个入口的尾部就是这段(只
摘了关键几行):
<!-- file: examples/mini-agent/src/demo-memory.ts -->
// …const result = await runAgent({ // … project: toLlm, // …});输出 turns=1 stop=stop。为什么只有一轮?因为历史里已经躺着一条 tool 结果,
mock 的规则 2 命中:「已经有 tool 结果就回一句总结,停」。它连 read 工具都
没要——tools: [],mock 也就不可能发 toolCall。
这正是 E01 说的「假模型的价值」:它让每一层的输入输出都可预期,你能一眼看出 这一轮是谁在起作用。
七、三个做坏实验
| # | 改动 | 判据 | 谁受影响 |
|---|---|---|---|
| 1 | display: false → true |
投影结果 same: true |
只有界面,模型不知道 |
| 2 | note 从开头挪到末尾 | 最后一句 user 变成 note | 模型答非所问 |
| 3 | toLlm([{ role: "unknown" }]) |
抛 unhandled: unknown |
开发期当场炸 |
实验 1 证明 display 不是开关;实验 2 证明格式对了,位置还能错;实验 3
证明类型擦除靠不住。三个都不是「跑通」的证明,而是「坏了能被看见」的证明。
八、代码地图
| 文件 | 关键符号 | 下一章怎么用 |
|---|---|---|
src/types.ts |
NoteMessage / AgentMessage |
不再改形状,E05 压缩要用它 |
src/messages.ts |
toLlm() / renderNote() |
E03 真 provider 只吃它的输出 |
src/demo-memory.ts |
lastUser() |
E06 存会话时,历史读写要保证这个顺序 |
src/loop.ts |
project 参数 |
E04 换工具时不动它 |
第四章会往 loop.ts 里塞并发执行,第五章才回来复用 NoteMessage 存摘要。
现在这个 34 行,是整个 Part E 里最不该省的一层:省了它,后面每一次加消息
类型都在赌「我这次没忘」。
自检
display: false的 note,会出现在toLlm的结果里吗?为什么?- 输出里「历史 5 条 → 模型 5 条」,数量没变。这说明了什么?如果哪天它变成
4 条,是好事还是坏事? - 如果让
toLlm支持「只发最近 N 条」,它和 E05 的压缩keep有什么区别? 哪个更适合放在闸门里?
参考答案:
第 1 题:会。toLlm 从不读 display,同一条 note 在 false 和 true
下投影完全相同(same: true)。display 只决定界面渲不渲染。
第 2 题:说明投影是 1:1 翻译,没有静默丢弃。变成 4 条意味着有一层开始 「替用户做减法」——那属于压缩(E05),不属于闸门。闸门只做形状转换,压缩 才做数量决策。这两个职责混在一起,就是你排查「模型为什么忘了刚才那件事」 时永远查不到原因的地方。
第 3 题:toLlm 的 N 是无状态截断,每次调用都从尾部切,切掉什么
就永远不知道了;压缩的 keep 是有状态替换,前面那段落被写成一条 note
留在历史里。所以压缩必须在 AgentMessage 层做(保留 note),不能塞进闸门。
九、与 Pi 的对照(可选,不需要打开源码)
packages/coding-agent/src/core/messages.ts:148 的 convertToLlm 和你刚写的
34 行同构,差别只有三处:
| 本章 34 行 | Pi convertToLlm |
|
|---|---|---|
| 额外角色 | note 一种 |
bash / custom / branchSummary / compactionSummary 四种 |
| 丢消息 | 不允许,必须抛 | 允许,filter 掉 undefined |
| 开关 | 无 | excludeFromContext(!! 前缀) |
它多出来的四种角色,全是「用户在终端里做过、但模型只该看到结论」的事: bash 执行、扩展注入、分支回退、压缩摘要。你以后加第六种时,形状一定是这 四条里的某一条。
真要看的时候再去看,现在你手上已经有一份能跑的。
十、下一章
loop.ts 现在还是硬绑 createMockProvider()。消息形状既然稳定了,下一步
就是换 provider:先写一个离线的 fixture(把一段真实回复录成 JSONL,回放
时逐块吐),再写真的 openai(解析 SSE 的增量块),最后把两种 provider
放进同一个循环里跑同样的输入,看输出是否一致。
E03 结束时,node src/demo-model.ts 会不联网地吐出一段「像模型说的话」。