检查点与 /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 中找到，检查点将透明禁用。
• 目录范围限制 —— Hermes 会跳过过于宽泛的目录（如根目录 /、主目录 $HOME）。
• 仓库大小限制 —— 包含超过 50,000 个文件的目录将被跳过，以避免缓慢的 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 工作树使用以获得最大安全性 —— 为每个 Hermes 会话使用独立的工作树/分支，检查点作为额外保护层。

如需在同一个仓库上并行运行多个代理，请参阅 Git 工作树 指南。