Section: Using Hermes · URL: https://hermesbible.com/docs/user-guide/checkpoints-and-rollback

檢查點與 `/rollback`

Hermes Agent 可以在破壞性操作之前自動對你的專案進行快照，並以單一指令還原。從 v2 開始，檢查點功能為選擇啟用——大多數使用者從未使用過 /rollback，而 shadow-store 的儲存空間隨時間累積並非微不足道，因此預設是關閉的。

透過 --checkpoints 在單次對話中啟用檢查點：

hermes chat --checkpoints

或在 ~/.hermes/config.yaml 中全域啟用：

checkpoints:
  enabled: true

這項安全機制由內部的 Checkpoint Manager 驅動，它在 ~/.hermes/checkpoints/store/ 下維護一個共用的 shadow git repository——你的專案 .git 絕對不會被觸碰。Agent 操作的所有專案共用同一個 store，因此 git 的 content-addressable object DB 會跨專案、跨對話回合自動去重。

什麼時候會觸發檢查點

以下操作之前會自動建立檢查點：

檔案工具 — 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 還原單一檔案

用於在對話之外檢查和管理 store 的 CLI：

指令	說明
`hermes checkpoints`	顯示總大小、專案數量、各專案明細
`hermes checkpoints status`	等同於不帶參數的 `checkpoints`
`hermes checkpoints list`	`status` 的別名
`hermes checkpoints prune`	強制掃描：刪除孤立/過時項目、GC、強制執行大小上限
`hermes checkpoints clear`	清除整個 checkpoint base（會先詢問確認）
`hermes checkpoints clear-legacy`	僅刪除 v1 遷移留下的 `legacy-*` 封存檔

檢查點運作原理

大致流程如下：

Hermes 偵測到工具即將修改檔案時——
在每次對話回合（每個目錄）中，它會：
- 為該檔案解析合理的專案根目錄。
- 初始化或重用位於 ~/.hermes/checkpoints/store/ 的共用 shadow store。
- 將變更加入專案索引、建立 tree，並提交至專案引用（refs/hermes/<project-hash>）。
這些專案引用形成檢查點歷史記錄，你可以透過 /rollback 檢查和還原。

flowchart LR
  user["使用者指令\n(hermes, gateway)"]
  agent["AIAgent\n(run_agent.py)"]
  tools["檔案與終端機工具"]
  cpMgr["CheckpointManager"]
  store["共用 shadow store\n~/.hermes/checkpoints/store/"]

  user --> agent
  agent -->|"tool call"| tools
  tools -->|"修改前\nensure_checkpoint()"| cpMgr
  cpMgr -->|"git add/commit-tree/update-ref"| store
  cpMgr -->|"OK / skipped"| tools
  tools -->|"apply changes"| agent

設定

在 ~/.hermes/config.yaml 中設定：

checkpoints:
  enabled: false              # 主開關（預設：false——選擇啟用）
  max_snapshots: 20           # 每個專案的最大檢查點數量（透過 ref 重寫 + gc 強制執行）
  max_total_size_mb: 500      # store 總大小的硬上限；超出時會依序刪除最舊的 commit
  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 時，Checkpoint Manager 會完全不做事，不會嘗試任何 git 操作。當 auto_prune: false 時，store 會持續成長，直到你手動執行 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 檢查 Store

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

強制執行完整掃描（忽略 24 小時的冪等性標記）：

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

使用 `/rollback diff` 預覽變更

在決定還原之前，先預覽自某個檢查點以來的變更：

/rollback diff 1

這會顯示 git diff 統計摘要，隨後是實際的差異內容。

使用 `/rollback` 還原

/rollback 1

在底層，Hermes 會：

驗證目標 commit 存在於 shadow store 中。
建立還原前快照，讓你之後可以「撤銷還原」。
還原工作目錄中的追蹤檔案。
撤銷最後一次對話回合，讓 Agent 的上下文與還原後的檔案系統狀態一致。

單一檔案還原

從檢查點還原單一檔案，不影響目錄中的其他內容：

/rollback 1 src/broken_file.py

安全性與效能防護

Git 可用性 — 如果 PATH 中找不到 git，檢查點功能會透明地停用。
目錄範圍 — Hermes 會跳過過於寬泛的目錄（根目錄 /、家目錄 $HOME）。
Repository 大小 — 檔案數超過 50,000 的目錄會被跳過。
單一檔案大小上限 — 超過 max_file_size_mb（預設 10 MB）的檔案會從快照中排除。避免意外納入資料集、模型權重或產生的媒體檔案。
Store 總大小上限 — 當 store 超過 max_total_size_mb（預設 500 MB）時，會輪流刪除每個專案最舊的 commit，直到低於上限。
實際清理 — max_snapshots 透過重寫專案引用並執行 git gc --prune=now 來強制執行，因此不會累積零碎物件。
無變更快照 — 如果自上次快照以來沒有任何變更，會跳過該檢查點。
非致命錯誤 — Checkpoint Manager 內的所有錯誤都會以 debug 等級記錄；你的工具會繼續正常運行。

檢查點的儲存位置

~/.hermes/checkpoints/
  ├── store/                 # 單一共用的 bare git repo
  │   ├── HEAD, objects/     # git 內部結構（跨專案共用）
  │   ├── refs/hermes/<hash> # 每個專案的 branch tip
  │   ├── indexes/<hash>     # 每個專案的 git index
  │   ├── projects/<hash>.json  # workdir + created_at + last_touch
  │   └── info/exclude
  ├── .last_prune            # 自動清理的冪等性標記
  └── legacy-<ts>/           # 從 v1 遷移的已封存專案 shadow repo

每個 <hash> 是由工作目錄的絕對路徑衍生而來。你通常不需要手動處理這些檔案——請改用 hermes checkpoints status / prune / clear。

從 v1 遷移

在 v2 重寫之前，每個工作目錄在 ~/.hermes/checkpoints/<hash>/ 下都有自己的完整 shadow git repo。那個配置無法跨專案去重物件，而且其清理工具已知不會運作——store 會無限成長。

在首次執行 v2 時，所有 v2 之前的 shadow repo 會被移動到 ~/.hermes/checkpoints/legacy-<timestamp>/，讓新的單一 store 配置從乾淨的狀態開始。舊的 /rollback 歷史記錄仍然可以透過手動使用 git 檢查 legacy 封存檔來存取；一旦你確認不再需要它，執行：

hermes checkpoints clear-legacy

即可回收空間。Legacy 封存檔也會在 retention_days 後被 auto_prune 清理。

最佳實踐

僅在需要時啟用檢查點 — hermes chat --checkpoints 或在設定檔中設定 enabled: true。
還原前先使用 /rollback diff — 預覽將要變更的內容，以選擇正確的檢查點。
當你只想撤銷 Agent 產生的變更時，使用 /rollback 取代 git reset。
如果定期使用檢查點，偶爾檢查 hermes checkpoints status — 了解哪些專案是活躍的，以及 store 佔用了多少空間。
搭配 Git worktrees 使用以獲得最大安全性 — 將每個 Hermes 對話放在自己的 worktree/branch 中，檢查點作為額外的安全層。

關於在同一個 repo 上平行運行多個 Agent，請參閱 Git worktrees 指南。

檢查點與 /rollback