上下文压缩 —— 两道闸门,两种摘要
M08 的最后一节说:每轮都要重算系统提示词。 原因是提示词依赖的工具集、目录、技能会变。
但还有一件事 M08 没提:重算的输入 messages 本身在变长。
用户问十句,模型跑二十次工具,messages 就有三十条以上。
每条工具结果动辄几千字符,一次 read 一整个文件就是上万字。
20 万 token 的窗口,撑不了多久。
撑不住的时候只有三条路:
- 报错。把 400 甩给用户,让人自己想办法。
- 静默截断。砍掉最早几条,假装没发生过。
- 主动压缩。把旧历史改写成摘要,保留最近的原文。
Pi 走第三条,而且走得很认真:compaction.ts 1,105 行、
branch-summarization.ts 387 行、utils.ts 164 行,不到 1,700 行,
处理的是同一个问题——
当对话必须变短时,丢掉什么、记住什么、凭什么决定。
这一章拆这道题。两条线索:
- 普通压缩:同一个会话越跑越长,就地压扁。
- 分支压缩:会话在树上分叉,被放弃的那条路怎么留个念想。
两者共用摘要调用与文件清单,但四个地方全不一样: 切点算法、提示词、预算口径、摘要存放位置。 章末有一张逐项对照表。
先说读法,两分钟能省你两小时。这一章的代码密度是全书最高的一章:
10,100 字配 1,062 行代码,每千字 105 行,正好是全书均值(52)的两倍。
其中二十五处是节选——从 1,105 行的 compaction.ts 里摘几行。
所以读的时候记住三条:
- 别指望把代码块拼回原文件。 节选只保留和论证有关的那几行。
- 行号才是真坐标。形如
compaction.ts:412-470的那串数字,去仓库里定位它, 不要按代码块的先后顺序找。 - 真正的主线只有两条:在哪切(§四)和写什么(§五)。其余各节都是 这两件事的边角。
§十一 的七个实验都能照抄,其中实验 1 值得真跑:它让你亲眼看到一条
compaction entry 落在磁盘上长什么样。
零、读这章之前,你需要先知道一件事
compaction(压缩):把旧对话压成一段摘要,用它顶替原来那一长串消息, 腾出上下文。它不是删除——原始 entry 还在会话文件里,只是不再进上下文: 像盖一张纸,不是撕掉。
没有它会怎样:以为压完历史就没了,不敢压;或者反过来,以为它能"清空",
结果会话文件越压越大(M10 会看到那条 compaction entry 占多少字节)。
本书哪里用到:§二 两道闸门;§八 摘要怎么生效(CompactionEntry 的形状)。
这章怎么读:三条路线,按你现在要解决的问题选。
- 只想知道"该不该压、压完会不会丢东西"→ §一、§二,二十分钟。
- 要改压缩策略(切点、估算、模板)→ §三、§四、§五,再加 §八。
- 要查证某个数字从哪来 → 直接跳 §十一 实验与章末源码索引。
全章 79 个代码块,一半以上是"结论只有一行"的摘录,读的时候可以只扫块前的黑体句。
一、压缩不是删除
1.1 磁盘上的历史一条都不能少
先排除一个直觉方案:既然太长了,就把前面的消息删掉。
做不到。原因不在模型,在存储。
session-manager.ts 的注释写得很直白:
// session-manager.ts:1525-1531/** * Get all session entries (excludes header). Returns a shallow copy. * The session is append-only: use appendXXX() to add entries, branch() to * change the leaf pointer. Entries cannot be modified or deleted. */getEntries(): SessionEntry[] { return this.fileEntries.filter((e): e is SessionEntry => e.type !== "session");}append-only:只能追加,不能改、不能删。
这不是洁癖,是四个功能的前提:
| 功能 | 依赖 |
|---|---|
| 恢复会话 | 重放 JSONL 就能重建上下文 |
| 分叉(fork / tree) | 每个 entry 有 parentId,靠链式指针回溯 |
| 审计 / 导出 | 发生过什么,文件里必须有 |
| 崩溃恢复 | 半截写入最多丢最后一行 |
如果压缩真的删了消息,上面四个全废。 所以压缩的做法是——在末尾追加一条"墓碑",声明之前的不用看了。
1.2 一条 entry 代替一段历史
墓碑长这样(CompactionEntry):
summary:改写后的摘要正文firstKeptEntryId:从哪条开始保留原文tokensBefore:压缩前多少 tokendetails:{ readFiles, modifiedFiles }usage:生成摘要那次调用的 token 消耗systemMessage:压缩瞬间的系统提示词快照
读上下文时,buildContextEntries 按这个规则筛:
// session-manager.ts:476-512(节选,参数折行)export function buildContextEntries(entries, leafId?, byId?): SessionEntry[] { const path = buildSessionPath(entries, leafId, byId); let compaction: CompactionEntry | null = null; for (const entry of path) { if (entry.type === "compaction") compaction = entry; // 取最后一条 } if (!compaction) return path; const compactionIdx = path.findIndex((entry) => entry.id === compaction.id); if (compactionIdx < 0) return path; const contextEntries: SessionEntry[] = [compaction]; // 其余 13 行:找到 firstKeptEntryId 那一行,从它开始逐条 push, // 跳过其后的 system 消息,再接上 compaction 之后的原文(:145-158) return contextEntries;}三步,值得逐句读:
- 沿当前叶子往上走,找最后一条 compaction,它自己排在结果数组首位。
- 从路径开头扫到 compaction 之前,只保留跨过
firstKeptEntryId之后的, 且跳过 system 消息(提示词状态由systemMessage字段承担)。 - compaction 之后的所有 entry 无条件保留。
于是模型看到的是:
摘要 + 被保留的尾部原文 + 压缩之后继续发生的一切。
原始 JSONL 里那几千条消息还在,只是不再进入上下文。 换一个叶子读就是另一条分支的上下文——M10 展开。
1.3 三个必须守住的东西
墓碑方案要成立,切点就不能乱切。三条硬约束:
| 约束 | 违反的后果 | 谁来守 |
|---|---|---|
| tool call 与 tool result 必须成对 | Anthropic 等 provider 直接 400 | isCutPointMessage 不允许切在 toolResult |
| 保留区必须是"最近的" | 模型丢掉刚做的事,重复劳动 | 从后往前累加 keepRecentTokens |
| 摘要必须能"接着干" | 摘要写成一本书的导读,模型不知道下一步 | 六节结构化模板 + 禁止续写 |
第三条最容易被低估。摘要不是给人看的总结,
是给另一个即将接手同一任务的模型看的交接单,
所以提示词里写着 another LLM will use to continue the work。
二、两道闸门
什么时候压?Pi 在两个位置各设一道闸门。
2.1 第一道:请求之前
每次准备下一轮(prepareNextTurnWithContext,即 M08 里算系统提示词的那个钩子),
第一件事就是检查阈值:
// agent-session.ts:792-801(折行)private async _compactBeforeNextAssistantResponse( context: AgentContext,): Promise<AgentContext> { const projection = this.sessionManager.buildSessionProjection(); // A virtual selection is checked in prepareRequest, against the model the // request is routed to. const model = this.model; if ( !model || isVirtualModel(model) || !this._exceedsCompactionThreshold(model, projection) ) { return { ...context, messages: projection.messages }; } await this._runAutoCompaction("threshold", false); return { ...context, messages: this.sessionManager.buildSessionProjection().messages, };}三个细节:contextWindow <= 0 直接返回 false(:783-790,没声明窗口的本地模型
不压也不报错);虚拟模型跳过(窗口要等路由后才知道,改在 prepareRequest
里对着 route.model 查,:854-857);压完必须重建投影(新 compaction entry
会让旧 projection.messages 失效)。
请求前再查一次,是因为"上一轮结束"到"这一轮请求"之间还会进东西:
用户刚打的字、steering 插话、follow_up 排队、扩展注入的消息。
2.2 第二道:响应之后
另一道在模型回完之后,按 stopReason 分类处理:
// agent-session.ts:3032-3056(节选)private async _checkCompaction(assistantMessage, skipAbortedCheck = true) { const settings = this.settingsManager.getCompactionSettings(this.model); if (!settings.enabled) return false; if (skipAbortedCheck && assistantMessage.stopReason === "aborted") return false; // Skip overflow check if the message came from a different model. const messageModel = this._modelForMessage(assistantMessage); const sameModel = messageModel !== undefined; const contextWindow = (messageModel ?? this.model)?.contextWindow ?? 0; // Skip compaction checks if this assistant message is older than the latest // compaction boundary. const branch = this.sessionManager.getBranch(); const compactionEntry = getLatestCompactionEntry(branch); const assistantIsFromBeforeCompaction = compactionEntry !== null && assistantMessage.timestamp <= new Date(compactionEntry.timestamp).getTime(); if (assistantIsFromBeforeCompaction) return false; // …}四道提前返回,每一道都对应一个真实事故:
| 提前返回 | 防的是什么 |
|---|---|
!settings.enabled |
用户显式关掉自动压缩 |
stopReason === "aborted" |
用户按了 Esc,不该顺手压一次 |
messageModel === undefined |
换模型后旧模型的溢出错误会误触发 |
| 消息早于最近一次 compaction | 压缩刚结束,旧 usage 又把阈值顶爆 |
第三条:切模型后上一条消息还挂着旧模型的 contextOverflow 标记,
只看当前 this.model 会凭空压一次;_modelForMessage 找回物理模型,
对不上就跳过。
第四条同理:刚压完,保留区的 usage 记的是压缩前的大小,
拿它算阈值必然又超,于是无限压缩。
2.3 三种 reason
自动路径只有两种,加上手动一共三种:
| reason | 触发点 | 会重试原请求吗 | 失败文案 |
|---|---|---|---|
manual |
用户 /compact、RPC、扩展 |
不会 | Compaction failed: … |
threshold |
请求前 / 响应后超阈值 | 不会 | Auto-compaction failed: … |
overflow |
provider 报溢出或输出被截断 | 首轮会 | Context overflow recovery failed: … |
reason 会一路透传进事件(compaction_start / compaction_end /
session_before_compact / session_compact / session_compact_failed),
扩展据此决定显示什么、要不要插手。
2.4 溢出只赔一次
threshold 只是"快到线了,提前压",压完继续跑,没风险。
overflow 是"已经撞墙了"——除了压,还得重放刚才那轮请求。
Pi 给这个重放只留一次机会:
// agent-session.ts:3100-3127(节选)if (this._overflowRecoveryAttempted) { const errorMessage = contextOverflow ? "Context overflow recovery failed after one compact-and-retry attempt. " + "Try reducing context or switching to a larger-context model." : "Truncated response recovery failed after one compact-and-retry attempt."; this._emit({ type: "compaction_end", reason: "overflow", result: undefined, aborted: false, willRetry: false, errorMessage }); await this._emitSessionCompactFailed({ /* … */ }); return false;}// …this._overflowRecoveryAttempted = true;this._omitRecoveryAttempt(assistantMessage);const retry = await this._runAutoCompaction("overflow", willRetry);if (retry) this._failedResponse = assistantMessage;return retry;为什么只给一次?成本是双向的:每次压缩都要花一次完整模型调用
(输入可能是几十万 token);压完还溢出,说明问题不在历史长度
(可能是单条工具结果就超窗口,或 maxTokens 配错),再压也是白花钱。
_omitRecoveryAttempt 那一步容易忽略:上一次失败的 assistant 消息要
持久地排除在上下文之外,否则重放的请求里还带着那条"失败的回答"。
2.5 输出被截断也算溢出
// agent-session.ts:3089-3091const recoverableLength = sameModel && assistantIsProjected && isRecoverableLength(assistantMessage, messageModel.maxTokens);if (contextOverflow || recoverableLength) {stopReason === "length" 表面上不是溢出——模型正常结束,只是被 maxTokens 截了。
为什么归到溢出里?
因为 provider 有时会悄悄把可用上下文压小(安全余量、路由降级),
表现就是"输入没超、输出却提前停了"。所以输出低于标称 maxTokens
算可恢复的长度失败,值得压一次;正好等于上限则是 maxTokens 配小了。
2.6 手动路径
/compact 走 AgentSession.compact()(:2849-2994),
它和自动路径的差别只有三处:
// agent-session.ts:2849-2873(节选)async compact(customInstructions?: string): Promise<CompactionResult> { await this.abort(); this._compactionAbortController = new AbortController(); this._emit({ type: "compaction_start", reason: "manual" }); try { const model = this.model; if (!model) throw new Error(formatNoModelSelectedMessage()); const settings = this.settingsManager.getCompactionSettings(model); const pathEntries = this.sessionManager.getBranch(); const preparation = prepareCompaction(pathEntries, settings); if (!preparation) { const lastEntry = pathEntries[pathEntries.length - 1]; if (lastEntry?.type === "compaction") throw new Error("Already compacted"); throw new Error("Nothing to compact (session too small)"); } // …- 先
await this.abort()。手动压缩不允许在模型跑一半时插队, 否则同一份上下文会被两条路径同时改写。 - 绝不重试、绝不续跑。压完就停在那儿等用户。
- 失败要 throw。自动路径失败只发事件(后台出错不能炸前端), 手动路径失败必须抛给调用方(用户按了按钮,得知道结果)。
两条报错也很有意思:Already compacted 和 Nothing to compact (session too small)。
它们说明 prepareCompaction 返回 undefined 有两种含义,
得看路径末端 entry 的类型才能区分。
2.7 三条路汇到同一个函数
/compact ──┐RPC ───────┤扩展 ──────┴─→ AgentSession.compact() ─┐ ├→ _runDefaultCompaction()请求前超阈值 ─→ _runAutoCompaction("threshold") ─┤ │响应后溢出 ───→ _runAutoCompaction("overflow") ─┘ ▼ compact() │ ┌───────────────────────────────┘ ▼ prepareCompaction → 切点 + 分段 ▼ generateSummaryWithUsage → 摘要文本 ▼ appendCompaction → 墓碑写进 JSONL_runDefaultCompaction(:2804-2827)只有十几行,
作用是"解析出这次摘要用哪个模型、哪个 key",再调用核心 compact():
// agent-session.ts:2804-2810(参数已折行)private async _runDefaultCompaction( preparation: CompactionPreparation, model: Model<any>, customInstructions: string | undefined, signal: AbortSignal, reason: "manual" | "threshold" | "overflow",): Promise<CompactionResult> { // Resolve the request only when Pi summarizes itself: routing may call models // or fail. const request = await this._getSummarizationRequestAuth(model, signal); return compact( preparation, request.model, request.apiKey, request.headers, customInstructions, signal, request.thinkingLevel, this.agent.streamFunction, request.env, this.settingsManager.getRetrySettings(), this._summarizationRetryCallbacks({ source: "compaction", reason }), undefined, // sessionId );}注意 undefined, // sessionId。压缩请求不复用会话的 prompt cache 路由 id,
理由在下一节 cacheRetention: "none" 里。
三、token 从哪来
要判断"超没超",先得知道"现在多少"。这一步没有完美答案,只能估。
Pi 用两级策略:有真实值就用真实值,没有就按字符数估。
3.1 第一级:provider 报回来的 usage
每次 assistant 消息都带 usage,四个字段:
// compaction.ts:140-142(折行)export function calculateContextTokens(usage: Usage): number { return ( usage.totalTokens || usage.input + usage.output + usage.cacheRead + usage.cacheWrite );}totalTokens 有就直接用;没有就加四个分量
(输入、输出、缓存读、缓存写都算进上下文)。
不是所有 assistant 消息的 usage 都可信:
// compaction.ts:148-161(节选)function getAssistantUsage(msg: AgentMessage): Usage | undefined { if (msg.role === "assistant" && "usage" in msg) { const assistantMsg = msg as AssistantMessage; if ( assistantMsg.stopReason !== "aborted" && assistantMsg.stopReason !== "error" && assistantMsg.usage && calculateContextTokens(assistantMsg.usage) > 0 ) { return assistantMsg.usage; } } return undefined;}aborted 的调用中途断了,usage 只有半截;error 的调用可能根本没送到;
全零的 usage 是某些 provider 的占位符。三种全部跳过,往前找上一条有效的。
3.2 第二级:尾部增量估算
真实 usage 是"上一次请求时的快照",之后又追加了几条消息。 所以总量 = 快照 + 尾部估算:
// compaction.ts:196-224(节选,参数折行)export function estimateContextTokens( messages: AgentMessage[],): ContextUsageEstimate { const usageInfo = getLastAssistantUsageInfo(messages); if (!usageInfo) { let estimated = 0; for (const message of messages) estimated += estimateTokens(message); return { tokens: estimated, usageTokens: 0, trailingTokens: estimated, lastUsageIndex: null }; } const usageTokens = calculateContextTokens(usageInfo.usage); let trailingTokens = 0; for (let i = usageInfo.index + 1; i < messages.length; i++) { trailingTokens += estimateTokens(messages[i]); } return { tokens: usageTokens + trailingTokens, usageTokens, trailingTokens, lastUsageIndex: usageInfo.index };}返回四个字段而不是一个数字,是为了让调用方能回答"这个数有多少是猜的"。
lastUsageIndex: null 表示整个数字都是估的,可信度最低。
3.3 estimateTokens 的九个分支
估算函数本身很简单,难点在按消息类型分类:
// compaction.ts:298-349(节选,大分支已折叠)export function estimateTokens(message: AgentMessage): number { let chars = 0; switch (message.role) { case "system": { chars = estimateTextAndImageContentChars(message.content); // 其余 5 行:累加各节长度与 toolsAdded 的 JSON(:302-305) return Math.ceil(chars / 4); } case "assistant": // 10 行:text / thinking / toolCall 各自的字符数累加(:308-317) return Math.ceil(chars / 4); // … 其余七个角色见下表,bashExecution 是 command + output 长度 } return 0;}逐个角色看:
| role | 计入什么 | 备注 |
|---|---|---|
system |
content + 各节长度 + toolsAdded 的 JSON |
提示词本身也占窗口 |
user |
文本 + 图片占位 | — |
assistant |
text + thinking + toolCall 名字与参数 | 参数是 JSON 字符串 |
custom |
content | 扩展注入的消息 |
toolResult |
content | 通常最大的一块 |
bashExecution |
command + output | ! 命令的输出 |
branchSummary |
summary | 分支摘要 |
compactionSummary |
summary | 上一次压缩的摘要 |
| 其它 | 0 | 元数据类 entry |
图片按固定值算:ESTIMATED_IMAGE_CHARS = 4800(compaction.ts:276),
除以 4 就是 1,200 token。这个数字是拍出来的(各 provider 差异从几百到几千),
至少比 0 好——完全忽略图片会让估算严重偏低。
3.4 chars/4 这条经验法则的两面
源码注释写着:
// compaction.ts:294-297/** * Estimate token count for a message using chars/4 heuristic. * This is conservative (overestimates tokens). */"conservative" 对英文和代码成立:BPE 词表下 4 个字符约 1 个 token,
实际往往更少,所以 /4 是偏高估。
但对中文不成立。一个汉字通常吃 1 个 token(部分模型 1.5–2 个),
而 /4 只给它 0.25 个。中文长会话在这一步被低估到 1/4 甚至更低。
后果不是"多压一次",而是"该压的时候没压"—— 第二道闸门看估算值没超线,请求发出去,provider 直接 400。
这是估算式方案的结构性缺陷,Pi 用两道闸门对冲: 请求前用估算,撞墙后用真实错误码兜底。
3.5 什么时候 usage 作废
estimateProjectedContextTokens(:227-262)处理一个更隐蔽的情况:
// compaction.ts:244-261(节选)const usageEntryIndex = usageEntryId ? branchEntries.findIndex((entry) => entry.id === usageEntryId) : -1;let latestInvalidatingEntryIndex = -1;for (let i = branchEntries.length - 1; i >= 0; i--) { const entry = branchEntries[i]; if (entry.type === "context_edit" || entry.type === "compaction") { latestInvalidatingEntryIndex = i; break; }}if (usageEntryIndex > latestInvalidatingEntryIndex) return estimate;const currentSystem = getCurrentSystemMessage(projection.messages);let tokens = currentSystem ? estimateTokens(currentSystem) : 0;for (const message of projection.messages) { if (message.role !== "system") tokens += estimateTokens(message);}return { tokens, usageTokens: 0, trailingTokens: tokens, lastUsageIndex: null };规则是:如果 usage 所在的消息,比最近一次 context_edit 或 compaction 还早,
这条 usage 就不能信。
context_edit 会改掉某条消息的内容,compaction 整体换掉历史——
两者都让"上次请求的大小"和"这次的输入"不是同一份东西。
此时全量重估,且把系统提示词也估进去(它的 sections 独立于
messages,容易漏)。
3.6 判定:一条不等式
// compaction.ts:267-270export function shouldCompact( contextTokens: number, contextWindow: number, settings: CompactionSettings,): boolean { if (!settings.enabled) return false; return contextTokens > contextWindow - settings.reserveTokens;}默认配置(compaction.ts:126-130):
export const DEFAULT_COMPACTION_SETTINGS: CompactionSettings = { enabled: true, reserveTokens: 16384, keepRecentTokens: 20000,};代入一个 200,000 窗口的模型:
| 量 | 值 | 含义 |
|---|---|---|
contextWindow |
200,000 | 模型标称窗口 |
reserveTokens |
16,384 | 给自己留的余量(给输出、给摘要请求) |
| 触发线 | 183,616 | 超过就压 |
keepRecentTokens |
20,000 | 压完保留最近约 2 万 token 原文 |
reserveTokens 留 16,384 不是随手写的:压缩本身要发一次请求,
输入是待压缩的历史,输出是摘要。上下文已顶到窗口上限时这次请求根本发不出去,
所以必须提前 16K 动手。
配置有三层优先级(settings-manager.ts:846-872):
compaction.modelOverrides["provider/model"].reserveTokens ↓ 没有就取compaction.reserveTokens ↓ 没有就取DEFAULT_COMPACTION_TOKEN_SETTINGS第一层很实用:20 万窗口的模型配 16K 余量,1M 窗口的配 64K,互不干扰。
四、切在哪
有了"该压"的判定,下一个问题就是"压到哪"。 这是整个压缩里最精细的 30 行,四个坑。
4.1 哪些位置可以切
// compaction.ts:351-386function isCutPointMessage(message: AgentMessage): boolean { switch (message.role) { case "user": case "assistant": case "bashExecution": case "custom": case "branchSummary": case "compactionSummary": return true; case "toolResult": return false; } return false;}function isTurnStartMessage(message: AgentMessage): boolean { switch (message.role) { case "user": case "bashExecution": case "custom": case "branchSummary": case "compactionSummary": return true; case "assistant": case "toolResult": return false; } return false;}function isTurnStartEntry(entry: SessionEntry): boolean { if (entry.type === "compaction") return false; return sessionEntryToContextMessages(entry).some(isTurnStartMessage);}两张表只差一行,但含义完全不同:
- 可切点:切在这条之前,上下文仍然合法。
assistant可以切—— 它和它的 toolResult 会一起被保留。 - 轮次起点:这条消息标志着"新一轮用户意图"。
assistant不是。
toolResult 两个表都不在——它永远不能作切点,否则就出现
"有结果没调用"的孤儿消息,provider 会拒。
4.2 从后往前累加
// compaction.ts:452-479(节选)const cutPoints = findValidCutPoints(entries, startIndex, endIndex);if (cutPoints.length === 0) { return { firstKeptEntryIndex: startIndex, turnStartIndex: -1, isSplitTurn: false, };}let accumulatedTokens = 0;let cutIndex = cutPoints[0]; // Default: keep from first message (not header)for (let i = endIndex - 1; i >= startIndex; i--) { const entry = entries[i]; const messageTokens = sessionEntryToContextMessages(entry) .reduce((sum, message) => sum + estimateTokens(message), 0); if (messageTokens === 0) continue; accumulatedTokens += messageTokens; if (accumulatedTokens >= keepRecentTokens) { // Prefer the closest valid cut point at or after this entry. cutIndex = cutPoints.find((candidate) => candidate >= i) ?? cutPoints[cutPoints.length - 1]; break; }}从最新一条往前累加,攒够 keepRecentTokens 就停。
为什么是"从后往前"?因为要保住的是最近的上下文。 从头往后数 2 万 token,保住的可能是几小时前那段无关的开场白。
Default: keep from first message 那行是给"历史还不够 2 万 token"用的:
这种情况本不该压缩(prepareCompaction 会返回 undefined),
但函数本身要有个合理默认值。
4.3 兜底是最后一个,不是第一个
?? cutPoints[cutPoints.length - 1] 这半句是关键修正。
设想历史末尾是这样一个形状:
[assistant: toolCall(read)] ← 这是第 900 条[toolResult: 30000 字符] ← 这是第 901 条,本身超预算倒着累加到 901 条时,accumulatedTokens 一次就超过了 keepRecentTokens。
此时 i = 901,从 901 往后找可切点——一条也没有(toolResult 不可切),
find 返回 undefined。
若兜底成 cutPoints[0](最早的切点),就会把整段历史都保留,
等于没压缩。兜底成最后一个可切点才对:
保留区从最后一个可切点开始,也就是那条 assistant: toolCall,
它带着自己的 toolResult 一起进来,成对且完整。
代价是保留区可能远超预算。但正确性优先于预算—— 少压一点最多多花点 token,切出孤儿 toolResult 会直接报错。
4.4 顺手吞掉不可见的元数据
// compaction.ts:481-489(节选,条件折行)// Scan backwards from cutIndex to include adjacent metadata entries// that do not affect context.while (cutIndex > startIndex) { const prevEntry = entries[cutIndex - 1]; // Stop at compaction boundaries or context-visible entries. if ( prevEntry.type === "compaction" || sessionEntryToContextMessages(prevEntry).length > 0 ) { break; } cutIndex--;}切点往前挪,把"不产生任何上下文消息"的 entry 一起并进保留区。
这类 entry 是 model_change、thinking_level_change、label、custom…
为什么吞?因为它们虽不占 token,但是状态。
比如切点前一条正好是 model_change,不吞进来保留区就不知道当前用的哪个模型。
(严格说 getSessionContextSettings 是沿整条路径扫的,不依赖保留区,
但把状态一起带上更安全。)
4.5 split turn:切在轮次中间
判定只有三行:
// compaction.ts:491-500(节选,三元折行)const cutEntry = entries[cutIndex];const startsTurn = isTurnStartEntry(cutEntry);const turnStartIndex = startsTurn ? -1 : findTurnStartIndex(entries, cutIndex, startIndex);return { firstKeptEntryIndex: cutIndex, turnStartIndex, isSplitTurn: !startsTurn && turnStartIndex !== -1,};如果切点落在 assistant 上,说明这一轮还没结束就切了——
用户问的一句话在摘要里,模型的回答在保留区里。
findTurnStartIndex 从这个切点往前找,找到最近的轮次起点:
// compaction.ts:412-419(参数折行)export function findTurnStartIndex( entries: SessionEntry[], entryIndex: number, startIndex: number,): number { for (let i = entryIndex; i >= startIndex; i--) { if (isTurnStartEntry(entries[i])) return i; } return -1;}于是变成三段:
[……更早的历史……] ← 主摘要(messagesToSummarize)[用户那句话 + 部分工具] ← turnPrefix 摘要(turnPrefixMessages)[……保留区……] ← 原文不动(firstKeptEntryId 起)中间那段是"被切开的半轮"。它比保留区早,却不能塞进主摘要—— 主摘要是"很久以前发生过什么",语气是过去式; 这半轮是"紧接着正在做的事",语气是现在时。 混在一起写,模型会搞不清哪些已经做完。所以单独生成,见 §六。
4.6 生产路径用的是投影版
findCutPoint 是导出函数,但 prepareCompaction 实际调用的是另一个:
// compaction.ts:789-816(节选,参数与条件折行)function findProjectedCutPoint( entries: ProjectedSessionEntry[], startIndex: number, endIndex: number, keepRecentTokens: number,): CutPointResult { const cutPoints: number[] = []; for (let i = startIndex; i < endIndex; i++) { const entry = entries[i]; const isCut = entry.messages.some(isCutPointMessage); if (entry.sourceEntry.type !== "compaction" && isCut) cutPoints.push(i); } // … let cutIndex = cutPoints[0]; for (let i = endIndex - 1; i >= startIndex; i--) { const messageTokens = entries[i].messages .reduce((sum, message) => sum + estimateTokens(message), 0); if (messageTokens === 0) continue; accumulatedTokens += messageTokens; if (accumulatedTokens >= keepRecentTokens) { exceededBudget = true; cutIndex = cutPoints.find((candidate) => candidate >= i) ?? cutPoints[cutPoints.length - 1]; break; } }差别是它操作投影后的 entry(ProjectedSessionEntry):
每条携带着"经过 context_edit 之后真正会发给模型的 messages"。
用户可以用 context_edit 抹掉某条大消息的内容:按原始 entry 估算是几万 token,
按投影已经归零,不该影响切点。
投影版还多一段专门的逻辑,处理"溢出重试被省略"这种特殊后缀:
// compaction.ts:818-843(节选,折行)// A recovery attempt and its omission edits are context-invisible after the// last visible input.const suffix = entries.slice(cutIndex + 1, endIndex);const omittedSuffixIds = new Set( suffix.filter(isOmitted).map((e) => e.sourceEntry.id),);const hasExternalReplacement = suffix.some((entry) => entry.sourceEntry.type === "context_edit" && entry.sourceEntry.replacement !== null && !omittedSuffixIds.has(entry.sourceEntry.targetId));const isRecoveryOmissionSuffix = exceededBudget && !hasExternalReplacement && suffix.some((entry) => entry.sourceEntry.type === "message" && entry.sourceEntry.message.role === "assistant" && isOmitted(entry)) && suffix.every((entry) => entry.sourceEntry.type !== "compaction" && (!isIntrinsicallyVisible(entry) || isOmitted(entry)));if (isRecoveryOmissionSuffix) cutIndex++;一句话概括:切点后面若是一串"看不见的"省略条目(溢出重试的产物), 就把切点往前推一格,别让它们被当成保留区内容。 只在"整段后缀都是省略产物"时推,否则会把用户还没发出去的话切走。
读它的方法是先问:切点之后有哪些东西会被投影成消息? 一条都没有(全是元数据 + 省略),切点就可以往前挪。
4.7 一次切分的具体样子
假设会话有 12 条 entry,keepRecentTokens = 20000:
| idx | entry | 估算 token | 说明 |
|---|---|---|---|
| 0 | message(user) | 120 | 开场 |
| 1 | message(assistant) | 300 | |
| 2 | message(user) | 80 | |
| 3 | message(assistant, toolCall) | 200 | 调 read |
| 4 | message(toolResult) | 9,000 | 读了一个大文件 |
| 5 | message(assistant) | 400 | |
| 6 | message(user) | 60 | "改一下第 3 行" |
| 7 | message(assistant, toolCall) | 180 | 调 edit |
| 8 | message(toolResult) | 150 | |
| 9 | message(assistant) | 500 | 报告完成 |
| 10 | message(user) | 70 | "再跑测试" |
| 11 | message(assistant, toolCall) | 220 | 调 bash |
从 11 倒着加:220 → 290 → 790 → 940 → 1,120 → 1,180 → 1,580 → 10,580
→ 10,780 → 10,860 → 11,160 → 11,280(到 idx 0)。全程没超过 20,000。
于是 cutIndex 停在 cutPoints[0] = 0,等于"全部保留"。
回到 prepareCompaction:firstKeptEntryIndex = 0 时
messagesToSummarize 与 turnPrefixMessages 都是空的,两段皆空 → 返回
undefined → 不压缩。这就解释了小会话按 /compact 为何说
"Nothing to compact (session too small)"——不是坏了,是真的没东西可压。
五、写摘要
切点定了,得到两段(或三段)消息。 接下来要调模型,把它们写成摘要。
5.1 六节模板
// compaction.ts:507-538(提示词原文,按语义折行)const SUMMARIZATION_PROMPT = `The messages above are a conversation tosummarize. Create a structured context checkpoint summary that another LLMwill use to continue the work.Use this EXACT format:## Goal[What is the user trying to accomplish? …]## Constraints & Preferences- [Any constraints, preferences, or requirements mentioned by user]- [Or "(none)" if none were mentioned]## Progress### Done- [x] [Completed tasks/changes]### In Progress- [ ] [Current work]### Blocked- [Issues preventing progress, if any]## Key Decisions- **[Decision]**: [Brief rationale]## Next Steps1. [Ordered list of what should happen next]## Critical Context- [Any data, examples, or references needed to continue]Keep each section concise. Preserve exact file paths, function names,and error messages.`;六节,每一节对应接手模型的一个具体问题:
| 节 | 回答的问题 | 缺了会怎样 |
|---|---|---|
Goal |
用户到底要什么 | 模型开始自由发挥 |
Constraints & Preferences |
有哪些不许做的事 | 重新踩已经踩过的坑 |
Progress(Done / In Progress / Blocked) |
完成到哪、手上卡在哪 | 重复劳动、从零重来、继续撞墙 |
Key Decisions |
为什么这么设计 | 推翻已有决策 |
Next Steps |
下一步做什么 | 停在原地等指令 |
Critical Context |
有哪些必须带着的数据 | 找不到文件、记不住报错 |
最后那句 Preserve exact file paths, function names, and error messages
看似客套,其实是全文最重要的一行:
摘要模型天然倾向于"概括",会把 packages/ai/src/compat.ts:88 写成"某个兼容层文件"。
路径被概括掉,接手模型就得重新搜一遍。
5.2 第二次压缩是"更新"不是"重写"
如果这次要压的历史里已经有一条摘要(上一次压缩留下的), 就不该重写,而该增量更新:
// compaction.ts:540-546const UPDATE_SUMMARIZATION_INSTRUCTIONS = `Update the existing structuredsummary with new information. RULES:- PRESERVE all existing information from the previous summary- ADD new progress, decisions, and context from the new messages- UPDATE the Progress section: move items from "In Progress" to "Done"- UPDATE "Next Steps" based on what was accomplished- PRESERVE exact file paths, function names, and error messages- If something is no longer relevant, you may remove it选择逻辑只有一行(generateSummaryWithUsage,:713-717):
// compaction.ts:713-717(三元折行)let basePrompt = previousSummary ? UPDATE_SUMMARIZATION_PROMPT : SUMMARIZATION_PROMPT;if (customInstructions) { basePrompt = `${basePrompt}\n\nAdditional focus: ${customInstructions}`;}为什么必须分开?因为摘要的摘要会衰减。
每次都重写,第一轮丢 30% 细节,第二轮再丢 30%,第五轮就剩个标题。
增量更新把上一版当底本,只增改,衰减慢得多。
代价是摘要会越来越长——所以规则里留了 you may remove it 这个出口。
/compact 后面跟的话 就是 customInstructions,
会以 Additional focus: … 附在模板后面,不替换模板。
5.3 把对话拍平成文本
摘要请求不是"把历史原样发过去让模型总结"。 Pi 先把对话序列化成一整段纯文本,再包进标签:
// compaction.ts:719-729(节选)// Serialize conversation to text so model doesn't try to continue itconst llmMessages = convertToLlm(currentMessages);const conversationText = serializeConversation(llmMessages);let promptText = `<conversation>\n${conversationText}\n</conversation>\n\n`;if (previousSummary) { promptText += `<previous-summary>\n${previousSummary}\n</previous-summary>\n\n`;}promptText += basePrompt;为什么要拍平?两个原因:
- 防止模型接着聊。标准对话结构下,模型很可能把最后一条当成 "该我回了",直接续写而不是写摘要。
- 统一格式。
bashExecution、custom、compactionSummary这些自定义类型 都要先经convertToLlm变成标准Message,否则序列化函数认不出来。
系统提示词是另一层保险(utils.ts:161-163,按语义折行):
// utils.ts:161-163(提示词原文,按语义折行)export const SUMMARIZATION_SYSTEM_PROMPT = `You are a contextsummarization assistant. Your task is to read a conversation between a userand an AI assistant, then produce a structured summary following the exactformat specified.Do NOT continue the conversation. Do NOT respond to any questions in theconversation. ONLY output the structured summary.`;三重保险:模板说"EXACT format"、系统提示说"ONLY output"、 输入是拍平的文本。少一层都可能得到一篇"好的,我来总结一下……"。
5.4 序列化时丢掉什么
// utils.ts:120-155(节选,assistant 分支已折叠)const TOOL_RESULT_MAX_CHARS = 2000;export function serializeConversation(messages: Message[]): string { const parts: string[] = []; for (const msg of messages) { if (msg.role === "user") { const content = contentText(msg.content, ""); if (content) parts.push(`[User]: ${content}`); } else if (msg.role === "assistant") { // 12 行:把每个 toolCall 折成 `name(k=v, …)`,收集进 toolCalls(:132-143) if (msg.content.some((block) => block.type === "text")) { parts.push(`[Assistant]: ${contentText(msg.content)}`); } // 有 toolCall 时再 push 一段 `[Assistant tool calls]: …`(:144-146) } else if (msg.role === "toolResult") { const content = contentText(msg.content, ""); if (content) { const text = truncateForSummary(content, TOOL_RESULT_MAX_CHARS); parts.push(`[Tool result]: ${text}`); } } } return parts.join("\n\n");}两个"丢弃":
thinking 完全不输出。 源码注释(:114-118)给的理由很硬:
Providers return summaries of the real reasoning, and replayed thinking isoften not part of the model's live context: for example, a block that doesnot match its request is dropped. Including it can make the summarizationrequest larger than the context it summarizes.两句话:① 回放的 thinking 常常不在实时上下文里(不匹配就被丢弃); ② 把 thinking 塞进摘要请求,可能让摘要请求比被摘要的内容还大。 第二句是致命的——压缩为了省 token,输入反而膨胀。
toolResult 截到 2,000 字符。 截断标记长这样:
// utils.ts:100-104(折行)function truncateForSummary(text: string, maxChars: number): string { if (text.length <= maxChars) return text; const truncatedChars = text.length - maxChars; return ( text.slice(0, maxChars) + `\n\n[... ${truncatedChars} more characters truncated]` );}保留开头 500 行代码 + 一句"还有 87,000 字符被截断"。 摘要不需要完整文件内容,它需要的是"读过哪个文件、看到了什么结论"。
5.5 三道失败判定
摘要调用回来后,不是"有文本就算成功":
// compaction.ts:585-593(参数与字符串折行)export function getSummarizationFailure( response: AssistantMessage, label: string,): string | undefined { if (response.stopReason === "error") { return `${label} failed: ${response.errorMessage || "Unknown error"}`; } if (response.stopReason === "length") { return ( `${label} failed: generation hit the token cap ` + `and the summary is incomplete` ); } return undefined;}调用处还有第三道:
// compaction.ts:742-752(节选)const failure = getSummarizationFailure(response, "Summarization");if (failure) throw new Error(failure);if (response.content.some((block) => block.type === "toolCall")) { throw new Error("Summarization attempted to call a tool");}const textContent = contentText(response.content);return { text: textContent, usage: response.usage };三条都很重要,尤其是第二条:
| 判定 | 为什么不能放过 |
|---|---|
error |
没有内容,写进会话就是空摘要 |
length |
有内容但是半截——## Next Steps 可能一个字没写 |
出现 toolCall |
模型想调工具,说明它又在"干活"而不是"总结" |
length 那条注释很明确:
A length stop contains partial text and must not become a session checkpoint.
半截摘要比没摘要更危险——它看起来像完整的,模型会照着它继续。
5.6 不复用缓存,但要重试
// compaction.ts:626-637// Avoid cache writes for one-off summaries. Reuse caller-supplied routing when// available; callers without a session ID, including branch summaries, receive// a fresh routing ID.const requestOptions: SimpleStreamOptions = { ...options, cacheRetention: "none", sessionId: options.sessionId ?? uuidv7(),};const produce = async (): Promise<AssistantMessage> => streamFn ? (await streamFn(model, context, requestOptions)).result() : completeSimple(model, context, requestOptions);return retryAssistantCall(produce, retry, requestOptions.signal, callbacks);两个决定:
cacheRetention: "none"。摘要请求是一次性的,写完再也不发, 让它写缓存是纯浪费(有些 provider 缓存写入比普通输入还贵)。sessionId也从调用方传,没有就现造一个——只是路由标识,不为命中缓存。- 包在
retryAssistantCall里。注释(:611-617): 流被中途掐断(terminated、socket close)要按重试策略重试, 而不是让整个压缩因为一次网络抖动失败。确定性错误和主动 abort 则立即返回。
5.7 两个已经废弃的参数
generateSummary 和 generateSummaryWithUsage 的第三个参数叫 _reserveTokens:
// compaction.ts:644-648export async function generateSummary( currentMessages: AgentMessage[], model: Model<any>, // Unused. Kept for existing callers; summaries use the model's output limit // (#9512). _reserveTokens: number | undefined,下划线前缀 + 注释,说明它是历史遗留。
旧实现用 reserveTokens 算摘要的 maxTokens(比如
min(0.8 × reserveTokens, model.maxTokens));现在不传了,
摘要直接用模型的输出上限。
为什么改?按 reserveTokens 算出的上限经常只有 2,000–4,000,
摘要写到一半就被 length 掐断,再被 §5.5 判为失败——一次压缩白跑。
六、split turn:串行的两份摘要
6.1 为什么必须分开
为什么必须分开?回到 §4.5 的三段结构。被切开的半轮有个尴尬的时间位置:
时间轴 ──────────────────────────────────────────→[主摘要区] [turnPrefix 区] [保留区]"很久以前" "刚才这一轮的前半" "现在的原文"turnPrefix 区里的内容比保留区还早,但比主摘要区晚。
如果并进主摘要:
- 叙述视角会乱——前面讲"上周做了什么",突然接"刚才我在改第 3 行"。
- 下次再压缩时,这段会被当成"历史"重新概括,正在进行的任务就变成了过去式。
并进保留区:又违背了"按 token 预算切"的原则——它可能很大,塞进去就超了。 所以单独一份,用专门的提示词。
6.2 三节模板
// compaction.ts:929-942const TURN_PREFIX_SUMMARIZATION_PROMPT = `The messages above are earliercontext from an ongoing conversation. Later messages are stored separately anddo not need to be reconstructed.Create a concise checkpoint of the user's request and the progress shown above.This checkpoint will be placed before the later messages so the conversationcan continue with the necessary context.## Original Request[What did the user ask for?]## Progress So Far- [Key decisions and work completed in these messages]## Context Needed to Continue- [Information from these messages needed to understand the later work]Only summarize information explicitly present above. Do not infer or recreatelater messages.`;三节,比主摘要少一半。少了 Goal(有 Original Request)、
Constraints、Key Decisions、Critical Context。
因为读者马上就要拿到后半段的原文,不需要提前知道最终目标。
最后一句是防幻觉的关键:
Only summarize information explicitly present above.Do not infer or recreate later messages.模型拿到的只有前半轮,它天然想"补全"后面发生了什么。 这句话把它按回去:只写你看见的。
6.3 串行,不是并行
这里要纠正一个很自然的猜测:两份摘要是不是 Promise.all 并行跑?
不是。
// compaction.ts:980-1019(节选)if (isSplitTurn && turnPrefixMessages.length > 0) { let historyText = previousSummary ?? "No prior history."; let historyUsage: Usage | undefined; if (messagesToSummarize.length > 0) { const historyResult = await generateSummaryWithUsage( messagesToSummarize, model, undefined, apiKey, headers, signal, customInstructions, previousSummary, thinkingLevel, streamFn, env, retry, callbacks, sessionId, ); historyText = historyResult.text; historyUsage = historyResult.usage; } const turnPrefixResult = await generateTurnPrefixSummary( turnPrefixMessages, model, apiKey, headers, env, signal, thinkingLevel, streamFn, retry, callbacks, sessionId, customInstructions, ); // Merge into single summary summary = `${historyText}\n\n---\n\n**Turn Context (split turn):**\n\n` + turnPrefixResult.text; summaryUsage = historyUsage ? combineUsage(historyUsage, turnPrefixResult.usage) : turnPrefixResult.usage;}两个 await 一前一后。
为什么不做并行?三个现实原因:
messagesToSummarize可能是空的(直接拿previousSummary), 这时只有一份请求,并行结构反而更绕。- 限流。压缩本身高频,同时发两份会翻倍触发 RPM 限制,还把重试搞复杂。
- 顺序即语义。先"历史讲完了",再"接着这一轮",串行写在代码里, 读的人也顺着这个顺序理解。
代价是慢一倍。但压缩发生在"对话已经很长"的时刻,用户本来就要等, 多等 3 秒比多一次 429 划算。
6.4 合并格式
${historyText}---**Turn Context (split turn):**${turnPrefixResult.text}--- 分割 + 一个粗体小标题。这个格式是给下游模型看的:
它一眼就知道"上面是背景,下面是刚才那一轮"。
usage 也合并(combineUsage),这个数字要写进 compaction_end 事件和
details,是计费依据。
6.5 空历史也要占位
注意 let historyText = previousSummary ?? "No prior history.";
——若 messagesToSummarize 为空且没有上一版摘要,主摘要位置就写这个占位。
否则合并后开头是 \n\n---,模型可能把它当成"上面被截断了",
然后开始道歉或补全。一个 16 字符的占位,省掉一次幻觉。
七、文件清单:摘要里最不该丢的东西
7.1 三个集合
摘要是有损压缩。写得再好也会丢细节, 但有一类丢了会直接导致返工:动过哪些文件。 所以 Pi 单独抽一层,边扫描边记账:
// utils.ts:12-24export interface FileOperations { read: Set<string>; written: Set<string>; edited: Set<string>;}export function createFileOps(): FileOperations { return { read: new Set(), written: new Set(), edited: new Set() };}三个 Set,天然去重。同一文件读十次只记一次。
7.2 只认三个工具,只认 args.path
// utils.ts:47-61function addFileOp(toolName: string, args: Record<string, unknown> | undefined, fileOps: FileOperations): void { const path = typeof args?.path === "string" ? args.path : undefined; if (!path) return; switch (toolName) { case "read": fileOps.read.add(path); break; case "write": fileOps.written.add(path); break; case "edit": fileOps.edited.add(path); break; }}三个刻意的窄口:
- 只认
read/write/edit。bash cat file不算读—— 命令里可能干十几件事,没法可靠解析。 - 只认
args.path。grep的path是目录;只匹配字段名不看工具, 会把目录记成文件。 - 没有 path 就默默跳过。不抛错,不猜测。
7.3 codemode 的嵌套调用也要算
// utils.ts:30-45(节选,参数与调用拆行)export function extractFileOpsFromMessage( message: AgentMessage, fileOps: FileOperations,): void { if (message.role === "toolResult") { // Calls made from codemode scripts are recorded on the script's result. for (const call of message.nestedCalls?.calls ?? []) { addFileOp(call.name, call.arguments, fileOps); } return; } if (message.role !== "assistant") return; if (!("content" in message) || !Array.isArray(message.content)) return; for (const block of message.content) { if (typeof block !== "object" || block === null) continue; if (!("type" in block) || block.type !== "toolCall") continue; if (!("arguments" in block) || !("name" in block)) continue; const args = block.arguments as Record<string, unknown> | undefined; addFileOp(block.name, args, fileOps); }}nestedCalls 是 codemode 的产物(M13 展开):
模型写的脚本里调了 edit(),真正执行发生在脚本内部,
assistant 消息里只有一次 run_script 调用。
不看 nestedCalls,脚本改过的文件一个都记不上。
7.4 readFiles 是「只读未改」
// utils.ts:67-72export function computeFileLists(fileOps: FileOperations): { readFiles: string[]; modifiedFiles: string[];} { const modified = new Set([...fileOps.edited, ...fileOps.written]); const readOnly = [...fileOps.read].filter((f) => !modified.has(f)).sort(); const modifiedFiles = [...modified].sort(); return { readFiles: readOnly, modifiedFiles };}关键在 filter((f) => !modified.has(f)):
| 操作序列 | read 集合 |
modified 集合 |
最终 readFiles |
|---|---|---|---|
| 只读 a.ts | {a.ts} | {} | [a.ts] |
| 读 b.ts,再改 b.ts | {b.ts} | {b.ts} | [] |
| 读 c.ts,写 c.ts,再读 c.ts | {c.ts} | {c.ts} | [] |
一个文件既读过又改过,只出现在 modifiedFiles 里,不会两边都写。
对下游模型来说,"读过"的价值是"我知道它的内容",
"改过"的价值是"我要为它负责"——后者覆盖前者。
两个列表都 .sort()。不是为了好看,是为了缓存稳定:
同一批文件无论处理顺序如何,摘要末尾的 XML 一模一样。
7.5 挂成 XML
// utils.ts:77-87(参数与调用折行)export function formatFileOperations( readFiles: string[], modifiedFiles: string[],): string { const sections: string[] = []; if (readFiles.length > 0) { sections.push(`<read-files>\n${readFiles.join("\n")}\n</read-files>`); } if (modifiedFiles.length > 0) { sections.push( `<modified-files>\n${modifiedFiles.join("\n")}\n</modified-files>`, ); } if (sections.length === 0) return ""; return `\n\n${sections.join("\n\n")}`;}摘要正文后面接两个 XML 块,形如:
## Critical Context- 目标是让摘要稳定保留完整的文件清单,不靠模型复述<read-files>packages/coding-agent/src/core/compaction/compaction.ts</read-files><modified-files>packages/coding-agent/src/core/compaction/utils.ts为什么用 XML 而不是 Markdown 列表? 因为列表会被摘要模型改写(它会"顺手整理一下"),XML 标签是结构, 模型倾向于原样保留。而且这两个块是代码拼上去的,不经过模型—— 模型只负责写前面六节。
这条设计很值得记:凡是不能丢的信息,就不要交给模型去复述。
八、摘要怎么生效
写完摘要是上半场。让它在下一次请求里真的出现,是下半场。
8.1 落盘
// session-manager.ts:1280-1296(节选,systemMessage 拆行)const systemMessage = getCurrentSystemMessage( this.buildSessionProjection().messages,);const systemState = systemMessage ? { ...systemMessage, timestamp: new Date(timestamp).getTime() } : undefined;const id = generateId(this.byId);const entry: CompactionEntry<T> = { type: "compaction", id, parentId: this.leafId, timestamp, summary, firstKeptEntryId: firstKeptEntryId ?? id, tokensBefore, details, usage, fromHook, ...(systemState ? { systemMessage: systemState } : {}),};this._appendEntry(entry);逐字段看:
| 字段 | 来源 | 作用 |
|---|---|---|
parentId |
当前叶子 | 挂在分支末端,压缩本身也是一次操作 |
summary |
模型生成的六节正文 + 文件 XML | 模型看到的东西 |
firstKeptEntryId |
切点算出来的 | 保留区从哪开始 |
tokensBefore |
estimateProjectedContextTokens |
统计与展示 |
details |
{ readFiles, modifiedFiles } |
结构化文件清单 |
usage |
摘要调用的 usage | 计费 |
fromHook |
扩展是否接管 | 区分来源 |
systemMessage |
压缩瞬间的系统提示词快照 | 提示词状态 |
systemMessage 那一行容易忽略。它把当时的八节提示词整份存进 entry——
因为 buildContextEntries 会跳过压缩前的全部 system 消息(§1.2 第 2 步),
不存快照,模型就再也看不到自己的工具列表和规则了。
firstKeptEntryId ?? id 的兜底同样有意思:算不出保留起点时,
就让保留区从这条 compaction 自己开始,等价于"全部压掉,只留摘要"。
8.2 投影时变成两条消息
sessionEntryToContextMessages 处理 compaction entry:
// session-manager.ts:461-464if (entry.type === "compaction") { const summary = createCompactionSummaryMessage( entry.summary, entry.tokensBefore, entry.timestamp, ); return entry.systemMessage ? [entry.systemMessage, summary] : [summary];}一条 entry 投影成两条消息:system + compactionSummary,顺序固定。
8.3 最后一步:变成 user 消息
compactionSummary 不是标准角色。发请求前 convertToLlm 再转一次:
// messages.ts:11-17export const COMPACTION_SUMMARY_PREFIX = `The conversation history before thispoint was compacted into the following summary:<summary>`;export const COMPACTION_SUMMARY_SUFFIX = `</summary>`;// messages.ts:176-183case "compactionSummary": return { role: "user", content: [ { type: "text" as const, text: COMPACTION_SUMMARY_PREFIX + m.summary + COMPACTION_SUMMARY_SUFFIX }, ], timestamp: m.timestamp, };摘要最终是一条 user 消息。
这个决定有讲究。放在 system 里会和真正的系统提示词打架
(一个请求只能有一段 system,M08 讲过);放 assistant 里更糟——
模型会以为自己说过这些话,进而认为"我已经知道结论了",跳过验证直接汇报。
包成 user 消息读起来像是"用户把之前的记录整理给你看", 模型会把它当输入而不是自己的记忆。
8.4 一次压缩的事件序列
_runAutoCompaction(reason, willRetry) ├─ prepareCompaction(branch, settings) ← 算切点,可能返回 undefined ├─ emit compaction_start { reason } ├─ session_before_compact 钩子 │ ├─ { cancel: true } → throw "Compaction cancelled" │ └─ { compaction: … } → 跳过默认摘要生成 ├─ compact(preparation, …) │ ├─ generateSummaryWithUsage(history) ← 串行 │ ├─ generateTurnPrefixSummary(prefix) ← 串行(split turn 时) │ └─ computeFileLists + formatFileOperations ├─ appendCompaction(summary, firstKeptEntryId, …) ├─ _refreshFinalizedContext() ← 把新投影写回 agent.state ├─ estimateMessagesTokens(projection.messages) → estimatedTokensAfter ├─ session_compact 钩子 └─ emit compaction_end { reason, result, willRetry }返回值决定上层怎么走:
// agent-session.ts:3288-3292if (willRetry) return true;// Auto-compaction can complete while follow-up/steering/custom messages are// waiting.// Continue once so queued messages are delivered.return this.agent.hasQueuedMessages();true 表示"再跑一轮"。两种来源:溢出恢复要重放刚才失败的那轮,
或者压缩期间用户又排了消息。
8.5 压缩完还是超怎么办
没有任何机制保证"压完一定不超"。可能的结果有三种:
| 情况 | 表现 | 下一步 |
|---|---|---|
| 正常 | estimatedTokensAfter 明显下降 |
继续对话 |
| 压了但还超 | 下一轮请求前闸门又触发 | 再压一次(此时走 UPDATE 模板) |
| 压了还是溢出 | provider 再次 400 | _overflowRecoveryAttempted 已置位 → 报错 |
第二种是常态。keepRecentTokens = 20000 意味着压完至少剩 2 万,
如果窗口只有 3.2 万(reserveTokens 16,384),压完立刻又超。
该做的是调小 keepRecentTokens,见 §十一 实验 3。
九、分支摘要:另一条完全不同的路
9.1 场景
用户在 /tree 里退回到三小时前,选了一条岔路。
原来那条路上的二十次工具调用、四次失败尝试、最终找到的那个 bug——
全在废弃分支上。但那个 bug 的结论对现在有用。
所以 Pi 问一句"要不要总结这条被放弃的路",
答案是 navigateTree(targetId, { summarize: true })。
两者分工一句话讲清:普通压缩解决"往前跑的路上,路太长";
分支压缩解决"往回走的时候,走过的路要不要带走"。
9.2 先找公共祖先
// branch-summarization.ts:120-147(节选)// Find common ancestor (deepest node that's on both paths)const oldPath = new Set(session.getBranch(oldLeafId).map((e) => e.id));const targetPath = session.getBranch(targetId);// targetPath is root-first, so iterate backwards to find deepest common ancestorlet commonAncestorId: string | null = null;for (let i = targetPath.length - 1; i >= 0; i--) { if (oldPath.has(targetPath[i].id)) { commonAncestorId = targetPath[i].id; break; }}// Collect entries from old leaf back to common ancestorconst entries: SessionEntry[] = [];let current: string | null = oldLeafId;while (current && current !== commonAncestorId) { const entry = session.getEntry(current); if (!entry) break; entries.push(entry); current = entry.parentId;}entries.reverse(); // 转成时间顺序三步:旧路径集合 → 沿目标路径从后往前找第一个交点(最深的公共祖先)
→ 从旧叶子沿 parentId 回溯到交点,再反转成时间序。
O(路径长度),不递归,不建新结构。
有个细节:回溯循环不跳过 compaction。被放弃的分支里如果有一次压缩,
那条 entry 也会被收集,转成 compactionSummary 消息参与摘要。
注释的理由是 those are included and their summaries become context——
跳过它,废弃分支里"压缩之前发生过什么"就永远丢了。
9.3 塞不进预算时,摘要优先
// branch-summarization.ts:220-246// Second pass: walk from newest to oldest, adding messages until token budgetfor (let i = entries.length - 1; i >= 0; i--) { const entry = entries[i]; const message = getMessageFromEntry(entry); if (!message) continue; // Extract file ops from assistant messages (tool calls) extractFileOpsFromMessage(message, fileOps); const tokens = estimateTokens(message); // Check budget before adding if (tokenBudget > 0 && totalTokens + tokens > tokenBudget) { // If this is a summary entry, try to fit it anyway as it's important // context if (entry.type === "compaction" || entry.type === "branch_summary") { if (totalTokens < tokenBudget * 0.9) { messages.unshift(message); totalTokens += tokens; } } break; } messages.unshift(message); totalTokens += tokens;}两遍扫描、各管一件事:第一遍(:205-218)扫全部 entry 收文件操作,
不管塞不塞得进预算(嵌套的 branch_summary 也带清单,只认
!entry.fromHook 的);第二遍从新到旧 unshift 到超预算为止。
保底的三层条件:① 超预算本应 break;② 这条是 compaction 或
branch_summary,信息密度最高;③ 已塞的量不到预算 90%。三者同时成立就硬塞。
0.9 是折中:留 10% 余量,避免一条巨型摘要把预算吃光。
注意这里没有 continue,塞完还是 break——再往前的只会更老。
9.4 跳过工具结果
// branch-summarization.ts:158-166(节选)function getMessageFromEntry(entry: SessionEntry): AgentMessage | undefined { switch (entry.type) { case "message": // Skip tool results - context is in assistant's tool call if (entry.message.role === "toolResult") return undefined; return entry.message;和普通压缩相反:普通压缩保留 toolResult(只截断到 2,000 字符),
分支摘要一条都不要。理由在注释里:context is in assistant's tool call——
分支摘要要回答"那条路上试过什么、结论是什么",
工具输出的原文在这里没有价值。副作用是它们也不计入预算,
同一个预算能塞进更多轮次的对话。
9.5 预算是输入预算,不是输出上限
这是最容易读错的一处:
// branch-summarization.ts:314-318// Token budget = context window minus reserved space for prompt + responseconst contextWindow = model.contextWindow || 128000;const tokenBudget = contextWindow - reserveTokens;const { messages, fileOps } = prepareBranchEntries(entries, tokenBudget);tokenBudget 是能塞进摘要请求的输入量,不是"摘要可以写多长"——
后者用模型自己的输出上限。
reserveTokens 默认 16,384(generateBranchSummary 的默认参数)。
model.contextWindow || 128000 的兜底是给"模型没声明窗口"用的:
普通压缩遇到这种模型直接跳过,分支摘要则假设一个 128K 的保守值。
两个模块不一致不是疏忽:普通压缩是自动触发的,猜错会打断用户;
分支摘要是用户点出来的,猜一个保守值比报错好。
9.6 五节模板
// branch-summarization.ts:260-287(节选,开头与结尾)const BRANCH_SUMMARY_PROMPT = `Create a structured summary of this conversationbranch for context when returning later.Use this EXACT format:## Goal[What was the user trying to accomplish in this branch?]## Constraints & Preferences…## Progress### Done / In Progress / Blocked…## Key Decisions- **[Decision]**: [Brief rationale]## Next Steps1. [What should happen next to continue this work]Keep each section concise. Preserve exact file paths, function names, and errormessages.`;和六节模板的差别只有一处:没有 Critical Context。
因为分支摘要是附加的,不是替代:导航回去之后,目标位置的原文全在
(branchWithSummary 只是换叶子),"继续干活要的数据"不在摘要里也有地方找。
而普通压缩是替换——被压掉的部分除了摘要再无痕迹,
所以必须有 Critical Context 兜住"文件路径、报错原文、关键数字"。
9.7 给摘要加一句"你去过别处"
// branch-summarization.ts:255-258const BRANCH_SUMMARY_PREAMBLE = `The user explored a different conversationbranch before returning here.Summary of that exploration:`;// branch-summarization.ts:371-378let summary = contentText(response.content);// Prepend preamble to provide context about the branch summarysummary = BRANCH_SUMMARY_PREAMBLE + summary;// Compute file lists and append to summaryconst { readFiles, modifiedFiles } = computeFileLists(fileOps);summary += formatFileOperations(readFiles, modifiedFiles);前缀回答了一个模型必然会问的问题:这段东西从哪来的?
没有它,模型会把一段结构化的 ## Goal / ## Progress 当成当前对话的早期摘要,
把里面的"待办"当成自己的待办。有它,模型知道这是支线探索的记录。
9.8 失败不抛,返回对象
// branch-summarization.ts:359-369// Check if aborted or erroredif (response.stopReason === "aborted") { return { aborted: true };}const failure = getSummarizationFailure(response, "Branch summarization");if (failure) { return { error: failure };}if (response.content.some((block) => block.type === "toolCall")) { return { error: "Branch summarization attempted to call a tool" };}对比普通压缩的 throw new Error(failure),这里返回 { aborted } / { error }。
差别在调用方的容错策略(agent-session.ts:4151-4156):
if (result.aborted) return { cancelled: true, aborted: true };if (result.error) throw new Error(result.error);abort 是正常路径——用户按 Esc 放弃总结,导航照旧。 error 是失败路径——总结失败就别跳了,抛给上层。 用返回对象而不是异常,就是为了让调用方能区分这两者。
9.9 摘要挂在目标位置
// agent-session.ts:4186-4198(节选)// Switch leaf (with or without summary)// Summary is attached at the navigation target position (newLeafId), not the// old branchlet summaryEntry: BranchSummaryEntry | undefined;if (summaryText) { // Create summary at target position (can be null for root) const summaryId = this.sessionManager.branchWithSummary( newLeafId, summaryText, summaryDetails, fromExtension, summaryUsage, ); summaryEntry = this.sessionManager.getEntry(summaryId) as BranchSummaryEntry;这是最反直觉的一步。直觉方案是挂在旧叶子下面, 但那样挂它就不在当前路径上了——沿新叶子往上走根本不经过它。
正确做法是挂在新位置。于是新路径变成:
root → … → 公共祖先 → [branch_summary] → 目标节点 → 新的对话…注意摘要挂的是目标位置,而 newLeafId 可能不是 targetId:
// agent-session.ts:4173-4184(节选)if (targetEntry.type === "message" && targetEntry.message.role === "user") { // User message: leaf = parent (null if root), text goes to editor newLeafId = targetEntry.parentId; editorText = contentText(targetEntry.message.content, "");} else if (targetEntry.type === "custom_message") { newLeafId = targetEntry.parentId; editorText = contentText(targetEntry.content, "");} else { // Non-user message: leaf = selected node newLeafId = targetId;}退回到一条用户消息时,叶子上移到它的父节点, 那条消息的文本回填到输入框——用户可以改一改再发。 这时候摘要挂在父节点上,正好在"改完要发的那句话"之前。
9.10 两个钩子各管一边
| 钩子 | 时机 | 能做什么 |
|---|---|---|
session_before_compact |
压缩前 | cancel / 直接给 compaction 结果 |
session_before_tree |
导航前 | cancel / 给 summary / 改 customInstructions / 改 label |
session_before_tree 的 preparation 里带着 entriesToSummarize——
扩展可以自己看一眼要总结什么,再决定插手还是放行:
// agent-session.ts:4106-4132(节选)if (this._extensionRunner.hasHandlers("session_before_tree")) { const result = (await this._extensionRunner.emit({ type: "session_before_tree", preparation, signal: this._branchSummaryAbortController.signal, })) as SessionBeforeTreeResult | undefined; if (result?.cancel) return { cancelled: true }; if (result?.summary && options.summarize) { extensionSummary = result.summary; fromExtension = true; } if (result?.customInstructions !== undefined) { customInstructions = result.customInstructions; } if (result?.replaceInstructions !== undefined) { replaceInstructions = result.replaceInstructions; } if (result?.label !== undefined) label = result.label;}replaceInstructions 是个精细开关:默认 customInstructions 是附加在模板后的
Additional focus: …;打开它就是整个替换模板,让扩展用自己的提示词。
9.11 差异表
本章验收项。两套机制长得像,逐项对一遍才知道哪些能复用、哪些不能。
| 维度 | 普通压缩 | 分支压缩 |
|---|---|---|
| 触发 | 阈值 / 溢出 / /compact |
/tree 导航时勾选总结 |
| 入口 | compact() 或 _runAutoCompaction() |
navigateTree() |
| 选材范围 | 当前分支,按预算从后往前切 | 旧叶到公共祖先之间,全部 |
| 切点算法 | findProjectedCutPoint(六种可切) |
无切点,新→旧塞满即止 |
| 预算口径 | keepRecentTokens:保留多少 |
window − reserve:能塞多少 |
| 超预算时 | 优先保证 toolResult 成对 | 摘要类 entry 在 90% 内强行塞入 |
| toolResult | 计入估算,截 2,000 字符进摘要 | 完全跳过 |
| 摘要模板 | 六节(含 Critical Context) |
五节(无 Critical Context) |
| 增量更新 | 有上一版时用 UPDATE 模板 | 无,每次独立生成 |
| 文案前缀 | The conversation history before this point… |
The user explored a different branch… |
| 失败处理 | 手动 throw / 自动发事件 | 返回 { aborted } / { error } |
| 落盘 entry | compaction + firstKeptEntryId |
branch_summary + fromId |
| 挂在哪 | 当前叶子末端 | 导航目标位置 |
| 对上下文的作用 | 替换旧历史 | 追加一段支线记录 |
| 钩子 | session_before_compact / session_compact |
session_before_tree / session_tree |
| 可取消 | 是(cancel) |
是(cancel) |
最该记住的两行:
- 预算口径相反。一个是"保留多少",一个是"能塞多少"。
两个
tokenBudget混用,会得出完全错误的结论。 - 摘要挂载位置反直觉。普通压缩挂在历史末端,分支摘要挂在导航目标。 想清楚"哪条路径会被读",就不会挂错。
十、完整链路
┌──────────── 普通压缩 ────────────┐用户 /compact ───────┤ │请求前超阈值 ────────┤→ prepareCompaction │响应后溢出/截断 ─────┤ ├ findProjectedCutPoint │ │ │ ├ 可切点(无 toolResult)│ │ │ ├ 倒着累加 ≥ keepRecent │ │ │ └ 兜底取最后一个可切点 │ │ ├ historyEnd = 切点 或 轮次头 │ │ └ 切出 history + turnPrefix │ │ ▼ │ │ compact() │ │ ├ generateSummaryWithUsage │ │ │ ├ serialize 丢 thinking │ │ │ ├ toolResult 截 2000 │ │ │ └ 六节 / UPDATE 模板 │ │ ├ generateTurnPrefixSummary │ │ │ └ 三节模板(split turn) │ │ └ formatFileOperations 外挂 │ │ ▼ │ │ appendCompaction(compaction) │ │ ▼ │ │ buildContextEntries │ │ ├ compaction 打头 │ │ ├ firstKeptEntryId 起保留 │ │ └ 跳过旧 system 消息 │ │ ▼ │ │ convertToLlm → role:"user" │ │ + "<summary>…</summary>" │ └──────────────────────────────────┘ ┌──────────── 分支压缩 ────────────┐/tree 导航 ──────────┤→ collectEntriesForBranchSummary │ │ ├ 旧路径集合 oldPath │ │ ├ 目标路径倒查最深公共祖先 │ │ └ 旧叶 → LCA 回溯,再 reverse │ │ ▼ │ │ session_before_tree 钩子 │ │ ▼ │ │ generateBranchSummary │ │ ├ tokenBudget = window-reserve│ │ ├ 新→旧 unshift,跳过 tool │ │ ├ 摘要类 90% 内保底 │ │ └ 五节模板 + 支线前言 │ │ ▼ │ │ branchWithSummary(newLeafId) │ │ └ 挂在导航目标,不是旧分支 │ └──────────────────────────────────┘两条路的汇合点只有一个:completeSummarization。
再往下就是普通的 streamSimple 调用,和 M04 讲的一样。
十一、自己动手验证
环境:v1.4.0 / node v24.12.0 / Windows 24H2。每条判据都是这一版实跑的输出。
七个实验,从"看数据"到"改配置"再到"写脚本",需要本地跑过 pi 并留下会话文件。
实验 1:找到会话文件,抓住一条 compaction
会话文件按 cwd 编码存放(session-manager.ts:589-594):
# Linux / macOSls ~/.pi/agent/sessions/# 形如 --home-you-code-myapp--grep -l '"type":"compaction"' ~/.pi/agent/sessions/*/*.jsonl# Windows PowerShelldir $env:USERPROFILE\.pi\agent\sessionsSelect-String -Path "$env:USERPROFILE\.pi\agent\sessions\*\*.jsonl" ` -Pattern '"type":"compaction"' -List目录名规则是:去掉开头斜杠,把 / \ : 全换成 -,两侧加 --。
所以 Windows 上的 D:\code\demo 变成 --D--code-demo--。
找到后用一条命令看字段:
node -e "const fs=require('fs');const f=process.argv[1];const e=fs.readFileSync(f,'utf8').split('\n').filter(Boolean) .map(JSON.parse).find(x=>x.type==='compaction');console.log({tokensBefore:e.tokensBefore,firstKept:e.firstKeptEntryId, keys:Object.keys(e.details||{}),usage:e.usage&&e.usage.input});" FILE# 多行 node 脚本在 PS 里转义最难:存成文件再跑@'const fs=require("fs");const f=process.argv[2];const e=fs.readFileSync(f,"utf8").split("\n").filter(Boolean) .map(JSON.parse).find(x=>x.type==="compaction");console.log({tokensBefore:e.tokensBefore,firstKept:e.firstKeptEntryId, keys:Object.keys(e.details||{}),usage:e.usage&&e.usage.input});'@ | Set-Content peek.cjs -Encoding utf8node peek.cjs FILE判据:tokensBefore 是几万级的数;details.keys 只有
readFiles / modifiedFiles;usage.input 是摘要请求的输入量。
实验 2:自定义指令能进摘要
在 TUI 里跑 /compact 一定要保留所有被修改的文件路径和报错原文
(interactive-mode.ts:3370-3374 解析这句话并以 customInstructions 传入)。
判据:新 compaction 的 summary 末尾 <modified-files> 块完整,
且正文里出现了你要求的细节。
如果此时会话很小,会直接报 Nothing to compact (session too small)——
这不是 bug,见 §4.7。
实验 3:把保留区调小
编辑 ~/.pi/agent/settings.json:
{ "compaction": { "enabled": true, "reserveTokens": 16384, "keepRecentTokens": 1000 }}再跑一次 /compact,然后对比两次 compaction 的
firstKeptEntryId 指向的 entry 位置。
判据:keepRecentTokens 从 20,000 降到 1,000 后,
保留区条目数明显减少,tokensBefore 不变,但下次请求输入量下降更多。
副作用也能观察到:保留太少,模型会忘掉刚做的事,开始重复读文件。
所以真正的结论是——keepRecentTokens 不是越小越好。
实验 4:给单个模型单独设余量
{ "compaction": { "reserveTokens": 16384, "modelOverrides": { "anthropic/claude-sonnet-4-5": { "reserveTokens": 32768 } } }}键名格式是 provider/modelId(settings-manager.ts:858)。
判据:只改了那一个模型的触发线。其它模型开会话压缩时机不变; 用这个模型压缩更早发生(阈值 = 窗口 − 32,768)。
实验 5:用 SDK 手动压一次
// compact-probe.mjsimport { createAgentSession, SessionManager,} from "@earendil-works/pi-coding-agent";const sessionManager = SessionManager.open(process.argv[2]);const { session } = await createAgentSession({ cwd: process.cwd(), sessionManager,});console.log("messages before:", session.messages.length);const result = await session.compact("保留所有文件路径");console.log({ tokensBefore: result.tokensBefore, tokensAfter: result.estimatedTokensAfter, firstKept: result.firstKeptEntryId, readFiles: result.details?.readFiles?.length, modifiedFiles: result.details?.modifiedFiles?.length, summaryChars: result.summary.length,});判据:tokensAfter 显著小于 tokensBefore(通常降到 1/3 以下);
summaryChars 在 2,000–8,000 之间;details.readFiles 与 modifiedFiles 无交集。
实验 6:分支摘要挂在哪
// branch-probe.mjsconst target = session.messages.at(-5); // 随便挑一条历史消息的 entry idconst entries = sessionManager.getEntries();const targetId = entries.at(3).id;await session.navigateTree(targetId, { summarize: true, label: "实验" });console.log("leaf now:", sessionManager.getLeafId());console.log(entries.map((e) => e.type).join(" → "));判据:新增 entry 的类型是 branch_summary,它的 parentId 等于导航目标位置
(newLeafId),不是你原来所在的旧叶子。打印 getBranch() 看,
摘要应该出现在新路径上、旧路径上找不到。
实验 7(破坏性):只留溢出闸门,把预警关掉
- 改哪里
settings.json里把reserveTokens压到 1,触发线就被推到 窗口边缘(阈值 = 窗口 −reserveTokens,见shouldCompact):
{ "compaction": { "enabled": true, "reserveTokens": 1, "keepRecentTokens": 20000 }}再把 core/agent-session.ts:796-799 那段里的
await this._runAutoCompaction("threshold", false); 临时注释掉——
这就是第一道闸门的全部。
- 预期 请求前不再预警压缩,上下文一直涨到 provider 报溢出(400)才走
"overflow"路径。用户感受是一句"跑到一半突然卡住,然后上下文剧变"。 与阈值路径的区别在 §二 那张表里:threshold压失败不丢消息,overflow是"这一轮请求先丢了,压完重发"。 - 连带
overflow路径不允许"先续后压"(没有 turn 可续), 所以这一轮的stopReason会变成error;恢复靠下一轮重新发问。 若模型侧不报 400 而是静默截断(部分兼容层),你会得到一个不自知的超长会话, 这比报错更难排查。 - 回滚
reserveTokens改回16384,恢复agent-session.ts:799那次调用。 - 未实跑的原因 要看到溢出得先烧掉一个真实窗口(约 20 万 token),
这里只给路径不给数字。判据改成可观察的形式:触发
reason从threshold变成overflow,那个字段在会话文件的 compaction entry 里能直接读(实验 1)。
十二、工程暗坑
这些坑的共同点:代码不报错,行为悄悄错。
12.1 chars/4 对中文严重低估
§3.4 讲过。后果是"该压没压",撞到 provider 400 才补救。
中文为主的 agent 应把系数改成 /2 或按 tokenizer 实测。
12.2 图片固定 1,200 token
ESTIMATED_IMAGE_CHARS = 4800 除以 4。一张 4K 截图和图标算出来一样。
多模态长会话里误差会累积成"估算说还有 3 万,实际已经爆了"。
12.3 摘要模型会"顺手整理"路径
模板里写了 Preserve exact file paths,仍然会丢。
真正保险的是 details 里的结构化清单 + 代码外挂的 <read-files> 块。
能外挂的别让模型复述。
12.4 thinking 被丢掉,等于丢掉推理链
对推理型模型,thinking 往往是"为什么这么改"的唯一记录。摘要里没它,
接手模型只能看到"改了什么"。源码的理由(避免摘要请求比被摘要内容还大)
站得住脚,但需要推理链的场景应该在 customInstructions 里显式要求。
12.5 length 停也要当失败,否则半截摘要进会话
放过 stopReason === "length",会话里就会出现一个写完 ## Goal、
## Progress 就断掉的摘要。它看起来完全正常,模型照着它继续——
但 Next Steps 根本没生成。
12.6 溢出只赔一次,第二次直接放弃
_overflowRecoveryAttempted 是实例字段,不清零。
一个长会话里已经救过一次,第二次溢出就是硬失败(得换会话或换模型)。
12.7 换模型后旧溢出标记会误触发
_modelForMessage 找不到产出这条消息的模型时,sameModel = false,
溢出检查整段跳过。这是保护,也是盲区:
如果模型真的没了(配置删了),溢出永远不会被恢复。
12.8 压缩刚结束,第一轮又触发
因为保留区里的 usage 是压缩前的,assistantIsFromBeforeCompaction
用时间戳挡住。自己写类似机制时,用时间戳比,而不是比"是否在保留区"——
保留区里的消息可能比 compaction entry 还新。
12.9 手动压缩会打断正在跑的 turn
compact() 第一行就是 await this.abort()。
扩展或脚本在模型输出中途调它,那次输出直接作废。
要"压完接着跑",得自己记住上下文再重发。
12.10 扩展接管压缩时,文件清单可能为空
session_before_compact 返回 { compaction } 时,details 由扩展自己给。
不给就是 undefined,下游拿到的 readFiles / modifiedFiles 全空。
fromHook: true 就是这个来源的标记。
12.11 分支摘要的 90% 保底可能仍然超预算
那个分支只在 totalTokens < tokenBudget * 0.9 时塞入,
但塞进去的那条摘要本身可能就有 5 万 token。
结果总量超预算,请求被 provider 拒绝。极端情况需要扩展在
session_before_tree 里自己接管。
12.12 分支摘要跳过 toolResult,可能丢掉关键证据
getMessageFromEntry 对 toolResult 返回 undefined。
如果那条支线的价值恰恰是"某条命令的输出证明了根因",这段证据不会进摘要。
需要就在 customInstructions 里明说,或让扩展接管 summary。
十三、三个可以带走的方法
13.1 用「追加墓碑」代替「原地删除」
只要存储是 append-only 的,任何"删除"都能表达成"追加一条声明"。
compaction entry 就是这个模式:
一条 entry 说"从这里往前别看,看我的 summary,从 firstKeptEntryId 起恢复原文"。
好处不只是可回滚。更关键的是同一份历史可以有多个视图—— 不同叶子读同一份 JSONL 得到不同上下文(M10 的分叉靠的就是这个)。
13.2 估算要两级:可信锚点 + 增量外推
estimateContextTokens 的骨架值得抄:
- 找一个可信锚点(provider 真实报回来的 usage)。
- 只对锚点之后的增量做估算。
- 锚点失效时(被 edit / compaction 改过)整体重估,别硬用。
纯估算会累积漂移,纯真实值又拿不到(成本、延迟),两级混合最省事。
第三点是关键:把"锚点可能已经失效"写进结构(lastUsageIndex: null),
而不是靠调用方自觉。
13.3 摘要要写成「交接单」,不是「读后感」
三条硬要求:
- 结构化。六节固定标题,缺一节模型就少一个抓手。
- 禁止续写。模板 + 系统提示 + 拍平输入,三重保险。
- 可丢弃。
tools do not call/length 即失败, 宁可整次压缩失败,也不接受一份"看起来完整"的残缺品。
最后一条最容易被忽略:压缩失败的成本是一次模型调用, 而残次摘要的成本是接下来几十轮都在错误的前提下工作。差两个数量级。
十四、压缩没生效时,先查这四件事
一,配置被上层覆盖了。 压缩配置三层解析:模型覆盖 > 全局 > 默认
(settings-manager.ts 1,457 行)。先看 modelOverrides 里有没有你忘了的那一项。
二,阈值算错了。 阈值 = 上下文窗口 − reserveTokens。
reserveTokens 调得过大,就会出现"还没装满就压"。
三,锚点失效了。 历史被 edit 或上一次压缩改过之后,估算必须整体重算,
不能继续用旧 usage 往后外推(§三 的 lastUsageIndex)。
四,摘要被拒了。 length 即失败、tools do not call——宁可整次失败,
也不接受一份残缺摘要(§13.3)。四件都排查完还没压,大概率是闸门根本没被调到:
_exceedsCompactionThreshold 返回 false 时,两道闸门都在等下一轮。
本章小结
- 压缩不是删除,是追加一条
compactionentry 当墓碑。 - 两道闸门:请求前预判(threshold)、响应后溢出(overflow)。
- 切点从后往前累加;兜底取最后一个,不是第一个。
- token 估算两级:可信锚点 + 增量外推,锚点失效就整体重估。
- 摘要写成交接单:结构化、禁续写、可丢弃。
概念回顾
| 术语 | 一句话 | 在哪 |
|---|---|---|
| 墓碑 | 用一条 entry 声明"从这里往前别看" | §一 |
| 两道闸门 | threshold 预判与 overflow 溢出 |
§二 |
| 切点 | 从后往前累加到预算为止 | §四 |
| 锚点 | provider 真实报回的 usage,之后只算增量 | §三 |
| 交接单 | 六节固定标题的摘要,不是读后感 | §五 |
练习
练习 1(读):§二 说两道闸门一前一后。
如果把 overflow 那道关掉,什么情况下会先崩?
→ 回 §二 的两道闸门与 M03 §十 的失败路径。
练习 2(改):照 §十一 实验 7 把 reserveTokens 设为 1,
并注释掉 _runAutoCompaction("threshold", false)。
预期:reason 从 threshold 变成 overflow;回滚:二者都恢复原样。
常见误区
- 你会以为 压缩后原文就没了;实际是 摘要 +
firstKeptEntryId之后的原文都在; 证据 §一、§八。 - 你会以为 摘要越短越好;实际是 缺一节就少一个抓手; 证据 §五 的六节模板。
- 你会以为 压缩失败很严重;实际是 失败只花一次调用,残次摘要拖几十轮; 证据 §13.3。
读完自检
三条,能不能不看稿说出来?
| 自检 | 一句话答案 | 不会就去 |
|---|---|---|
| 压缩到底是删还是追加? | 追加一条 compaction entry 当墓碑,磁盘上一条不少 |
§一 |
| 两道闸门分别守在哪? | 请求之前(预判)和响应之后(溢出) | §二 |
| 切点从哪头开始找? | 从后往前累加;兜底是最后一个,不是第一个 | §4.2、§4.3 |
下一步
压缩是"改历史",还剩一个更基础的问题没讲: 历史存在哪、怎么恢复、怎么分叉。
M10 讲会话:session-manager.ts 的 JSONL 格式、entry 的树结构、
fork 与 tree 的差别,以及为什么 packages/durable 要把存储单独拎出去。
本章的 compaction 和 branch_summary,到 M10 会变成两种普通 entry 类型——
它们和 message、custom、model_change 排在同一个数组里,
一起被序列化、一起被重放。
想亲手写一个最简压缩器?Part E 的 E05 用 56 行造了同构的两道闸,四个验收数字直接可跑。
本章源码索引
| 文件 | 行数 | 一句话职责 |
|---|---|---|
core/compaction/compaction.ts |
1,105 | 切点算法、token 估算、摘要模板与主流程 |
core/compaction/branch-summarization.ts |
387 | 分支摘要:LCA 收集、预算裁剪、五节模板 |
core/compaction/utils.ts |
164 | 文件清单、对话序列化、摘要系统提示词 |
core/compaction/index.ts |
8 | 两个子模块的统一导出 |
core/agent-session.ts |
4,480 | 两道闸门、手动入口、分支导航与事件编排 |
core/session-manager.ts |
2,029 | compaction entry 的落盘、投影与路径筛选 |
core/settings-manager.ts |
1,457 | 压缩配置的三层解析(模型覆盖 > 全局 > 默认) |
core/messages.ts |
197 | compactionSummary / branchSummary 转 LLM 消息 |
core/slash-commands.ts |
45 | /compact 的内置命令登记 |
modes/interactive/interactive-mode.ts |
7,212 | /compact [指令] 的解析与调用 |
modes/rpc/rpc-mode.ts |
820 | RPC compact 命令 |
行号为 v1.4.0 实测。interactive-mode.ts 只引了命令解析与处理两处,
其余章节不再展开。