Skip to main content

检查点

检查点会在 Roo Code 任务期间自动对你的工作区文件进行版本控制，让你能够以非破坏性的方式探索 AI 建议，并轻松地从不需要的更改中恢复。

检查点让你能够：

  • 安全地试验 AI 建议的更改
  • 轻松地从不需要的修改中恢复
  • 比较不同的实现方法
  • 还原到之前的项目状态而不会丢失工作
重要提示
  • 默认启用检查点。
  • 必须安装 Git 才能使用检查点 - 查看安装说明
  • 不需要 GitHub 账户或仓库
  • 不需要配置 Git 个人信息
  • 影子 Git 仓库独立于你项目的现有 Git 配置运行

配置选项​

在 Roo Code 设置的“检查点”部分访问检查点设置：

  1. 点击齿轮图标 → 检查点打开设置

  2. 配置检查点行为：

    • 勾选或取消勾选“启用自动检查点”复选框
    • 调整“检查点初始化超时”（10-60 秒，默认：30 秒）
    Roo Code 配置中的检查点设置

检查点初始化超时​

控制系统在显示警告之前等待检查点初始化完成的时间。如果你的项目有很多文件或位于较慢的存储上，增加此超时可以防止过早出现警告。

  • 范围：10-60 秒
  • 默认：30 秒
  • 何时增加：大型项目、磁盘 I/O 缓慢或网络挂载目录
  • 位置：设置 → 检查点 → “检查点初始化超时”

检查点工作原理​

Roo Code 使用影子 Git 仓库来捕获项目状态的快照，该仓库独立于你的主版本控制系统。这些快照称为检查点，会在文件修改之前自动创建，确保你始终可以撤销不需要的更改。检查点在任务开始和文件修改之前记录。它们不会在命令执行之前自动创建。

检查点以 Git 提交的形式存储在影子仓库中，捕获：

  • 文件内容更改
  • 新增文件
  • 删除的文件
  • 重命名的文件
  • 二进制文件更改

使用检查点​

检查点通过聊天界面直接集成到你的工作流程中。

检查点直接出现在你的聊天记录中：

  • 任务检查点标记你的起始项目状态

    聊天记录中的任务检查点指示器

  • 常规检查点在文件修改之前创建，允许轻松撤销任何更改

    聊天记录中的常规检查点指示器

每个检查点都提供两个主要功能，这些功能在聊天记录和检查点菜单中都始终可用：

查看差异​

要比较当前工作区与之前的检查点：

  1. 在聊天记录中找到检查点或打开检查点菜单

  2. 点击检查点的查看差异按钮

    查看差异按钮界面

  3. 在比较视图中查看差异：

    • 新增的行以绿色高亮显示
    • 删除的行以红色高亮显示
    • 修改的文件会列出详细更改
    • 重命名可能不会总是被检测到；差异反映的是提交之间的每个文件更改
    • 新增或删除的文件会被清楚标记
检查点的查看差异选项

还原检查点​

还原选项在检查点按钮和对话框中始终可见，无论是否检测到更改。这确保你始终可以还原到任何检查点状态。

要将项目还原到之前的检查点状态：

  1. 在聊天记录或检查点菜单中找到检查点

  2. 点击检查点的还原检查点按钮（始终可见）

    还原检查点按钮界面

  3. 选择以下还原选项之一：

    还原检查点选项

    • 仅还原文件 - 仅将工作区文件还原到检查点状态，而不修改对话历史。适用于在保持聊天上下文的同时比较替代实现，让你可以在不同的项目状态之间无缝切换。此选项不需要确认，让你可以快速在不同的实现之间切换。

    • 还原文件和任务 - 还原工作区文件并删除所有后续对话消息。当你想要将代码和对话完全重置到检查点的时间点时使用。此选项需要在对话框中确认，因为它无法撤销。

      还原检查点（文件和任务）的确认对话框

限制和注意事项​

  • 范围：检查点只捕获在活动 Roo Code 任务期间所做的更改
  • 外部更改：在任务之外所做的修改（手动编辑、其他工具）不包含在内
  • 大文件：非常大的二进制文件可能会影响性能
  • 未保存的工作：还原将覆盖工作区中的任何未保存更改
  • 时机：检查点在更改应用之前创建，为所有修改提供安全网

技术实现​

检查点架构​

检查点系统包括：

  1. 影子 Git 仓库：专门为检查点跟踪创建的独立 Git 仓库，作为检查点状态的持久存储机制。

  2. 检查点服务：通过以下方式处理 Git 操作和状态管理：

    • 仓库初始化
    • 检查点创建和存储
    • 差异计算
    • 状态还原

  3. UI 组件：聊天中显示的界面元素，支持与检查点交互。

还原过程​

当执行还原时，Roo Code 会：

  • 对指定的检查点提交执行硬重置
  • 将影子仓库中的所有文件复制到你的工作区
  • 更新内部检查点跟踪状态

存储类型​

检查点是任务范围的，意味着它们特定于单个任务。

差异计算​

检查点比较使用 Git 的基础差异功能来生成结构化的文件差异：

  • 修改的文件显示逐行更改
  • 二进制文件被正确检测和
  • 重命名检测可能有限；差异关注检查点之间的文件内容更改
  • 文件创建和删除被清楚识别

文件排除和忽略模式​

检查点系统使用智能文件排除来只跟踪相关文件：

内置排除​

系统内置了全面的排除模式，可自动忽略：

  • 构建产物和依赖目录（node_modules/、dist/、build/）
  • 媒体文件和二进制资源（图像、视频、音频）
  • 缓存和临时文件（.cache/、.tmp/、.bak）
  • 包含敏感信息的配置文件（.env）
  • 大型数据文件（归档文件、可执行文件、二进制文件）
  • 数据库文件和日志

这些模式会在初始化期间写入影子仓库的 .git/info/exclude 文件。

.gitignore 支持​

检查点系统会遵循工作区中的 .gitignore 模式：

  • 被 .gitignore 排除的文件不会触发检查点创建
  • 被排除的文件不会出现在检查点差异中
  • 暂存文件更改时应用标准 Git 忽略规则

Git LFS 模式​

工作区中 .gitattributes 文件定义的 Git LFS 模式会被读取并添加到检查点排除项中。这有助于避免在影子仓库中跟踪由 LFS 管理的大型资源。

.rooignore 行为​

.rooignore 文件（控制 AI 对文件的访问权限）与检查点跟踪是分开的：

  • 被 .rooignore 排除但未被 .gitignore 排除的文件仍会被创建检查点
  • 对 AI 无法访问的文件的更改仍可通过检查点恢复

这种分离是故意的，因为 .rooignore 限制的是 AI 可以访问哪些文件，而不是哪些文件应该被跟踪以保留版本历史。

嵌套 Git 仓库​

如果在您的工作区中检测到嵌套的 Git 仓库，检查点将被禁用。当由于存在嵌套仓库而导致检查点初始化失败时，您会收到明确的通知。请移除或重新定位嵌套仓库以启用检查点。

并发控制​

扩展程序可防止在单个流式操作中重复创建检查点。没有专用的 Git 操作队列。

Git 安装​

检查点功能要求您的系统上已安装 Git。该实现使用 simple-git 库，该库依赖 Git 命令行工具来创建和管理影子仓库。

macOS​

  1. 使用 Homebrew 安装（推荐）：

    brew install git

  2. 备选方案：使用 Xcode 命令行工具安装：

    xcode-select --install

  3. 验证安装：

    • 打开终端
    • 输入 git --version
    • 您应该看到类似 git version 2.40.0 的版本号

Windows​

  1. 下载 Git for Windows：

  2. 运行安装程序：

    • 接受许可协议
    • 选择安装位置（建议使用默认位置）
    • 选择组件（通常默认选项已足够）
    • 选择默认编辑器
    • 选择如何从命令行使用 Git（推荐：从命令行以及第三方软件中使用 Git）
    • 配置行尾转换（推荐：检出 Windows 风格，提交 Unix 风格）
    • 完成安装

  3. 验证安装：

    • 打开命令提示符或 PowerShell
    • 输入 git --version
    • 您应该看到类似 git version 2.40.0.windows.1 的版本号

Linux​

Debian/Ubuntu：

sudo apt update
sudo apt install git

Fedora：

sudo dnf install git

Arch Linux：

sudo pacman -S git

验证安装：

  • 打开终端
  • 输入 git --version
  • 您应该看到版本号