SuperAPI AI 工具集

pr-review

编程与开发

查看项目

更新于 10-15 15:45

技能介绍

PR Review 是一个面向 PR/MR 代码差异的审查技能,核心思路是把审查工作交给多个独立角色子代理并行完成,主会话只做编排与发布,从而避免单一视角带来的偏差。

【用途】 用于审查 PR/MR diff 并产出结构化发现,覆盖安全、逻辑、性能、跨文件影响、测试覆盖与规格合规等维度。明确不适用于:撰写或改进 PR 描述、需要业务判断的范围/方向设计评审、编写实际代码或 diff、深度 CVE/供应链/OWASP 扫描、撰写发布说明或 CHANGELOG、终端用户/UX 评审(应使用 /qa 或 /design-review),以及自动批准或自动合并(本技能只产出发现,由人工合并)。

【主要能力】

  • 并行调度角色子代理:security-reviewer、staff-engineer、sdet;当存在 spec 时额外调度 spec-auditor。
  • 并行要求:在单条消息中发起多个 Agent 工具调用,且每个调用都设置 run_in_background: false。并行指“一条消息、多次调用”,并非后台执行;在任一报告未返回前结束回合会导致该报告被丢弃且不发布任何内容。
  • 失败处理:某个子代理失败时继续其余部分,但必须在置顶评论头部暴露该失败(绝不静默);全部失败则报告失败,不回退到自我审查。
  • 发布在主会话完成(合并之后),不在子代理中进行。
  • 输出形式:一条置顶摘要评论 + 逐条行内评论;置顶评论内嵌定位标记与上次审查 HEAD 的 SHA 标记。
  • 模式:auto(默认)/ full / incremental / local。auto 依据是否存在置顶评论、last_sha 是否可达、是否等于 HEAD 来决定走增量、全量或 noop。
  • 严重度合并规则与数量上限(volume caps)在合并阶段应用。
  • 支持 dry-run:构建置顶与行内负载并打印到控制台,不写入远端 API。

【使用方式】 必需输入:pr,格式为 <owner>/<repo>#<N> 或完整 PR/MR URL(GitHub PR 或 GitLab /-/merge_requests/<iid>),用于平台识别、置顶查找与发布;不做基于分支的隐式检测。例外:mode: local 不需要 pr。 可选输入:mode、dry-run、base(仅 local 模式,替代基于置顶/PR 的 base 查找)、last_sha(仅 local 模式用于增量审查)、spec(路径/URL/内联/多条,设置 has_spec 标志;缺失则不调度 spec-auditor)、test direction(approach/location/focus,缺失时 sdet 依据 diff 性质使用启发式)、context(业务风险、领域规则、已知取舍、环境约束、部署上下文、热修复收窄、跨 PR 耦合等,可在合并时调整严重度)、repo rules(来自已提交项目文件的仓库级审查约束,如 ADR、测试约定、术语表、模块 README、已接受的设计取舍)。 平台:通过 gh 发布到 GitHub,通过 glab 发布到 GitLab;两者使用相同的置顶/行内标记,仅传输方式不同。自托管 GitLab 需从 MR URL 或 git remote 推导主机名,不可硬编码;需在每个调用 glab 的 bash 块内设置 GITLAB_HOST 并先用 glab api user 断言认证,失败则中止,不得改用 curl 兜底。

【适用场景】

  • 对 PR/MR diff 做安全/逻辑/性能扫描并产出结构化发现。
  • 存在 spec 时进行规格合规验证。
  • 按严重度、影响范围(blast radius)与置信度组织发现。
  • 将发现以置顶摘要 + 行内评论形式发布到 PR/MR。
  • 由其他技能或监督会话调用 local 模式,对 diff 做无偏的多角色审查(输出 JSON 到 stdout,而非 PR/MR 置顶/行内评论)。

【限制与注意事项】

  • 主会话不得自行审查任何类别,必须调度子代理;不得顺序调度;不得在审查期间编辑代码(审查只读不写)。
  • 不得因“diff 看起来没有 X”而跳过某个子代理;不得在未阅读子代理发现的情况下声称审查通过。
  • 不得在合并发现之前发布行内评论(顺序为调度 → 合并 → 发布)。
  • 先前发现的行号移动不等于行为已修复,需子代理验证后才可标记为“Likely fixed”。
  • GitLab 特有坑:置顶评论必须用 PUT .../notes/$ID 原地编辑,每次新发会导致增量检测失败;行内位置必须通过 --input 以 JSON 体传递,使用 -f "position[...]" 形式会被静默丢弃并变成未锚定的普通 DiscussionNote;提交状态状态词为 failed(GitHub 为 failure),且 GitLab 无删除状态 API。
  • 当存在多个置顶评论(历史遗留重复)时,以最新(id 最大)为权威,发布时原地编辑该条并删除其余。
  • 若 last_sha 不可达(force-push 等),回退到全量并在置顶正文前加提示。
  • 若 last_sha == HEAD,则跳过调度与发布并打印提示,不触碰置顶评论。
  • 关于收费、价格、具体平台支持范围之外的信息,资料未提供。