Pi Agent 源码级教程
M09

上下文压缩 —— 两道闸门,两种摘要

11,593 字 · 含 1,034 行代码 · 约 60 分钟

M08 的最后一节说:每轮都要重算系统提示词。 原因是提示词依赖的工具集、目录、技能会变。

但还有一件事 M08 没提:重算的输入 messages 本身在变长。

用户问十句,模型跑二十次工具,messages 就有三十条以上。 每条工具结果动辄几千字符,一次 read 一整个文件就是上万字。 20 万 token 的窗口,撑不了多久。

撑不住的时候只有三条路:

  • 报错。把 400 甩给用户,让人自己想办法。
  • 静默截断。砍掉最早几条,假装没发生过。
  • 主动压缩。把旧历史改写成摘要,保留最近的原文。

Pi 走第三条,而且走得很认真:compaction.ts 1,105 行、 branch-summarization.ts 387 行、utils.ts 164 行,不到 1,700 行, 处理的是同一个问题——

当对话必须变短时,丢掉什么、记住什么、凭什么决定。

这一章拆这道题。两条线索:

  1. 普通压缩:同一个会话越跑越长,就地压扁。
  2. 分支压缩:会话在树上分叉,被放弃的那条路怎么留个念想。

两者共用摘要调用与文件清单,但四个地方全不一样: 切点算法、提示词、预算口径、摘要存放位置。 章末有一张逐项对照表。

先说读法,两分钟能省你两小时。这一章的代码密度是全书最高的一章: 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 的注释写得很直白:

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:压缩前多少 token
  • details:{ readFiles, modifiedFiles }
  • usage:生成摘要那次调用的 token 消耗
  • systemMessage:压缩瞬间的系统提示词快照

读上下文时,buildContextEntries 按这个规则筛:

ts
// 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;}

三步,值得逐句读:

  1. 沿当前叶子往上走,找最后一条 compaction,它自己排在结果数组首位。
  2. 从路径开头扫到 compaction 之前,只保留跨过 firstKeptEntryId 之后的, 且跳过 system 消息(提示词状态由 systemMessage 字段承担)。
  3. 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 里算系统提示词的那个钩子), 第一件事就是检查阈值:

ts
// 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 分类处理:

ts
// 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 给这个重放只留一次机会:

ts
// 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 输出被截断也算溢出

ts
// 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), 它和自动路径的差别只有三处:

ts
// 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)");		}		// …
  1. 先 await this.abort()。手动压缩不允许在模型跑一半时插队, 否则同一份上下文会被两条路径同时改写。
  2. 绝不重试、绝不续跑。压完就停在那儿等用户。
  3. 失败要 throw。自动路径失败只发事件(后台出错不能炸前端), 手动路径失败必须抛给调用方(用户按了按钮,得知道结果)。

两条报错也很有意思:Already compacted 和 Nothing to compact (session too small)。 它们说明 prepareCompaction 返回 undefined 有两种含义, 得看路径末端 entry 的类型才能区分。

2.7 三条路汇到同一个函数

text
/compact ──┐RPC ───────┤扩展 ──────┴─→ AgentSession.compact()      ─┐                                            ├→ _runDefaultCompaction()请求前超阈值 ─→ _runAutoCompaction("threshold") ─┤        │响应后溢出 ───→ _runAutoCompaction("overflow")  ─┘        ▼                                                    compact()                                                        │                        ┌───────────────────────────────┘                        ▼              prepareCompaction → 切点 + 分段                        ▼              generateSummaryWithUsage → 摘要文本                        ▼              appendCompaction → 墓碑写进 JSONL

_runDefaultCompaction(:2804-2827)只有十几行, 作用是"解析出这次摘要用哪个模型、哪个 key",再调用核心 compact():

ts
// 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,四个字段:

ts
// compaction.ts:140-142(折行)export function calculateContextTokens(usage: Usage): number {	return (		usage.totalTokens ||		usage.input + usage.output + usage.cacheRead + usage.cacheWrite	);}

totalTokens 有就直接用;没有就加四个分量 (输入、输出、缓存读、缓存写都算进上下文)。

不是所有 assistant 消息的 usage 都可信:

ts
// 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 是"上一次请求时的快照",之后又追加了几条消息。 所以总量 = 快照 + 尾部估算:

ts
// 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 的九个分支

估算函数本身很简单,难点在按消息类型分类:

ts
// 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 这条经验法则的两面

源码注释写着:

ts
// 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)处理一个更隐蔽的情况:

ts
// 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 判定:一条不等式

ts
// 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):

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

text
compaction.modelOverrides["provider/model"].reserveTokens  ↓ 没有就取compaction.reserveTokens  ↓ 没有就取DEFAULT_COMPACTION_TOKEN_SETTINGS

第一层很实用:20 万窗口的模型配 16K 余量,1M 窗口的配 64K,互不干扰。


四、切在哪

有了"该压"的判定,下一个问题就是"压到哪"。 这是整个压缩里最精细的 30 行,四个坑。

4.1 哪些位置可以切

ts
// 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 从后往前累加

ts
// 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] 这半句是关键修正。

设想历史末尾是这样一个形状:

text
[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 顺手吞掉不可见的元数据

ts
// 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:切在轮次中间

判定只有三行:

ts
// 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 从这个切点往前找,找到最近的轮次起点:

ts
// 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;}

于是变成三段:

text
[……更早的历史……]      ← 主摘要(messagesToSummarize)[用户那句话 + 部分工具] ← turnPrefix 摘要(turnPrefixMessages)[……保留区……]          ← 原文不动(firstKeptEntryId 起)

中间那段是"被切开的半轮"。它比保留区早,却不能塞进主摘要—— 主摘要是"很久以前发生过什么",语气是过去式; 这半轮是"紧接着正在做的事",语气是现在时。 混在一起写,模型会搞不清哪些已经做完。所以单独生成,见 §六。

4.6 生产路径用的是投影版

findCutPoint 是导出函数,但 prepareCompaction 实际调用的是另一个:

ts
// 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, 按投影已经归零,不该影响切点。

投影版还多一段专门的逻辑,处理"溢出重试被省略"这种特殊后缀:

ts
// 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 六节模板

ts
// 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 第二次压缩是"更新"不是"重写"

如果这次要压的历史里已经有一条摘要(上一次压缩留下的), 就不该重写,而该增量更新:

ts
// 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):

ts
// 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 先把对话序列化成一整段纯文本,再包进标签:

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

为什么要拍平?两个原因:

  1. 防止模型接着聊。标准对话结构下,模型很可能把最后一条当成 "该我回了",直接续写而不是写摘要。
  2. 统一格式。bashExecution、custom、compactionSummary 这些自定义类型 都要先经 convertToLlm 变成标准 Message,否则序列化函数认不出来。

系统提示词是另一层保险(utils.ts:161-163,按语义折行):

ts
// 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 序列化时丢掉什么

ts
// 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)给的理由很硬:

text
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 字符。 截断标记长这样:

ts
// 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 三道失败判定

摘要调用回来后,不是"有文本就算成功":

ts
// 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;}

调用处还有第三道:

ts
// 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 不复用缓存,但要重试

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

ts
// 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 的三段结构。被切开的半轮有个尴尬的时间位置:

text
时间轴 ──────────────────────────────────────────→[主摘要区]        [turnPrefix 区]        [保留区]"很久以前"        "刚才这一轮的前半"     "现在的原文"

turnPrefix 区里的内容比保留区还早,但比主摘要区晚。 如果并进主摘要:

  • 叙述视角会乱——前面讲"上周做了什么",突然接"刚才我在改第 3 行"。
  • 下次再压缩时,这段会被当成"历史"重新概括,正在进行的任务就变成了过去式。

并进保留区:又违背了"按 token 预算切"的原则——它可能很大,塞进去就超了。 所以单独一份,用专门的提示词。

6.2 三节模板

ts
// 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。 因为读者马上就要拿到后半段的原文,不需要提前知道最终目标。

最后一句是防幻觉的关键:

text
Only summarize information explicitly present above.Do not infer or recreate later messages.

模型拿到的只有前半轮,它天然想"补全"后面发生了什么。 这句话把它按回去:只写你看见的。

6.3 串行,不是并行

这里要纠正一个很自然的猜测:两份摘要是不是 Promise.all 并行跑?

不是。

ts
// 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 一前一后。

为什么不做并行?三个现实原因:

  1. messagesToSummarize 可能是空的(直接拿 previousSummary), 这时只有一份请求,并行结构反而更绕。
  2. 限流。压缩本身高频,同时发两份会翻倍触发 RPM 限制,还把重试搞复杂。
  3. 顺序即语义。先"历史讲完了",再"接着这一轮",串行写在代码里, 读的人也顺着这个顺序理解。

代价是慢一倍。但压缩发生在"对话已经很长"的时刻,用户本来就要等, 多等 3 秒比多一次 429 划算。

6.4 合并格式

text
${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 单独抽一层,边扫描边记账:

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

ts
// 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 的嵌套调用也要算

ts
// 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 是「只读未改」

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

ts
// 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 块,形如:

text
## 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 落盘

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

ts
// 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 再转一次:

ts
// 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>`;
ts
// 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 一次压缩的事件序列

text
_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 }

返回值决定上层怎么走:

ts
// 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 先找公共祖先

ts
// 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 塞不进预算时,摘要优先

ts
// 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 跳过工具结果

ts
// 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 预算是输入预算,不是输出上限

这是最容易读错的一处:

ts
// 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 五节模板

ts
// 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 给摘要加一句"你去过别处"

ts
// branch-summarization.ts:255-258const BRANCH_SUMMARY_PREAMBLE = `The user explored a different conversationbranch before returning here.Summary of that exploration:`;
ts
// 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 失败不抛,返回对象

ts
// 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):

ts
if (result.aborted) return { cancelled: true, aborted: true };if (result.error) throw new Error(result.error);

abort 是正常路径——用户按 Esc 放弃总结,导航照旧。 error 是失败路径——总结失败就别跳了,抛给上层。 用返回对象而不是异常,就是为了让调用方能区分这两者。

9.9 摘要挂在目标位置

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

这是最反直觉的一步。直觉方案是挂在旧叶子下面, 但那样挂它就不在当前路径上了——沿新叶子往上走根本不经过它。

正确做法是挂在新位置。于是新路径变成:

text
root → … → 公共祖先 → [branch_summary] → 目标节点 → 新的对话…

注意摘要挂的是目标位置,而 newLeafId 可能不是 targetId:

ts
// 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—— 扩展可以自己看一眼要总结什么,再决定插手还是放行:

ts
// 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 混用,会得出完全错误的结论。
  • 摘要挂载位置反直觉。普通压缩挂在历史末端,分支摘要挂在导航目标。 想清楚"哪条路径会被读",就不会挂错。

十、完整链路

text
                     ┌──────────── 普通压缩 ────────────┐用户 /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):

bash
# Linux / macOSls ~/.pi/agent/sessions/# 形如 --home-you-code-myapp--grep -l '"type":"compaction"' ~/.pi/agent/sessions/*/*.jsonl
powershell
# 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--。 找到后用一条命令看字段:

bash
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
powershell
# 多行 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:

json
{  "compaction": {    "enabled": true,    "reserveTokens": 16384,    "keepRecentTokens": 1000  }}

再跑一次 /compact,然后对比两次 compaction 的 firstKeptEntryId 指向的 entry 位置。

判据:keepRecentTokens 从 20,000 降到 1,000 后, 保留区条目数明显减少,tokensBefore 不变,但下次请求输入量下降更多。 副作用也能观察到:保留太少,模型会忘掉刚做的事,开始重复读文件。 所以真正的结论是——keepRecentTokens 不是越小越好。

实验 4:给单个模型单独设余量

json
{  "compaction": {    "reserveTokens": 16384,    "modelOverrides": {      "anthropic/claude-sonnet-4-5": { "reserveTokens": 32768 }    }  }}

键名格式是 provider/modelId(settings-manager.ts:858)。

判据:只改了那一个模型的触发线。其它模型开会话压缩时机不变; 用这个模型压缩更早发生(阈值 = 窗口 − 32,768)。

实验 5:用 SDK 手动压一次

js
// 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:分支摘要挂在哪

js
// 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):
json
{  "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 的骨架值得抄:

  1. 找一个可信锚点(provider 真实报回来的 usage)。
  2. 只对锚点之后的增量做估算。
  3. 锚点失效时(被 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 时,两道闸门都在等下一轮。


本章小结

  1. 压缩不是删除,是追加一条 compaction entry 当墓碑。
  2. 两道闸门:请求前预判(threshold)、响应后溢出(overflow)。
  3. 切点从后往前累加;兜底取最后一个,不是第一个。
  4. token 估算两级:可信锚点 + 增量外推,锚点失效就整体重估。
  5. 摘要写成交接单:结构化、禁续写、可丢弃。

概念回顾

术语 一句话 在哪
墓碑 用一条 entry 声明"从这里往前别看" §一
两道闸门 threshold 预判与 overflow 溢出 §二
切点 从后往前累加到预算为止 §四
锚点 provider 真实报回的 usage,之后只算增量 §三
交接单 六节固定标题的摘要,不是读后感 §五

练习

练习 1(读):§二 说两道闸门一前一后。 如果把 overflow 那道关掉,什么情况下会先崩? → 回 §二 的两道闸门与 M03 §十 的失败路径。

练习 2(改):照 §十一 实验 7 把 reserveTokens 设为 1, 并注释掉 _runAutoCompaction("threshold", false)。 预期:reason 从 threshold 变成 overflow;回滚:二者都恢复原样。

常见误区

  1. 你会以为 压缩后原文就没了;实际是 摘要 + firstKeptEntryId 之后的原文都在; 证据 §一、§八。
  2. 你会以为 摘要越短越好;实际是 缺一节就少一个抓手; 证据 §五 的六节模板。
  3. 你会以为 压缩失败很严重;实际是 失败只花一次调用,残次摘要拖几十轮; 证据 §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 只引了命令解析与处理两处, 其余章节不再展开。