《叙事策划与叙事工艺》卷三《叙事体验与路径度量》目录

#!/usr/bin/env python3
# file: sim/nm_00_toc_metric.py
# tier: S
# verify: /opt/homebrew/bin/python3 sim/nm_00_toc_metric.py
"""目录篇的一页度量摘要：走一条确定性路径，量出它的张力曲线与分支覆盖率。

与 ne_00_toc_engine.py 分工：那个量「引擎跑不跑得通」，本脚本量「跑出来这条路
的体验形状」。只量一条（卷二 ne_02 采样 500 条），给出三个整数：
张力 MAE（千分位）、分支覆盖率（千分位）、结局熵（毫比特）。
全部走定点整数，不出现浮点。
"""
import json
import os
import sys
from math import log2

AFF_LO, AFF_HI = 0, 100
HERE = os.path.dirname(os.path.abspath(__file__))


def cond_ok(c, s):
    if c is None:
        return True
    k = c[0]
    if k == "flag":
        return s["flags"].get(c[1], 0) == c[2]
    if k == "item":
        return s["items"].get(c[1], 0) == c[2]
    if k == "aff":
        v, op, n = s["aff"].get(c[1], 0), c[2], c[3]
        return v >= n if op == ">=" else v < n if op == "<" else v == n if op == "==" else v != n
    if k == "and":
        return cond_ok(c[1], s) and cond_ok(c[2], s)
    if k == "or":
        return cond_ok(c[1], s) or cond_ok(c[2], s)
    return not cond_ok(c[1], s)          # not


def node(spec, nid):
    return next(n for n in spec["dialogue"] if n["id"] == nid)


def init_state(spec):
    aff = {v: next(c for c in spec["characters"] if c["id"] == v)["affinity"]["init"]
           for v in sorted(spec["state"]["vars"])}
    return {"node": spec["meta"]["start"], "aff": aff,
            "flags": {f: 0 for f in sorted(spec["state"]["flags"])},
            "items": {i: 0 for i in sorted(spec["state"]["items"])},
            "path": [spec["meta"]["start"]]}


def step(spec, s, c):
    eff = c.get("effects") or {}
    aff, flags, items = dict(s["aff"]), dict(s["flags"]), dict(s["items"])
    for k, v in (eff.get("set") or {}).items():
        flags[k] = v
    for k, v in (eff.get("add") or {}).items():
        aff[k] = min(AFF_HI, max(AFF_LO, aff.get(k, 0) + v))
    for k, v in (eff.get("grant") or {}).items():
        items[k] = v
    for k in (eff.get("revoke") or {}):
        items[k] = 0
    return {"node": c["goto"], "aff": aff, "flags": flags, "items": items,
            "path": s["path"] + [c["goto"]]}


def walk(spec):
    """确定性策略：每步选第一个条件成立的选项。同 ne_00_toc_engine.py。"""
    s, trail = init_state(spec), []
    for _ in range(64):
        cur = node(spec, s["node"])
        if cur.get("ending"):
            break
        opts = [c for c in (cur.get("choices") or []) if cond_ok(c.get("when"), s)]
        if not opts:
            break
        trail.append(opts[0]["id"])
        s = step(spec, s, opts[0])
    return s, trail


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

    s, _ = walk(spec)
    path = s["path"]
    m = spec["metrics"]

    # 张力曲线：路径经过的场景 → 该场景的节拍；目标值取 target_tension_curve 同下标
    scenes = {node(spec, nid)["scene"] for nid in path}
    pairs = [(b["tension"], m["target_tension_curve"][i])
             for i, b in enumerate(spec["beats"]) if b["scene"] in scenes]
    mae_milli = sum(abs(a - b) for a, b in pairs) * 1000 // len(pairs)

    # 分支覆盖率：走过的对话边 / 全部对话边（千分位）
    dl = spec["dialogue"]
    all_edges = {(n["id"], c["goto"]) for n in dl for c in (n.get("choices") or [])}
    walked = {(path[i], path[i + 1]) for i in range(len(path) - 1)}
    cov_milli = len(walked & all_edges) * 1000 // len(all_edges)

    # 结局分布熵：这条路径只到一个结局，故按「5 结局均匀分布」给出上界作参照
    ends = spec["endings"]
    ent_milli_bits = int(log2(len(ends)) * 1000) if ends else 0

    print(f"起点         {spec['meta']['start']}")
    print(f"节点数       {len(path)}")
    print(f"终局节点     {s['node']}")
    print(f"结局         {node(spec, s['node']).get('ending', '(未终局)')}")
    print(f"覆盖场景     {len(scenes)} / {len(spec['scene_graph']['nodes'])}")
    print(f"覆盖节拍     {len(pairs)} / {len(spec['beats'])}")
    print(f"结局覆盖     1 / {len(ends)}")
    print(f"张力曲线     {' '.join(str(b['tension']) for b in spec['beats'] if b['scene'] in scenes)}")
    print(f"目标曲线     {' '.join(str(m['target_tension_curve'][i]) for i, b in enumerate(spec['beats']) if b['scene'] in scenes)}")
    print(f"张力 MAE     {mae_milli} 毫（阈值 {m['tension_mae_max'] * 1000} 毫）")
    print(f"分支覆盖率   {cov_milli} 千分（目标 {m['coverage_target_permille']} 千分）")
    print(f"结局熵上界   {ent_milli_bits} 毫比特（阈值 {m['ending_entropy_min_milli_bits']} 毫比特）")

    bad = []
    if mae_milli > m["tension_mae_max"] * 1000:
        bad.append("张力 MAE 超阈值")
    if cov_milli < m["coverage_target_permille"]:
        bad.append("分支覆盖率未达目标")
    if ent_milli_bits < m["ending_entropy_min_milli_bits"]:
        bad.append("结局熵上界低于阈值")
    for b in bad:
        print(f"WARN {b}")
    if len(bad) >= 2:
        return 1
    print("OK nm_00_toc_metric：一条路径的张力曲线、覆盖率与熵上界已量出")
    return 0


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

起点         d_pier_1
节点数       26
终局节点     e_lit
结局         灯守
覆盖场景     9 / 14
覆盖节拍     11 / 16
结局覆盖     1 / 5
张力曲线     1 2 3 2 3 4 4 3 4 4 2
目标曲线     1 2 3 2 3 4 4 3 4 4 2
张力 MAE     0 毫（阈值 1000 毫）
分支覆盖率   446 千分（目标 850 千分）
结局熵上界   2321 毫比特（阈值 1500 毫比特）
WARN 分支覆盖率未达目标
OK nm_00_toc_metric：一条路径的张力曲线、覆盖率与熵上界已量出