检查点（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`

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

命令行管理工具

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

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，而且会先问你。

容器后端要注意

如果你用的是容器终端后端（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 改代码、跑危险命令，强烈建议开起来。毕竟——后悔药这东西，可以不用，但不能没有。