阶段二 · 状态与边界
上下文压缩 —— 窗口装不下时怎么办
上下文窗口是硬上限,对话是无限增长的。Pi 的答案是两层防护:进上下文之前先截断工具输出,历史太长就让模型自己总结旧对话。而压缩只有一条铁律——不能把一次工具调用和它的结果拆开。这一章讲清压缩何时触发、在哪里下刀、切掉的东西怎么处理。
具体回答三个问题:什么时候该压缩?在哪里下刀?切掉的内容去哪了?
学习目标
- 理解两层防护各解决什么问题:输入侧截断,历史侧压缩。
- 理解压缩的触发条件,以及"预留缓冲"这个说法在新版本里的变化。
- 理解切割点的真实约束:不是"不跨轮",而是"不拆对"。
- 理解 token 估算为什么"不精确但够用",以及它其实比你以为的准。
一、问题:窗口是固定的,对话是增长的
模型的上下文窗口是硬上限。对话越聊越长,迟早要撑爆。不处理会怎样?只有两个选择:拒绝继续(用户不能接受),或者静默截断(更糟——模型不知道前面发生了什么,因果断裂,回答质量崩坏)。
Pi 把"窗口"当预算管理:窗口大小是上限,每次请求都在消耗预算;预算不够时,腾出空间。
二、两层防护,各管一段
| 防护 | 时机 | 手段 |
|---|---|---|
| 输入侧 | 工具结果进入上下文之前 | 截断:限行数 + 限字节,双重限制 |
| 历史侧 | 上下文逼近上限时 | 压缩:让模型总结旧消息,保留近期窗口 |
- 输入侧解决"一条命令的输出占满上下文":输出在进上下文之前就被截断,完整内容留在临时文件里。
- 历史侧解决"对话本身太长":旧对话被总结成摘要。
两者都要。只做输入侧,对话照样越来越长;只做历史侧,一条超长输出就能瞬间占满窗口。
截断的两个细节
- 双重限制,先到先算:只限行数挡不住超长单行,只限字节挡不住海量短行。
- 不切半行、不切半个字符:截断只发生在完整行边界;如果第一行就超字节上限,返回空内容并标记,而不是切出半个字符。"被截断了"这件事本身也是结果的一部分——工具会告诉模型"输出不完整,完整内容在临时文件里"。
三、跟着两小时的长对话走一遍
下午两点开始,你和 Agent 一起排查一个线上问题。到四点,对话已经很长了。
先是输入侧的拦截。 中间有一次跑测试,刷了三千行日志。这三千行进上下文之前就被截到 2000 行 / 50KB——完整内容在临时文件里,结果里带着"被截断了"的标记和文件路径。模型因此知道"我看的不是全部",需要时可以让你再取一次。
然后是历史侧。 某次请求前,估算发现用量已经超过"窗口减去预留量"。于是触发压缩:从最新的一条往前找切割点,但每找到一处都先检查是否切开了一对调用与结果——切开就往前退,直到不切。
压缩之后。 前端你能看到一条"已压缩"的提示;模型则看到一段结构化摘要(目标、约束、进展、关键决定、下一步、关键上下文、改过哪些文件),后面接着最近保留的那几条原始消息。中间那段旧对话没有消失——点开会话树还能看到原文。
如果这一轮特别长。 比如你贴了一段很长的错误日志,长到"最近的这一段"本身就超预算:这一轮会被拆成两份摘要(历史摘要 + 本轮前缀摘要),而不是硬塞进去。
四、压缩要回答三个问题
什么时候触发
判断很直白:已经用掉的 token 超过"窗口减去预留量"。也就是说,不等窗口真的满,提前留出一段余量。
这里有个说法需要更新。旧资料会说"预留是因为摘要本身也要占 token"。新版本里,摘要请求改用模型自己的输出上限,预留量只负责回答"什么时候开始压缩"。所以它现在的准确角色是触发阈值,不是摘要预算。
在哪里下刀
真正的约束只有一条硬的:
绝不切在一条工具结果上,也绝不把调用和它的结果分开。
因为模型服务商要求它们成对出现(见 04 章)。所以切割点会尽量往前找,直到不拆开任何一对为止。
另外两条约束容易被误传:
- 可以切在一轮中间。如果最近这一段用户消息本身就超过"保留量",Pi 会把这一轮拆成两半:前半进历史摘要,后半单独做一份"本轮前缀摘要"。所以"必须切在轮边界"是错的,正确的说法是"必须切在成对完整的地方"。
- 压缩记录本身不是切割点。重复压缩的起点是"上次压缩后保留的第一条",不是那条压缩记录。
切掉的部分怎么处理
不是删除,是替换:被切掉的旧消息在投影里被一条摘要替换,原始记录仍然只追加地留在会话文件里。
摘要不是自由文本,而是结构化的:目标、约束、进展、关键决定、下一步、关键上下文,外加读过和改过的文件清单。这样窗口缩小之后,模型依然知道"我们本来要干什么"。
五、token 估算:不精确,但比你以为的准
触发判断需要知道"现在用了多少 token",精确计算代价太高。Pi 的做法分两段:
- 先拿最近一次助手回复报告的真实用量作为锚点;
- 只对锚点之后新增的尾部消息用字符数估算(图片按固定值换算)。
只有当真实用量不可用、或者被上下文编辑/压缩弄失效时,才退回整段估算。所以"不准"主要发生在尾部增量上,而不是全量。
六、压缩与上下文编辑共用一个"投影"
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:准备阶段之后补取插话的地方。
失败与边界实验
对应测试覆盖三类边界,都指向同一条不变量——压缩后历史仍然合法:
- 切在工具批中间。 摘要替换旧消息后,某个调用丢了结果,下一轮请求直接被拒。修法:切割点必须对齐"成对完整",要么都进摘要,要么都保留。
- 摘要本身溢出预算。 历史太大,摘要又接近上限,压了等于没压。修法:摘要也要受约束;必要时对摘要再压,而不是任它膨胀。
- 敏感信息进摘要。 压缩让模型复述历史,密钥、个人路径会被写进摘要并长期驻留。修法:在压缩前钩子里脱敏——这是扩展介入压缩的合法时机。
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 与模型。