---
slug: "tokenroll-pi-cpat"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/tokenRollAI/pi-cpat@main/README.md"
repo: "https://github.com/tokenRollAI/pi-cpat"
source_file: "README.md"
branch: "main"
---
# pi-cpat — Context Patch as Tool for pi

把 [CPAT](https://github.com/tokenRollAI/CPAT)(Context Patch as Tool)这套**主动上下文治理**方案带进 [pi coding agent](https://pi.dev)。

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

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

## 安装

```bash
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>/`。

## 开发与发布

```bash
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](https://pi.dev/packages) 画廊(预览图 `assets/preview.png`)。

## 致谢

- [CPAT](https://github.com/tokenRollAI/CPAT) — 原型、研究与全部设计决策
- CAT 论文([arXiv:2512.22087](https://arxiv.org/abs/2512.22087))— 范式来源