SuperAPI AI 工具集

pr-code-review

编程与开发

查看项目

更新于 10-16 06:56

技能介绍

用途

PR Code Review 用于对拉取请求(Pull Request)进行全面的代码审查。它通过并行调度多个专项审查子代理,每个子代理聚焦代码质量的一个方面,从而比单一通用审查者发现更多问题。所有发现均带置信度评分,过滤后仅呈现高信号问题。

主要能力

  • 并行专项审查:为每个适用的审查维度启动一个子代理,包括缺陷检测、错误处理、类型设计、测试覆盖、注释质量和项目规范符合度。
  • 置信度评分:每个发现获得 0-100 的置信度分数,低于 75 的发现被过滤掉。
  • 误报预防:不报告 PR 之前已存在的问题、项目既定模式、风格挑剔、linter 可捕获的问题等。
  • GitHub 审查提交:针对 GitHub PR 提交正式审查,使用行内评论并给出审查结论(批准或请求更改)。
  • 重新审查:检测重新审查场景,获取未解决的审查线程,对照当前代码判断是否已解决,并解决已处理的线程。

使用方式

工作流程

  1. 收集上下文:获取 PR diff、变更文件列表、项目指南(如 CLAUDE.md、AGENTS.md、.cursorrules、CONTRIBUTING.md 等)以及 PR 描述。若 PR 已关闭、为草稿或仅涉及锁文件/生成代码/CI 配置,则跳过审查。
  2. 调度并行审查者:根据变更内容选择适用的审查维度,为每个维度启动一个子代理。子代理接收 PR diff、变更文件完整内容、项目指南、维度特定指令和输出格式。
  3. 收集与过滤:合并所有审查者的发现,丢弃置信度低于 75 的项。使用 git blame 验证标记行确实在本 PR 中变更,对既有代码的发现降级或丢弃。
  4. 报告:输出审查摘要,按严重程度分组列出关键问题(置信度 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 已有先前审查线程时,进入重新审查流程:

  1. 使用 GraphQL API 获取所有未解决的审查线程。
  2. 对每个未解决线程,读取当前文件内容,对照原始评论判断问题是否已解决。判断标准:标记位置的代码明确解决了关切 → 已解决;线程标记为 isOutdated 且周围代码正确 → 已解决;问题原样存在 → 未解决;部分解决或解决方式不同 → 酌情判断,若关切不再有效则解决。
  3. 对确认已解决的线程,通过 GraphQL 解决。不要解决仍然有效的线程。
  4. 报告已解决和仍开放的线程,然后对新变更继续正常审查流程。

适用场景

  • 合并前审查拉取请求
  • 被要求“审查这个 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 看似简单而跳过维度 至少始终运行缺陷检测和测试覆盖