AI Session Diff Review

AI Session Diff Review 是一个 VS Code 扩展。它通过 AI 客户端的 PreToolUse、PostToolUse 和 Stop Hook，按 Codex/Claude 原生 Session ID 保存代码修改前后的快照，并在活动栏中提供逐文件审查。在 Paseo 中运行时，插件还会记录 Paseo Agent ID。

功能

• 按 Codex/Claude 原生 Session ID 或 Paseo Agent ID 筛选 AI 会话。
• 展示当前待处理的 AI 修改文件；接受或撤销后立即从列表移除。
• 活动栏图标右下角显示当前工作区待处理改动文件数；接受或撤销后自动减少，归零后隐藏。
• 点击文件打开 VS Code 原生 Diff 编辑器。右侧 AI 修改后内容与真实文件一致时，Diff 会绑定真实文件 URI，使 VS Code 原生的文件资源管理器自动定位保持关联，但不会强制切换左侧视图。
• 点击勾号接受文件修改。
• 点击叉号安全撤销文件修改。
• 点击视图标题栏的垃圾桶，清空当前工作区已记录的 Session、Diff 和快照；不会修改源码或卸载 Hook，之后的新 AI 改动仍会继续记录。
• 为当前工作区一键安装、检查或卸载 Claude Code / Codex Hook。
• Stop 事件把当前 turnId 标记为 completed，状态文件变化会自动刷新视图。
• 支持 Claude Code 的 Write、Edit、MultiEdit、NotebookEdit，Codex 的 apply_patch，以及 Paseo 的顶层 exec、exec_command 和对应封装名称；Shell 工具中带有标准 patch 内容时也能识别目标文件。

工作方式

PreToolUse  -> 找到待修改文件，保存修改前快照
PostToolUse -> 保存修改后快照，生成 .diff，更新 session / turn / file 记录
Stop        -> 标记当前 turn completed，触发 VS Code 文件监听刷新

Session 与 Paseo Agent 的关系

• Codex/Claude 原生 Session ID 是存储和聚合修改文件的主键。同一原生 Session 的连续修改仍聚合到同一组文件。
• Hook 在 Paseo 启动的 Agent 进程中读取 PASEO_AGENT_ID，并把它作为可选的附加身份写入 Session 记录；插件不会调用 Paseo API。
• 一个 Paseo Agent 可能关联多个 Codex/Claude 原生 Session。按 Paseo Agent ID 筛选时，会按原生 Session 分组显示它们的全部待处理文件；按原生 Session ID 筛选时，只显示该 Session 的文件。
• 直接运行 Codex/Claude 或历史记录没有 Paseo Agent ID 时，仍可继续按原生 Session ID 使用，不需要迁移旧记录。

快照和 unified diff 文件默认保存在 ~/.ai-code-review。如需修改目录，请在启动 VS Code 时设置 AI_CODE_REVIEW_HOME；扩展生成的 Hook 配置会通过 --storage 固定使用同一目录。扩展不会把这些文件写入业务仓库。

每个快照使用内容哈希去重；每个文件会生成聚合 .diff，每次工具写入也会生成对应的操作级 .diff。状态目录权限默认为仅当前用户可读写。快照和 Diff 包含源码内容，请按照代码安全要求管理该目录。

开发运行

前置条件：VS Code 1.85+、Node.js 18+。

1. 用 VS Code 打开本目录。
2. 按 F5 启动 Extension Development Host。
3. 在新窗口的 AI Code Review 视图中点击“为当前工作区安装 Hook”。
4. 选择 Claude Code、Codex 或同时安装，然后确认写入。
5. 重启对应 AI 客户端。Codex 首次还需要执行 /hooks，审核并信任新增 Hook。

Hook 在 AI 会话启动时加载。修改配置后，现有会话不会热更新。

一键安装 Hook

插件不会覆盖用户级配置，而是合并当前工作区内的本地配置：

• Claude Code：.claude/settings.local.json
• Codex：.codex/hooks.json

已有 Hook 会原样保留，插件自己的旧条目会被替换，重复安装不会产生重复条目。已有配置发生变化前，插件会把备份写入 ~/.ai-code-review/backups。卸载命令只删除 AI Code Review 自己的 Hook。

默认 runtime 和存储目录位于用户主目录时，Hook 命令使用 $HOME/.ai-code-review/...，不会把 /Users/<用户名>/... 这类本机绝对路径写入项目配置。自定义目录位于用户主目录之外时仍保留绝对路径，以避免 Hook 在不同工作目录下解析错误。

Hook 命令会先检查 runtime 是否存在：安装了插件时正常记录 Diff；没有安装插件或 runtime 已被清理时静默跳过，不会报 MODULE_NOT_FOUND，也不会自动下载或安装任何内容。

Codex 只会加载已信任项目中的工作区 Hook，并要求按 Hook 内容哈希单独审核。安装后请重启 Codex，再通过 /hooks 完成一次信任确认。

这些工作区配置可能出现在 Git 状态中。它们是本地配置时，可以加入仓库的 .git/info/exclude；需要团队共同使用时，也可以由团队评审后提交。

卸载 Hook

支持两种卸载方式：

• 手动卸载：打开视图标题栏的 ... 菜单，或者执行 AI Code Review: 从当前工作区卸载 Hook。选择客户端并确认后立即清理当前工作区。
• 跟随扩展卸载：插件把安装过的工作区记录在 ~/.ai-code-review/installations.json。从 VS Code 卸载扩展并完整重启 VS Code 后，vscode:uninstall 生命周期脚本会逐个清理登记过的 Hook。

两种方式都只移除命令中带有 ai-code-review-hook.js 标识的 Hook，并在修改已有配置前创建备份。其他 Hook、工作区配置字段、已捕获的 Diff、快照和备份都会保留。自动卸载遇到损坏的 JSON 时不会覆盖文件，失败记录写入 ~/.ai-code-review/uninstall-errors.ndjson。

F5 启动的 Extension Development Host 不属于真正安装的扩展，不会触发 VS Code 的卸载生命周期；开发调试时请使用手动卸载命令。

手动配置兜底

执行 AI Code Review: 查看手动 Hook 配置 会把 Hook runtime 更新到稳定路径，并生成 Claude Code 和 Codex 配置片段。配置采用以下调用形式：

[ ! -f "$HOME/.ai-code-review/runtime/scripts/ai-code-review-hook.js" ] || node "$HOME/.ai-code-review/runtime/scripts/ai-code-review-hook.js" --event PreToolUse --client claude --storage "$HOME/.ai-code-review"
[ ! -f "$HOME/.ai-code-review/runtime/scripts/ai-code-review-hook.js" ] || node "$HOME/.ai-code-review/runtime/scripts/ai-code-review-hook.js" --event PostToolUse --client claude --storage "$HOME/.ai-code-review"
[ ! -f "$HOME/.ai-code-review/runtime/scripts/ai-code-review-hook.js" ] || node "$HOME/.ai-code-review/runtime/scripts/ai-code-review-hook.js" --event Stop --client claude --storage "$HOME/.ai-code-review"

通常不需要手动复制。只有一键安装因现有配置不是合法 JSON 等原因被阻止时，才使用这些片段排查或手动合并；不要覆盖原有 Hook。

Codex 还要求持久化 Hook 信任。合并配置并重启 Codex 后，请在 /hooks 中确认并信任新增的 ai-code-review-hook。不要把 --dangerously-bypass-hook-trust 作为日常启用方式。

接受与撤销

• 接受：只把记录标记为 accepted，磁盘文件保持不变。
• 撤销：当磁盘内容仍与 AI 最后快照一致时，恢复修改前内容；AI 新建的文件会被删除，AI 删除的文件会被恢复。
• 列表清理：接受或撤销成功后，该文件会立即从左侧待处理列表移除；底层记录仍会保留，用于审计和冲突保护。
• 冲突保护：如果 AI 写完后文件又被修改，扩展不会覆盖新内容，而是提示冲突。
• 交错修改保护：如果同一文件的两次 AI 写入之间出现人工修改或其他会话修改，扩展不会用会话初始快照覆盖它们，而是拒绝自动撤销。
• 未保存保护：文件在 VS Code 中存在未保存编辑时，扩展不会执行撤销。

当前边界

Hook 只有在 PreToolUse 阶段能识别目标文件时才能保存可靠的修改前快照。任意 Shell 命令可能修改未知文件，因此不会通过扫描和复制整个工作区来猜测；无法从文件字段或 patch 内容识别路径的改动不会进入审查列表。

默认单文件快照上限为 2 MiB。可以通过 AI_CODE_REVIEW_MAX_FILE_BYTES 调整。超过上限的既有文件会记录元数据，但不能展示文本 Diff，也不能恢复其旧内容；超限的新建文件仍可通过删除文件安全撤销。

验证

npm run verify
npm run test:extension-host