上下文 —— 一道阈值,一条摘要,四个数字
E04 之后,工具能并发、能加锁,但历史还是每轮往上加。跑三十轮,请求体会从几 KB 涨到几百 KB,直到某个接口返回 400,而你完全不理解它为什么突然不干了。
这一章加第一版压缩。它不调用模型、不做摘要生成,只做一件事:到期就把前面的 历史换成一条 note。
三个问题:
- 「多少个 token 了」怎么估?估错了会怎样?
- 压掉的是哪几条?为什么不是「随便砍一半」?
- 压完之后,模型怎么知道前面发生过什么?
AgentMessage[] AgentMessage[] [u][a][t][a][u][a][t]... --> [note][a][u][a] | | | threshold? keep? | toLlm() v v compactIfNeeded() provider一、本章终点:先跑起来
cd examples/mini-agentnode src/demo-compact.tstokens 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
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 -->
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 现在只数条数——因为它不调用模型。这不是偷懒,是分工:先把「什么时候
压、压哪几条」跑通,再换「怎么总结」。
四、四个数字怎么读
tokens 238 → 104compacted true dropped 7len 4 first note238 → 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 -->
/** * 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 这个载体。
自检
- 为什么条件用
||而不是&&?给出一个&&会出问题的输入。 dropped和len加起来为什么不等于原来的条数?- 如果把摘要改成
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:
The conversation history before this point wascompacted into the following summary:它也把摘要翻译成 user(:176),但前缀把「这一段是压出来的」写死进文本里。
我们的 <summary> 标签是同一个思路的轻量版。
真正的差别不在格式,而在触发条件:Pi 用模型上下文上限算预算、在消息边界上下刀、 保留最近的工作集,并且用一次模型调用生成摘要。你这一版只做了「预算 + 切割」 这两步里最粗的那一版。
九、下一章
历史压得动了,但它只在内存里。关掉终端,一切归零;想接着上次的会话,只能靠 复制粘贴。
E06 做会话:JSONL 追加写、逐行读、坏行报行号。node src/demo-session.ts 会先
跑两轮再重新加载,证明「进程无状态,记忆在文件里」。