Checkpoint 與 rewind
Gemini CLI checkpointing、/restore、rewind 的作用：修改前儲存狀態、恢復檔案、恢復會話和降低實驗風險。
Checkpointing 會在 AI 工具修改檔案前自動儲存專案狀態。官方文件說明：它會建立一個 shadow Git repository 快照，並儲存 conversation history 和即將執行的 tool call。
價值：checkpoint 讓你敢做實驗，但不能替代 Git commit、程式碼審查和測試。
工作方式
當你批准 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
}
}
}官方文件註明 --checkpointing CLI flag 已在 0.11.0 移除，現在透過 settings 配置。
使用 /restore
檢視可恢復 checkpoint：
/restore恢復指定 checkpoint：
/restore <checkpoint_file>rewind 的使用邊界
rewind 適合回退和重放 session；checkpoint 更偏“檔案修改前狀態”。兩者都降低風險，但不能替代清晰任務邊界。
可以這樣區分：
| 機制 | 解決什麼 | 不能替代什麼 |
|---|---|---|
| Session resume | 繼續舊對話 | 當前檔案狀態檢查 |
/chat save | 給會話打標籤 | Git commit |
| Checkpoint | 修改前恢復點 | 長期版本管理 |
/restore | 恢復 checkpoint | 程式碼審查和測試 |
| Git branch / commit | 專案級版本記錄 | Agent 會話上下文 |
如果任務會跨天、跨分支、跨 agent，應該用 Git 管理長期狀態，用 checkpoint 管理單次 AI 寫入風險。不要把 checkpoint 當成“可以隨便改”的許可證。
推薦策略
- 大改前手動確認 Git 工作區。
- 開 checkpoint。
- 每次只授權小步修改。
- 跑測試。
- 確認無誤後再正常 Git commit。
恢復演練
第一次在真實專案裡使用 checkpoint 前，建議先用臨時檔案做一次演練：
- 開啟 checkpointing。
- 讓 Gemini CLI 修改一個低風險測試檔案。
- 用
/restore檢視可恢復項。 - 恢復到修改前狀態。
- 用
git diff確認檔案確實回來了。
這個演練能確認三個關鍵點：配置是否生效、恢復路徑是否理解、恢復後是否還需要重新給出工具批准。真正遇到誤改時再摸索恢復流程，成本會更高。
失敗邊界
checkpoint 不應該承擔這些職責：
- 不用它儲存金鑰、資料庫、遠端服務狀態。
- 不用它替代資料庫 migration 回復。
- 不用它恢復已經推送、部署或釋出到外部系統的結果。
- 不用它覆蓋其他 agent 或使用者剛剛改過的檔案。
涉及外部副作用時，恢復檔案不等於恢復系統。雲資源、CI 釋出、資料庫寫入、賬號後臺操作，都需要單獨的回復方案。
接下來去哪
Plan mode
高風險修改前先只讀規劃，減少進入恢復流程的機率。
Settings
繼續看 checkpointing、sandbox、工具許可權如何寫進 settings.json。
Sandbox
涉及 shell、檔案系統和命令執行時，繼續看 sandbox 與審批邊界。