AI Diff Review

对 AI 编码智能体（opencode、Cursor、Claude Code、Trae、Aider 等）产生的文件改动进行 逐块人工审查：可以逐条接受、逐条拒绝，也可以按文件或一键全部接受 / 拒绝。

原理

扩展在文件系统层面记录一份 基线（baseline），即改动之前的文件内容。之后外部程序对工作区文件的改动会被文件监听器捕获，并与基线对比生成 diff：

• 接受：把基线推进到当前磁盘内容 —— 保留这次改动，不再显示为待审查。
• 拒绝：把磁盘内容回退到基线 —— 丢弃这次改动。

因为接受 / 拒绝只影响被选中的 diff 块，所以可以做到“改 10 处，接受 7 处、拒绝 3 处”。

每个操作执行前都会重新读取磁盘。因此“文件先被修改、随后又被删除（或再次修改、或整个目录被删掉）”时，接受 / 拒绝不会报“找不到文件”：

• 文件已不存在时，接受会按“接受删除”处理（移除基线）；
• 文件已不存在时，拒绝会从基线重建文件（必要时自动创建父目录）；
• 批量操作逐个隔离错误，一个文件失败不会中断其余文件。

快速开始

1. 用 VS Code 打开工程目录。
2. 左侧活动栏 AI 审查 → 设置 → 打开 启动监听（默认是关闭的）。
   • 也可以执行命令 AI 审查: 启动监听，或点击状态栏的 已关闭。
   • 启动时会以当前文件内容记录基线。
3. 让 AI 智能体改文件，改动会被实时捕获。
4. 在侧边栏或审查面板里逐块 / 按文件 / 全局接受或拒绝。

默认关闭监听是为了避免在用户没有明确同意时长期占用文件监听、读取和缓存空间。每个工作区的开关是独立保存的。

审查入口

侧边栏（AI 审查 活动栏）

• 待审查改动：树视图，按 文件夹层级嵌套（文件夹 → 文件 → 改动块）。点击文件在审查面板中打开；点击改动块会跳转定位到对应位置；行内按钮可逐块 / 按文件接受或拒绝。右键文件节点可 打开文件 / 在资源管理器中显示 / 打开原生对比。
  • 监听关闭 / 尚未记录基线 / 没有改动 时，树里会显示一行状态提示，点击即可启动监听或记录基线。
  • 只有换行符或编码标记（BOM）变化的文件会标注 仅格式变化，使用文件级接受 / 拒绝。
• 全局操作：显示监听状态；监听开启时提供 全部接受 (N) / 全部拒绝 (N)。
• 设置：点顶部齿轮进入的 整页设置（进入后整个侧边栏都是设置页，← 返回 退出）。

审查面板（Webview，推荐）

• 宽面板为双栏布局：左侧是待审查文件列表（状态、增删统计、当前项高亮），右侧是当前文件内容；面板较窄时自动收起文件列表，仍可用顶部的上一个 / 下一个按钮切换。
• 每次只显示当前打开的那一个文件，显示整份文件内容（未改动行也完整显示，改动行高亮，删除行就地插入）；或在设置里改为仅变更片段。
• 顶部是当前文件操作：上一个 / 下一个、上一处 / 下一处改动、刷新、接受当前文件、拒绝当前文件。
• 文件列表支持搜索（按路径过滤）。
• 文件信息条：路径 / 状态 / 增删统计 + 打开原生对比 / 在资源管理器中显示。
• 每个改动块头部有块级 接受 / 拒绝，不遮挡代码；超长代码行自动换行，不再显示省略号。
• 有未保存的编辑器缓冲时会先提示：接受可先保存，拒绝会明确警告可能被未保存内容覆盖。
• 任何操作后剩余块、行号、增删计数实时刷新。
• 当前文件不会自动跳到下一个：没有差异后继续显示该文件操作后的最终内容。
• 超大文件 / 超长文件会给出提示，仍可使用文件级操作。

原生 diff 编辑器

• 点 打开原生对比 打开 VS Code 内置 diff（基线 ↔ 工作区，整份文件）。
• 块级操作在悬停菜单里（鼠标移到某块出现 接受此改动 / 拒绝此改动）；标题栏只有文件级按钮。
• 接受 / 拒绝后两侧实时更新；文件全部审查完毕后其 diff 标签页自动关闭。

侧边栏「设置」页

• 启动监听（默认关闭）：关闭 = 停止监听并清空列表；打开 = 按当前范围记录基线（仅补齐缺失的基线）。
• 监听路径：只追踪所选文件/文件夹（工作区内，可多选）；留空 = 整个工作区。暂不存在的路径会保留并标记「不存在」，不会因为其他路径的增删而丢失；若配置的路径全部失效则自动回退为整个工作区。
• 排除（本工作区）：加入排除路径 / glob 时会自动删除其已存基线；移除排除项后会为重新进入范围的文件补记基线（不会误报为“新增”）。与全局 aiReview.ignore 相互独立、同时生效。
• 缓存：显示当前目录与占用；选择目录… / 恢复默认；更改后把已有基线移动到新目录；清理删除当前工作区全部基线（清理后需要重新记录基线，侧边栏会提示）。
  • 查看所有缓存… 会打开独立的全宽管理面板，列出所有工作区（包括已被删除/移动的工作区）的基线缓存、占用、文件数与最后更新时间；支持逐个删除、勾选批量删除、一键清理失效缓存；当前工作区的清理仍然走确认流程。
  • 设置页也会显示所有工作区的缓存数量与总占用，并在有失效缓存时显示数量。
• 内容：
  • 追踪二进制文件（默认关）：关闭时会延迟 5 秒删除已存的二进制基线（期间重开则取消）。
  • diff 显示范围：整份文件（默认）/ 仅变更片段。
  • 复用 VS Code 编码识别（默认关）：仅当 VS Code 的 files.autoGuessEncoding 已开启时可启用；开启后对已打开的文件复用 VS Code 的编码猜测，其余文件使用内置检测。
• 基线：重置基线（以当前内容重新开始，丢弃所有待审查项）。

编码与换行

• 自动识别文件编码（UTF-8、UTF-16、GBK/GB2312、GB18030、Big5、Shift_JIS、EUC 等），中文注释不再乱码；拒绝回写时保持原编码和 BOM。
• UTF-16 文本不会再被误判为二进制。
• diff 比较忽略纯换行符差异；仅在换行符或 BOM/编码标记变化时显示为「仅格式变化」，不会把整份文件标成删除 + 新增。
• 逐块应用时，上下文行保留原文件的行尾风格；从另一侧插入的行会转换为目标文件的主要行尾风格，避免一个文件里混入两种换行。

重命名 / 移动

改动文件被重命名或移动时，会尽量搬迁基线（而不是删除再重建）：

• 有 git 时用重命名检测（含相似度，改名同时改内容也能识别）；
• 否则用内容哈希匹配（纯改名 / 移动）。

基线按工作区根目录的哈希分别存放，因此多根工作区中增删一个根目录不会让其他根目录的基线错位。

缓存管理

基线默认保存在扩展的 workspace storage 中；也可以为每个工作区单独指定缓存目录。设置页的「缓存」区域和独立的全宽面板可以集中查看：

• 所有工作区的缓存列表：工作区名称、路径、类型（默认 / 自定义 / 全局）、文件数、占用空间、最后更新时间；
• 失效缓存：工作区文件夹或 .code-workspace 文件已经不存在（通常来自已删除的旧项目），可以一键清理；
• 路径不可用：工作区或其父目录都不存在（通常是网络盘/移动硬盘未挂载），不会参与“清理失效”，避免误删只是暂时离线的项目；
• 使用中：缓存里最近有心跳（另一个 VS Code 窗口可能正打开该工作区）；批量清理会跳过，单个删除会二次确认；
• 自定义目录：跨工作区注册表会记住自定义缓存目录，即使工作区已被移除也能在这里找到；
• 逐个删除 / 勾选批量删除 / 清理失效，删除前都有确认并显示缓存根路径；当前工作区也可以在这里直接清理（会清空待审查列表，需要重新记录基线）。

自定义缓存目录如果位于某个工作区内，会被自动忽略，不会被当作待审查文件。旧版本（0.1.x）的基线布局也会显示为「旧版本」，可直接清理。

隐私提示：基线是工作区文件的明文副本。默认忽略列表不包含 .env、密钥等内容，请按需把它们加入 aiReview.ignore；不要把 cacheDir 指向 OneDrive、Dropbox、共享盘等同步/公共目录。

命令（命令面板 Ctrl+Shift+P）

接受/拒绝当前文件、接受/拒绝此改动、打开文件 等为树视图 / 面板 / 右键菜单的内联操作，不在命令面板中显示。

设置项

默认忽略：.git、node_modules、.vscode、.vscode-test、out、dist、build、.ai-review、各类 lock 文件、*.vsix 等，同时尊重 VS Code 的 files.exclude / search.exclude。自定义缓存目录如果落在工作区内，也会被自动忽略，不会自我追踪。

与 opencode 配合

opencode 直接写入磁盘文件，扩展监听器会自动捕获，无需额外集成。推荐：

1. 在目标工作区执行一次 AI 审查: 启动监听（之后会记住该工作区的选择）。
2. AI 改完文件后在「AI 审查」里审查。
3. 逐块接受 / 拒绝，或一键处理。

若希望审查范围是相对 HEAD 的所有改动，可设 aiReview.baselineFromGit: true。

开发与调试

npm install
npm run compile      # 或 npm run watch
npm run test:unit    # 纯 Node 单元测试（glob / diff / 编码）
npm test             # 运行 VS Code 集成测试（会下载测试用 VS Code）

在 VS Code 中按 F5 启动 Extension Development Host 测试；Ctrl+Shift+P → Developer: Show Running Extensions 可确认已加载。

打包安装：

npm run package      # 生成 ai-diff-review-0.3.1.vsix
code --install-extension ai-diff-review-0.3.1.vsix

已知限制

• 只追踪工作区内的文件（file scheme）。
• 二进制文件默认不追踪（可在设置开启）；超大文件仅支持文件级接受 / 拒绝。
• 编码识别为启发式；极短或歧义的文本可能识别不准（会回退 UTF-8）。「复用 VS Code 编码识别」只对已打开的文件生效，避免为每个文件创建文本模型。
• 基线默认存在扩展的 workspace storage，可在设置里改到自定义目录；不污染工程目录，但不同机器 / 工作区之间不共享。
• 未保存的编辑器缓冲不参与比较，比较和回写对象是磁盘内容。
• 无 git 且“改名同时改内容”时，重命名可能退化为删除 + 新增。
• 监听关闭时不会捕获改动；需要先启动监听或手动记录基线。