AI 写的 PR 越来越长，审查顺序却还是按文件名：Guided Review 如何把 diff 还给人读
AI 编码 Agent 可以在一次提交中改动 schema、接口、调用点和测试。真正难的往往不是让模型再给一段摘要，而是让审查者建立正确的阅读顺序：先看数据结构和约束，再看核心逻辑，最后回到调用点与测试。GitHub 的 Files changed 视图按文件排列，这对小改动足够；面对跨文件的 Agent 变更，却会让人反复在不同文件间跳转，难以判断一处修改到底改变了什么行为。
Guided Review 是一个面向 GitHub Pull Request 的 Chrome 扩展。它不试图替人批准代码，而是把 diff 中相关的 hunks 聚为有顺序的 review units，并在 GitHub 页面上用覆盖层带领审查。项目采用 Apache-2.0 许可证，源码可读；从仓库 README 和公开文档看，扩展直接与 GitHub 及用户选定的模型提供商通信，没有由 Guided Review 托管的审查后端。
这决定了它适合解决的问题很具体：把 AI 当作审查路径的编排器，而不是代码正确性的裁判。如果团队需要的是自动阻止高风险变更、强制合规检查或 CI 门禁，仍应使用测试、静态分析、分支保护和人工审批；Guided Review 只改善人实际阅读 diff 的过程。
它把“文件列表”变成什么
启动一次审查时，扩展读取 PR 的 unified diff，把它发送给选定的模型提供商，请模型生成逻辑分组与简短说明；随后将分组映射回真实解析的 diff。文档给出的理想顺序是 schema、逻辑、调用点、测试。模型可以帮助描述结构，但代码行、评论位置与最终提交都仍依附 GitHub 的真实 diff，而不是模型虚构的补丁。
例如，一个 Agent 为订单增加“取消原因”时，原始文件顺序可能是：api.ts、db.sql、order.ts、order.test.ts。更可审查的顺序应当是：
- 先看
db.sql：字段是否允许为空、历史记录如何迁移； - 再看
order.ts：状态转换是否只在可取消状态执行； - 接着看
api.ts：权限与参数校验是否在写入前完成； - 最后看
order.test.ts：正常取消、重复取消、无权限调用是否都有证据。
这里的价值不是“模型总结得漂亮”，而是让审查者能沿着一次行为变更的因果链走完。若分组不合理，审查者仍应回到原始 Files changed 视图核对；分组是导航建议，不是事实来源。
先用无密钥路径校验工作流
项目提供了一个很实用的降级行为：未配置模型 API key 时，仍可以一文件一个 review unit 的方式导航和评论。这意味着团队可以先验证浏览器扩展是否适合现有审查习惯、快捷键是否顺手、评论是否正确落在目标 diff 行，再决定是否接入模型。
从源码构建扩展时，在仓库根目录执行以下命令：
npm install npm run build:extension
接着打开 chrome://extensions，启用 Developer mode，选择“Load unpacked”，并加载 apps/extension/dist。
加载后打开一个 GitHub PR，点击 Start Guided Review。即便尚未设置模型 key，也可以观察“按文件退化”的导航是否正常；这一步很适合在不把私有 diff 发送给任何模型前完成基础验收。
接入模型前，先确认数据边界
需要 AI 分组时，用户在扩展选项页配置 Anthropic、OpenAI 或 Grok 之一以及自己的 API key。官方文档说明，key 保存于本机的 chrome.storage.local；开始审查时，相关 PR 内容会从 GitHub 取得，并发送到用户选择的模型提供商以生成审查计划。因而“扩展没有自建审查后端”不等于“代码永不离开设备”。
落地前应至少做四件事：
- 核对组织是否允许把该仓库或该类 PR 内容发送给选定模型提供商；敏感代码、客户数据和受出口管制的项目应有单独规则。
- 使用低风险、已公开或已脱敏的 PR 做试点，并记录一次计划生成实际提交了哪些内容。
- 为不同仓库准备不同的审查策略：依赖升级可以接受较粗粒度分组，认证、支付和数据删除类变更则应要求审查者先看安全约束与测试。
- 把“模型给出的两行概览”当作索引，不把它复制成批准理由。批准理由应明确写出审查过的行为、风险和测试证据。
扩展也支持在覆盖层中留下行级评论并提交 review；但提交 review 需要连接 GitHub，而仅阅读 PR 与生成计划不需要 GitHub OAuth。将两种权限拆开，可以减少“为了看一个分组就授权写入”的不必要范围。
失败模式：把导航工具误当审查自动化
第一个常见错误是直接依赖摘要。大 diff 的分组可能遗漏跨单元的数据流，模型也可能把变化的意图说得比实际代码更完整。解决方法是把每个 unit 的结论回链到真实 hunk，并对权限、错误处理、事务边界和测试缺口保留自己的检查清单。
第二个错误是忽略成本和上下文规模。生成计划至少会向所选模型发出一次请求，费用随 diff 大小和模型选择变化。对于自动生成的大型 PR，可以先让提交者按逻辑拆分，或要求先运行格式化、测试与静态检查，避免把大量无意义格式改动送入审查计划。
第三个错误是把本地存储等同于完整的数据治理。API key 虽在本机，但 PR 内容仍会流向用户配置的第三方模型；GitHub 连接则用于代表用户提交评论或 review。团队应把这些边界写入仓库贡献指南，而不是只在某个开发者的浏览器选项中默认开启。
适合从哪里开始
Guided Review 最适合“代码已经由人负责、但阅读路径被 AI 生成的大量改动打散”的团队。先在一个小型、低风险 PR 上使用无 key 模式验证导航；再用经允许的模型和非敏感变更验证分组质量；最后才把它纳入日常审查。无论是否使用它，最重要的控制仍不变：看真实 diff、运行可重复的检查、让有业务上下文的人对合并负责。
它并没有消灭代码审查的判断成本；它做的是把这份成本从“在文件列表里找关联”转移回“判断一次变更是否真的正确”。对 AI 编码时代的审查流程而言，这通常是更值得保留在人手中的部分。
把 review unit 接回既有质量门禁
要避免“界面更顺手，所以审查更可靠”的错觉，建议把每个 review unit 和已有工程控制对应起来。涉及数据库或状态机的 unit，审查者应要求迁移脚本、回滚方案与并发测试；涉及接口边界的 unit，应确认鉴权、输入校验、错误码与兼容性；涉及调用点的 unit，应搜索旧调用是否仍保留，以及 feature flag、配置默认值是否改变；涉及测试的 unit，则要区分“代码覆盖到”与“失败时真的能阻止合并”。Guided Review 能把这些内容排出先后，但不能替 CI 运行它们。
一个可操作的团队约定是：提交者在 PR 描述中先列出变更的业务不变量与验证命令；审查者用 review unit 逐项定位实现证据；对无法从 diff 证明的结论，要求补测试、运行记录或设计说明。这样，AI 生成的分组不会取代 PR 模板，反而会成为把模板问题落回代码位置的索引。若一个 unit 涉及删除数据、权限提升、计费或对外发送，最好把“是否允许执行”单独列为人工确认项，不因为摘要看起来合理就默认通过。
对于由 Agent 批量生成的重构，还应主动检查分组的盲区：同名函数是否在未改动文件中仍被调用、生成的测试是否只复述实现细节、异常分支是否被模型为了简化叙述而忽略。审查完成后，可以随机从每个 unit 抽取一个关键结论，回到原始 diff 和测试结果做反向验证。这个小步骤能防止团队逐渐把“被 AI 组织过”误认为“已经被 AI 验证过”。
它并没有消灭代码审查的判断成本；它做的是把这份成本从“在文件列表里找关联”转移回“判断一次变更是否真的正确”。对 AI 编码时代的审查流程而言，这通常是更值得保留在人手中的部分。