1. 独立仓库管理#

插件会自动在本地创建一个独立的 Git 仓库（Shadow Git），用于存储所有的快照。与用户的主项目 Git 仓库不同，Shadow Git 专注于“快照管理”，而非“版本控制”。

2. 非侵入式操作#

在快照创建过程中，插件通过 pi.appendEntry() 将快照元数据写入 Pi 的会话树。同时，它会调用 Git 命令将当前工作区的文件状态提交到 Shadow Git 中。关键点在于，它拒绝直接修改用户主项目的 Git 提交、分支、索引或 reflog。这避免了插件误操作污染用户的代码历史。

3. 处理未跟踪文件与 Shell 输出#

Shadow Git 策略的另一大价值在于它能处理主 Git 仓库难以覆盖的场景。在 AI 编码过程中，可能会产生大量的临时文件、Shell 命令输出文件，甚至是未跟踪的配置文件。传统的 Git Diff 难以捕捉这些非代码变更。Shadow Git 通过捕获完整的文件系统状态，确保了快照的完整性，使得 AI 能够恢复到包含所有这些临时产物的时间点。

1. 资源限制：快照数量上限#

为了防止磁盘空间无限膨胀，插件设定了严格的限制：每个会话最多保留 100 个 checkpoint。当达到上限时，系统将无法创建新的快照。这意味着用户必须主动管理历史节点，或者依赖插件提供的 /redo-rewind 命令来撤销最近的恢复操作，从而腾出空间。

2. 安全性约束：拒绝符号链接与硬链接#

在文件恢复机制中，项目明确拒绝了通过符号链接或硬链接进行恢复。这一设计是为了防止“写穿链接”攻击或文件系统损坏。通过强制进行文件内容的完整拷贝，插件确保了快照的独立性和安全性，避免了因主项目文件变动导致快照失效的风险。

3. 语言适配与运行时环境#

插件内置了运行时中英文适配逻辑，确保在不同语言环境的系统下，UI 提示与日志输出保持一致。然而，这并不意味着它能完全隔离运行时环境。如果 AI 在容器或虚拟机中运行，且容器未挂载 Shadow Git 仓库，快照功能将失效。因此，该工具的适用边界是本地文件系统，而非远程容器环境。

安装与配置#

1. 安装插件：在终端中运行以下命令安装 pi-claude-rewind。

   1
   npm i pi-claude-rewind
   2
   # 或使用 Pi 的包管理器
   3
   pi install npm:pi-claude-rewind

   安装完成后，插件将自动在 Pi 的会话树中注册其功能模块。

2. 启用会话树：在 Pi 的交互界面中，按下快捷键（如双击 Esc）以打开原生会话树。

验证步骤#

1. 创建初始状态：在当前目录创建一个文件 test.txt，写入初始内容，并提交到 Shadow Git（或等待插件自动触发）。
2. 触发变更：在 Pi 中发送指令修改 test.txt 的内容。
3. 创建快照：在发送新指令前，触发插件快照功能，或依赖其自动在每次用户提示词前建立 checkpoint。
4. 执行回退：在会话树中找到上一个节点，点击恢复。
5. 验证结果：检查 test.txt 的内容是否恢复到了快照时的状态，且未影响主项目的 Git 历史。

检查清单#

• Shadow Git 仓库是否在项目根目录下创建？
• 是否能通过双击 Esc 打开会话树？
• 恢复后，未跟踪文件是否也被正确还原？
• 主项目的 Git 提交记录是否保持干净？