用途:在信任或优化某个软件度量(metric/score/index)之前,对其进行经验性验证。它把候选度量与语料交给一组实验,尝试证伪可信、可优化度量应具备的各项属性,并按属性输出 PASS/FAIL,每项结果对应 deterministic-metric-design 设计技能中的检查类别。
适用时机:有人提出、评审、调优或上线某度量需要证据;分数感觉异常(疑似跟踪 LOC、多次运行跳动或饱和);即将让智能体优化某度量需确认不能靠表面修改刷分;按 deterministic-metric-design 构建了候选度量需经验确认;在两个度量间选择需判断哪个真正预测结果并胜过简单基线。
主要检查:determinism(运行两次并在 PYTHONHASHSEED 0/1 下运行,要求数值一致)、invariance(加入注释、空行、空白等表面修改后分数不变,否则可被刷分)、monotonicity(追加递增代码块后分数不下降且不饱和)、robustness(空输入与单语句边界输入下有限、在声明范围内且不崩溃)、tractability(随输入增长计时,需在预算内且亚二次增长)、validity(与公认指标及 LOC 的 Spearman、与结果的 AUC,要求收敛性高、判别性不等于 LOC、预测性优于基线)。统计用纯 Python 标准库实现,无需 numpy/scipy。
适配器约定:度量是任意以路径为最后一个参数、并只向 stdout 打印一个数字的命令,如 python3 mymetric.py path/to/file.py 输出 42。与语言无关,诊断信息走 stderr。自带示例度量 scripts/examples/metric_ast_nodes.py(AST 节点数),开箱即用。
使用方式:bash scripts/verify.sh 验证自带示例;METRIC_CMD="python3 /abs/path/mymetric.py" bash scripts/verify.sh 验证自己的度量;bash scripts/selftest.sh 自测;bash scripts/run-metric.sh path/to/file.py 检查适配器是否只输出一个数字。verify.sh 运行全部检查并给出最终 PASS/FAIL,各项检查也可单独运行。
配置:可用 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_MIN、declared_max/DECLARED_MAX。有效性阈值可用 CONVERGENT_MIN、DISCRIMINANT_MAX、PREDICTIVE_MIN 调节,默认较宽松,正式运行应收紧。空配置字段回退到自带示例,不会因缺少配置而崩溃。退出码:全部通过为 0,任一失败为 1。
限制:只读,只计算并报告,不修改度量、语料或外部状态,可无人值守运行。需要 python3(3.8+)、bash 与 awk,脚本兼容 macOS bash 3.2,无需网络和外部包。FAIL 会指出属性和应查阅的设计规则。