pi-midcompact

English

Attention-aware 的上下文中段压缩：压缩噪声，保留关键信息。

这里的 Attention-aware 借用注意力机制的核心想法：保留与压缩的判断，要看后续工作仍需关注什么，不能只按消息新旧划分。长会话里的内容不会同时失去价值。早期探索、失败尝试、常规工具输出，以及已经完成的实现过程，在对应工作结束后往往只有很少的后续价值，却可能占据大部分上下文。相比之下，较早的用户需求、关键决策或尚未解决的错误，仍可能需要保留原文。

Pi 内置的 /compact 可理解为前缀压缩（prefix compaction）：它把一段较早的连续历史汇总为一份摘要，并保留近期上下文。这适合自动维护会话；不过，切分边界本身不会区分可舍弃的早期探索和应保留原文的较早决策。

pi-midcompact 名称中的 mid 指向另一种做法：上下文中段压缩（mid-context compression）。它在活跃上下文内部选择区段压缩，让两侧仍有价值的内容保留原文，并保留原始会话历史，供需要时召回。

• 可选择多个对话区段进行压缩。
• 区段边界和摘要均须审查后才会生效。
• 原始 Pi 会话条目可在需要时由 Agent 召回。
• 压缩状态只在当前会话树分支生效。

它解决什么问题

在合适的工作节点，pi-midcompact 会把当前会话叶节点冻结为锚点，并开启独立事务。Agent 负责为已经完成、后续价值较低的阶段拟定压缩区段，关键消息保留原文；草案必须经过审查，只有显式提交后才会生效。

用户确定方向，Agent 设计方案

这套流程由 Agent 推动，方向由用户确定。用户只需说明希望保留什么、准备压缩到什么程度；Agent 会查看冻结后的锚点，与用户讨论取舍，拟定待压缩区段和摘要。用户不必自己定位对话原子编号。

“我只想回收大约 30% 的陈旧上下文，不要压得太狠；早期决策背后的推理请保留原文。”

这里的比例只作规划参考，语义上的重要性高于精确比例。Agent 会把要求转成一份可审查的方案：列出拟压缩区段、明确 KEEP 保留区，并为每个区段撰写摘要。用户可以批准、修改或否决，再决定是否提交。

在临时分支中规划，提交后选择性投影

/midcompact:start 会把当前会话叶节点冻结为锚点。规划工作发生在临时子分支上，因此用于制定和修改草案的对话不会进入提交后的工作上下文。

冻结锚点：原始会话历史

  [早期探索]────[保留的决策]────[常规工具输出]────[最近工作]  ◀ 锚点
      ╰── d1 ──╯                       ╰── d2 ──╯

规划工作在临时分支上进行：

  ... [最近工作] ──┬── [事务] ── [草案 v1] ── [草案 v2]  ◀ 审查 / 修改
                   │                  （提交时舍弃）
                   └── [midcompact-state]                ◀ 提交后的叶节点
                         （记录已审查的选择；不是模型消息；仅由 /midcompact:commit 写入）

后续模型请求看到的是选择性投影后的上下文：

  [d1 摘要]────[保留的决策]────[d2 摘要]────[最近工作]

原始会话 JSONL 仍保留：

  [d1 原文]────[保留的决策]────[d2 原文]────[最近工作]

实际压缩效果

下面的早期浏览器和 TUI 截图展示了一份包含 2 个区段、覆盖 73 个 atom 中 42 个的草案，其余 31 个 atom 保留原文。当前 UI 以 Pi 上报的锚点 usage 为基线，并根据文档化的字符分类假设推导仅供展示的 commit 后占用预计（标注 est.、以区间呈现、绝不参与门禁）；事实性的 content chars 与图片数量仍然并列展示。

前缀压缩与上下文中段压缩

两种机制都保留 JSONL 中存储的原始历史，但它们决定后续模型请求内容的方式不同：

Pi 内置 /compact —— 达到阈值时自动执行，或手动执行一次命令

  [较早的一段连续历史────────────────────][保留的近期上下文]
                         │
                         ▼
  [一份压缩摘要──────────────────────────][保留的近期上下文]

pi-midcompact —— 上下文中段压缩，审查后由用户提交

  [陈旧阶段]────[关键决策]────[常规输出]────[近期工作]
      d1             KEEP            d2
       │                               │
       ▼                               ▼
  [d1 摘要]────[关键决策]────[d2 摘要]────[近期工作]

项目	Pi /compact	pi-midcompact
开始条件	接近上下文上限时自动触发，或运行 /compact	在合适的工作节点运行 /midcompact:start
选择范围	一段较早的连续前缀，并按 token 预算保留近期内容	一个或多个经过审查的区段；支持不连续区段和 KEEP 保留区
规划方式	支持一次性指令，用于限定生成摘要的重点	用户说明范围和保留深度；Agent 讨论取舍并拟定区段与摘要
提交约束	直接生成压缩检查点	先形成草案，再用 TUI 或浏览器审查，最后由用户运行 /midcompact:commit
适用场景	自动维护上下文、从上下文溢出中恢复	清理已经完成的工作阶段，同时保留特定决策原文

pi-midcompact 不会关闭或替代 Pi 的自动压缩；它提供另一条经过人工审查的选择性压缩路径。Pi 内置机制可参阅 Pi 的 compaction 文档。

安装

从 npm 安装：

pi install npm:pi-midcompact

从 GitHub 安装：

pi install git:github.com/frostime/pi-midcompact

安装后重启 Pi，或运行 /reload。此扩展适用于 Pi 0.84.x。

使用方法

应在合适的工作节点启动事务：当前阶段已完成到足以概括的程度，且 Pi 处于空闲状态。当前节点会成为冻结的锚点。Agent 只针对这个快照拟定方案，之后的规划对话不会意外进入被压缩的工作上下文。

1. 设置压缩检查点

运行：

/midcompact:start

Pi 会在创建事务状态前提供三个选项：Agent direct、User manual 和 Drop。Agent direct 进入现有的 inventory-first Agent 流程；选择 User manual 后，可以使用 Web UI 或 TUI 粗选范围，再让 Agent 细化区段并撰写摘要。也可以在命令中直接写明初始重点：

/midcompact:start 压缩前期仓库探索过程，但保留用户需求原文。

2. 与 Agent 讨论压缩方案

直接用自然语言说明目标，例如：

压缩前期仓库探索和常规命令输出。
保留用户需求、被否决的数据库方案，以及最终验证错误的原文。
希望回收约 30% 的陈旧上下文，但不要为了凑精确数字而丢失语义差别。

Agent 会在冻结的会话快照中定位相关内容，提出一个或多个区段，并为每个区段撰写摘要。可以要求它保留某条消息、拆分区段，或重写摘要。

3. 审查草案

运行 /midcompact:review，选择推荐的 Web UI 或内置 TUI。也可以直接打开指定界面：

/midcompact:review webui
/midcompact:review tui

两种界面都会把冻结的对话显示为线性时间线。每个条目都会标为 KEEP，或标明其所属的拟压缩区段。请检查区段边界，以及将用来替换原文的摘要。

需要创建或调整区段与 KEEP 保留洞时，使用 Selection：

/midcompact:select
/midcompact:select webui
/midcompact:select tui

TUI 与本地浏览器 Review 界面用于编辑摘要/主题和否决区段。Review 不创建或调整区段边界；边界变化应重新打开 Selection。用户先创建计划后，只需发送普通消息要求 Agent 继续当前 midcompact draft，Agent 会先读取已有计划。

4. 提交已审查的压缩

方案确认后，运行：

/midcompact:commit

这个命令只能由用户执行，Agent 无法自行提交压缩。

Pi 会回到锚点，放弃临时规划分支，保存已审查的压缩状态，然后从提交后的分支继续工作。后续模型请求会收到所选旧区段的摘要，而不是原始消息。

5. 继续工作或放弃事务

提交后可以继续正常工作。若决定不压缩，运行：

/midcompact:abort

该命令会回到锚点，丢弃事务，不改变当前生效的上下文。

原生 TUI 快捷键

在 /midcompact:review tui 中：

n/p 或 Left/Right  选择拟压缩区段
Up/Down、j/k       滚动
PgUp/PgDn          翻页
x                  展开所选区段中的对话原子
e                  编辑所选摘要
t                  编辑所选主题
d                  移除所选区段
Enter/Esc/q        关闭

命令

命令	作用
/midcompact:start [instructions]	显示 Agent direct / User manual / Drop，并在当前会话树叶节点启动事务。
/midcompact:select [tui|webui]	选择 Selection 界面，或直接打开指定界面。
/midcompact:select-webui	/midcompact:select webui 的兼容别名。
/midcompact:review [tui|webui]	选择 Review 界面，或直接打开指定界面。
/midcompact:review-webui	/midcompact:review webui 的兼容别名。
/midcompact:commit	提交已审查的草案；只能由用户执行。
/midcompact:abort	放弃事务并回到锚点。
/midcompact:status	显示当前草案，或本分支已提交的压缩状态。

扩展只在事务进行期间在 Pi 页脚显示规划状态；提交或放弃后会自动清除。

Web UI 开发

在源码 checkout 中，无需启动 Pi 即可用内存 fixture 运行浏览器工作台：

npm run dev:webui
npm run dev:webui -- --port=4180 --no-open

命令会打开一个 fixture router，其中包含 review-ready、review-pending、 selection-mixed、no-telemetry 和 wide-content。每个按钮都会打开一套独立的 工作台和内存草案。刷新浏览器或点击 Close 不会终止 fixture；HTML 修改会自动刷新 页面，导入的 TypeScript 修改会触发进程重启。用 Ctrl+C 停止 router。只有在验证 真实 Pi 会话集成时，才需要使用 dev/midcompact-debug-ui.ts。

保证与限制

• 保留原始历史。 压缩只改变后续模型请求看到的内容，不改写存储的 Pi 消息。
• 匹配失败时保留原文。 若无法精确定位已审查的消息序列，扩展会原样发送历史，而不会删除不确定的内容。
• 状态只在分支内生效。 用 /tree 回到压缩状态之前的节点会恢复原始历史；回到其后代节点则恢复投影。
• 必须人工审查。 Agent 可以提出方案，不能执行 /midcompact:commit。
• 保护工具调用协议边界。 调用及其匹配结果不能被压缩边界拆开。冻结锚点中确认没有任何结果的调用可作为废弃交互整体压缩；关系不明确的配对和孤立结果仍受保护。
• 支持重复事务。 后续事务可以继续压缩新积累的原始上下文；已有摘要保持受保护状态。
• 与 Pi 原生 /compact 的组合仍需更多真实会话验证。 在完成充分验证前，不应在关键工作中依赖两者混用。
• Provider 与扩展互操作性仍需更多真实会话验证。 非常规消息形态、第三方上下文转换顺序，以及长时间运行的精确消息指纹尚未得到广泛验证。
• 超长会话尚未完成压力测试。 审查快照很大、压缩块反复累积时，最终可能需要进一步整合。
• 浏览器工作台仅在本机开放。 Web UI 界面绑定到 loopback，并与原生 TUI 操作同一份分支内 DraftPlan。