企业官网建设流程全解析

Roo Code 如何用 Checkpoints 查看 AI 修改差异并恢复到之前的状态

【免费下载链接】Roo-CodeRoo Code gives you a whole dev team of AI agents in your code editor.项目地址: https://gitcode.com/GitHub_Trending/ro/Roo-Code

让 Roo Code 跑完一次任务后，你常常面对同一个问题：AI 到底改了哪些文件？哪些改动不想要，怎么退回之前的样子？Checkpoints 就是为这个场景设计的。它在任务进行过程中通过一个独立的影子 Git 仓库自动对工作区文件做版本快照，你可以用它对照任意历史状态逐文件查看差异，也可以一键把工作区（连同对话）恢复回那个时刻。Checkpoints 默认开启，只要求系统安装了 Git，不需要 GitHub 账号或 Git 身份信息，影子仓库与项目自身的 Git 配置互相独立。

前提条件：确认 Git 可用

Checkpoint 底层通过simple-git库调用 Git 命令行来创建和管理影子仓库，所以 Git 是硬性前提。先打开终端执行：

git --version

能输出版本号（文档示例为git version 2.40.0）即表示已安装；未安装时按文档给出的方式补装（这些命令会修改系统环境，Linux 命令需要 sudo 权限）：

# macOS（Homebrew，文档推荐方式） brew install git # Debian/Ubuntu sudo apt update sudo apt install git # Fedora sudo dnf install git # Arch Linux sudo pacman -S git

Windows 使用 Git for Windows 安装程序（文档指向 Git 官方下载入口），按默认选项安装后再用git --version验证。

另外注意一个文档明确列出的禁用条件：如果工作区里检测到嵌套的 Git 仓库，Checkpoints 会被整体禁用，你会收到初始化失败的提示通知；需要移除或挪走嵌套仓库才能启用。

了解快照的生成时机与范围

Roo Code 在两个时点创建 checkpoint，都发生在变更落盘之前：

• 任务开始时创建一个Task checkpoint，标记本次任务的起始项目状态；
• 每次文件修改之前创建普通 checkpoint。命令执行前不会自动创建 checkpoint。

checkpoint 以影子仓库中的 Git commit 形式存储，覆盖文件内容变更、新增、删除、重命名和二进制文件变更。但注意它的边界：只捕获 Roo Code 任务期间发生的变更，任务之外的手动编辑或其他工具的修改不会进入快照。

如果项目文件多、磁盘 I/O 慢或挂载在网络目录上，可以在设置里调整初始化超时：打开齿轮图标进入 Settings → Checkpoints，可勾选/取消Enable automatic checkpoints，并把Checkpoint initialization timeout调大（范围 10–60 秒，默认 30 秒）。该超时控制系统在弹出“初始化超时”警告前的等待时间，文档建议在大型项目或慢速存储上调高以避免过早告警。

查看 AI 修改的差异

checkpoint 直接显示在聊天历史中——任务起始的 Task checkpoint 和每次文件修改前的普通 checkpoint 都能被定位到，也可以打开 checkpoint 菜单查找。

要对比当前工作区与某个 checkpoint 的差异：

1. 在聊天历史或 checkpoint 菜单中定位目标 checkpoint；
2. 点击该 checkpoint 的View Differences按钮；
3. 在对比视图中查看差异。

读取差异视图时的判断依据（均来自文档说明）：

• 新增行以绿色高亮，删除行以红色高亮，修改过的文件按文件列出详细变更；
• 新增或删除的文件会被明确标出；
• 重命名不一定能总是被检测到，diff 反映的是各 commit 之间的逐文件内容变化；
• 被.gitignore排除的文件不会出现在 checkpoint diff 中，影子仓库初始化时也会自动排除构建产物与依赖目录（如node_modules/、dist/、build/）、媒体文件、缓存临时文件、.env及数据库文件等内置模式。如果你预期看到某个文件的改动却没出现，先检查它是否落在这些排除规则里。

恢复到之前的状态

每个 checkpoint 的Restore Checkpoint按钮始终可见——无论系统是否检测到后续变更，恢复入口都可用。点击后有两个选项：

• Restore Files Only：只把工作区文件回退到 checkpoint 状态，不修改对话历史，且无需确认。适合想保留聊天上下文、在不同实现版本之间快速来回切换的场景。
• Restore Files & Task：同时回退工作区文件并删除该时刻之后的所有对话消息，属于不可撤销操作，会弹出确认对话框后才执行。文档也提到，当遇到input length and max tokens exceed context limit这类上下文超限报错时，回滚到之前的 checkpoint 是可用恢复手段之一。

恢复执行时，Roo Code 会对指定 checkpoint 的 commit 执行硬重置，并把影子仓库中的文件复制回工作区，同时更新内部 checkpoint 跟踪状态。选择恢复前记得保存工作区中未提交的编辑器改动——文档明确说明：恢复会覆盖工作区里所有未保存的修改。

限制与已知问题

• 范围限制：只有活跃 Roo Code 任务期间产生的变更被捕获，命令执行前的状态不会自动快照；
• 性能：非常大的二进制文件可能影响 checkpoint 性能；
• 嵌套仓库：检测到嵌套 Git 仓库时 checkpoint 直接禁用，伴随明确通知；
• Windows 路径问题：旧版本曾在 Windows 上因 git 正斜杠路径与 VS Code 反斜杠路径不一致而报 “Checkpoints can only be used in the original workspace”，该问题已在 v3.48.0 更新说明 中记录修复，遇到此报错可先确认扩展版本；
• 初始化告警：大项目上如果出现初始化超时的提前警告，调高前文提到的初始化超时即可，而不是禁用 checkpoint。

完成一次典型流程后你应当能看到：差异视图逐文件列出新增（绿）、删除（红）与标记的新建/删除文件；选择恢复选项后工作区文件被覆盖为 checkpoint 时刻的内容，Restore Files & Task还会让对话历史同步截断到该时刻。更多细节可查阅 Checkpoints 功能文档。

【免费下载链接】Roo-CodeRoo Code gives you a whole dev team of AI agents in your code editor.项目地址: https://gitcode.com/GitHub_Trending/ro/Roo-Code