SuperAPI AI 工具集

judge

编程与开发

查看项目

更新于 11-16 03:53

技能介绍

用途 Judge 用于在合并或自动合并之前审查一个变更(pull request、分支或 diff),包括由子代理构建的 PR。触发说法如“judge this PR”“review this…”。它在终端输出审查报告,然后修复审查发现的问题。报告同时展示检查了什么和发现了什么,让读者看到审查没有覆盖的地方。

来源与授权 该技能改编自 Felipe Rodrigues(github.com/felipfr)与 Tech Leads Club 的 The Judge v1.4.0,https://github.com/tech-leads-club/agent-skills,采用 CC-BY-4.0(https://creativecommons.org/licenses/by/4.0/)许可。修改点包括:以终端报告替代 GitHub review、增加覆盖表、使用全新上下文的审查者、增加修复循环。许可细节见 NOTICE.md。

规则

  • 仅限终端。绝不向 GitHub 发布 review、评论或批准。
  • 每个发现都要有证据。关于本仓库的断言需引用你读过的 path:line;关于库、API 或框架的断言需引用本次审查中获取的官方 URL;可在本地复现的 blocker 需附命令及其输出。
  • 不得凭记忆引用外部信息。在断言依赖行为之前,先阅读当前文档、变更日志或安全公告。研究无结论时,把发现转为问题。
  • 报告每一个真实问题。严重程度与有效性是两回事:小的真实问题是 nit,不是丢弃。只有缺证据才丢弃发现。
  • 工具类结果属于检查结果。lint、typecheck 和测试捕获的内容放在“Checks run”下,而非 findings 下。
  • 审查者不写代码。各轮审查在具备全新上下文的子代理中运行,主会话负责核验。
  • 覆盖情况是报告的一部分。没有任何审查轮次读过的文件列为未审查。审查报告它检查了什么,不能证明没有遗漏,报告不得声称相反。

严重程度 🔴 blocker:数据丢失、可利用的安全问题、金额错误、认证失效、不可逆迁移、日志中出现 PII;判定 FIX_FIRST。 🟠 should-fix:真实缺陷但不是合并风险;判定 FIX_FIRST。 🟡 nit:次要问题;无判定。 🟣 pre-existing:本次变更未引入的缺陷;无判定,作为后续跟进报告。 只有在没有未关闭的 🔴 和 🟠 时判定才是 MERGE。用户以其本人措辞接受的发现视为关闭:将状态设为 accepted,并把原话放入 accepted_reason。

工作流程 Step 0:解析变更。有 PR 时使用 gh pr view <n> --json number,title,body,baseRefName,headRefName 和 gh pr diff <n>;无 PR 时将该分支与其与默认分支的合并基点做 diff。把 diff 和改动文件列表保存到临时文件。将每个改动文件归类为 core 或 skipped(锁文件、生成代码、快照、vendored 依赖、构建产物)。每个 skipped 文件都要有原因。一处删除、另一处相同新增的代码属于移动,不按新增审查。

Step 1:确定性检查。下文 <judge-skill-dir> 指本 SKILL.md 所在文件夹。运行仓库的 typecheck、lint 以及覆盖改动文件的测试,记录确切数量。若某项检查未配置,应说明。然后对 diff 运行绕过扫描:

python3 <judge-skill-dir>/scripts/scan_bypasses.py < diff.patch

每个命中项是 Pass F 的候选,不是发现。

Step 2:调研。列出 diff 触及的每个外部面:新增或升级的依赖、调用的 API、对版本敏感的框架与语言特性。阅读每个的官方来源,记录 URL 及其支持或反驳的断言。若 diff 未触及任何外部面,写明这一点。

Step 3:审查轮次。将审查者作为子代理派发。改动 core 行少于 400 行:一个审查者运行所有轮次;超过:三个审查者并行(A+B、C+D、E+F)。当运行环境允许选择模型时,审查者使用比本会话低一档的模型。

每次派发提示需包含:diff 路径、core 文件列表、Step 1 和 Step 2 的结果、本技能 references/review-standards.md 的绝对路径并要求先阅读,以及下述返回结构。

A. 正确性与逻辑 B. 安全性 C. 结构与可维护性 D. AI 冗余与无用注释 E. PR 描述或提交信息中的声明 F. 绕过、重复与临时凑合实现

每个审查者返回:候选发现(断言、严重程度、证据),以及每个 core 文件它实际为该文件运行了哪些轮次。空间不足的审查者要说明未覆盖哪些文件。

若 Claude Code 内置的 code-review 技能可用,可在同一目标上将其作为独立的第二审查者运行,<target> 设为 high。绝不传 --fix 或 --comment。其结果加入 Step 4 的候选。它不报告逐文件轮次,因此只增加发现,永不计入覆盖。

Step 4:核验。在主会话中,对每个候选:打开引用位置确认断言。当仓库内的测试或短脚本可复现时,复现 A 和 B 的 🔴 候选;可行的复现若失败则否决该发现。去重。确定最终严重程度;不确定的 blocker 转为 🟠 问题。

Step 5:门禁。将 findings.json 写入临时目录,然后在仓库根目录运行:

python3 <judge-skill-dir>/scripts/judge_gate.py findings.json changed-files.txt

示例结构: { "round": 1, "verdict": "FIX_FIRST", "files": {"core": ["src/billing/invoice.ts"], "skipped": [{"path": "bun.lock", "reason": "lockfile"}]}, "coverage": {"src/billing/invoice.ts": ["A", "B", "C", "D", "F"]}, "unverified": [], "claims": [{"claim": "fixes the rounding bug", "evidence": "tests/invoice.test.ts:40"}], "findings": [{ "id": "F1", "path": "src/billing/invoice.ts", "line": 142, "severity": "blocker", "status": "open", "claim": "applyDiscount divides by items.length with no empty-list guard", "evidence": [{"type": "internal", "ref": "src/billing/invoice.ts:142"}] }] }

未被任一审查轮次覆盖的 core 文件放入 unverified,格式为 {"path": "...", "reason": "..."}。证据类型分 internal(相对仓库根目录的 path:line)、external(https URL)或 repro(命令及其输出)。已修复的发现需用 fixed_in 指明提交。

出现以下情况时门禁失败:

  • 某个改动文件既非 core 也非 skipped,或 skipped 文件无原因;
  • 某个 core 文件缺少轮次且没有 unverified 条目;
  • 引用的 path:line 不存在或指向仓库外;
  • 🔴 或 🟠 没有证据;
  • finding id 重复、缺少 claims,或 round 不在 1 到 3;
  • 判定与未关闭发现不一致。 修复输入直到退出码为 0。不要修改门禁脚本。

Step 6:报告。按以下顺序打印各节:

  • Verdict:MERGE 或 FIX_FIRST,并用一句话说明原因。
  • Findings:ID、严重程度、path:line、断言、修复。先说明问题及位置,再给出在根因处生效的最小修复。
  • Coverage:每个 core 文件一行,附读取它的轮次。
  • Not verified:审查未覆盖的文件或轮次及原因,为空时写 none。
  • Hardening notes:见 review-standards.md 的 Pass B。
  • Research log:URL 及每个支持或反驳的内容。
  • Checks run:Step 1 的数量。
  • Skipped files with reasons。
  • Promote to lint rule:下次可由 linter 捕获的发现,或写 none。

Step 7:修复。当该技能作为用户已批准工作的合并前门禁运行时执行修复。若用户只是提问(如“pode mergear?”“what's wrong with this PR?”)或要求报告,则在 Step 6 后停止。修复所有 🔴 和 🟠,在变更范围内修复 🟡,将 🟣 留作后续跟进。修复后进行新一轮:重跑 Step 1,将每个发现标记为 fixed(并指明提交)或 open,把修复 diff 发给一个全新子代理只查找新的 🔴。把修复触及的文件加入文件列表和覆盖范围。重跑门禁并再次打印报告。最多两轮修复。若第二轮修复后(round 3)仍有 🔴 或 🟠 未关闭,停止并向用户给出未关闭发现及已尝试的措施。判定为 FIX_FIRST 时不得合并或启用自动合并。

适用场景与限制 适用于合并前或自动合并前的变更审查,尤其需要对审查覆盖范围透明、要求证据支撑结论的场景。限制:仅在终端输出,不向 GitHub 发布任何内容;不凭记忆断言外部依赖行为;覆盖情况只能说明检查了什么,不能证明无遗漏;修复循环最多两轮;具体依赖的安装方式、收费与平台支持信息暂未提供。