$ cat ~/map/pi-rolling-compaction.md

pi-rolling-compaction

在上下文达到窗口的可配置阈值（默认 50%）时即触发 pi 内置压缩，让大上下文模型始终拿到一份持续维护的滚动摘要，避免在接近满载时一次性丢失大量历史。

extensions✓ 10月16日

cp rolling-compaction.ts ~/.pi/agent/extensions/

## 速览

pi 的 Codex 式滚动摘要——单文件扩展，按上下文窗口的百分比（默认 50%）触发压缩而非临近打满才触发，让大窗口模型始终保持一份持续维护的摘要。

## 要点

• $pi 内置自动压缩只在 contextTokens 超过 contextWindow 减 16384 时触发——百万 token 窗口的模型上约为 98%，实际等于永远不触发；本扩展改为按百分比阈值（默认 50%）触发。
• $由于 pi 每次压缩都会把上一份摘要折入，反复在阈值处触发即得到真正的滚动摘要：旧工作保持压缩，近期工作逐字保留（keepRecentTokens 默认 20000）。
• $单文件扩展：把 rolling-compaction.ts 复制进 pi 的自动发现目录（~/.pi/agent/extensions/）即在每个会话生效；也可用 pi -e ./rolling-compaction.ts 单次试用。
• $工作原理：监听 agent_settled，检查 ctx.getContextUsage()，再以 Codex 风格的摘要指令调用 ctx.compact()——覆盖目标、带理由的决策、任务状态、文件读改情况与下一步；循环守卫防止重复触发。
• $v2 加固：经 before_agent_start 把压缩推迟到排队轮次落定，把 session_compact 事件视为即发即忘的 ctx.compact() 唯一成功信号，并设 3 分钟安全计时器，超时未触发即重置守卫。
• $配置方式：环境变量 PI_AUTOCOMPACT_THRESHOLD 或改文件里的 THRESHOLD_PERCENT；keepRecentTokens 与 reserveTokens（16384 兜底）通过 ~/.pi/agent/settings.json 的 compaction 块设置。
• $摘要由当前对话模型生成；想换更便宜的模型，可参照 pi 的 custom-compaction 示例和 session_before_compact 钩子。

## 常见问题

## 参考链接

• README ↗

最后更新: 2026年8月31日