检查点
功能概述：检查点是iFlow CLI的安全回退系统，在用户每次输入请求前自动保存项目状态快照。
学习时间：5-10分钟
前置要求：了解基本的Git概念，熟悉文件版本管理
什么是检查点
检查点是iFlow CLI提供的安全保障机制，在用户每次输入请求时会自动保存当前项目状态的完整快照。您可以放心地让AI执行各种操作，随时回退到任意一次请求输入前的状态，可选择性回退AI删除的文件、未达预期的代码。
核心特点
| 特点 | 说明 | 优势 |
|---|---|---|
| 自动创建 | 每次用户请求前自动保存状态 | 无需手动操作 |
| 完整快照 | 保存文件、对话、工具调用 | 全面的状态恢复 |
| 独立存储 | 不干扰项目Git仓库 | 安全隔离 |
| 即时恢复 | 一键回退到任意检查点 | 快速撤销更改 |
| 本地存储 | 所有数据保存在本地 | 隐私和安全 |
工作原理
检查点创建流程
用户输入请求 → 创建检查点 → 调用LLM → 工具执行（可能多次） → 请求完成
↓
[用户请求] → [状态快照] → [LLM处理] → [安全执行] → [状态保存]
快照内容组成
检查点通过Git机制保存项目的完整状态：
- 在
~/.iflow/history/<project_hash>创建影子Git仓库 - 捕获项目文件的完整状态
- 不干扰项目原有的Git仓库
- 支持快速恢复到任意检查点
详细配置说明
启用检查点功能
检查点功能默认开启。当用户输入请求时，系统会在调用LLM前自动创建检查点。
场景1：系统已安装Git（推荐）
正常启动iFlow CLI，检查点功能自动开启
iflow
场景2：系统未安装Git
启动iFlow后，检查点功能将不可用。系统会在小帖士中提醒：
检查点功能暂不可用，如需启用请先安装Git
禁用检查点功能
场景3：长期禁用配置
在 ~/.iflow/settings.json 文件中，将 "enabled" 的值设为：false
"checkpointing": {
"enabled": false
}
场景4：临时禁用启动
通过命令行参数禁用检查点功能
iflow --no-checkpointing
使用检查点
检查点自动创建
- 检查点在用户输入请求后、调用LLM前自动创建
- 每个检查点都有唯一的时间戳标识
- 系统会提示检查点创建完成
查看检查点
# 使用/restore指令查看所有检查点
/restore
在指令补齐预览界面会显示所有可用检查点的信息，包括时间戳和操作的文件。
恢复检查点
# 1. 输入/restore查看检查点列表
/restore
# 2. 使用上下键选择目标检查点
# 3. 按回车补齐指令，再次按回车执行回退
/restore <checkpoint-name>
手动清理检查点
若发现检查点缓存占用磁盘空间较大，或想自主清理检查点历史，可采取使用以下指令执行清理：
/cleanup-checkpoint
注意，上述指令仅删除当前项目路径下的检查点。若想删除其他项目路径的检查点缓存，请切换到目标路径下，启动iFlow-CLI再执行指令。
使用示例
基本写入操作
用户指令：
> 在@test.txt 中写入"hello world"
系统响应：
# 1. 系统自动创建检查点（在调用LLM前）
[检查点] 快照创建完成: 2025-11-03T15-00-20_193
# 2. 调用LLM并执行文件写入操作
# ... 文件已更新 ...
如需回退：
# 1. 输入/restore查看检查点列表
/restore
# 2. 使用上下键选择目标检查点
# 显示: 2025-11-03T15-00-20_193
# 在@test.txt 中写入"hello world" +1 -0
# 3. 按回车补齐指令
/restore 2025-11-03T15-00-20_193
# 4. 再次按回车执行回退，文件恢复到写入前的状态
故障排除
常见问题及解决方案
| 问题 | 可能原因 | 解决方案 |
|---|---|---|
| 检查点创建失败 | 磁盘空间不足或权限问题 | 检查磁盘空间和文件权限 |
| 恢复失败 | 检查点文件损坏 | 使用其他检 查点或手动恢复 |
| 检查点列表为空 | 功能未启用或无修改 | 启用功能并进行文件操作 |
| 恢复后文件丢失 | 检查点不完整 | 检查Git仓库状态 |
安全注意事项
- 不可恢复性：执行检查点回退后，该检查点往后的所有改动内容都不可恢复，请确认后再执行回退指令
- 存储空间：检查点会占用磁盘空间，定期清理旧检查点
- 隐私保护：检查点包含完整对话历史，注意敏感信息
- Git冲突：恢复可能与当前Git状态冲突，需要手动处理
- 大文件处理：大型项目的检查点可能耗时较长
平台兼容性
| 平台 | 支持程度 | 特殊说明 |
|---|---|---|
| Windows | 完全支持 | 路径处理自动适配 |
| macOS | 完全支持 | 完整的文件系统支持 |
| Linux | 完全支持 | 原生Git集成 |