Skip to main content

检查点与 /rollback

Hermes Agent 会在执行破坏性操作前自动对你的项目进行快照，并可通过一条命令轻松恢复。检查点功能默认启用——当没有文件修改类工具触发时，完全无额外开销。

这一安全机制由内部的 检查点管理器（Checkpoint Manager） 驱动，它在 ~/.hermes/checkpoints/ 下维护一个独立的影子 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 检测到即将对工作树中的文件进行修改。
  • 每个对话回合（按目录）内执行一次：
    • 确定合理的项目根目录。
    • 初始化或复用一个与该目录绑定的 影子 Git 仓库。
    • 将当前状态暂存并提交，附带简明易读的说明。
  • 这些提交构成可查看和恢复的检查点历史记录，通过 /rollback 进行管理。

配置选项​

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

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

如需禁用：

checkpoints:
  enabled: false

禁用后，检查点管理器将不执行任何操作，也不会尝试任何 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 统计摘要及实际差异内容：

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

后台操作流程如下：

  1. 验证目标提交在影子仓库中存在。
  2. 对当前状态创建一个回滚前的快照，以便后续“撤销撤销”。
  3. 恢复工作目录中受控文件的内容。
  4. 撤销上一轮对话，使代理上下文与恢复后的文件系统状态保持一致。

成功后：

✅ 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.

此对话撤销机制确保代理不会“记住”已被回滚的更改，避免下一轮交互时产生混淆。

单文件恢复​

仅恢复一个文件而不影响目录中其他文件：

/rollback 1 src/broken_file.py

当代理对多个文件进行了修改，但只需回滚其中某一个时非常有用。

安全与性能保护机制​

为确保检查点机制既安全又高效，Hermes 应用了多项防护措施：

  • Git 可用性检测 — 若 git 在 PATH 上不可用，则检查点会透明禁用。
  • 目录范围限制 — 跳过过于宽泛的目录（如根目录 /、主目录 $HOME）。
  • 仓库大小限制 — 文件超过 5 万个的目录会被跳过，以避免缓慢的 Git 操作。
  • 无变更时不创建快照 — 若自上次快照以来无任何变更，则跳过本次检查点。
  • 非致命错误处理 — 所有检查点管理器内的错误均以调试级别记录；不影响工具正常运行。

检查点存储位置​

所有影子仓库均位于：

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

每个 <hash> 由工作目录的绝对路径生成。每个影子仓库内包含：

  • 标准 Git 内部结构（HEAD、refs/、objects/）
  • 一个 info/exclude 文件，包含经过筛选的忽略列表
  • 一个 HERMES_WORKDIR 文件，指向原始项目根目录

通常情况下，你无需手动干预这些文件。

最佳实践建议​

  • 保持检查点开启 — 默认已启用，且未发生文件修改时无任何成本。
  • 恢复前使用 /rollback diff — 预览变更内容，选择正确的检查点。
  • 若只想撤销代理驱动的更改，请优先使用 /rollback 而非 git reset。
  • 结合 Git 工作区（worktree）实现最大安全保障 — 为每个 Hermes 会话创建独立的工作区/分支，检查点作为额外保护层。

关于在同一仓库上并行运行多个代理的场景，请参阅 Git 工作区指南。