检查点（Checkpoints）——AI 的后悔药

你有没有过这种时刻：AI 帮你改代码，一顿操作猛如虎，结果把好好的项目改崩了？想反悔，却发现 Ctrl+Z 根本不够用。别慌，Hermes Agent 的**检查点（Checkpoints）**功能就是你的后悔药——在 AI 动手搞破坏之前，自动给你的项目拍一张“快照”，随时一键还原。

默认关闭，按需开启

好消息是，这个功能在 v2 里是默认关闭的。因为影子仓库会占点磁盘空间，不是所有人都需要。想用的话，两种方式开启：

临时开启（当前会话）：

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`	列出所有检查点及变更统计
`/rollback <N>`	恢复到第 N 个检查点（保留你手动改的内容，同时撤销上一轮对话）
`/rollback <N> --all`	完全恢复（连你手改的也覆盖）
`/rollback diff <N>`	预览第 N 个检查点和当前状态的差异
`/rollback <N> <file>`	只恢复某个文件

嵌套 Git 仓库：拍不全，也恢复不了

如果你的项目里套着另一个 Git 仓库（比如 vendor/ 或某个 submodule），这里有个重要的坑要提醒你：

父目录的检查点只会把嵌套仓库存成一个 Git gitlink（也就是一个 commit 引用），不会把它里面的文件复制进来。也就是说，嵌套仓库里那些没提交的改动和未跟踪的文件，是没法从这个父检查点里恢复的。

所以从这一版开始：

/rollback 列表里会给这类快照打上标记，比如 before write_file: app.py [nested git repos not captured: tool]，一眼就能看出“这个快照没抓全”。
如果你选中的检查点里含 gitlink，那么完整回滚（包括 --all）会被直接拒绝——在动任何文件、创建回滚前快照之前就拦下来。
选中嵌套仓库本身、它下面的某个文件，或者匹配到它的 Git pathspec，同样会被拒绝，而不是假装成功。
不相关的、已经抓到的文件还是能正常恢复，比如 /rollback 1 notes.txt。

一句话：嵌套仓库请单独备份，或者直接在那个仓库自己的工作目录里单独拍检查点。

影子仓库：不动你的 `.git`

检查点背后是一个共享影子仓库，存在 ~/.hermes/checkpoints/store/。你的真实项目 .git 永远不会被碰。所有项目共用同一个存储，Git 的对象寻址机制会自动去重，省空间。

旁边还有一个 .checkpoints.lock 文件，用来协调多个进程的操作，清空存储后它也会保留。Hermes 运行期间别手动删它。

命令行管理工具

在会话外也能管理检查点：

hermes checkpoints          # 查看总大小、项目数、明细
hermes checkpoints status   # 同上，等价写法
hermes checkpoints list     # status 的别名
hermes checkpoints prune    # 手动清理孤儿/过期数据
hermes checkpoints clear    # 清空所有检查点（会先问你）
hermes checkpoints clear-legacy  # 只删 v1 迁移留下的 legacy-* 归档

配置项一览

checkpoints:
  enabled: false            # 总开关（默认关）
  max_snapshots: 20         # 每个项目最多保留 20 个快照
  max_total_size_mb: 500    # 存储上限 500MB
  max_file_size_mb: 10      # 超过 10MB 的文件不存档
  auto_prune: true          # 自动清理过期数据
  retention_days: 7         # 保留 7 天
  min_interval_hours: 24    # 至少隔 24 小时才扫一次

自动清理现在是后台跑的：CLI 启动后会在辅助线程里扫一遍，网关则在它的日常维护节奏里做。它不会卡住你的输入或启动——毕竟大仓库上跑一次 git gc 可能要几十秒。另外它只删过期的项目条目，不会动那些“工作目录找不到”的孤儿条目（可能是项目被删了，也可能是外接盘/网络共享/VPN 还没挂上，说不准），孤儿清理只走 hermes checkpoints prune，而且会先问你。

存储超过 max_total_size_mb 时，会按项目轮流丢弃最旧的提交，每丢一个就回收一次空间再判断是否还要继续，每个项目至少保留一个快照。如果某次 Git 操作失败，清理会停下并报告，不会为了补上回收失败而多删历史。快照、恢复、diff 和维护共用一把进程级存储锁，遇到别的进程正在操作时会报“存储忙”，而不是在别人未发布的对象上跑 GC；恢复会先应用选中的树，再清理安全快照的历史。快照失败不会阻塞你的工具，清理失败会记警告，显式维护则会报告错误数。

容器后端要注意

如果你用的是容器终端后端（docker、singularity、modal、daytona、vercel_sandbox 或容器插件），文件路径属于沙箱而不是宿主机，Hermes 就不会给这些路径拍快照、也不记 agent 写入台账。这时 /rollback 会告诉你原因：宿主机上已有的检查点还能列出来，但 diff 和恢复会被拒绝——CLI、消息网关、TUI、桌面端都一样，/rollback list 照常能用，/rollback diff 和 /rollback <N> 会被挡下，/diff session 也是同样的理由。本地和 SSH 后端不受影响。

看一眼快照长啥样

在会话里敲 /rollback，会看到类似这样的输出：

📸 Checkpoints for /path/to/project:

  1. 4270a8c  2026-03-16 04:36  before patch  (1 file, +1/-0)
  2. eaf4c1f  2026-03-16 04:35  before write_file
  3. b3f9d2e  2026-03-16 04:34  before terminal: sed -i s/old/new/ config.py  (1 file, +1/-1)

每个快照都标明了触发原因和变更统计，一目了然。

小结

检查点就是给 AI 操作加的一道安全网。虽然默认关着，但如果你经常让 AI 改代码、跑危险命令，强烈建议开起来。毕竟——后悔药这东西，可以不用，但不能没有。