检查点

功能概述：检查点是iFlow CLI的安全回退系统，在AI工具修改文件前自动保存项目状态快照。

学习时间：5-10分钟

前置要求：了解基本的Git概念，熟悉文件版本管理

什么是检查点

检查点是iFlow CLI提供的安全保障机制，在AI工具修改文件系统之前自动保存项目状态的完整快照。这个功能让您可以安全地实验和应用代码更改，随时可以立即回退到工具运行前的状态，确保您的项目安全。

核心特点

特点	说明	优势
默认开启	YOLO模式和默认模式下自动创建	无需手动配置
自动创建	文件改写动作前自动保存状态	无需手动操作
完整快照	保存文件、对话、工具调用	全面的状态恢复
独立存储	不干扰项目Git仓库	安全隔离
即时恢复	一键回退到任意检查点	快速撤销更改
本地存储	所有数据保存在本地	隐私和安全

工作原理

检查点创建流程

检查点功能支持三种文件改写工具：replace、write_file 和 multi_edit

YOLO模式流程

工具调用 → 同步创建检查点 → 工具执行 → 检查点完成
    ↓
[AI请求] → [状态快照] → [安全执行] → [状态保存]

默认模式流程

工具调用 → 用户确认请求 → 创建检查点 → 工具执行 → 检查点完成
    ↓
[AI请求] → [等待批准] → [状态快照] → [安全执行] → [状态保存]

快照内容组成

1. Git状态快照

• 在 ~/.iflow/snapshots/<project_hash> 创建影子Git仓库
• 捕获项目文件的完整状态
• 不干扰项目原有的Git仓库

2. 对话历史

• 保存与AI助手的完整对话记录
• 包括上下文和交互状态
• 支持对话状态的完整恢复

3. 工具调用信息

• 存储即将执行的具体工具调用
• 记录参数和执行上下文
• 支持重新执行或修改调用

数据存储位置

数据类型	存储路径	说明
Git快照	~/.iflow/snapshots/<project_hash>	影子Git仓库
对话历史	~/.iflow/cache/<project_hash>/checkpoints	JSON格式文件
工具调用	~/.iflow/cache/<project_hash>/checkpoints	调用详情记录

详细功能说明

启用检查点功能

检查点功能默认开启，支持YOLO模式和默认模式。当Agent执行文件改写动作时，会在改动前自动创建检查点。

场景1：系统已安装Git（推荐）

# 正常启动iFlow CLI，检查点功能自动开启
iflow

场景2：系统未安装Git

启动iFlow后，检查点功能将不可用。系统会在小帖士中提醒：

检查点功能暂不可用，如需启用请先安装Git

场景3：手动禁用检查点功能

# 通过命令行参数禁用检查点功能
iflow --no-checkpointing

使用检查点

检查点自动创建

• 检查点在文件改写工具执行前自动创建
• 每个检查点都有唯一的时间戳和文件名标识
• 系统会提示检查点创建完成

查看检查点

# 使用/restore指令查看所有检查点
/restore

在指令补齐预览界面会显示所有可用检查点的信息，包括时间戳和操作的文件。

恢复检查点

# 1. 输入/restore查看检查点列表
/restore

# 2. 使用上下键选择目标检查点

# 3. 按回车补齐指令，再次按回车执行回退
/restore <checkpoint-name>

手动清理检查点

若发现检查点缓存占用磁盘空间较大，或想自主清理检查点历史，可采取使用以下指令执行清理：

/cleanup-checkpoint

注意，上述指令仅删除当前项目路径下的检查点。若想删除其他项目路径的检查点缓存，请切换到目标路径下，启动iFlow-CLI再执行指令。

使用示例

基本写入操作

用户指令：

> 在@test.txt 中写入"hello world"

系统响应：

# 1. 系统自动创建检查点
[检查点] 快照创建完成: 2025-11-03T15-00-20_193-test.txt-write_file

# 2. 执行文件写入操作
# ... 文件已更新 ...

如需回退：

# 1. 输入/restore查看检查点列表
/restore

# 2. 使用上下键选择目标检查点
# 显示: 2025-11-03T15-00-20_193-test.txt-write_file
#       在@test.txt 中写入"hello world" +1 -0

# 3. 按回车补齐指令
/restore 2025-11-03T15-00-20_193-test.txt-write_file

# 4. 再次按回车执行回退，文件恢复到写入前的状态

故障排除

常见问题及解决方案

问题	可能原因	解决方案
检查点创建失败	磁盘空间不足或权限问题	检查磁盘空间和文件权限
恢复失败	检查点文件损坏	使用其他检查点或手动恢复
检查点列表为空	功能未启用或无修改	启用功能并进行文件操作
恢复后文件丢失	检查点不完整	检查Git仓库状态

安全注意事项

• 不可恢复性：执行检查点回退后，该检查点往后的所有改动内容都不可恢复，请确认后再执行回退指令
• IDE模式限制：在默认模式中启用IDE时，改动会在IDE中弹出Preview窗口需要手动确认。由于用户手动确认了改动，iFlow CLI不会创建检查点，因此无法通过/restore指令回退。只有在终端中运行且没有打开IDE时，所有文件改写动作均可使用检查点回退
• 存储空间：检查点会占用磁盘空间，定期清理旧检查点
• 隐私保护：检查点包含完整对话历史，注意敏感信息
• Git冲突：恢复可能与当前Git状态冲突，需要手动处理
• 大文件处理：大型项目的检查点可能耗时较长

平台兼容性

平台	支持程度	特殊说明
Windows	完全支持	路径处理自动适配
macOS	完全支持	完整的文件系统支持
Linux	完全支持	原生Git集成