@betterlmy/pi-auto-compact

Pi 编码助手的自动上下文管理插件：对话再长，任务不中断，关键信息不丢失。

English | 简体中文

这个插件解决什么问题？

先解释两个概念：

上下文：AI 处理任务时能"看到"的全部内容，包括你提出的要求、它的回答、执行过的命令和输出。上下文有大小上限，占满后就装不下新内容。

压缩：当上下文接近上限时，把之前的内容整理成一份较短的摘要，腾出空间继续工作。

Pi 自带压缩功能，但默认触发得太晚（通常要到占用 98% 左右），带来两个常见问题：

1. 打断工作：压缩经常发生在任务进行到一半的时候；
2. 摘要丢信息：整理出的摘要可能漏掉改过的文件路径、执行过的命令、当前的任务目标。

本插件对压缩的时机和内容都做了管理，避免这两个问题。

装上之后有什么不同？

1. 达到阈值强制压缩，压完自动继续跑

• 上下文占用达到设定的阈值（默认 75%，支持会话级或全局调整）时，插件立即强制触发压缩（无论是在工具执行中途还是单轮沉淀后），不再等到上下文爆满或死等停机。
• 自动无缝续跑：压缩完成后，插件自动发送隐式接续指令唤醒 Agent 继续执行未完成的任务，无需手动输入“继续”，体验与 Codex / Claude Code 等主流 Agent 一致，长任务永不中断。
• 如果某一步操作（例如读取超大文件）让占用瞬间超过 92%，插件自动提升为紧急熔断保全，除压缩事实外额外保全被中断的工具断点信息，保证续跑无缝接上。

2. 压缩前先提取关键事实，摘要不遗漏

压缩之前，插件从对话记录中直接提取以下信息，连同摘要要求一起交给 AI：

• 修改过的文件（精确路径）
• 查看过的文件
• 执行过的命令
• 当前的任务目标

这些信息来自逐条核对的原始记录，不依赖 AI 的记忆，摘要因此不容易出错。

3. 压缩后自动核对，漏了就补回

摘要生成后，插件核对上述信息是否都保留在摘要里。发现遗漏时，插件把缺少的内容补充到对话中，界面上不会显示任何内容。下一步工作开始时，信息是完整的。

4. 超长输出先裁剪，再进入上下文

一条命令的输出如果有几十万个字符，插件会在它进入上下文之前裁掉中间部分，保留开头和结尾，并注明省略了多少字。多数情况下，占用达不到 92%，紧急压缩自然也很少发生。

5. 安全压缩防溢出守护（杜绝 400 报错与死锁）

长会话中开启推理思考（Thinking）时，原生压缩会把几十万字符的思考草稿全量塞入摘要请求，极易触发 400 ContextWindowExceededError 并导致死锁。本插件提供安全防护：

• 剥离无用 Thinking：生成摘要时自动过滤思考过程，节省大量 Token 与调用成本；
• Token 预算硬约束：根据模型上下文窗口设定安全上限，会话过长时自动保留最初目标和最新状态并修剪中部，确保 Prompt 绝不越界；
• 确定性自愈快照：遇到网络异常或模型故障时，自动基于已提取的代码与命令事实生成保底快照，确保压缩正常落地，彻底解救卡死会话。

6. 会话统计

本次会话压缩了几次、裁剪了几次、紧急处理了几次，都有记录。中途关闭 Pi 后重新恢复会话，记录仍然保留。随时用 /auto-compact status 查看。

7. 两种状态栏显示

• 默认：状态栏显示 compact: 75%，不占用其他位置，与界面美化类插件兼容。
• 接管：运行 /auto-compact footer 后，占用信息合并到 Pi 原生统计行末尾，显示为 14.1%/1.0M (auto:75%)；压缩进行中显示 (auto:compacting...)。

接管模式下，占用数字会随用量变色：越接近触发线越红——以「当前用量 ÷ 触发线」的比值取色，绿色起步，接近一半时变琥珀色，到达触发线时变红（例如触发线 60%、当前 50%，则取 50/60 ≈ 83% 处的颜色）。不需要的话用 /auto-compact progress 关掉，回到红/黄/蓝三档固定色。

安装

在终端执行以下任一命令，然后重启 Pi（或运行 /reload）：

# 从 npm 安装（推荐）
pi install npm:@betterlmy/pi-auto-compact

# 或从 GitHub 安装
pi install git:github.com/betterlmy/pi-auto-compact

默认配置即可使用，不需要额外设置。

常用命令

| 命令 | 作用 | | :--- | :--- | | /auto-compact 80 | 把自动压缩的触发线调整为 80%（默认仅当前会话生效） | | /auto-compact global 80 | 将自动压缩触发线设置为 80% 并保存为全局默认 | | /auto-compact | 打开对话框调整触发线（可输入数值或加 global） | | /auto-compact footer | 切换状态栏显示方式 | | /auto-compact progress | 切换占用数字的渐变变色 | | /auto-compact status | 查看当前生效阈值（区分当前会话/全局）和会话统计 | | /auto-compact setup | （可选）把 Pi 自带的兜底压缩配置调整为推荐值 |

配置（可选）

配置文件位于 ~/.pi/agent/auto-compact.json：

{
  "threshold": 75,
  "customFooter": false,
  "progressColor": true,
  "autoManageSettings": false,
  "safeCompaction": true,
  "maxToolResultChars": 50000
}

• threshold：全局自动压缩触发线，上下文占用的百分比（默认 75）。每次启动新会话默认加载该全局值。执行 /auto-compact 60 仅调整当前会话，执行 /auto-compact global 60 才会改写此全局配置。
• customFooter：是否使用接管式状态栏（默认关闭）。
• progressColor：占用数字是否随用量渐变变色（默认开启）。关闭后改为三档固定色：超过 90% 红色、超过 70% 黄色、其余蓝色。
• autoManageSettings：是否允许插件自动调整 Pi 自带的兜底压缩配置（默认关闭）。
• safeCompaction：是否启用安全压缩防溢出守护与 Thinking 剥离（默认开启）。
• maxToolResultChars：单条输出进入上下文前的字符数上限，超出部分裁剪（默认 50000，设为 0 关闭）。

常见问题

需要会编程吗？ 不需要。安装并重启 Pi 即可，默认配置就能工作。

会影响我的文件吗？ 不会。插件只处理对话记录本身，不读写你的项目文件。

什么时候会压缩？ 两种情况：占用达到 75% 且 AI 恰好处于步骤之间的空闲；或某一步操作让占用瞬间超过 92%。其余时间不干预。

压缩有额外成本吗？ 压缩本身是一次 AI 调用（把之前的内容读一遍、写成摘要），成本与普通对话相当。默认的 75% 触发线就是为了选一个合适的时机完成这件事。

给开发者

npm test           # 运行测试
npm run typecheck  # 类型检查

开源协议

本项目采用 MIT 许可证。 设计思路参考了 pi-smart-compact (alpertarhan) 与 agent-context-guard-pi (j1nn0)。