pi DP-Based Compaction Extension

English Documentation

参考 bash-agent 动态压缩决策 实现的 pi 插件，用缓存感知的 DP 经济模型替代原有的固定阈值 compact。

核心思想

原有 pi 的 compact 策略：

• 当 contextTokens > contextWindow - reserveTokens 时触发压缩
• 固定保留最近 keepRecentTokens 的消息

本扩展的 DP 策略：

• 枚举候选保留量 k（保留最近多少条消息）
• 对每个 k 计算五项净收益：
  1. 后续节省：压缩后后续请求少携带旧历史 token 的缓存价节省
  2. 缓存失效：新摘要前缀导致的一次性缓存失效成本
  3. 压缩请求成本：summary call 本身的输入/输出成本
  4. 信息失真惩罚：摘要丢失细节带来的信息损失
  5. 质量改善收益：缩短长上下文带来的质量提升
• 只有最优净收益 > 0 时才压缩
• 切点对齐到 user message 边界，避免从 assistant/tool 片段中间截断

安装

通过 npm 安装（推荐）

从 npm registry 安装（所有会话可用）：

pi install npm:pi-better-compact

或仅在当前项目本地安装：

pi install -l npm:pi-better-compact

通过 Git 安装

直接从 GitHub 安装：

pi install git:github.com/takltc/pi-better-compact

或本地安装：

pi install -l git:github.com/takltc/pi-better-compact

手动安装

1. 复制扩展文件到 pi 扩展目录：

mkdir -p ~/.pi/agent/extensions
cp src/dp-compact.ts ~/.pi/agent/extensions/

禁用内置自动压缩

安装完成后，禁用 pi 内置 auto-compact（在 ~/.pi/agent/settings.json 或项目 .pi/settings.json）：

{
  "compaction": {
    "enabled": false,
    "reserveTokens": 16384,
    "keepRecentTokens": 20000
  }
}

然后启动 pi，扩展会自动加载。

使用

• 自动触发：扩展在每次 agent_end 后检查上下文使用量。当超过 CHECK_THRESHOLD（默认 60%）时，自动触发 compact，但 session_before_compact 中的 DP 模型会决定是否真正执行。
• 手动触发：仍然可以用 /compact [instructions] 手动触发。
• 查看状态：/dp-status 显示当前 DP 参数和会话统计。
• 评估决策：/dp-eval 立即运行 DP 评估，显示是否值得压缩及最优保留量。

参数调优

通过环境变量调整 DP 参数：

| 环境变量 | 默认值 | 说明 | |---------|-------|------| | DP_P_INPUT | 3.0 | 未命中缓存的输入价格 ($/MTok) | | DP_P_CACHE | 0.3 | 命中缓存的输入价格 ($/MTok) | | DP_P_OUT | 15.0 | 输出价格 ($/MTok) | | DP_V | 5000 | 固定前缀 token（system prompt、tools 等） | | DP_S | 500 | 预计 summary 输出 token | | DP_BASELINE_E | 8 | 预计剩余用户输入轮数基准 | | DP_E_FIXED | 0 | 固定 E（>0 时跳过动态估算） | | DP_R | 0.8 | 单次摘要信息保留率 | | DP_BETA | 0.03 | 信息失真惩罚系数 | | DP_QUALITY_PENALTY | 0.2 | 长上下文质量衰减惩罚系数 | | DP_MIN_KEEP_RATIO | 0.12 | 最少保留消息行比例 | | DP_FORCE_THRESHOLD | 0.9 | 强制压缩阈值（context 使用率超过此值） | | DP_CHECK_THRESHOLD | 0.6 | 自动检查阈值（context 使用率超过此值时检查） |

示例：

export DP_P_INPUT=2.0
export DP_P_CACHE=0.2
export DP_FORCE_THRESHOLD=0.85
pi

文件结构

src/
└── dp-compact.ts    # 扩展主文件