SuperAPI AI 工具集

code-reviewer

编程与开发

查看项目

更新于 10-16 10:40

技能介绍

用途

Code Reviewer 是一个 AI 技能,充当独立的 Lead Dev Reviewer 角色,用于判断精确的 Candidate 实现是否正确覆盖了已批准范围。它验证实现而不生成新需求,发现缺陷而不扩大架构。主要使用场景是:实现 Candidate 已形成,需要基于已批准需求/设计与精确 Git 边界做首次完整 Code Review,或对整改 delta 进行复审。

使用边界

该技能默认只读。可执行必要的非破坏性诊断与隔离本地验证;但未经用户授权,不改产品代码、不 push、不触发 CI、不建 PR、不 merge、不部署,不写 Secret 或共享环境。PRD、Contract、HLD/LLD、Guardrails 和用户明确批准的决定定义边界;作者 note、自测 PASS、旧 reviewer 建议不是新增需求的授权。基线带有 APPROVED 字样仍须核对具体批准来源。Code Review 通过仅表示源码可进入后续流程,不授予后续操作权限;源码、exact-SHA CI、环境/发布结论始终分层。评审不因审查轮数、发现数量或“安全起见”提高准出标准,P0/P1 关闭且必要证据完整时停止,P2 永不阻断。

主要能力

技能围绕一条评审流程展开,包含若干明确的控制点:

  1. 冻结边界与精确输入:先读取目标仓库的 AGENTS/README 与相关批准基线,生成 CRV-<UUIDv4> 标识一次实质评审。Scope Lock 包含逐仓 review_root_base、批准来源、In/Out Scope、Must Not Change、architecture budget、验证边界,并可用附带的脚本生成 canonical payload/digest。
  2. 不可变与可变绑定:Immutable 部分绑定 exact commit/tree、base/range 和 changed paths,拒绝 replace refs 与 legacy grafts;Mutable 部分通过 snapshot 脚本捕获 worktree 状态,并在给出 verdict 前重算比对,得到 MATCH/DRIFT。漂移会使旧 binding 失效。
  3. 要求、修复、建议分开:区分 Architecture surface 变化与工程边界内实现;未在批准 budget 内的增改删均视为未授权。基线含糊或最小正确修复确需未批准 surface 时,给出 SCOPE_DECISION_REQUIRED 并交 Owner 决定。
  4. 先重建生产行为,再核对作者证据:从真实入口/调用关系形成关键路径与假设,再核对作者的 PASS/修复解释,避免重复同一错误假设。行为证据以简短的行为证据行记录,覆盖 invariant、入口、helper、独立 oracle、结果与调用方。
  5. Finding 与证据分层:发现按 P0、P1、P2 分级,每条 P0/P1 需包含稳定 ID、severity、scope_classification、provenance、violated_frozen_invariant、exact_evidence、reproducer_or_failure_path、impact、minimum_boundary_preserving_fix、architecture_surface_delta 等核心字段。
  6. 整改、复用与漏审责任:根据触发事实与影响范围选择最小充分动作,可能是 initial_full_review、remediation_delta_review、focused_recovery_review 或纯 binding 收据。旧源码中原本可发现的问题会被承认为 reviewer miss,而不是转嫁给 Dev。
  7. 判定与停止:按 EVIDENCE_BLOCKED → SCOPE_DECISION_REQUIRED → CHANGES_REQUIRED → APPROVED 汇总,不使用 conditional pass,并分别报告 P0/P1、可选 P2、CI 和环境状态。满足全部 APPROVED 条件即结束。

使用方式

技能给出了一份可直接使用的 SKILL.md 文本以及一系列配套引用文件(如 reviewer-checklist、scope-lock-template、report-templates、review-policy.yaml、evidence-reuse、artifact-tools 等)。使用流程大致为:新会话先读取本文件;首次完整评审再读取 checklist 的适用章节与所需语言的模板;整改/补审只读上一轮短结论、未闭合项、delta 与受影响证据。需要磁盘恢复时可运行提供的 workflow_context.py resume 命令,参数为 --entry、--role、--task 等。可复用的命令示例包括:

python3 <plugin-dir>/scripts/workflow_context.py resume \
  --entry <已登记入口> --role reviewer --task <当前请求对应的task-id>

以及 snapshot 相关脚本:

python3 <plugin-dir>/scripts/snapshot_worktree.py --repo <repo> --base <immutable-base> --output <Candidate之外>/snapshot-before.json

技能还提供 scripts/read_machine_context.py 用于按 JSON Pointer 读取大型机器 JSON,scripts/scope_lock_digest.py 生成 canonical payload/digest,scripts/verify_candidate_binding.py 用于同内容提交的绑定核验。

适用场景

适合在已有明确批准基线的工程流程中,对某个精确 commit 或本地实现进行结构化代码评审;也适合复审新 Candidate 并闭合上一轮 P1,或在多仓库本地实现中做受控范围的独立审查。示例请求包括:“对 commit abc123 相对 main 做 Lead Dev code review”“复审新 Candidate,闭合上一轮 P1;不扩大范围”“审查三个仓库本地实现,CI/环境状态单列”。

限制

该技能默认只读,不能代替 Owner 做产品/架构批准,不自动重跑昂贵测试,也不把 CI 或环境缺口算作源码缺陷。缺少证据时不猜测 P1,而是记录最小 EB;需要改变批准边界时记录 SD 并交回原始有权决定者。同一 Candidate 内容、命令、配置/toolchain 的昂贵测试只由单一执行者(默认 Writer/CI)运行。无法稳定绑定时只列必要 EB;只有全部 immutable 才能给 certificate。mutable 与 immutable 产物必须区分,source approval 不能自动变成部署许可。