检查点与 /rollback

Hermes Agent 会在执行破坏性操作前自动为你的项目创建快照，并允许你用一条命令恢复。检查点默认启用，而且只要没有触发修改文件的工具，就不会产生额外成本。

这个安全网由内部的 Checkpoint Manager 提供，它会在 ~/.hermes/checkpoints/ 下维护一个独立的 shadow git 仓库，你真实项目中的 .git 永远不会被动到。

什么会触发检查点

以下操作前会自动创建检查点：

文件工具 - write_file 和 patch
破坏性终端命令 - rm、mv、sed -i、truncate、shred、输出重定向（>），以及 git reset / clean / checkout

每轮对话中，同一目录最多只会创建一个检查点，因此长会话不会疯狂堆积快照。

快速参考

命令	说明
`/rollback`	列出所有检查点及其变更统计
`/rollback <N>`	恢复到编号为 N 的检查点（同时撤销上一轮聊天）
`/rollback diff <N>`	预览检查点 N 与当前状态之间的差异
`/rollback <N> <file>`	从检查点 N 恢复单个文件

检查点如何工作

高层流程如下：

Hermes 会检测工具何时即将修改工作树中的文件
每轮对话中（按目录分别计算），它会：
- 为该文件解析出一个合理的项目根目录
- 初始化或复用绑定到该目录的 shadow git repo
- 用简短、可读的原因说明暂存并提交当前状态
这些提交共同组成检查点历史，你可以通过 /rollback 查看并恢复

配置

检查点默认启用。可在 ~/.hermes/config.yaml 中配置：

checkpoints:
  enabled: true          # master switch (default: true)
  max_snapshots: 50      # max checkpoints per directory

如需禁用：

checkpoints:
  enabled: false

禁用后，Checkpoint Manager 会变成 no-op，不会尝试执行任何 git 操作。

列出检查点

在 CLI 会话中输入：

/rollback

Hermes 会返回带有变更统计的格式化列表：

📸 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)

  /rollback <N>             restore to checkpoint N
  /rollback diff <N>        preview changes since checkpoint N
  /rollback <N> <file>      restore a single file from checkpoint N

每条记录会显示：

短哈希
时间戳
原因说明（是什么触发了快照）
变更摘要（改动文件数、插入和删除）

用 `/rollback diff` 预览变更

在正式恢复之前，你可以先预览自某个检查点以来的变更：

/rollback diff 1

这会先显示 git diff stat 摘要，再显示实际 diff：

test.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/test.py b/test.py
--- a/test.py
+++ b/test.py
@@ -1 +1 @@
-print('original content')
+print('modified content')

为了避免终端被刷屏，长 diff 最多只显示 80 行。

用 `/rollback` 恢复

你可以按编号恢复到某个检查点：

/rollback 1

Hermes 在后台会执行以下步骤：

验证目标提交在 shadow repo 中确实存在
先对当前状态创建一个回滚前快照，这样之后还能“撤销这次撤销”
恢复工作目录中的已跟踪文件
撤销最后一轮对话，让 agent 的上下文与恢复后的文件系统状态保持一致

成功时会看到类似输出：

✅ Restored to checkpoint 4270a8c5: before patch
A pre-rollback snapshot was saved automatically.
(^_^)b Undid 4 message(s). Removed: "Now update test.py to ..."
  4 message(s) remaining in history.
  Chat turn undone to match restored file state.

撤销对话的意义在于，agent 不会“记得”那些已经被回滚的修改，从而避免下一轮出现上下文错乱。

单文件恢复

如果你只想恢复单个文件，而不影响目录中其他文件，可以这样做：

/rollback 1 src/broken_file.py

这在 agent 同时改了多个文件，但其中只有一个需要回退时尤其有用。

安全与性能保护

为了让检查点既安全又高效，Hermes 加入了多项保护机制：

Git availability - 如果 PATH 中找不到 git，检查点功能会被透明禁用
Directory scope - Hermes 会跳过过于宽泛的目录，例如根目录 / 和用户主目录 $HOME
Repository size - 如果目录中文件数超过 50,000 个，会跳过该目录以避免缓慢的 git 操作
No-change snapshots - 如果自上次快照以来没有变化，就不会创建新检查点
Non-fatal errors - Checkpoint Manager 中的所有错误都只会记录为 debug 日志，工具仍会继续执行

检查点存放位置

所有 shadow repo 都存放在：

~/.hermes/checkpoints/
  ├── <hash1>/   # shadow git repo for one working directory
  ├── <hash2>/
  └── ...

每个 <hash> 都由工作目录的绝对路径派生而来。在这些 shadow repo 中，你会看到：

标准的 git 内部结构（HEAD、refs/、objects/）
一个 info/exclude 文件，其中包含精心维护的忽略列表
一个 HERMES_WORKDIR 文件，用来指回原始项目根目录

通常你完全不需要手动碰这些内容。

最佳实践

保持检查点启用 - 它默认打开，而且没有文件修改时不会产生额外成本
恢复前先使用 /rollback diff - 先预览会发生什么，再选择正确的检查点
想撤销 agent 驱动的改动时，用 /rollback 而不是 git reset
与 Git worktree 搭配使用以获得更高安全性 - 每个 Hermes 会话都放在自己的 worktree / branch 中，检查点则作为额外的一层保险

如果你要在同一仓库中并行运行多个 agent，请参阅 Git worktrees。

什么会触发检查点​

快速参考​

检查点如何工作​

配置​

列出检查点​

用 /rollback diff 预览变更​

用 /rollback 恢复​

单文件恢复​

安全与性能保护​

检查点存放位置​

最佳实践​