第30篇：检查点与回滚——AI 的后悔药

你有没有过这种时刻：AI 助手一顿操作猛如虎，结果把你的配置文件改得乱七八糟，你想回到五分钟前那个“还能跑”的状态，却只能干瞪眼？

好消息是，Hermes Agent 从 v2 开始内置了检查点（Checkpoint） 系统——相当于给 AI 装了一颗“后悔药”。更妙的是，它默认是关闭的，想用才开，不打扰大多数人。

怎么开启？

两种方式，任选其一：

临时开启（仅本次会话）：

hermes chat --checkpoints

永久开启（写入全局配置）：

# ~/.hermes/config.yaml
checkpoints:
  enabled: true

什么时候会自动拍照？

Hermes 会在破坏性操作前自动快照，比如：

文件工具：write_file、patch
危险命令：rm、rmdir、cp、install、mv、sed -i、truncate、dd、shred、> 重定向，还有 git reset / clean / checkout

每个目录每轮对话最多存一个快照，不会刷屏。

怎么用？超简单！

在会话里直接敲：

命令	作用
`/rollback`	列出所有检查点
`/rollback 3`	恢复到第 3 个检查点（保留你手动改的内容）
`/rollback 3 --all`	完全恢复（覆盖你手动改的内容）
`/rollback diff 3`	预览第 3 个检查点和现在的差异
`/rollback 3 config.py`	只恢复单个文件

嵌套 Git 仓库：一个要留心的坑

如果你的项目里套着另一个 Git 仓库（比如 vendor/ 下有个独立 repo），检查点只会把它记成一个 gitlink（一个 commit 引用），不会把它里面的文件一起打包。也就是说，那个嵌套仓库里没提交的改动和未跟踪的文件，是恢复不回来的。

所以：

新版本打的检查点，在 /rollback 列表里会带个标记，比如 before write_file: app.py [nested git repos not captured: tool]，一眼就能看出这次快照没抓到嵌套仓库。
如果你选中的检查点里含 gitlink，那么完整回滚（包括 --all）会被直接拒绝，而且是在动任何文件、创建回滚前快照之前就拒绝——不会给你一个“假成功”。
同理，单独选中那个嵌套仓库、它下面的某个文件，或者匹配到它的 Git pathspec，恢复也会被拒绝，而不是假装成功。
但不相关的、已捕获的文件照样能恢复，比如 /rollback 1 notes.txt 没问题。
想给嵌套仓库上保险，就单独给它做备份，或者直接在它自己的工作目录里打检查点。

背后的黑科技

这个系统靠一个共享的影子仓库工作，存在 ~/.hermes/checkpoints/store/ 里。你项目的真实 .git 完全不会被碰。所有项目共用同一个存储，Git 的内容寻址机制会自动去重，所以不会爆炸式增长。存储旁边还有个 .checkpoints.lock 文件，用来协调多个进程，清空存储后它也会保留——Hermes 运行期间别手动删它。

另外，目录里文件超过 50,000 个的项目会被跳过，不做检查点。

命令行管理

在终端外也能管：

hermes checkpoints          # 查看总大小、项目数
hermes checkpoints prune    # 手动清理孤儿/过期快照
hermes checkpoints clear    # 清空整个检查点库（会先问你）

顺带一提，hermes checkpoints status 和 list 跟裸敲 hermes checkpoints 是一回事；如果你是从 v1 升上来的，还能用 hermes checkpoints clear-legacy 单独删掉迁移时留下的旧归档。

容器后端的小提醒

如果你用的是容器终端后端（docker、singularity、modal、daytona、vercel_sandbox 或容器插件），文件路径属于沙箱而不是宿主机，Hermes 就不会给这些路径做检查点。这时 /rollback 还是能列出宿主机上已有的检查点，但 diff 和恢复会被拒绝，并告诉你原因；TUI 和 Desktop 里也一样，/rollback list 能用，/rollback diff 和 /rollback <N> 会被挡下。本地和 SSH 后端不受影响。

配置调优

checkpoints:
  enabled: true
  max_snapshots: 20          # 每项目最多 20 个快照
  max_total_size_mb: 500     # 总大小上限 500MB
  max_file_size_mb: 10       # 超过 10MB 的文件不备份
  auto_prune: true           # 自动清理过期快照
  retention_days: 7          # 保留 7 天

自动清理现在是后台跑的：CLI 启动后会在辅助线程里扫一遍，网关则在自己的例行维护时扫，不会卡住你的输入或启动（毕竟大仓库上跑一次 git gc 可能要几十秒）。它只删超过 retention_days 的项目，从不动那些“孤儿”条目（工作目录找不到的）——因为目录消失可能是项目删了，也可能是外接盘/网络共享/VPN 还没挂上，所以清孤儿只能靠你手动 hermes checkpoints prune，还会先问你一句。

超过 max_total_size_mb（默认 500MB）时，会按轮转方式丢弃每个项目最旧的提交，每丢一次先回收再判断是否还需要继续；每个项目至少保留一个快照。如果某次 Git 操作失败，清理会停下并报告错误，维护流程不会为了弥补回收失败而多删历史。

另外，快照、恢复、diff 和维护操作共用一把跨进程的存储锁：如果另一个进程正在用这个存储，操作会直接报“存储忙”，而不是在别人还没发布的 Git 对象上跑 GC。恢复时会先把选中的目录树应用好，再去清理安全快照的历史。

快照失败不会阻塞你的工具调用；清理失败会记为警告，手动维护则会报告错误数量。

小结

检查点系统就像游戏里的自动存档——平时感觉不到它的存在，但关键时刻能救你一命。强烈建议开启试试，尤其是做大规模重构或者让 AI 跑危险命令的时候。

下次 AI 把代码改崩了，别慌，一句 /rollback 就能回到从前。这感觉，真香！