阶段二 · 状态与边界

上下文压缩 —— 窗口装不下时怎么办

上下文窗口是硬上限,对话是无限增长的。Pi 的答案是两层防护:进上下文之前先截断工具输出,历史太长就让模型自己总结旧对话。而压缩只有一条铁律——不能把一次工具调用和它的结果拆开。这一章讲清压缩何时触发、在哪里下刀、切掉的东西怎么处理。

具体回答三个问题:什么时候该压缩?在哪里下刀?切掉的内容去哪了?

学习目标

  • 理解两层防护各解决什么问题:输入侧截断,历史侧压缩。
  • 理解压缩的触发条件,以及"预留缓冲"这个说法在新版本里的变化。
  • 理解切割点的真实约束:不是"不跨轮",而是"不拆对"。
  • 理解 token 估算为什么"不精确但够用",以及它其实比你以为的准。

一、问题:窗口是固定的,对话是增长的

模型的上下文窗口是硬上限。对话越聊越长,迟早要撑爆。不处理会怎样?只有两个选择:拒绝继续(用户不能接受),或者静默截断(更糟——模型不知道前面发生了什么,因果断裂,回答质量崩坏)。

Pi 把"窗口"当预算管理:窗口大小是上限,每次请求都在消耗预算;预算不够时,腾出空间。

二、两层防护,各管一段

防护 时机 手段
输入侧 工具结果进入上下文之前 截断:限行数 + 限字节,双重限制
历史侧 上下文逼近上限时 压缩:让模型总结旧消息,保留近期窗口
  • 输入侧解决"一条命令的输出占满上下文":输出在进上下文之前就被截断,完整内容留在临时文件里。
  • 历史侧解决"对话本身太长":旧对话被总结成摘要。

两者都要。只做输入侧,对话照样越来越长;只做历史侧,一条超长输出就能瞬间占满窗口。

截断的两个细节

  1. 双重限制,先到先算:只限行数挡不住超长单行,只限字节挡不住海量短行。
  2. 不切半行、不切半个字符:截断只发生在完整行边界;如果第一行就超字节上限,返回空内容并标记,而不是切出半个字符。"被截断了"这件事本身也是结果的一部分——工具会告诉模型"输出不完整,完整内容在临时文件里"。

三、跟着两小时的长对话走一遍

下午两点开始,你和 Agent 一起排查一个线上问题。到四点,对话已经很长了。

先是输入侧的拦截。 中间有一次跑测试,刷了三千行日志。这三千行进上下文之前就被截到 2000 行 / 50KB——完整内容在临时文件里,结果里带着"被截断了"的标记和文件路径。模型因此知道"我看的不是全部",需要时可以让你再取一次。

然后是历史侧。 某次请求前,估算发现用量已经超过"窗口减去预留量"。于是触发压缩:从最新的一条往前找切割点,但每找到一处都先检查是否切开了一对调用与结果——切开就往前退,直到不切。

压缩之后。 前端你能看到一条"已压缩"的提示;模型则看到一段结构化摘要(目标、约束、进展、关键决定、下一步、关键上下文、改过哪些文件),后面接着最近保留的那几条原始消息。中间那段旧对话没有消失——点开会话树还能看到原文。

如果这一轮特别长。 比如你贴了一段很长的错误日志,长到"最近的这一段"本身就超预算:这一轮会被拆成两份摘要(历史摘要 + 本轮前缀摘要),而不是硬塞进去。

四、压缩要回答三个问题

什么时候触发

判断很直白:已经用掉的 token 超过"窗口减去预留量"。也就是说,不等窗口真的满,提前留出一段余量。

这里有个说法需要更新。旧资料会说"预留是因为摘要本身也要占 token"。新版本里,摘要请求改用模型自己的输出上限,预留量只负责回答"什么时候开始压缩"。所以它现在的准确角色是触发阈值,不是摘要预算。

在哪里下刀

真正的约束只有一条硬的:

绝不切在一条工具结果上,也绝不把调用和它的结果分开。

因为模型服务商要求它们成对出现(见 04 章)。所以切割点会尽量往前找,直到不拆开任何一对为止。

另外两条约束容易被误传:

  • 可以切在一轮中间。如果最近这一段用户消息本身就超过"保留量",Pi 会把这一轮拆成两半:前半进历史摘要,后半单独做一份"本轮前缀摘要"。所以"必须切在轮边界"是错的,正确的说法是"必须切在成对完整的地方"。
  • 压缩记录本身不是切割点。重复压缩的起点是"上次压缩后保留的第一条",不是那条压缩记录。

切掉的部分怎么处理

不是删除,是替换:被切掉的旧消息在投影里被一条摘要替换,原始记录仍然只追加地留在会话文件里。

摘要不是自由文本,而是结构化的:目标、约束、进展、关键决定、下一步、关键上下文,外加读过和改过的文件清单。这样窗口缩小之后,模型依然知道"我们本来要干什么"。

五、token 估算:不精确,但比你以为的准

触发判断需要知道"现在用了多少 token",精确计算代价太高。Pi 的做法分两段:

  1. 先拿最近一次助手回复报告的真实用量作为锚点;
  2. 只对锚点之后新增的尾部消息用字符数估算(图片按固定值换算)。

只有当真实用量不可用、或者被上下文编辑/压缩弄失效时,才退回整段估算。所以"不准"主要发生在尾部增量上,而不是全量。

六、压缩与上下文编辑共用一个"投影"

0.87 之后引入的上下文编辑(见 05 章)和压缩做的是同一件事的两种形式:都不改历史,只改变"模型看到的上下文"。

于是切点计算、token 估算、摘要生成,都基于这份投影:被省略的记录不参与切点、不计入 token、不进摘要,但它们仍在磁盘上,导出时照样能看到。

这也解释了为什么恢复会话时要做一次"投影重建"——不重建,你算出来的预算和实际发给模型的就不是一回事。

当前 Pi 行为

  • 自动压缩默认开启(默认预留 16384 token、保留 20000 token);也可以手动触发并给一句聚焦指令(比如"重点总结改了哪些文件")。
  • 触发条件是"已用 token 超过窗口减去预留量";预留量只决定何时开始,不再限制摘要长度。
  • 切割点从不落在工具结果上;切到带工具调用的助手回复时,它的结果随后被保留。
  • 超长的一轮会拆成两份摘要:历史摘要 + 本轮前缀摘要。
  • 压缩记录本身不是切割点;重复压缩从"上次保留的第一条"起算。
  • 在会话树里切换分支时,会先询问要不要给离开的分支留摘要,可以选择不要。
  • session_before_compact 这个钩子可以在压缩前取消,或者自己提供摘要。
  • 压缩属于"耗时准备":准备结束后会再取一次用户插话,所以压缩期间打字不会丢。
  • 生成摘要时会省略思考块(重放的思考常常不在活跃上下文里,带上反而可能让摘要请求比被摘要的内容还大),并把单条工具结果截到 2000 字符。
  • 可以按"服务商 / 模型"单独覆盖预留量与保留量。

代码里的名字

通俗说法 代码里的名字
触发判断 shouldCompact
预留量 / 保留量 reserveTokens / keepRecentTokens
切割点 findCutPoint
压缩记录 compaction + 摘要消息
压缩前钩子 session_before_compact
按模型覆盖 compaction.modelOverrides

源码位置

  • packages/coding-agent/src/core/compaction/:切点、摘要、分支摘要。
  • packages/coding-agent/docs/compaction.md:行为与配置的一手说明。
  • packages/agent/src/agent-loop.ts:准备阶段之后补取插话的地方。

失败与边界实验

对应测试覆盖三类边界,都指向同一条不变量——压缩后历史仍然合法:

  1. 切在工具批中间。 摘要替换旧消息后,某个调用丢了结果,下一轮请求直接被拒。修法:切割点必须对齐"成对完整",要么都进摘要,要么都保留。
  2. 摘要本身溢出预算。 历史太大,摘要又接近上限,压了等于没压。修法:摘要也要受约束;必要时对摘要再压,而不是任它膨胀。
  3. 敏感信息进摘要。 压缩让模型复述历史,密钥、个人路径会被写进摘要并长期驻留。修法:在压缩前钩子里脱敏——这是扩展介入压缩的合法时机。
python3 -m learn_pi_lab lab compaction
python3 -m unittest tests.test_05_compaction -v

在 Pi 里怎么操作

/compact 重点总结这次会话改了哪些文件

不带指令就是普通压缩;带指令时,指令会同时用于历史摘要与本轮前缀摘要(旧版本在拆轮场景里会漏掉后半段,已经修好)。

Python 实验

compaction.py 把"成对不拆"写成一段可以读懂的回退逻辑。核心问题是:保留最新 N 条时,如果第 N 条正好切在一对调用与结果的中间怎么办?

start = max(0, len(units) - keep_units)
while True:
    expanded_start = start
    for indices in pair_indices.values():
        includes_pair_unit = any(index >= start for index in indices)
        excludes_pair_unit = any(index < start for index in indices)
        if includes_pair_unit and excludes_pair_unit:      # 这一对被切开了
            expanded_start = min(expanded_start, min(indices))
    if expanded_start == start:
        break
    start = expanded_start

边界往更旧的方向扩张,直到不再切开任何一对。 注意扩张的是"保留区"——多留几条,而不是把半个对丢进摘要。保留区变大的代价是多占一点预算;拆对的代价是下一轮请求直接非法。

还有一个细节:_pair_indices 在入口处就断言每个配对编号恰好出现两次。这把"配对完整性"从一条口头约定,升级成了构造时就检查的约束。

零预算的语义也值得看:保留量为零时什么都不留,包括完整的对——摘要替换全部历史。这是合法的极端情况,不是 bug。

Tau 的做法类似,只是用"被替换的记录编号"来记录,回放时把旧消息换成摘要。

python3 -m learn_pi_lab lab compaction   # 打印保留集合与摘要集合

这一模块的核心代码在核心代码导览 · 压缩切割点有逐段解读。

验证方式

python3 -m unittest tests.test_05_compaction tests.test_03_context_files tests.test_06_resources -v

边界与安全

  • 压缩前后都应该能回答:保留了哪个目标、哪些文件被改过、哪些工具结果仍然相关。
  • 摘要里的不确定必须标明,不能伪造验证结果。
  • 本课程实验不估算 token、不调用模型、不写 Pi 的会话文件。

自测三问

  • 为什么切割点可以落在一轮中间,却绝不能落在一个工具结果上?
  • 预留量变小,会让压缩更频繁还是摘要更短?
  • 上下文里省略掉的记录,为什么还会影响"压缩从哪儿开始"?

回顾

  • 两层防护:输入侧截断工具输出,历史侧压缩旧对话。
  • 压缩不是丢消息,是让模型总结自己:摘要留在上下文里保住因果。
  • 切割点的铁律是"不拆对":可以跨轮,不可以拆开调用与结果。
  • 阈值与摘要预算是两件事:预留量只决定何时开始。

窗口管理之外,还要面对"换模型、接多家服务商"——下一章Provider 与模型。