6.3 代理指标的口径声明

{
  "metric": "tension_curve_mae",
  "kind": "proxy",
  "unit": "permille",
  "rounding": "floor_integer",
  "inputs": {
    "actual": "beats[].tension",
    "target": "metrics.target_tension_curve"
  },
  "measures": "作者标注的节拍张力序列与设计目标曲线的平均绝对偏离",
  "does_not_measure": [
    "玩家实际感受到的情绪强度",
    "台词的感染力",
    "机制层的张力动力学"
  ],
  "allowed_use": [
    "同一规格内两条曲线的相对偏离",
    "规格演化前后的回归对照"
  ],
  "forbidden_claims": [
    "更感人",
    "提升 N 倍",
    "玩家满意度 X%",
    "情绪强度绝对达标"
  ],
  "threshold_milli": 1000
}

#!/usr/bin/env python3
# file: sim/nm_06_3_proxy_metric_declaration.py
# tier: S
# verify: /opt/homebrew/bin/python3 sim/nm_06_3_proxy_metric_declaration.py
"""卷三 6.3 代理指标的口径声明（S 层）。

张力曲线 MAE 是 proxy：它度量的是「作者标注 vs 设计目标」的偏离，**不是**玩家
实际感受到的情绪。本脚本读 config/nm_06_3_proxy_declaration.json，逐条 lint 这份
声明的字段是否齐全，再把当前规格下实测的 MAE 填进报告，落 out/nm_06_3_proxy.json。

声明的 lint 是硬断言：缺字段、kind 不是 proxy、单位不是千分位、禁声称清单为空，
任一不满足即 FAIL。这样「这个数是 proxy、不能声称什么」不是文档里的一句话，而是
一份可被机器检查的产物。
"""
from __future__ import annotations

import json
import os
import sys

HERE = os.path.dirname(os.path.abspath(__file__))
OUT = os.path.join(HERE, "../out")
DECL = os.path.join(HERE, "../config/nm_06_3_proxy_declaration.json")

REQUIRED = ["metric", "kind", "unit", "rounding", "inputs", "measures",
            "does_not_measure", "allowed_use", "forbidden_claims", "threshold_milli"]


def main() -> int:
    with open(os.path.join(HERE, "../config/story_spec.json"), encoding="utf-8") as fh:
        spec = json.load(fh)
    with open(DECL, encoding="utf-8") as fh:
        decl = json.load(fh)

    beats = spec["beats"]
    target = spec["metrics"]["target_tension_curve"]
    actual = [b["tension"] for b in beats]
    mae = sum(abs(a - t) for a, t in zip(actual, target)) * 1000 // len(actual)

    missing = [k for k in REQUIRED if k not in decl]
    print(f"声明文件       config/{os.path.basename(DECL)}")
    print(f"指标           {decl['metric']}")
    print(f"口径类型       {decl['kind']}  （必须为 proxy）")
    print(f"单位           {decl['unit']}  （千分位整数地板除）")
    print(f"输入真源       {decl['inputs']['actual']}  /  {decl['inputs']['target']}")
    print(f"度量的是       {decl['measures']}")
    print(f"不度量         {len(decl['does_not_measure'])} 项：{'；'.join(decl['does_not_measure'])}")
    print(f"允许的用途     {len(decl['allowed_use'])} 项：{'；'.join(decl['allowed_use'])}")
    print(f"禁声称         {len(decl['forbidden_claims'])} 项：{'；'.join(decl['forbidden_claims'])}")
    print(f"当前实测 MAE   {mae} 毫  （全 16 节拍，阈值 {decl['threshold_milli']} 毫）")
    print(f"lint 字段      {len(REQUIRED) - len(missing)} / {len(REQUIRED)} 齐" +
          (f"，缺 {missing}" if missing else ""))

    assert not missing, f"声明缺字段 {missing}"
    assert decl["kind"] == "proxy", "口径类型必须是 proxy"
    assert decl["unit"] == "permille", "单位必须是千分位"
    assert decl["forbidden_claims"], "禁声称清单不能为空"
    assert decl["does_not_measure"], "不度量清单不能为空"
    assert mae <= decl["threshold_milli"], "MAE 超阈值"

    os.makedirs(OUT, exist_ok=True)
    with open(os.path.join(OUT, "nm_06_3_proxy.json"), "w", encoding="utf-8") as fh:
        json.dump({"declaration": decl, "observed_mae_milli": mae,
                   "lint_ok": not missing, "fields": len(REQUIRED)},
                  fh, ensure_ascii=False, indent=1)
        fh.write("\n")
    print("wrote out/nm_06_3_proxy.json")
    print("OK nm_06_3_proxy_metric_declaration：口径声明字段齐全，MAE 为 proxy 且已声明边界")
    return 0


if __name__ == "__main__":
    sys.exit(main())

声明文件       config/nm_06_3_proxy_declaration.json
指标           tension_curve_mae
口径类型       proxy  （必须为 proxy）
单位           permille  （千分位整数地板除）
输入真源       beats[].tension  /  metrics.target_tension_curve
度量的是       作者标注的节拍张力序列与设计目标曲线的平均绝对偏离
不度量         3 项：玩家实际感受到的情绪强度；台词的感染力；机制层的张力动力学
允许的用途     2 项：同一规格内两条曲线的相对偏离；规格演化前后的回归对照
禁声称         4 项：更感人；提升 N 倍；玩家满意度 X%；情绪强度绝对达标
当前实测 MAE   0 毫  （全 16 节拍，阈值 1000 毫）
lint 字段      10 / 10 齐
wrote out/nm_06_3_proxy.json
OK nm_06_3_proxy_metric_declaration：口径声明字段齐全，MAE 为 proxy 且已声明边界