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