wikieval

技能：wikieval

将 wiki 黄金样例变成 CI 门禁：通过低成本的确定性断言判断大多数黄金样例，提交基线以捕获回归，并将唯一昂贵的环节（LLM 评审器）隔离在单个适配器文件之后。

内容

目的与背景

• 目的： 将 wiki 黄金页面变成纯代码检查的回归测试套件（不使用模型），并提交基线；只有指标低于基线时，CI 才会返回失败退出码。
• 触发条件（何时使用）：
  • 你希望 wiki 页面成为回归测试套件，避免 Agent（或 PR）在无人察觉的情况下破坏页面。
  • 你有黄金输入→预期结果配对，希望用纯代码检查，无需模型。
  • 你需要一个 CI 步骤，只有指标低于已提交的基线时才返回非零退出码。
  • 用户提到“wikieval”“wiki 的评估套件”“黄金样例回归门禁”“断言级联”“评估结果下降时阻止 CI”，或使用 /wikieval（禁用模型调用——由用户自行调用）。
• 非目标： 绝不调用 LLM（第 3 层会报告 needs-judge，而非进行评审）；不生成候选输出（候选输出来自 --outputs）；不代为编写黄金样例的内容。

心智模型

黄金样例（输入 · 预期结果 · 评分标准？ · 断言？）+ 候选输出 → 级联：第 1 层断言 → [第 2 层相似度] → [第 3 层需要评审] → 每个黄金样例的通过状态+分数 → 基线（写入）| 回归差异（检查）。低成本层会短路判断；昂贵环节则隔离在单个适配器文件之后。

输入与输出约定

	字段	必需？	含义
输入	goldens llmwiki/wiki/sources/evals/*.md	是	YAML frontmatter 中包含 input、expected、可选的 rubric、可选的 asserts、可选的 id；还包含 R9 type 和 R2 ## Origin
输入	--outputs <outputs.json>	是	每个黄金样例对应的候选输出——无需任何模型即可运行测试套件
输入	mode	否	none = 报告；--write-baseline；--check
输入	harness/wikieval.config.yaml	否	适配器配置（verified: false）：评审模型、评分标准提示词、embedding.backend
输出	report	是	每个黄金样例的通过/失败/分数/needs-judge
输出	harness/metrics/eval-baseline.json	使用 --write-baseline 时	已提交的每个黄金样例的通过状态 + 分数
输出	exit code	使用 --check 时	0 = 无回归；2 = 指标低于基线（附回归差异）

规则与能力

• RULE-01（必须）：如果黄金样例声明了 asserts，则仅由第 1 层决定通过或失败。未知操作一律判失败。
• RULE-02（必须）：只有黄金样例没有断言时，才会进入第 2 层相似度检查；除非设置了 embedding.backend，否则会跳过并注明（difflib = 使用标准库进行词法比较，可离线运行；在适配器接通前，真实模型 ID 会保持跳过）。
• RULE-03（必须）：在确定性模式下，绝不会调用 judge(output, rubric) -> {score, reason} 存根；升级处理的黄金样例会报告为 needs-judge。
• RULE-04（必须）：--check 是与已提交基线进行确定性差异比较；只有指标下降时才返回退出码 2。
• RULE-05（必须）：适配器边界仅限一个文件——完成评审器后，只需修改 harness/wikieval.config.yaml 和 judge()；WikiEval 的其余部分不变。
• 能力：读取黄金样例、候选输出和适配器配置；写入基线文件；不联网、不使用模型。

失败边界

• 断言失败 → 黄金样例失败（报告）；使用 --check 时，如果相较基线有所下降 → 退出码 2 + 回归差异。
• 未知断言操作 → 直接判失败（不跳过）。
• 黄金样例没有断言且未设置 embedding.backend → 跳过第 2 层并注明；评分标准升级处理 → needs-judge（既非通过，也非失败）。
• --outputs 文件缺失或无效 → 受阻：没有候选输出就无法运行。

用法

主要工作流

步骤	类型	输入	操作	输出/退出	失败/后续
W01	确定性	基准样例，--outputs	加载基准样例 + 候选输出	每个基准样例对应一组配对	缺少输出 → 阻止执行
W02	确定性	配对，asserts	第 1 层确定性断言	声明了断言时，返回通过/失败	未知操作 → 失败关闭
W03	确定性	配对，配置	第 2 层相似度（仅在没有断言时）	得分或“已跳过 + 已注明”	未设置后端 → 跳过
W04	确定性	评分标准	第 3 层 → 报告 needs-judge（不会调用评审器）	needs-judge	—
W05	确定性	结果，模式	报告 / --write-baseline / 与基准的 --check 差异	报告、基准文件、退出码 0/2	回退 → 退出码 2

各步骤详情（W01–W05 的事实来源）：

断言级联（从廉价到昂贵，短路执行）

1. 第 1 层 — 确定性断言（立即构建的核心）：在候选输出上运行 equals / contains / icontains / not-contains / regex / is-json / is-sql-ish。如果基准样例声明了 asserts，则仅由第 1 层决定通过/失败。未知操作会失败关闭。
2. 第 2 层 — 相似度（可选）：只有当基准样例没有断言时才会执行。除非在配置中设置了 embedding.backend，否则会跳过并注明（difflib = 标准库词法比较，可离线运行；真正的 模型 ID 在适配器接通前仍会跳过）。
3. 第 3 层 — LLM 评分标准评审器 = 适配器（verified: false）。存根 judge(output, rubric) -> {score, reason} 在确定性模式下绝不会调用；升级处理的基准样例会报告为 needs-judge。

基准样例

位于 llmwiki/wiki/sources/evals/ 下的 Markdown 文件，带有 YAML frontmatter：input、expected、 可选的 rubric、可选的 asserts（每个值都要加引号：'contains:foo'、'regex:^...$'、 'is-json'、'equals:bar'、'is-sql-ish'）。id 可选（默认为文件名主体）。 每个基准样例也必须遵守 R9（frontmatter 中的 type）和 R2（## Origin）。

运行（不需要模型）

# run the cascade with a fixed candidate set, print a report
python3 harness/scripts/wikieval.py --outputs harness/evals/wikieval-outputs.example.json

# write / refresh the committed baseline (per-golden pass + score)
python3 harness/scripts/wikieval.py --outputs <outputs.json> --write-baseline

# CI gate: re-run and exit 2 if any metric dropped below baseline (deterministic diff)
python3 harness/scripts/wikieval.py --outputs <outputs.json> --check

基准文件：harness/metrics/eval-baseline.json。适配器配置：harness/wikieval.config.yaml。

分支

ID	类型	条件	行为	跳过/失败	汇合点
B01	能力可选	基准样例没有 asserts，且已设置 embedding.backend	第 2 层相似度（difflib 可离线运行）	未设置后端或未接通真实模型 ID → 跳过并注明	W04
B02	用户可选	--write-baseline	写入/刷新 harness/metrics/eval-baseline.json	—	结束
B03	用户可选	--check	与基准进行确定性差异比较，发生回退时退出码为 2	没有基准 → 先运行 --write-baseline	结束

验证与停止

所有内容都经过代码检查：断言、级联、基准差异比较和退出码都是确定性的。只有第 3 层需要审核（needs-judge），在适配器最终确定前不会纳入通过/失败判定。

自测（立即构建的部分）

OUT=harness/evals/wikieval-outputs.example.json
python3 harness/scripts/wikieval.py --outputs $OUT --write-baseline   # both goldens PASS
python3 harness/scripts/wikieval.py --outputs $OUT --check            # exit 0 — no regression
# flip one output to break an assert, then:
python3 harness/scripts/wikieval.py --outputs <broken.json> --check   # exit 2 + regression diff

示例

• **通过：**写入基准后运行 python3 harness/scripts/wikieval.py --outputs harness/evals/wikieval-outputs.example.json --check → 两个基准样例均通过 → 退出码 0。
• **边界/失败：**更改一个候选输出，使其不再匹配 'contains:foo' → --check 以退出码 2 退出，并在回归差异中指出该基准样例。
• **边界：**基准样例只有 rubric，没有断言，也未设置 embedding.backend → 第 2 层跳过并注明，报告为 needs-judge；不会调用评审器。

参考 — 适配器边界（现在构建，稍后适配）

• **现在已构建并测试：**第 1 层断言、级联、基准写入 + --check 回归差异比较。
• 隔离（verified: false）：harness/wikieval.config.yaml（评审模型 + 评分标准提示词、 嵌入后端——每项都标有 # ASSUMPTION），以及 judge() 存根。
• **最终确定：**将 judge() 接入配置的模型，运行自测，然后设为 verified: true。 只需更改一个文件；WikiEval 的其余部分无需改动。

Reference — Files

• harness/scripts/wikieval.py — the eval engine.
• harness/wikieval.config.yaml — the one adapter (verified: false).
• harness/metrics/eval-baseline.json — committed regression baseline (generated).
• llmwiki/wiki/sources/evals/*.md — goldens.
• harness/evals/wikieval-outputs.example.json — self-test candidate outputs.