pi-cpat — Context Patch as Tool for pi

把 CPAT(Context Patch as Tool)这套主动上下文治理方案带进 pi coding agent。

核心命题:上下文管理不该是框架在阈值处的被动压缩,而应是 agent 的主动、可逆决策。runtime 只发预算压力信号;选择压缩 / 卸载 / 恢复哪些 block 的,是 agent 自己。

CPAT 原型研究(受限窗口、超长程深度研究任务)显示:200K 窗口下,主动治理与被动阈值压缩同样达到 100% 准确率,但只花 1/5.8 的 prompt tokens(省 83%)——机制是"读完即 offload",context 始终压在低位,而不是背着近满窗口等阈值触发。

安装

pi install git:github.com/tokenRollAI/pi-cpat
# 或本地开发:
pi -e /path/to/pi-cpat

工作原理

pi 的 session 文件是 append-only 的,原文永不丢失。CPAT 在其上做零拷贝视图治理:

ContextBlock   可寻址、可 patch 的治理单元,按指纹映射到 session 消息
ContextView    每次 LLM 调用前(pi `context` 事件)按 block 状态渲染的消息列表
ContentStore   payload 离开视图时(offload/replace)存一份,artifact://<key> 是恢复通道
Journal        append-only 审计日志(ingest / patch / llm_call),可重放全部治理决策

每轮流程:

1. 同步:session 消息 ↔ block(新消息自动建块,旧块保持治理状态)。
2. 预算检查:70% soft → 80% must_act → 95% critical(runtime 兜底强制 offload 最大的 inline tool result)。token 估算用字符启发式起步,每轮用 provider 返回的真实 prompt tokens 在线校准——学习一个加性开销(system prompt + 工具 schema 等治理视图看不到的部分,EWMA 平滑,/cpat 可见)。
3. 渲染:hidden/archived 块移出视图;offloaded 块渲染为「一行摘要 + artifact 引用」;summary 块注入原位置。
4. 易变尾部:budget report + <context_manifest> 作为最后一条消息追加——稳定前缀持续命中 provider cache。

agent 通过两个工具治理:

• context_update — 事务式原子 patch:任一 op 被拒则整体不生效,全部 rejection 返回供修正重试。
• artifact_get — 按 artifact://<key> 临时取回已 offload 的全文。

8 个原子操作

op	作用	可逆性
set_visibility	archive(留 manifest 可恢复)/ hidden(彻底移出)/ model(恢复)	高
payload_offload	大 tool_result → 一行摘要 + artifact 引用	高(restore)
restore	把已 offload 的 payload 全文回填(offload 的逆操作)	—
compact	一组完成的探索 → 一个 dense summary(源块归档)	中
fold	一段连续子任务轨迹 → 一个 scoped summary	中
merge	2+ 重叠/重复块 → 一个 canonical 块	中
replace(gated)	改写非 protected 块内容	低
redact(gated)	删除 inline JSON tool_result 的字段	低

关键护栏(与 CPAT 原型一致):

• chain_atomicity:tool-call 链(assistant 头 + 它全部 tool results,含已 offload 的)必须整体 patch,否则拒绝——破链会导致下一轮 API 400。
• protected_current_question / protected_state:当前问题与任务状态不可被 compact/fold/merge 吞掉(防语义漂移,CPAT 研究中实测的失效模式)。
• protected 原件(用户消息)只能 archive,不可 hidden / replace。

与 pi 内置 compaction 的关系

完全接管:session_before_compact 一律返回 cancel: true。触发时(manual/threshold/overflow)CPAT 先跑一次 critical 兜底强制 offload,保证下一轮视图缩回窗口内。若想回到 pi 原生 compaction,/cpat off 即可。

命令与配置

/cpat            状态总览(压力、视图 token、块统计、patch 计数)
/cpat manifest   查看当前 context manifest
/cpat journal    最近 10 条 patch 事务
/cpat on|off     开关治理

CLI flags:

--cpat-max-context <tokens>   治理预算(默认:模型窗口的 85%)
--cpat-allow-replace          开启 gated replace op
--cpat-allow-redact           开启 gated redact op
--cpat-off                    启动时禁用

治理状态经 pi.appendEntry 持久化在 session 里,/resume 后自动重建;offload 的 payload 落盘 ~/.pi/agent/cpat/<sessionId>/。

开发与发布

npm install
npm test          # 22 个离线测试(patch 引擎 + 校准 + schema 归一化,不调 API)
npm run typecheck

发布到 npm 后即可 pi install npm:@tokenroll/pi-cpat;package.json 已带 pi-package keyword 与 pi.image gallery 元数据,会出现在 pi.dev/packages 画廊(预览图 assets/preview.png)。

致谢

• CPAT — 原型、研究与全部设计决策
• CAT 论文(arXiv:2512.22087)— 范式来源