检查点和 /rollback

Hermes Agent 在破坏性操作之前自动快照你的项目，让你用一个命令恢复。检查点默认启用 — 当没有文件修改工具触发时零成本。

这个安全网由内部检查点管理器驱动，它在 ~/.hermes/checkpoints/ 下维护一个独立的 shadow git 仓库 — 你的真实项目 .git 永远不会被触碰。

什么会触发检查点

检查点自动在以下之前拍摄：

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

Agent 每个目录每轮最多创建一个检查点，因此长时间运行的会话不会产生快照垃圾。

快速参考

命令	描述
/rollback	列出所有检查点及更改统计
/rollback <N>	恢复到检查点 N（也会撤销最后一个聊天轮次）
/rollback diff <N>	预览检查点 N 与当前状态之间的差异
/rollback <N> <file>	从检查点 N 恢复单个文件

检查点如何工作

高层概述：

• Hermes 检测工具何时要修改你工作树中的文件。
• 每轮对话（每个目录）一次，它：
  • 解析该文件的合理项目根目录。
  • 初始化或重用绑定到该目录的 shadow git repo。
  • 使用简短、人可读的理由暂存并提交当前状态。
• 这些提交形成检查点历史，你可以通过 /rollback 检查和恢复。

配置

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

checkpoints:
  enabled: true          # 主开关（默认：true）
  max_snapshots: 50      # 每个目录最大检查点数

禁用：

checkpoints:
  enabled: false

禁用后，检查点管理器是一个空操作，永远不会尝试 git 操作。

列出检查点

从 CLI 会话中：

/rollback

Hermes 返回格式化的列表，显示更改统计：

📸 检查点 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 摘要，然后是实际差异：

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

长差异被限制在 80 行以避免淹没终端。

使用 /rollback 恢复

通过编号恢复到检查点：

/rollback 1

在后台，Hermes：

1. 验证目标提交存在于 shadow repo 中。
2. 拍摄当前状态的预回滚快照，以便以后可以"撤销撤销"。
3. 恢复你工作目录中的跟踪文件。
4. 撤销最后一个对话轮次，使 Agent 的上下文与恢复的文件系统状态匹配。

成功时：

✅ 已恢复到检查点 4270a8c5: before patch
已自动保存预回滚快照。
(^_^)b 撤销了 4 条消息。已删除："Now update test.py to ..."
  4 条消息留在历史中。
  聊天轮次已撤销以匹配恢复的文件状态。

对话撤销确保 Agent 不"记住"已被回滚的更改，避免下一轮混淆。

单文件恢复

从检查点仅恢复一个文件，不影响目录的其余部分：

/rollback 1 src/broken_file.py

当 Agent 更改了多个文件但只需要还原一个时，这很有用。

安全和性能保护

为保持检查点的安全性和快速性，Hermes 应用了几种保护措施：

• Git 可用性 — 如果在 PATH 上找不到 git，检查点会被透明地禁用。
• 目录范围 — Hermes 跳过过于宽泛的目录（根 /、主目录 $HOME）。
• 仓库大小 — 超过 50,000 个文件的目录会被跳过以避免缓慢的 git 操作。
• 无更改快照 — 如果自上次快照以来没有更改，则跳过检查点。
• 非致命错误 — 检查点管理器内的所有错误都以调试级别记录；你的工具继续运行。

检查点存储位置

所有 shadow repos 位于：

~/.hermes/checkpoints/
  ├── <hash1>/   # 一个工作目录的 shadow git repo
  ├── <hash2>/
  └── ...

每个 <hash> 派生自工作目录的绝对路径。在每个 shadow repo 内你会发现：

• 标准 git 内部文件（HEAD、refs/、objects/）
• 包含精选忽略列表的 info/exclude 文件
• 指向原始项目根目录的 HERMES_WORKDIR 文件

你通常不需要手动触碰这些。

最佳实践

• 保持检查点启用 — 它们默认开启，在没有文件被修改时零成本。
• 恢复前使用 /rollback diff — 预览会更改什么以选择正确的检查点。
• 使用 /rollback 而不是 git reset 当你只想撤销 Agent 驱动的更改时。
• 与 Git worktrees 结合使用 以获得最大安全性 — 将每个 Hermes 会话保留在自己的 worktree/分支中，并将检查点作为额外层。

要在同一仓库上并行运行多个 Agent，请参见 Git worktrees 指南。