用途
PR Code Review 用于对拉取请求(Pull Request)进行全面的代码审查。它通过并行调度多个专项审查子代理,每个子代理聚焦代码质量的一个方面,从而比单一通用审查者发现更多问题。所有发现均带置信度评分,过滤后仅呈现高信号问题。
主要能力
- 并行专项审查:为每个适用的审查维度启动一个子代理,包括缺陷检测、错误处理、类型设计、测试覆盖、注释质量和项目规范符合度。
- 置信度评分:每个发现获得 0-100 的置信度分数,低于 75 的发现被过滤掉。
- 误报预防:不报告 PR 之前已存在的问题、项目既定模式、风格挑剔、linter 可捕获的问题等。
- GitHub 审查提交:针对 GitHub PR 提交正式审查,使用行内评论并给出审查结论(批准或请求更改)。
- 重新审查:检测重新审查场景,获取未解决的审查线程,对照当前代码判断是否已解决,并解决已处理的线程。
使用方式
工作流程
- 收集上下文:获取 PR diff、变更文件列表、项目指南(如 CLAUDE.md、AGENTS.md、.cursorrules、CONTRIBUTING.md 等)以及 PR 描述。若 PR 已关闭、为草稿或仅涉及锁文件/生成代码/CI 配置,则跳过审查。
- 调度并行审查者:根据变更内容选择适用的审查维度,为每个维度启动一个子代理。子代理接收 PR diff、变更文件完整内容、项目指南、维度特定指令和输出格式。
- 收集与过滤:合并所有审查者的发现,丢弃置信度低于 75 的项。使用 git blame 验证标记行确实在本 PR 中变更,对既有代码的发现降级或丢弃。
- 报告:输出审查摘要,按严重程度分组列出关键问题(置信度 90-100)和重要问题(置信度 75-89),并附正面观察。
审查维度选择
| 维度 | 包含条件 | 参考文件 |
|---|---|---|
| 缺陷检测 | 始终 | bug-detection.md |
| 错误处理 | 含 try/catch、错误回调、回退的代码 | error-handling.md |
| 类型设计 | 新增或修改的类型/接口/类定义 | type-design.md |
| 测试覆盖 | 始终(即使 diff 中无测试也标记缺失) | test-coverage.md |
| 注释质量 | 含文档注释、JSDoc、docstring 的文件 | comment-quality.md |
| 规范符合度 | 存在项目指南文件时 | guidelines-compliance.md |
在 GitHub 上提交审查
当审查目标是 GitHub PR 时,应提交正式审查而非普通评论。对每个发现使用行内评论,包含置信度分数和建议。提交审查结论:若过滤后无置信度 ≥75 的发现则批准;若存在关键(90-100)或重要(75-89)发现则请求更改。使用平台的 PR 审查 API(如 GitHub CLI 的 gh api)一次性提交行内评论和结论,不要将发现作为独立评论逐个发布。
重新审查
当用户说“重新审查”、“跟进审查”或“检查评论是否已处理”,或 PR 已有先前审查线程时,进入重新审查流程:
- 使用 GraphQL API 获取所有未解决的审查线程。
- 对每个未解决线程,读取当前文件内容,对照原始评论判断问题是否已解决。判断标准:标记位置的代码明确解决了关切 → 已解决;线程标记为 isOutdated 且周围代码正确 → 已解决;问题原样存在 → 未解决;部分解决或解决方式不同 → 酌情判断,若关切不再有效则解决。
- 对确认已解决的线程,通过 GraphQL 解决。不要解决仍然有效的线程。
- 报告已解决和仍开放的线程,然后对新变更继续正常审查流程。
适用场景
- 合并前审查拉取请求
- 被要求“审查这个 PR”或“代码审查”
- 批准生产代码前
- 作者处理审查意见后重新审查 PR
限制
- 不适用于审查本地未提交的更改(应直接审查 diff)
- 不适用于整个代码库的架构审查(范围过宽)
- 仅审查新增/修改的行及其直接上下文,不审查变更文件中的所有代码
- 不报告 PR 之前已存在的问题
- 不报告项目既定模式、风格挑剔、linter/格式化器/类型检查器可捕获的问题
- 不提供与本次 diff 中具体风险无关的通用“最佳实践”建议
- 置信度低于 75 的发现被过滤掉
- 始终至少运行缺陷检测和测试覆盖两个维度
置信度评分
| 范围 | 含义 | 行动 |
|---|---|---|
| 90-100 | 确定的缺陷、安全问题或明确违反指南 | 必须修复 |
| 75-89 | 可能的问题,值得关注 | 应当修复 |
| 50-74 | 可能的关切但不确定 | 过滤掉 |
| 0-49 | 挑剔、既有问题或误报 | 过滤掉 |
降低置信度的情况:问题在 PR 之前已存在、周围代码显示有意模式、会被 linter 或类型检查器捕获、无运行时上下文时含义模糊、风格偏好而非正确性。
提高置信度的情况:新代码中明确的逻辑错误、本 PR 引入的安全漏洞、明确违反项目指南、明显失败模式缺少错误处理、关键代码路径缺少测试。
常见错误
| 错误 | 纠正 |
|---|---|
| 审查变更文件中的所有代码 | 仅审查新增/修改的行及其直接上下文 |
| 报告既有问题 | 使用 git blame 验证问题来自本 PR |
| 大量低置信度发现 | 严格执行 ≥75 阈值 |
| 通用建议(“增加更多测试”) | 具体缺口(“auth.ts:47 错误路径缺少测试”) |
| 因 PR 看似简单而跳过维度 | 至少始终运行缺陷检测和测试覆盖 |