pi-press

pi-press 是一个面向 Pi 的 TypeScript 扩展，在上下文接近压缩阈值时提前在后台生成摘要。

检查点可用后，provider 请求使用“摘要 + 当前未压缩尾部”的虚拟上下文。

当前 agent 运行结束后，再由 Pi 写入正式 compaction entry。

功能与取舍

• 后台生成摘要，不阻塞当前 agent。
• 虚拟上下文只影响当前 provider 请求，不修改 Pi 内部消息或原始 session entry。
• 正式压缩、上下文重建、session 恢复和分支管理继续使用 Pi 原生实现。
• 同一正式压缩周期内可按增量历史连续刷新检查点，避免长时间工具调用使虚拟尾部持续增长。
• 结构化运行事件默认写入独立 SQLite 数据库，可按 session 查询且不参与压缩状态恢复。
• 检查点失效、超过 hard limit 或 provider 请求失败时，使用 Pi 原生压缩。

与 Pi 原生压缩相比，pi-press 可以减少正式压缩时等待摘要的时间，但可能产生额外的 provider 请求和 token 消耗，并需要维护额外配置。完整设计和边界规则见预压缩设计。

安装

运行要求：

• Node.js >=22.19.0
• Pi coding-agent >=0.84.3
• 已配置可用的模型和 provider

# 安装最新版本
pi install npm:@sunnyx11/pi-press

# 固定安装指定版本
pi install npm:@sunnyx11/pi-press@0.4.0

# 在当前进程中临时加载
pi -e npm:@sunnyx11/pi-press@0.4.0

# 更新未固定版本或卸载
pi update npm:@sunnyx11/pi-press
pi remove npm:@sunnyx11/pi-press

pi-press 是 Pi 扩展包，不提供独立 CLI。Pi 扩展与宿主进程具有相同的系统权限，安装前应检查包来源和源码。

配置

配置优先级为：项目配置 > 全局配置 > 内置默认值。

• 全局配置：~/.pi/agent/pi-press.json
• 项目配置：<cwd>/.pi/pi-press.json

全局目录可以通过 PI_CODING_AGENT_DIR 修改。项目配置只需声明需要覆盖的字段。

{
  "precomputeMode": "threshold",
  "softThresholdPercent": 80,
  "taskTimeoutMs": 300000,
  "diagnosticsPersistence": "sqlite",
  "diagnosticsRetentionDays": 30,
  "diagnosticsMaxDatabaseMiB": 64
}

softThresholdPercent 同时用于首次预压缩和后续增量刷新。旧版 targetPostCompactionPercent 已移除；配置中仍存在该字段时会记录一次警告并忽略其值。

precomputeMode 支持以下取值：

值	作用
"off"	停止后台预压缩和检查点复用。
"threshold"	处理阈值触发的后台预压缩、请求级虚拟上下文和 settled 后正式化。
"threshold-and-manual"	在阈值压缩之外，复用没有自定义指令的手动压缩检查点。

完整字段、默认值、校验规则和容量计算见预压缩设计。

诊断查询

默认数据库为 ~/.pi/agent/pi-press/diagnostics.sqlite3，保留 30 天且上限为 64 MiB。SQLite 只保存结构化事件和 Runtime 标量状态，不保存用户消息、完整摘要、工具结果、认证信息或完整 provider 响应。数据库故障不会阻止预压缩或 Pi 原生压缩。

/pi-press-diagnostics
/pi-press-diagnostics --session <session-id> --last 50
/pi-press-diagnostics --session <session-id> --last 100 --json

默认查询当前 session 最近 20 条事件；--last 允许 1..100。设置 "diagnosticsPersistence": "memory" 可以只保留当前进程内诊断。Node 22 使用内置 node:sqlite 时会显示 SQLite 实验性功能警告。

开发

npm install
pi -e ./src/index.ts
npm run typecheck
npm test
npm run test:smoke:pi

npm run test:smoke:pi 使用当前 shell 环境中安装的 Pi 和当前配置模型执行真实 provider 冒烟测试，可能产生调用费用。该命令拒绝仓库本地 Pi；特殊环境可通过 PI_BIN 指定外部 Pi 可执行文件。

项目入口由 package.json 的 pi.extensions 指向 src/index.ts。扩展结构、生命周期、并发、持久化和测试约束见代码规范。

相关文档

• 变更记录
• 预压缩设计
• 代码规范

致谢

感谢 LINUX DO 社区。

许可证

本项目使用 MIT License。