用记分板量化评估AI代码评审，而非靠Demo感觉

Full translation

完整中文译文

团队考虑引入 AI 评审助手时，有一种熟悉的流程：有人打开产品，把当前迭代里的某个文件丢进去，看着它输出一段听起来很自信的文字，然后回来汇报说"看起来还不错"。两个月后，没人能说清楚这个订阅究竟是找到了真正的 bug，还是只是在生成听起来合理的废话。

问题不在工具，而在测试本身。单次的印象无法区分一个真正能发现缺陷的评审，和一个只是听起来像在评审的评审。你真正需要的是一块记分牌：一组固定输入及已知答案、一套提前写好的评分规则，以及一个可以随时重跑的脚本。本文将详细讲解如何用免费层级的模型访问来搭建这套体系，并在最后如实说明它在哪些地方会失效。

为什么"看起来不错"不能作为证据

代码评审助手需要完成三项截然不同的工作，随便演示的方式会把它们全部混为一谈：

检测 — 标记出行为确实有问题的那些行。

解释 — 说明为什么有问题，且方式要让维护者能够采取行动。

克制 — 对文件中没问题的百分之九十保持沉默。

大多数演示式的测试只验证了前两项，因为粘贴进去的代码片段满是缺陷，自然会引发评论。克制——这个属性决定你的团队是否会在一周内把工具关掉——只有在干净代码上测量误报率时才会显现。因此下面的实验会分别测试这三项工作。

产物：基于变异评级的记分牌

设计包含三个部分：变异语料库、干净文件的对照组，以及评分脚本。

1. 用变异改造真实代码，而不是手写假的 buggy 代码

手写的"buggy 示例"文件看起来往往像教科书练习。真实的缺陷隐藏在看似合理的逻辑内部。所以从你维护的项目中选取文件，对每个副本施加一个小变异：

删除一条守卫子句的一行（if (!user) return; 消失），
翻转一个边界（<= 变成 <），
交换两条有依赖关系的语句的顺序，
从清理列表中移除一个元素（finally 块里的一个 close() 调用消失），
把调用中的一个参数改成类型相似但值错误的参数。

每个变异产生一个一到两行的 diff，对抗的是之前能正常工作的代码。这是你能得到的"一个疲惫队友会写的 bug"的最接近版本。将原始文件保存为对照文件。对于每个变异副本，在清单中记录预期判决：

{
  "case_id": "cart-total-boundary",
  "file": "mutated/cart_total_03.js",
  "control": false,
  "expect_finding": true,
  "severity": "high",
  "hint_terms": ["off-by-one", "boundary", "total"]
}

对照文件使用相同的清单条目，但 control: true 且 expect_finding: false。目标是突变文件与干净文件大约 2:1 的比例——干净的案例足够多，误报才能真实反映在数据里。

2. 一个评测严重程度而非感觉的运行器

这里是评测框架，用 Node 编写，因为大多数评估评审工具的团队本来就生活在 JS 或 TS 代码库中。它将每个文件 POST 到一个可配置的端点，应用严重程度加权规则，并且——这是大多数评测会跳过的一部分——在重命名局部变量后重新运行每个变异案例，以检验发现结果是否能经受一次表面上的重写：

#!/usr/bin/env node
// review-scoreboard.mjs
// Usage: REVIEW_URL=... REVIEW_TOKEN=... node review-scoreboard.mjs manifest.json
// Provider-agnostic: adjust buildRequest/parseReply to your endpoint's shape.

import { readFileSync } from "node:fs";

const URL_ = process.env.REVIEW_URL;
const TOKEN = process.env.REVIEW_TOKEN ?? "";

const SYSTEM =
  "You are a code reviewer. Report only correctness defects. " +
  "Format each finding as: @<line> [severity:low|med|high] <reason>. " +
  "If the code is correct, reply with exactly: CLEAN";

const SEVERITY_POINTS = { high: 3, med: 2, low: 1 };

async function review(code) {
  const res = await fetch(URL_, {
    method: "POST",
    headers: {
      "content-type": "application/json",
      authorization: `Bearer ${TOKEN}`,
    },
    body: JSON.stringify({ system: SYSTEM, input: code }),
  });
  if (!res.ok) throw new Error(`HTTP ${res.status}`);
  const body = await res.json();
  return body.output; // adapt to your provider
}

// Superficial rename: swap identifier spellings so we can test
// whether the model is reasoning about structure or pattern-matching names.
function renameNoise(code) {
  return code
    .replaceAll("total", "acc")
    .replaceAll("items", "rows")
    .replaceAll("user", "acct");
}

function grade(reply, testCase) {
  if (testCase.control) {
    const noisy = reply.trim().toUpperCase() !== "CLEAN";
    return { kind: "control", falseAlarm: noisy };
  }
  const mentionsHint = testCase.hint_terms.some((t) =>
    reply.toLowerCase().includes(t.toLowerCase()),
  );
  const sevMatch = reply.match(/severity:(high|med|low)/i);
  const sev = sevMatch ? sevMatch[1].toLowerCase() : null;
  return {
    kind: "mutated",
    found: mentionsHint,
    severityRight: sev === testCase.severity,
    points: mentionsHint ? SEVERITY_POINTS[testCase.severity] : 0,
  };
}

const manifest = JSON.parse(readFileSync(process.argv[2], "utf8"));
const rows = [];

for (const c of manifest.cases) {
  const code = readFileSync(c.file, "utf8");
  const first = await review(code);
  const g1 = grade(first, c);

  let stable = null;
  if (!c.control) {
    const second = await review(renameNoise(code));
    stable = grade(second, c).found;
  }
  rows.push({ id: c.case_id, ...g1, stableAfterRename: stable });
}

const mutated = rows.filter((r) => r.kind === "mutated");
const controls = rows.filter((r) => r.kind === "control");

console.log(`detection rate : ${mutated.filter((r) => r.found).length}/${mutated.length}`);
console.log(`severity match : ${mutated.filter((r) => r.severityRight).length}/${mutated.length}`);
console.log(`false alarms   : ${controls.filter((r) => r.falseAlarm).length}/${controls.length}`);
console.log(`rename-stable  : ${mutated.filter((r) => r.stableAfterRename).length}/${mutated.length}`);
console.table(rows);

三个设计选择值得解释：

重命名轮次。如果当 total 变成 acc 时发现结果消失了，说明工具是在按键名（identifier）而非逻辑来匹配。一个只在常规命名的变量里抓 bug 的评审，在你真实代码库（变量名往往比较随意）上会表现不佳。这是一个廉价的鲁棒性代理指标，大多数评测从不运行。

严重程度加权。漏掉一个低严重程度的 nit 和漏掉一个数据损坏 bug 不应该算作同等结果。评分规则不必多复杂——只需要在看到结果之前提前写好，这样你事后就无法调整它。

对照组是强制的。标记一切的工具有 100% 的检测率，但在实践中毫无用处。误报这一行通常才是真正决定是否购买的数据。

3. 一次运行的样子

一组 15 个案例（10 个变异，5 个干净）从头到尾需要几分钟，包括重命名轮次。输出可能是：

detection rate : 7/10
severity match : 4/10
false alarms   : 1/5
rename-stable  : 5/10

这一个数据块讲述的故事比任何演示都丰富：召回率尚可、严重程度校准较弱、噪音可接受，以及——令人担忧的那一行——一半的发现结果在变量重命名后无法保持。这个问题是否致命取决于你的代码库，而你现在可以用数字而不是形容词来展开讨论了。

为什么这在免费层级上可行（以及 MonkeyCode 的位置）

注意到这个算术：整个实验大约需要 25 次中等大小的请求。这是评估规模的流量，而非生产规模——免费访问正是为了填补这个缺口而存在的。你不需要信用卡就能弄清楚一个评审模型能否区分 < 和 <=。

披露：本文是 MonkeyCode 产品推广的一部分。具体来说，MonkeyCode 目前提供免费模型访问加上免费服务器选项，所以在这个阶段是一个实用的 REVIEW_URL 后端——上面的脚本不关心端点后面是什么，只要你调整请求和响应的格式即可。如果你想要一个零成本的目标来进行第一次记分牌运行，将框架指向它，看看四行汇总数据说什么；无论如何保留好语料库，因为下次评估任何其他工具时你还会用到它。

不过方法论才是重点。免费访问是为了做决策；而决策标准应该与提供商无关。

你应该依赖免费方案吗？一个快速自检

对每条回答是或否：

[ ] 你在 committing 预算之前正在比较工具或模型。
[ ] 你的评审流量是间歇性的（偶尔一个 PR），而非持续的。
[ ] 你的 diff 可以舒适地放在一个请求里——没有 monorepo 超大文件。
[ ] 明天失去这个服务是件麻烦事，而不是一次故障。
[ ] 提供商的数据处理条款覆盖了你将要发送的代码。

大多数是：免费层级是你评测和轻度持续使用的合法归宿。两个或更多的否——尤其是最后两个——你已经知道实验的结论了：你需要一个有保障的付费方案，而记分牌的任务只是告诉你哪个方案值得。

这个方法的局限性

构建语料库是昂贵的部分。15 个精心挑选的变异加对照组是半天工作的量。粗糙的语料库产生自信但毫无意义的数字——比没有数字还差，因为它们更难反驳。

提示词匹配低估了同义改写。一个模型写"循环跳过了最后一个元素"而不是"off-by-one"，会被这个评分器标记为错误。把脚本的输出当作下界，在信任这个比率之前对手动审查每一次 miss。

15 个案例对工具的分级是粗糙的。你能区分"明显有问题"和"可能没问题"，但无法区分"比替代方案好 2%"。细粒度排名需要数百个案例，这通常本身就超出了免费访问的承受范围。

免费服务是移动靶子。任何免费计划的 lineup、限制和条款都可能变化；永远不要把它接入你团队所依赖的路径中。

如果你已经有一个有资金支持的、正常运行的评审流程，这个实验回答的是一个你已经解决了的问题——那就跳过它。

记分牌，而非订阅，才是资产

一旦你有了变异语料库、对照组和提前写好的评分规则，未来每一次评估——新模型、新供应商、prompt 变更——都变成了一次五分钟的重跑，而不是新一轮的凭感觉判断。先在免费访问上启动它，让四行汇总数据替你说明为什么要申请预算。