metric-validation-harness

指标验证工具包

将这个工具包指向一个候选指标和一个语料库，它会运行实验，尝试证伪可信且可优化的指标必须具备的每项属性。它是 deterministic-metric-design 的实证补充：该技能要求你证明单调性、不变性、确定性和构念效度；本技能则运行实验并报告 PASS/FAIL，每项结果都会映射到它所检查的设计技能类别。

**只读。**它只负责计算和报告；绝不会修改你的指标、语料库或任何外部状态。可放心在无人监督的情况下运行。

何时应用

• 有人提出、评审、调整或发布某个指标／分数／指数，而你需要证据证明它可靠
• 某个分数“感觉不对”——你怀疑它反映的是 LOC、每次运行结果不一致，或趋于饱和
• 你准备让 Agent 优化某个指标，需要确认它无法通过表面改动作弊
• 你按照 deterministic-metric-design 构建了候选指标，并想通过实证确认你论证的属性
• 你正在两个指标之间做选择，需要了解哪个指标真正能预测结果（并且优于简单基线）

工作流概览

config.json / env  →  resolve metric_cmd, corpus, thresholds (env > config > bundled default)
        │
        ▼
   verify.sh ──► determinism ─ invariance ─ monotonicity ─ robustness ─ tractability ─ validity
        │            (each property check maps to a deterministic-metric-design category)
        ▼
   PASS / FAIL per property  →  exit 0 (all pass) or 1 (any group failed)

适配器约定

你的指标可以是任何一个以路径作为最后一个参数，并且只向 stdout 输出一个数字的命令：

$ python3 mymetric.py path/to/file.py
42

与语言无关——Python、shell 单行命令、编译后的二进制文件，均可。诊断信息写入 stderr；stdout 中只能有数字。工具包附带了一个示例指标（scripts/examples/metric_ast_nodes.py，用于统计 AST 节点数），因此开箱即用。

如何运行

# 1. Validate the bundled example metric (works with zero setup):
bash scripts/verify.sh

# 2. Validate YOUR metric — set metric_cmd in config.json, or override per-run:
METRIC_CMD="python3 /abs/path/mymetric.py" bash scripts/verify.sh

# 3. Prove the harness itself works (positive + negative cases):
bash scripts/selftest.sh

# 4. Sanity-check your adapter prints one number:
bash scripts/run-metric.sh path/to/file.py

verify.sh 会运行所有检查，并打印最终的 PASS/FAIL。每项检查也可以单独运行（例如 bash scripts/check-determinism.sh）。

检查内容

检查	映射到（设计技能）	检查方式	PASS 条件
check-determinism.sh	det-	运行指标两次，并在 PYTHONHASHSEED 为 0／1 时运行	每次结果的数字都相同
check-invariance.sh	prop- / game-	添加注释／空行／空白字符（表面改动）	分数不变（否则就能被操纵）
check-monotonicity.sh	prop-	附加代码块（增加构念），并检查分布范围	分数不下降，且未饱和
check-robustness.sh	prop-	测试空输入和单语句边界输入	数值有限，处于声明范围内，且不崩溃
check-tractability.py	comp-	测量指标处理规模逐渐增大的输入所需时间	在预算范围内，增长速度低于二次方
check-validity.py	valid-	计算与人工认可结果的 Spearman 相关性、与 LOC 的相关性，以及相对于结果的 AUC	收敛效度高，区分效度不接近 ~LOC，预测能力优于基线

统计方法（Spearman、AUC／Mann–Whitney）仅使用 Python 标准库——无需 numpy/scipy。

设置与配置

该工具包无需任何配置即可使用附带的示例运行。要验证你自己的指标，请在 config.json 中设置字段（或者每次运行时通过对应的 UPPER_CASE 环境变量覆盖任意字段）：

config.json	环境变量覆盖	含义
metric_cmd	METRIC_CMD	你的指标命令（输出路径 → 数字）
baseline_cmd	BASELINE_CMD	简单基线（默认：附带的 LOC）
corpus_dir	CORPUS_DIR	属性检查所遍历的产物
labels_csv	LABELS_CSV	用于效度检查的 path[,outcome][,accepted]
declared_min / declared_max	DECLARED_MIN / DECLARED_MAX	鲁棒性检查要求的取值范围

效度阈值可通过环境变量调整：CONVERGENT_MIN、DISCRIMINANT_MAX、PREDICTIVE_MIN（默认值较宽松——正式运行时请调严；参见 gotchas.md）。

配置字段为空时会回退到附带的演示配置，因此即使缺少设置，本技能也不会崩溃，而是运行示例。

工具要求

• python3（3.8+）——运行指标、变换和统计
• bash 和 awk——用于编排和数值比较（脚本兼容 macOS bash 3.2）

无需网络，也无需外部软件包。

结果解读

FAIL 会指出相关属性和需要参阅的设计技能规则。示例：

• 表面噪声改变了分数 → 该指标读取表层文本；请参阅 prop-prove-invariance-under-irrelevant-transforms 和 game-make-cheapest-improvement-the-right-one。
• 添加代码后分数下降 → 指标不具单调性；优化它可能会奖励更差的代码（prop-prove-monotonicity）。
• |Spearman(metric, LOC)| 过高 → 这只是换了个名称的 LOC（valid-discriminant-not-just-loc）。

相关技能

• deterministic-metric-design — 设计环节。用它来构建指标（定义构念、选择可计算的代理指标、确定尺度并论证其属性）；用此测试框架来实证验证你的论证。
• same-results-less-code、complexity-optimizer、knip-deadcode — 用于指导代码精简的技能；在让 Agent 据此优化之前，先用此测试框架验证你构建的任何精简指标。

请参阅 references/workflow.md，了解每项检查的详情、如何接入自定义指标和语料库，以及故障排除方法。