Checkpoint 與 rewind

你是 Gemini CLI Checkpoint 顧問。

【角色】
Gemini CLI Checkpoint 顧問，按最小夠用、安全優先的原則給可落地方案，每條結論落到能照做的步驟或示例。

【輸入】
- 我擔心哪些操作出錯：___
- 任務的風險程度：___
- 是否多步改動：___
- 熟練度：___

【工作流程】
1. 說明何時該打 checkpoint
2. 給 rewind 回退的用法
3. 把 checkpoint 作為安全網
4. 給和版本控制的配合

【輸出規範】
▌一、何時打 checkpoint
▌二、rewind 用法
▌三、當安全網用
▌四、和版本控制配合

【硬約束】
- 高風險操作前先打 checkpoint
- checkpoint 不替代版本控制
- 回退後重新驗證
- 不要替我臆測情況或編造不存在的命令，資訊不全先問清
- 不確定的命令或引數一律以官方文件為準，禁止照搬過時寫法

Checkpointing 會在 AI 工具修改檔案前自動儲存專案狀態。官方文件說明：它會建立一個 shadow Git repository 快照，並儲存 conversation history 和即將執行的 tool call。

工作方式

當你批准 write_file、replace 等會修改檔案系統的工具時，Gemini CLI 可以建立 checkpoint：

• 在 ~/.gemini/history/<project_hash> 的 shadow Git repo 中儲存專案檔案快照。
• 儲存目前對話歷史。
• 儲存即將執行的工具呼叫。

恢復 checkpoint 會：

• 把專案檔案恢復到快照狀態。
• 恢復對話歷史。
• 重新提出原始工具呼叫。

flowchart LR
    Approve["批准寫入工具"] --> Snapshot["建立 checkpoint"]
    Snapshot --> Change["執行檔案修改"]
    Change --> Review{"結果可接受?"}
    Review -->|是| Test["跑測試並繼續"]
    Review -->|否| Restore["/restore 回到快照"]
    Restore --> Replan["重新審查計劃"]

    style Snapshot fill:#dbeafe,stroke:#3b82f6
    style Restore fill:#fee2e2,stroke:#ef4444
    style Test fill:#dcfce7,stroke:#22c55e

啟用 checkpointing

官方文件說明 checkpointing 預設關閉，需要在 settings.json 中啟用：

{
  "general": {
    "checkpointing": {
      "enabled": true
    }
  }
}

使用 /restore

檢視可恢復 checkpoint：

/restore

恢復指定 checkpoint：

/restore <checkpoint_file>

rewind 的使用邊界

rewind 適合回退和重放 session；checkpoint 更偏“檔案修改前狀態”。兩者都降低風險，但不能替代清晰任務邊界。

可以這樣區分：

如果任務會跨天、跨分支、跨 agent，應該用 Git 管理長期狀態，用 checkpoint 管理單次 AI 寫入風險。不要把 checkpoint 當成“可以隨便改”的許可證。

推薦策略

• 大改前手動確認 Git 工作區。
• 開 checkpoint。
• 每次只授權小步修改。
• 跑測試。
• 確認無誤後再正常 Git commit。

恢復演練

第一次在真實專案裡使用 checkpoint 前，建議先用臨時檔案做一次演練：

1. 開啟 checkpointing。
2. 讓 Gemini CLI 修改一個低風險測試檔案。
3. 用 /restore 檢視可恢復項。
4. 恢復到修改前狀態。
5. 用 git diff 確認檔案確實回來了。

這個演練能確認三個關鍵點：設定是否生效、恢復路徑是否理解、恢復後是否還需要重新給出工具批准。真正遇到誤改時再摸索恢復流程，成本會更高。

失敗邊界

checkpoint 不應該承擔這些職責：

• 不用它儲存金鑰、資料庫、遠端服務狀態。
• 不用它替代資料庫 migration 回復。
• 不用它恢復已經推送、部署或釋出到外部系統的結果。
• 不用它覆蓋其他 agent 或使用者剛剛改過的檔案。

涉及外部副作用時，恢復檔案不等於恢復系統。雲資源、CI 釋出、資料庫寫入、賬號後臺操作，都需要單獨的回復方案。

接下來去哪

官方來源

• Google Developers Gemini CLI
• Gemini CLI GitHub