$ cat ~/map/pi-rewind-hook.md

pi-rewind-hook

记录文件状态回滚点的 pi 扩展——/tree 导航、分支与会话恢复都能在对话之外把文件精确还原到某个时间点。

extensions✓ 10月16日

pi install npm:pi-rewind-hook

## 速览

pi 扩展——把精确的文件状态回溯点记录为会话内的隐藏条目，在 /tree 导航以及跨分叉、跨恢复的会话中都能还原文件状态，快照以 git 提交挂在单一 ref 下保存。

## 要点

• $记录精确的文件状态回溯点，在 /fork 与 /tree 导航及跨恢复、跨分叉会话中提供还原；元数据以隐藏条目存在会话自身里，因此回溯历史能在分叉、恢复、树导航和压缩后存活。
• $快照提交通过单一的仓库本地 ref（refs/pi-rewind/store）保持可达，而非每个检查点一个 ref；权威来源是会话账本，worktree 树 SHA 相同时会复用既有快照提交去重。
• $/fork 提供四种选项：仅会话（保留文件）、全部还原（文件加会话）、仅代码（还原文件保留会话）和撤销上次文件回退；/tree 提供保留当前文件、还原到该点文件和撤销上次回退。
• $还原覆盖已跟踪文件和未跟踪且未忽略的文件，且不暂存真实 git 索引；被忽略文件、空目录以及 toolResult、bashExecution 节点不在范围内，并且只能在 git 仓库中使用。
• $回溯点经 parentSession 链跨会话谱系解析；v2 只读会话原生的 rewind-turn 与 rewind-op 元数据，不再读取旧版检查点 ref。
• $~/.pi/agent/settings.json 中的可选 retention 用 maxSnapshots、maxAgeDays 约束未固定的快照，支持固定带标签条目及 scanMode、startupBudgetMs；不配置则永久保留精确历史。
• $与 pi-custom-compaction 协作：精确检查点可绑定到自定义压缩标记所在的会话树节点，/tree 便能直接在其上提供还原——这是可选项，默认压缩检查点无需伴侣扩展照常工作。

## 常见问题

## 参考链接

• README ↗

最后更新: 2026年8月31日