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 与审批边界。