← Pi Agents

压缩

Pi 如何判断上下文窗口什么时候满了、它用什么替换成摘要、什么会原封不动地保留下来,以及一个扩展可以在哪里接管摘要的生成。

重构进行了两个小时,页脚说你已经用了 87% 的上下文。一切正常。然后它说智能体已经压缩过了,接着模型让你重新解释那个它一小时之前被告知过的 schema。

这种重新提问正是压缩真实的行为,而不是你的提示词里的一个 bug。旧消息并没有被删除——它们全都还在会话文件里——但它们已经不在下一个请求之中了。模型现在手里取而代之的,是另一个模型写下的、关于那些消息说了什么的一段话。

本章讲的就是这套机制:它何时触发、它替换掉什么,以及你能在哪里介入。

两种机制,一个想法

机制 触发条件 用途
压缩 上下文超出阈值,或者 /compact 摘要旧消息以腾出上下文
分支摘要 /tree 导航 切换分支时保留上下文

“两者使用紧密相关的结构化格式,并累积式地跟踪文件操作。摘要请求会禁用提示词缓存写入,因为这些一次性的提示词不太可能被复用。”

最后那半句值得记住。压缩会故意破坏你的提示词缓存,因为它发出的请求与之前任何一个请求都不一样。缓存命中在它之后紧接着恢复。

它何时触发

触发条件是算术,而第 4 章拥有它:contextTokens > contextWindow - reserveTokens,在工具结果被追加之后、下一个请求之前检查,也在一条新的用户提示词之前检查,另外还会在某个 provider 以请求过长为由拒绝一次请求时,作为恢复手段再检查一次。reserveTokens(默认 16384)存在的意义是"为 LLM 的响应留出空间",这就是为什么触发条件是一次减法,而不是与窗口本身比较。本章补充的是第 4 章不需要的那一部分。

轮与轮之间的检查只有一种情况下会被跳过:“当已完成的工具批次终止了本次运行,且没有排队的消息要求再一次响应时。“没有下一个请求,就没有必要为它腾出空间。而恢复是一条带着硬性上限的修复路径:“一次 provider 的上下文溢出错误,或一个提前出现的最终 stopReason: "length",可以选择使用一次压缩并重试的恢复尝试。“一次尝试,不是一个循环。第 29 章完整讲述恢复。

压缩实际做了什么

五个步骤,来自 compaction.md:

  1. 找到切点 — 在已最终确定的会话投影上向后走,累积 token 估计值,直到达到 keepRecentTokens(默认 20000)。
  2. 提取消息 — 从上一个被保留的边界(或会话起始处)到切点,收集投影得到的消息。
  3. 生成摘要 — 以一种结构化格式调用 LLM,当存在前一份摘要时,把它作为迭代上下文传入。
  4. 追加条目 — 保存一个带摘要和 firstKeptEntryId 的 CompactionEntry。
  5. 重建上下文 — 会话为下一个请求重建上下文,使用摘要加上自 firstKeptEntryId 起的消息。

第 3 步是让人吃惊的那一步。前一份摘要不会被丢弃;它会被作为新摘要的上下文传入。每一次压缩摘要的,都是上一次摘要过的内容,加上那之后发生的事。这就是为什么"重新提问"是逐渐退化的,而不是一下子发生。

用文档自己那个示例里的条目编号把它展开。条目 0 到 9 在压缩之前就存在;条目 10 是之后追加的那个 compaction 条目:

    flowchart TD
  subgraph FILE["会话文件 — 每个条目都留下"]
    direction LR
    e0["0 hdr"] --> e1["1 usr"] --> e2["2 ass"] --> e3["3 tool"] --> e4["4 usr"] --> e5["5 ass"] --> e6["6 tool"] --> e7["7 tool"] --> e8["8 ass"] --> e9["9 tool"]
  end
  e9 --> c10["10 compaction"]
  subgraph NEXT["下一个请求 — 重建后的上下文"]
    direction LR
    sys["system"] --> sm["0 到 3 的摘要"] --> k4["4 usr"] --> k5["5 ass"] --> k6["6 tool"]
  end
  c10 --> sm
  e4 --> k4
  

第一个框是会话文件,而压缩只会往它里面追加。第二个框是模型所看到的东西,而它是另一回事:系统提示词、摘要,然后是自 firstKeptEntryId——本示例中是条目 4——起的那些条目。

错误:“压缩会删除旧消息。” 正确:它改变的是下一个请求由什么构建而成。session-format.md:Pi “会用压缩摘要替换掉较旧的、已被摘要的条目,并保留自该条目起的范围。"compaction.md 补充说:“被省略的原始条目仍然被存储,但不会影响切点选择、摘要、检查点或 token 估计。“文件里没有任何东西被删除,而模型丢掉的东西仍然是实打实的。

切点规则

合法的切点是用户消息、助手消息、BashExecution 消息,以及自定义消息。然后是那条能阻止半个工具调用存在的规则:

“绝不要在工具结果处下刀(它们必须与它们的工具调用待在一起)。”

在一次工具调用和它的结果之间切开,会让模型去追问一个永远不会有返回的工具调用。因此 keepRecentTokens 的预算可以略微超支,以便落在一个合法的边界上。

还有一种情况叫做被切分的用户消息跨度(split user-message span)。“一个用户消息跨度始于一条用户消息,并包含到下一条用户消息为止的所有轮次。“正常情况下,压缩会在那些边界之一处下刀。但当单个跨度本身就超过 keepRecentTokens 时——一个带有许多工具调用的漫长轮次——刀就会落在它内部,落在一条助手消息上。文档把这种情况标记为 isSplitTurn = true,其中 messagesToSummarize 为空,靠前的部分保留为 turnPrefixMessages,并且 Pi “生成两份摘要并把它们合并”:一份针对先前的上下文,一份针对该用户消息跨度的前缀。

它写下的条目

形状复刻自 session-format.md。这是一份供参考的类型声明,不是一个可运行的示例。

interface CompactionEntry<T = unknown> {
  type: "compaction";
  id: string;
  parentId: string | null;
  timestamp: string;
  summary: string;
  firstKeptEntryId: string;
  tokensBefore: number;
  usage?: Usage;       // LLM usage that generated the summary
  fromHook?: boolean;  // true if provided by extension (legacy field name)
  details?: T;         // implementation-specific data
  systemMessage?: SystemMessage; // complete prompt and tool state at this boundary
}

// Default compaction uses this for details:
interface CompactionDetails {
  readFiles: string[];
  modifiedFiles: string[];
}

firstKeptEntryId 就是整套机制。Pi “会用压缩摘要替换掉较旧的、已被摘要的条目,并保留自该条目起的范围。“改掉这个字段,你就改变了模型看到哪一段历史。

tokensBefore 是在写入新的 CompactionEntry 之前,“从重建后的、经上下文编辑的会话投影"重新计算的,“因此 token 计数反映的是实际被替换掉的压缩前上下文。“注意它不做什么:“被省略的原始条目仍然被存储,但不会影响切点选择、摘要、检查点或 token 估计。”

摘要格式

压缩摘要和分支摘要都使用结构化输出。压缩摘要有 Goal、Constraints & Preferences、Progress、Key Decisions、Next Steps 和 Critical Context 几个小节。分支摘要在 Next Steps 之后就结束。“Pi 会在相关时把文件列表附加到任何一种格式上。”

## Goal
[What the user is trying to accomplish]

## Constraints & Preferences
- [Requirements mentioned by user]

## Progress
### Done
- [x] [Completed tasks]

### In Progress
- [ ] [Current work]

## Key Decisions
- **[Decision]**: [Rationale]

## Next Steps
1. [What should happen next]

## Critical Context
- [Data needed to continue]

这里有两处刻意为之。Critical Context 之所以存在,是因为摘要的工作不是叙事上的完整——而是把下一个请求所需要的事实带过去。而文件列表被附加进来,是因为"我读了哪些文件、改了哪些文件"正好是一个正在做摘要的模型最先丢掉的状态,也正好是下一轮接手工作所需要的东西。

在摘要之前,消息会被序列化成纯文本,而不是作为一场对话发出去:[User]:、[Assistant thinking]:、[Assistant]:、[Assistant tool calls]:、[Tool result]:。“这可以防止模型把它当成一场需要继续下去的对话。“工具结果会被截断到 2000 个字符,“因为工具结果(尤其是来自 read 和 bash 的)通常是上下文体积的最大贡献者。”

配置它

这些设置——enabled、reserveTokens、keepRecentTokens 以及按模型的覆盖项——都属于第 4 章。有一个细微之处属于本章,因为它关系到摘要本身:"reserveTokens 也会影响摘要的输出上限,但以模型的最大输出 token 数为封顶;它不仅仅是一个触发阈值。“在一个输出上限为 64K 的模型上留出 400000,并不会让摘要变长,因为输出上限先起作用。

用扩展接管它

session_before_compact 在自动压缩或 /compact 之前触发,并且有两种有文档记载的结果。它可以提供摘要,而把切点留给 Pi:

pi.on("session_before_compact", async (event) => {
	const { preparation } = event;

	// preparation.messagesToSummarize : the messages that are about to be replaced
	// preparation.previousSummary     : the last compaction's summary, if any
	// preparation.firstKeptEntryId    : where the kept messages start
	const serialized = serializeConversation(convertToLlm(preparation.messagesToSummarize));

	return {
		compaction: {
			summary: `Custom summary of ${preparation.messagesToSummarize.length} message(s):\n${serialized.slice(0, 500)}`,
			firstKeptEntryId: preparation.firstKeptEntryId,
			tokensBefore: preparation.tokensBefore,
		},
	};
});

或者它可以取消:

pi.on("session_before_compact", async (event) => {
	return event.reason === "manual" ? { cancel: true } : undefined;
});

这个事件还带有 branchEntries、customInstructions、reason("manual"、"threshold" 或 "overflow")、willRetry 和 signal。本章的初稿把两种结果写成同一个处理器里的两个 return 语句,那是跑不通的,还写了一个从未定义的 summaryResponse。它们是两个处理器,因为它们是两个决定。

两者都在 examples/ch23-compaction/ 里被运行过,通过一个真实的会话,其 keepRecentTokens 被调低,好让一段简短的脚本化对话有东西可摘要:

  • 摘要来自扩展,而切点仍然是 Pi 的:那个条目带有它自己的 firstKeptEntryId,并被标记为 fromHook: true;
  • 下一个请求由摘要加上被保留的消息构建而成:最早的那个问题不再作为消息被发送,最近的那个被发送了,而摘要本身以一条用户角色的消息到达(第 26 章的 compactionSummary 转换,已观察);
  • 之后每一个 message 条目都仍然在文件里,这就是作为计数的"压缩不删除”;
  • 一个取消手动 /compact 的处理器会止住它:没有压缩条目出现。

本章也在同一段共享历史上接受测试,好让这几章读起来是一个主题、是一段随时间演变的状态,而不是四个。它是一个持久化会话里的三轮:问题 A 及其回答;问题 B,它发起一次 bash 工具调用然后回答;问题 C 及其回答。examples/harness/history.ts 构建这段历史,每一章都从同一次运行中读出不同的属性。

在那段历史上,第 23 章的问题是压缩替换掉了什么,而什么能在它之后存留?examples/ch23-compaction/state.test.ts:

  • 切点从不在一个工具结果处,在 50 到 2500 之间七个 keepRecentTokens 取值上试过,并且在每一种情况下,随后的请求包含的工具结果都和工具调用一样多:没有不带其结果的一次调用,也没有不带其调用的一次结果;
  • 压缩是迭代的:第一次压缩没有 previousSummary,而第二次被给了第一次的摘要;
  • fileOps 是三个 Set:模型读过的一个文件在 read 里,它写过的一个文件在 written 里,而 edited 是空的;
  • **单个长跨度会被切分。**一条用户消息后面跟着六个会发起工具调用的轮次,产生了 isSplitTurn: true、messagesToSummarize 为空,以及十一条 turnPrefixMessages,正是上面那段文字提醒处理器要当心的情况;
  • 压缩不会缩小系统提示词或工具声明:它之后的请求仍然带着一条声明了 bash 的系统消息;
  • 它替换的是模型读到的内容,文件里的东西一概不动:导航到压缩之前的那一个条目会再次发送原始消息,而不是摘要;
  • 一个取消压缩的扩展让条目数量保持不变,并且不写入任何压缩。

有一条注意事项是这个示例有意略去不谈的。一个被切分的用户消息跨度会把该跨度的靠前部分放进 preparation.turnPrefixMessages,并让 messagesToSummarize 为空。像这个示例一样只读 messagesToSummarize 的处理器,在这种情况下会摘要不出任何东西。随附的 custom-compaction.ts 把两个列表接在一起。如果你的会话里包含漫长的单个轮次,请复制那个,而不是这个。

如果你想用另一个模型来生成摘要,serializeConversation 是有文档记载的路径:用 convertToLlm 转换 AgentMessage[],序列化成文本,然后把它发到你想发到的任何地方。session_compact_failed 是它的终局对位事件——“对那些需要把 session_before_compact 尝试与终局结果配对的遥测扩展很有用”——带有 reason、errorMessage、aborted、willRetry 和 fromExtension。

失败不是死路

“如果 provider 不可用,或者无法接受摘要请求,压缩可能会失败。修正 provider 的问题,然后再运行一次 /compact。“失败模式在事件流中显示为 compaction_end,带着 aborted: false 和一个 errorMessage;当安排了重试时,则会单独显示为 summarization_retry_scheduled。

有一处值得知道的不对称:“对于 fromHook 字段为 true 的、由扩展生成的摘要,Pi 不会自动沿用其文件列表;扩展自行管理它们自己的 details 格式。“如果你的自定义摘要丢掉了文件列表,后续的压缩不会把它们找回来——累积式跟踪只在 Pi 生成的摘要之间累积。

所以,模型在一次压缩之后忘了你的 schema,并不是这套机制的失败。一段关于 schema 的段落所能做的,就是这个。补救措施在你这一侧——把持久的事实放进一个上下文文件(第 28 章),让它们作为被加载的指令随每一次请求同行,而不是被历史携带着。

从满上下文中脱身的另一条出路,根本不是压缩。当一个会话走错方向时,/tree、/fork 和 /clone 是同一个问题的三个不同答案。