Pi Agent 源码级教程
E05

上下文 —— 一道阈值,一条摘要,四个数字

1,771 字 · 含 112 行代码 · 约 10 分钟

E04 之后,工具能并发、能加锁,但历史还是每轮往上加。跑三十轮,请求体会从几 KB 涨到几百 KB,直到某个接口返回 400,而你完全不理解它为什么突然不干了。

这一章加第一版压缩。它不调用模型、不做摘要生成,只做一件事:到期就把前面的 历史换成一条 note。

三个问题:

  1. 「多少个 token 了」怎么估?估错了会怎样?
  2. 压掉的是哪几条?为什么不是「随便砍一半」?
  3. 压完之后,模型怎么知道前面发生过什么?
text
  AgentMessage[]                      AgentMessage[]  [u][a][t][a][u][a][t]...    -->     [note][a][u][a]        |                                    |        | threshold?  keep?                  | toLlm()        v                                    v   compactIfNeeded()                    provider

一、本章终点:先跑起来

bash
cd examples/mini-agentnode src/demo-compact.ts
text
tokens 238 → 104compacted true dropped 7len 4 first notenote: <summary>早期 7 条(user 7 / tool 0)</summary>投影后 4 条  user      <note kind="summary"><su  user      第 8 条:很长的内容很长的内容很长的内容很长的  user      第 9 条:很长的内容很长的内容很长的内容很长的  user      第 10 条:很长的内容很长的内容很长的内容很长

四个数字是这一章的全部验收标准:压了没有(compacted)、丢了几条(dropped)、 还剩几条(len)、第一条是不是摘要(first note)。后面投影那四行,是 E02 那道 闸门在干活:note 变成一条 user,而且排在最前面。

文件 行数 本章变化
src/compact.ts 56 新增:估算 + 两道闸
src/demo-compact.ts 31 新增:本章入口
合计 948 E04 的 861 + 本章 87

二、估算:JSON 字符数 / 4

ts
export function estimateTokens(messages: AgentMessage[]): number {  return Math.ceil(JSON.stringify(messages).length / 4);}

一行。为什么是 /4?英文大约 4 个字符 1 个 token,这是流传最广的粗估。 中文完全不准(一个汉字常常 1~2 token,而 JSON.stringify 里它算 1 个字符), 误差能到 30% 以上。

那就把话说清楚:这个数字的唯一用途是「要不要开始压」,不是「还能放多少」。 前者错 30% 只是提前或推迟一点压;后者错 30% 就会 400。

真实请求里,准确的 token 数只有两个来源:接口返回的 usage,或者本地跑一个 tokenizer(多一个依赖、多一份模型词表)。我们两个都不用。


三、压缩器:56 行

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

ts
import type { AgentMessage, NoteMessage } from "./types.ts";export interface CompactOptions {  threshold?: number;  keep?: number;}export interface CompactResult {  messages: AgentMessage[];  compacted: boolean;  tokensBefore: number;  dropped: number;}/** 粗估:JSON 字符数 / 4。不追求准,只追求「先有一道闸」。 */export function estimateTokens(messages: AgentMessage[]): number {  return Math.ceil(JSON.stringify(messages).length / 4);}/** * 两道闸门:先看 token 估计,再看末尾保留几条。 * 过闸就把早期消息压成一条 note,最近 keep 条原样留下。 */export function compactIfNeeded(  messages: AgentMessage[],  options: CompactOptions = {},): CompactResult {  const threshold = options.threshold ?? 8000;  const keep = options.keep ?? 6;  const tokensBefore = estimateTokens(messages);  if (tokensBefore <= threshold || messages.length <= keep) {    return { messages, compacted: false, tokensBefore, dropped: 0 };  }  const cut = messages.length - keep;  const head = messages.slice(0, cut);  const tail = messages.slice(cut);  const note: NoteMessage = {    role: "note",    kind: "summary",    display: true,    timestamp: Date.now(),    text: `<summary>${summarize(head)}</summary>`,  };  return {    messages: [note, ...tail],    compacted: true,    tokensBefore,    dropped: cut,  };}function summarize(messages: AgentMessage[]): string {  const users = messages.filter((m) => m.role === "user").length;  const results = messages.filter((m) => m.role === "tool").length;  return `早期 ${messages.length} 条(user ${users} / tool ${results})`;}

三处决策值得记。

决策一:两道闸,|| 不是 &&。 条件写的是 tokensBefore <= threshold || messages.length <= keep ——任意一条成立就不压。 keep 是硬的:只有 5 条消息时,哪怕字符特别多也不压,因为压完只剩 3 条, 上下文薄到模型没法干活。

决策二:压的是「前面」,留的是「末尾」。 cut = length - keep,前 cut 条 变成一条摘要,后 keep 条原样不动。这符合对话的形状:最近几轮才是当前任务。

决策三:摘要用 NoteMessage,不是字符串。 它得进历史(要能存盘、能回放), 又不能假装是用户说的话。E02 定义的 display: true 在这里第一次有了实际含义: 这条摘要要上屏,用户得知道「前面被压了」。

summarize 现在只数条数——因为它不调用模型。这不是偷懒,是分工:先把「什么时候 压、压哪几条」跑通,再换「怎么总结」。


四、四个数字怎么读

text
tokens 238 → 104compacted true dropped 7len 4 first note
  • 238 → 104:压缩前后的估算值。它验证的是「确实变小了」,不是「现在安全了」。
  • dropped 7:10 条里砍掉 7 条。这个数字是 cut,也是摘要里那个 早期 7 条。
  • len 4:7 条变成 1 条,加末尾 3 条 = 4。
  • first note:第一条是摘要。如果这里是 first user,说明位置错了——摘要跑到 中间或末尾,模型会把它当成「用户刚说的话」(E02 第四节)。

再看投影那四行:第一条 user 的内容是 <note kind="summary">...。这正是 E02 设计的形状。压缩只改 AgentMessage,投影层一行都没动。


五、这一版故意留的三个错

写完就该知道它哪里不对,否则你会以为「压缩做完了」。

错一:会切断工具调用对。 cut 按条数切,可能在 toolCall 和它的 toolResult 之间下刀。下一轮请求里,assistant 说有 toolCall,但对应的 tool 结果被压掉了——严格的实现直接 400,宽松的实现则让模型困惑。修法:切点必须落在 「消息边界」上,且不拆开 call/result 对。

错二:摘要里没有文件。 模型记得「我们改过某个文件」,但不记得改到哪一步。 真正的摘要是「当前任务 + 已改文件 + 未决问题」,不是聊天记录的缩写。这需要一次 模型调用(或至少一次结构化提取)。

错三:阈值是拍脑袋的。 8000 对 8k 上下文的模型是自杀,对 200k 的模型是浪费。 正确做法是「模型上下文上限 − 预留输出 − 安全余量」,动态算,而不是写死。

这三个错在 M09(Pi 的压缩实现)里都有解法。现在先记住:「能跑的压缩」和 「正确的压缩」是两件事。


六、入口:31 行

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

ts
/** * E05 的终点:一道阈值,一条摘要,四个数字。 * 运行:cd examples/mini-agent && node src/demo-compact.ts */import { compactIfNeeded, estimateTokens } from "./compact.ts";import { toLlm } from "./messages.ts";import type { AgentMessage } from "./types.ts";const long = "很长的内容".repeat(12);const history: AgentMessage[] = Array.from({ length: 10 }, (_, i) => ({  role: "user",  content: `第 ${i + 1} 条:${long}`,}));const before = estimateTokens(history);const result = compactIfNeeded(history, { threshold: 60, keep: 3 });console.log(`tokens ${before} → ${estimateTokens(result.messages)}`);console.log(`compacted ${result.compacted} dropped ${result.dropped}`);console.log(`len ${result.messages.length} first ${result.messages[0]?.role}`);if (result.messages[0]?.role === "note") {  console.log(`note: ${result.messages[0].text}`);}/* 摘要进上下文的样子:一条 note,投影成一条 user,放在最前面 */const llm = toLlm(result.messages);console.log(`投影后 ${llm.length} 条`);for (const message of llm) {  const text = typeof message.content === "string" ? message.content : "";  console.log(`  ${message.role.padEnd(9)} ${text.slice(0, 24)}`);}

threshold: 60 是故意调小的:正常 8,000 的阈值下,这个 demo 根本压不动,你看 不到任何输出。做演示时,「把闸门调到必过」比「写一堆数据」可靠。


七、代码地图

文件 关键符号 下一章怎么用
src/compact.ts estimateTokens() / compactIfNeeded() E08 的 project() 里先压后投影
src/demo-compact.ts threshold: 60 以后调参都照这个套路:小阈值 + 打印四个数
src/messages.ts toLlm() 压缩后仍然只经过它出门

顺序永远是:压缩(AgentMessage 层)→ 投影(Message 层)→ provider。反过来 先投影再压缩,你就丢了 note 这个载体。

自检

  1. 为什么条件用 || 而不是 &&?给出一个 && 会出问题的输入。
  2. dropped 和 len 加起来为什么不等于原来的条数?
  3. 如果把摘要改成 role: "user" 直接塞进历史,会发生什么?在哪一层暴露?

参考答案:

第 1 题:&& 要求「token 超了且条数够多」才压。于是「两条超长消息」永远 不压——token 早爆了,条数还没到 keep。|| 让任意一条成立就动手。

第 2 题:因为 7 条被换成了1 条。dropped 7 + len 4 = 11 = 10 + 1,多的 那一条就是摘要本身。对不上这个等式,说明你的压缩在多处塞了摘要或者丢了别的东西。

第 3 题:模型会把摘要当成用户说的话,答非所问。暴露点在两处:投影表里第一条 是 user 且内容不像用户语气;存盘后你也分不清「压出来的」和「用户真说的」——你 写的是 role: "user",kind 从这一刻就不存在了,E06 的 JSON.stringify 帮不了你。


八、与 Pi 的对照(可选)

Pi 的摘要前缀在 packages/coding-agent/src/core/messages.ts:11:

text
The conversation history before this point wascompacted into the following summary:

它也把摘要翻译成 user(:176),但前缀把「这一段是压出来的」写死进文本里。 我们的 <summary> 标签是同一个思路的轻量版。

真正的差别不在格式,而在触发条件:Pi 用模型上下文上限算预算、在消息边界上下刀、 保留最近的工作集,并且用一次模型调用生成摘要。你这一版只做了「预算 + 切割」 这两步里最粗的那一版。


九、下一章

历史压得动了,但它只在内存里。关掉终端,一切归零;想接着上次的会话,只能靠 复制粘贴。

E06 做会话:JSONL 追加写、逐行读、坏行报行号。node src/demo-session.ts 会先 跑两轮再重新加载,证明「进程无状态,记忆在文件里」。