pi-mctx

pi 的手动上下文管理插件。两个互补操作, 把上下文的管理权交给用户——不自动、不后台、不按阈值替你做决定。

命令

/mctx new [补充指示] — 蒸馏重置

把当前会话交给 LLM 蒸馏成一份四段式 kickoff prompt (上下文精华 / 当前任务 / 需要读取的文件 / 接下来做什么), 然后清空上下文进入新会话, prompt 以编辑器草稿预填, 你审查、编辑后回车提交才真正进入上下文。

• 旧会话文件保留 (parentSession 关联), /resume 可随时回溯
• 总结失败 / Esc 中止时, 当前上下文零影响
• 补充指示可引导总结侧重点: /mctx new 重点保留数据库设计决策
• "需要读取的文件"由 toolCall 机械提取的事实清单约束, LLM 只能从中选择, 不会编造路径

适合: 任务阶段切换, 上下文里堆满了上一个阶段的探索残留。

/mctx sink [--keep N] / --undo — 工具结果下沉

把确定用完的大块工具输出 (构建日志、测试输出、大文件读取等) 移出发给模型的请求, session 原文不动, 模型需要时用 obs({ id }) 整条无损读回。

/mctx sink              沉掉所有合格结果 (纯文本且 >= 2KB)
/mctx sink --keep 5     保留最近 5 条合格结果, 其余下沉
/mctx sink --undo       撤销本会话全部下沉

• 下沉后原位置显示占位符, 模型按需 obs({ id }) 读回
• 批量只断一次缓存前缀, 分多次下沉会多次断裂——一次沉完
• 存储在 <tmpdir>/pi-mctx/<sessionId>/, 重启 / 系统清理 tmp 后自动回滚为未下沉, 无数据损坏
• 失败的命令输出 (构建失败、测试失败) 同样可沉——通常正是最大最该移出的内容

适合: 会话还要继续, 但早期的大块输出确定不再需要。

配置 (可选)

~/.pi/agent/pi-mctx.json:

{
  "sink": {
    "minBytes": 2048,
    "placeholder": "[系统操作提示] 此结果已移出上下文。需要时调用tool： obs({ id: \"{id}\" }) 取回。"
  }
}

文件不存在时全部使用默认值。

本地测试

pi -e ./pi-mctx/index.ts

调试日志默认关闭。开启方式: 环境变量 PI_MCTX_DEBUG_ENABLED=1 后启动 pi (无需改代码), 输出到 <tmpdir>/pi-mctx/debug.log, 记录命令入口 / 候选筛选 / 投影命中 / obs 回读 / LLM 调用全过程。

设计

完整设计 (含决策记录与调研附录) 见 docs/design.md。

License

MIT