在智能体开发中，文件状态的回滚往往比对话历史的回溯更棘手。当代码生成进入深水区，开发者需要一种机制，能够在对话的每个回合边界保存当前工作区的状态，以便随时回滚文件改动。dsh-tui-checkpoints 旨在解决这一痛点，通过影子仓库机制，为 dsh-TUI 补全文件级别的“真回溯”能力。
下面介绍 dsh-tui-checkpoints 插件。
定位与功能¶
dsh-tui-checkpoints 是一个用于 dsh-TUI 的社区插件。它不会触碰项目原本的 .git 仓库，而是为每个工作区创建一个独立的影子仓库。
核心功能包括：
* 回合快照：在每个 turn 边界自动保存工作区状态。
* 影子仓库：在 ~/.dsh/checkpoints/repos/ 下维护独立的 git 仓库。
* 文件回溯：通过 /checkpoints 面板浏览和恢复文件状态。
* 安全机制：恢复操作前自动创建 safety-* 分支，确保可回滚。
* 撤销能力：支持对文件级别的修改进行回滚。
安装与启用¶
该插件目前处于 Spike（技术验证）阶段，未发布到 npm。需要从源码打包安装。
git clone https://github.com/FUSU123fusu/dsh-tui-checkpoints.git
cd dsh-tui-checkpoints
npm pack
dsh plugin --profile dsh-tui add file:dsh-tui-checkpoints-0.1.0.tgz
安装后，重启 dsh-TUI 即可生效。
功能与用法¶
1. 打开检查点面板¶
在终端中输入命令：
/checkpoints
2. 浏览快照¶
面板列表显示快照的元数据：
* 符号：● 表示轮后快照，◦ 表示轮前快照。
* 信息：Turn 编号、Commit 短 Hash、时间戳。
3. 查看差异¶
选中列表中的某一行，下方会实时显示该快照与当前工作区的差异统计。
4. 恢复文件状态¶
按下 r 键进行恢复。系统会要求在 3 秒内按两次确认。
* 恢复逻辑为 reset --hard + clean，即还原文件内容并删除新增文件。
* 恢复前，当前状态会先提交到 safety-* 分支，因此恢复本身也是可逆的。
5. 对话回溯¶
文件状态恢复后，需配合 dsh-TUI 内置的双击 Esc /rewind 功能，将对话回溯到同一轮，以保持文件与对话的一致性。
原理与细节¶
影子仓库机制¶
插件在 ~/.dsh/checkpoints/repos/<工作区hash>.git 创建影子仓库。项目目录本身被当作该影子仓库的 work tree。这意味着：
* 项目的 .git 目录完全不受影响。
* 即使项目目录不是 git 仓库，插件也能正常工作。
快照时机¶
插件监听 session/event，在顶层会话的 turn/start（轮前）和 turn/end（轮后）各执行一次快照。快照操作是串行排队执行的，如果文件无变化，会复用 HEAD 提交，避免生成大量空提交。
忽略规则¶
默认排除 .git、node_modules 等目录，并读取项目的 .gitignore，将规则写入影子仓库的 info/exclude。
性能表现¶
- 首次全量快照：约 5.8s。
- 无变化快照：约 0.7s（使用
add -A+diff --cached）。
嵌套仓库处理¶
如果工作区包含嵌套的 git 仓库（子模块或 worktree），插件会将其记录为 Gitlink，不展开其内部漂移。
注意事项¶
- Spike 阶段：这是技术验证版本，尚未发布到 npm，代码可能存在不稳定性。
- 文件覆盖风险：恢复操作是工作区级的。如果当前有未保存的编辑内容，恢复时会直接覆盖，尽管这些内容已被安全提交到
safety-*分支。 - 对话与文件分离：对话回溯由 dsh-TUI 内置功能处理，本插件仅负责文件层面的状态管理。
结语¶
dsh-tui-checkpoints 为 dsh-TUI 提供了文件级别的回溯能力，解决了智能体开发中“改代码难回滚”的痛点。虽然目前是 Spike 版本，但其影子仓库的设计思路和双段式恢复机制（文件 + 对话）为未来的核心 PR 提供了验证基础。
