Pi Agent 源码级教程
E02

记忆 —— 第五种消息,和唯一一道闸

2,559 字 · 含 196 行代码 · 约 12 分钟

E01 收尾留了两个洞:types.ts 里 NoteMessage 定义了没人用,loop.ts 的 project 参数一直是空的。这一章把两个洞一起填上:消息从四种变五种, 但发给模型的永远只有四种。

三个问题:

  1. 系统自己记的消息,凭什么不能直接进 prompt?
  2. 忘改一个 case,凭什么当场炸,而不是悄悄污染历史?
  3. 摘要变成 user 消息之后,为什么「放在哪」也能出事?
text
  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 -->

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}`);

跑:

bash
cd examples/mini-agentnode src/demo-memory.ts
text
历史 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 -->

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,投影结果一模一样:

text
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: true

toLlm 里根本没有读 display。这不是漏洞,是分工:投影层只回答「给模型 看什么」,界面层只回答「给用户看什么」。 一个字段背两个职责,迟早会有人 用错。

Pi 里对应的是 CustomMessage,字段名不同,思路一致:

ts
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 -->

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 的做法更啰嗦一点,压缩摘要前缀是整句话:

text
The conversation history before this point was compacted intothe following summary:

一句话说清「这是摘要,不是用户说的」,比任何格式都管用。

第三段:default 抛错。 这是本章真正的重点。它不是为了处理未知角色, 而是为了在你将来加了第六种消息、却忘了改这里时,立刻炸掉。


四、位置:note 放末尾就变味

note 被翻译成 user 之后,它就和用户的话同一种形状了。于是「放哪」变成了 语义问题。上面那段真实输出里,同一段历史只改位置:

text
摘要放开头 → 最后一句 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 只做类型擦除, 不做类型检查。我写了一个五行文件:

ts
const m = { role: "note" } as AgentMessage;const x: never = m;console.log("ran", typeof x);

编辑器把第二行标成红色的类型错误,node tmp-never.ts 的输出是:

text
ran object

一行错误都没报。所以「有没有漏角色」只能放在运行时判断:

text
ERR: unhandled: unknown

这就是一张能用的网:开发时你会立刻看到它,而不是等模型答非所问。Pi 在同一 位置用了另一招——用 never 做编译期检查,同时兜底返回 undefined:

<!-- file: pi-main/pi-main/packages/coding-agent/src/core/messages.ts -->

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 -->

ts
  /** 把 AgentMessage 投影成给模型看的 Message;E02 才传入。 */  project?: (messages: AgentMessage[]) => Message[];
ts
  const project = options.project ?? ((all: AgentMessage[]) => all as Message[]);

默认值是恒等函数——所以 E01 的 demo.ts 一行不改也能跑。E02 只要把它换成 toLlm,整个循环就自动「只看四种消息」了。本章那个入口的尾部就是这段(只 摘了关键几行):

<!-- file: examples/mini-agent/src/demo-memory.ts -->

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 里最不该省的一层:省了它,后面每一次加消息 类型都在赌「我这次没忘」。

自检

  1. display: false 的 note,会出现在 toLlm 的结果里吗?为什么?
  2. 输出里「历史 5 条 → 模型 5 条」,数量没变。这说明了什么?如果哪天它变成 4 条,是好事还是坏事?
  3. 如果让 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 会不联网地吐出一段「像模型说的话」。