检查点与 `/rollback`

Hermes Agent 可以在破坏性操作前自动为项目创建快照，并通过一条命令将其恢复。检查点（Checkpoints）从 v2 版本起为可选功能——大多数用户从不使用 /rollback，而影子存储库随时间积累的存储开销不可忽视，因此默认关闭。

使用 --checkpoints 在当次会话中启用检查点：

hermes chat --checkpoints

或在 ~/.hermes/config.yaml 中全局启用：

checkpoints:
  enabled: true

此安全保障由内部检查点管理器驱动，该管理器在 ~/.hermes/checkpoints/store/ 下维护一个共享的影子 git 仓库——你的真实项目 .git 永远不会被触碰。Agent 所操作的所有项目共享同一个存储库，因此 git 的内容寻址对象数据库可以跨项目、跨轮次进行去重。

何时触发检查点

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

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

每次对话轮次中，Agent 每个目录最多创建一个检查点，避免长时间会话产生大量快照。

快速参考

会话内斜杠命令：

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

在会话外检查和管理存储库的 CLI 命令：

命令	说明
`hermes checkpoints`	显示总大小、项目数量及各项目详情
`hermes checkpoints status`	与裸 `checkpoints` 命令相同
`hermes checkpoints list`	`status` 的别名
`hermes checkpoints prune`	强制执行清理：删除孤立/过期条目，运行 GC，强制执行大小上限
`hermes checkpoints clear`	清空整个检查点存储库（需要确认）
`hermes checkpoints clear-legacy`	仅删除 v1 迁移留下的 `legacy-*` 归档文件

检查点工作原理

概要流程：

Hermes 检测到工具即将修改工作目录中的文件。
每次对话轮次中（每个目录一次），它会：
- 为该文件解析合理的项目根目录。
- 初始化或复用 ~/.hermes/checkpoints/store/ 下唯一的共享影子存储库。
- 写入到各项目的索引，构建树对象，并提交到各项目的引用（refs/hermes/<project-hash>）。
这些各项目引用形成了可通过 /rollback 检查和恢复的检查点历史。

配置

在 ~/.hermes/config.yaml 中配置：

checkpoints:
  enabled: false              # 总开关（默认：false——需主动开启）
  max_snapshots: 20           # 每个项目的最大检查点数量（通过引用重写 + gc 执行）
  max_total_size_mb: 500      # 存储库总大小的硬性上限；超过时删除最旧的提交
  max_file_size_mb: 10        # 跳过超过此大小的单个文件

  # 自动维护（默认开启）：启动时扫描 ~/.hermes/checkpoints/
  # 删除工作目录不再存在的项目条目（孤立条目）
  # 或 last_touch 超过 retention_days 的条目。每隔至少
  # min_interval_hours 执行一次，通过 .last_prune 标记追踪。
  auto_prune: true
  retention_days: 7
  delete_orphans: true
  min_interval_hours: 24

若要完全禁用：

checkpoints:
  enabled: false
  auto_prune: false

当 enabled: false 时，检查点管理器为空操作，不会尝试任何 git 操作。当 auto_prune: false 时，存储库会持续增长，直到你手动运行 hermes checkpoints prune。

列出检查点

在 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

在 Shell 中检查存储库

hermes checkpoints

示例输出：

Checkpoint base: /home/you/.hermes/checkpoints
Total size:      142.3 MB
  store/         138.1 MB
  legacy-*       4.2 MB
Projects:        12

  WORKDIR                                                       COMMITS    LAST TOUCH  STATE
  /home/you/code/hermes-agent                                        20       2h ago  live
  /home/you/code/experiments/rl-runner                                8       1d ago  live
  /home/you/code/old-prototype                                        3       9d ago  orphan
  ...

Legacy archives (1):
  legacy-20260506-050616                           4.2 MB

Clear with: hermes checkpoints clear-legacy

强制执行完整扫描（忽略 24h 幂等标记）：

hermes checkpoints prune --retention-days 3 --max-size-mb 200

用 `/rollback diff` 预览变更

在执行恢复前，预览自某个检查点以来发生了哪些变更：

/rollback diff 1

这将显示 git diff 统计摘要，随后显示实际的 diff 内容。

使用 `/rollback` 恢复

/rollback 1

在内部，Hermes 会：

验证目标提交是否存在于影子存储库中。
对当前状态创建回滚前快照，以便稍后可以"撤销撤销"操作。
恢复工作目录中被追踪的文件。
撤销最后一轮对话，使 Agent 的上下文与已恢复的文件系统状态保持一致。

单文件恢复

从检查点中仅恢复一个文件，不影响目录中的其他内容：

/rollback 1 src/broken_file.py

安全与性能保障

Git 可用性 — 若 PATH 中找不到 git，检查点功能会自动透明地禁用。
目录范围 — Hermes 会跳过过于宽泛的目录（根目录 /、家目录 $HOME）。
仓库大小 — 超过 50,000 个文件的目录会被跳过。
单文件大小上限 — 超过 max_file_size_mb（默认 10 MB）的文件会被排除在快照之外。防止意外将数据集、模型权重或生成的媒体文件纳入快照。
存储库总大小上限 — 当存储库超过 max_total_size_mb（默认 500 MB）时，会以轮询方式删除每个项目中最旧的提交，直到低于上限。
真实剪枝 — max_snapshots 通过重写各项目引用并在之后运行 git gc --prune=now 来强制执行，避免松散对象积累。
无变更快照 — 若自上次快照以来没有变更，则跳过该检查点。
非致命错误 — 检查点管理器内部的所有错误均以 debug 级别记录日志；你的工具会继续正常运行。

检查点存储位置

~/.hermes/checkpoints/
  ├── store/                 # 单一共享裸 git 仓库
  │   ├── HEAD, objects/     # git 内部对象（跨项目共享）
  │   ├── refs/hermes/<hash> # 各项目分支最新提交
  │   ├── indexes/<hash>     # 各项目 git 索引
  │   ├── projects/<hash>.json  # 工作目录 + created_at + last_touch
  │   └── info/exclude
  ├── .last_prune            # 自动剪枝幂等标记
  └── legacy-<ts>/           # 归档的 v1 版本各项目影子仓库

每个 <hash> 由工作目录的绝对路径派生。通常无需手动操作这些文件——请使用 hermes checkpoints status / prune / clear 命令代替。

从 v1 迁移

在 v2 重写之前，每个工作目录都会在 ~/.hermes/checkpoints/<hash>/ 下拥有一个完整的独立影子 git 仓库。这种布局无法跨项目去重对象，且已记录存在无效的剪枝器——存储库会无限增长。

首次运行 v2 时，所有 v2 之前的影子仓库会被移入 ~/.hermes/checkpoints/legacy-<timestamp>/，以便新的单一存储库布局从干净状态开始。旧的 /rollback 历史仍可通过 git 手动检查遗留归档来访问；确认不再需要后，运行：

hermes checkpoints clear-legacy

以回收存储空间。遗留归档在 retention_days 后也会被 auto_prune 清理。

最佳实践

仅在需要时启用检查点 — hermes chat --checkpoints 或在各配置文件中设置 enabled: true。
恢复前使用 /rollback diff — 预览将要变更的内容，以便选择正确的检查点。
使用 /rollback 而非 git reset — 当你只想撤销 Agent 驱动的变更时。
定期查看 hermes checkpoints status — 如果你经常使用检查点，可以了解哪些项目处于活跃状态以及存储库的开销。
与 Git Worktree 结合使用以获得最大安全保障 — 将每个 Hermes 会话保持在各自的 worktree/分支中，以检查点作为额外的保护层。

关于在同一仓库上并行运行多个 Agent，请参阅 Git Worktrees 指南。

何时触发检查点​

快速参考​

检查点工作原理​

配置​

列出检查点​

在 Shell 中检查存储库​

用 /rollback diff 预览变更​

使用 /rollback 恢复​

单文件恢复​

安全与性能保障​

检查点存储位置​

从 v1 迁移​

最佳实践​