檢查點與 /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          # 主開關（默認：true）
  max_snapshots: 50      # 每個目錄的最大檢查點

如需禁用：

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. 撤銷上一輪對話，使 Agent 的上下文與恢復後的文件系統狀態一致。

成功後：

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

對話撤銷確保 Agent 不會“記住”已被回滾的變更，避免下一輪對話產生混淆。

單文件恢復

僅從檢查點恢復單個文件，而不影響目錄中其他文件：

/rollback 1 src/broken_file.py

當 Agent 對多個文件進行了修改，但僅需回滾其中一個時，此功能非常有用。

安全與性能保護機制

為確保檢查點機制安全且高效，Hermes 應用了多項保護措施：

• Git 可用性檢查 —— 若 git 未在 PATH 中找到，檢查點將透明禁用。
• 目錄範圍限制 —— Hermes 會跳過過於寬泛的目錄（如根目錄 /、主目錄 $HOME）。
• 倉庫大小限制 —— 包含超過 50,000 個文件的目錄將被跳過，以避免緩慢的 Git 操作。
• 無變更快照跳過 —— 若自上次快照以來無任何變更，將跳過本次檢查點。
• 非致命錯誤處理 —— 所有檢查點管理器內部錯誤均以調試級別記錄；你的工具仍將繼續運行。

檢查點存儲位置

所有影子倉庫均位於：

~/.hermes/checkpoints/
  ├── <hash1>/   # 一個工作目錄的影子 git 存儲庫
  ├── <hash2>/
  └── ...

每個 <hash> 由工作目錄的絕對路徑生成。每個影子倉庫內部包含：

• 標準 Git 內部結構（HEAD、refs/、objects/）
• 一個 info/exclude 文件，包含經過篩選的忽略列表
• 一個 HERMES_WORKDIR 文件，指向原始項目根目錄

通常你無需手動操作這些內容。

最佳實踐

• 保持檢查點啟用 —— 默認已開啟，且在無文件修改時無任何開銷。
• 恢復前使用 /rollback diff —— 預覽變更內容，選擇正確的檢查點。
• 使用 /rollback 而非 git reset —— 當你只想撤銷 Agent 驅動的變更時。
• 結合 Git 工作樹使用以獲得最大安全性 —— 為每個 Hermes 會話使用獨立的工作樹/分支，檢查點作為額外保護層。

如需在同一個倉庫上並行運行多個 Agent，請參閱 Git 工作樹 指南。