11.1 对话节点、选项与跳转

#!/usr/bin/env python3
# file: sim/na_11_1_dialogue_node_goto.py
# tier: S
# verify: /opt/homebrew/bin/python3 sim/na_11_1_dialogue_node_goto.py
"""卷一 11.1 对话节点、选项与跳转（S 层）：把 48 个对话节点与 115 条选项的
跳转目标当成一张有向图的边来校验，并输出每个节点的出 / 入度数表。

三件事：
  1) 字段盘点：节点层字段（id/scene/speaker/line/line_when/line_else/choices/ending）
     与选项层字段（id/text/when/effects/goto）各有几个、各自出现在多少个节点 / 选项上；
  2) 跳转完整性：**每一条 goto 的目标都必须是已声明的节点 id**（115/115）；
  3) 分工校验：`goto` 是 choice 的独立字段，**不是效果算子**——`effects` 的键只允许
     set / add / grant / revoke，且任何 effects 里都不出现 goto。

产出 out/na_11_1_dialogue_goto.csv（节点度数表）。整数不变量：好感度初值 ∈ [0,100]。
"""
from __future__ import annotations

import csv
import json
import os
import sys

HERE = os.path.dirname(os.path.abspath(__file__))
ROOT = os.path.dirname(HERE)
OUT = os.path.join(ROOT, "out")
CSV_PATH = os.path.join(OUT, "na_11_1_dialogue_goto.csv")

NODE_FIELDS = ["id", "scene", "speaker", "line", "line_when", "line_else", "choices", "ending"]
CHOICE_FIELDS = ["id", "text", "when", "effects", "goto"]
EFFECT_OPS = ("set", "add", "grant", "revoke")


def load_spec():
    with open(os.path.join(ROOT, "config/story_spec.json"), encoding="utf-8") as fh:
        return json.load(fh)


def main() -> int:
    spec = load_spec()
    dlg = spec["dialogue"]
    ids = {n["id"] for n in dlg}
    choices = [c for n in dlg for c in (n.get("choices") or [])]
    gotos = [c["goto"] for c in choices]

    # 1) 字段盘点（每个字段出现多少个非空值）
    print(f"spec={spec['meta']['title']}  节点 {len(dlg)}  选项 {len(choices)}")
    print("节点层字段：" + "  ".join(f"{f}={sum(1 for n in dlg if n.get(f) is not None)}" for f in NODE_FIELDS))
    print("选项层字段：" + "  ".join(f"{f}={sum(1 for c in choices if c.get(f) is not None)}" for f in CHOICE_FIELDS))

    # 2) 跳转完整性
    bad = sorted({g for g in gotos if g not in ids})
    print(f"跳转目标校验：{len(gotos) - len([g for g in gotos if g not in ids])} / {len(gotos)} 条 goto 指向已声明节点"
          f"；未命中 {len(bad)} 个 {bad}")
    if bad:
        print("FAIL 存在指向未声明节点的 goto")
        return 1

    # 3) goto 不是效果算子
    eff_keys = sorted({k for c in choices for k in (c.get("effects") or {})})
    print(f"effects 段出现过的键：{eff_keys}")
    illegal = [k for k in eff_keys if k not in EFFECT_OPS]
    if illegal:
        print(f"FAIL effects 出现非法算子 {illegal}")
        return 1
    goto_in_eff = [c["id"] for c in choices if "goto" in (c.get("effects") or {})]
    print(f"effects 里出现 goto 的选项：{len(goto_in_eff)} 个（goto 是 choice 的字段，不是算子）")
    if goto_in_eff:
        print("FAIL goto 混进了效果算子")
        return 1

    # 度数表
    in_deg = {n["id"]: 0 for n in dlg}
    for c in choices:
        in_deg[c["goto"]] += 1
    rows = []
    for n in dlg:
        ch = n.get("choices") or []
        kind = "ending" if n.get("ending") else "choice"
        rows.append({
            "id": n["id"], "scene": n["scene"], "speaker": n["speaker"], "kind": kind,
            "out_degree": len(ch), "in_degree": in_deg[n["id"]],
            "cond_choices": sum(1 for c in ch if c.get("when")),
        })
    out_hist: dict[int, int] = {}
    for r in rows:
        out_hist[r["out_degree"]] = out_hist.get(r["out_degree"], 0) + 1
    print("出度分布（节点数）：" + "  ".join(f"{k}->{v}" for k, v in sorted(out_hist.items())))
    in_hist: dict[int, int] = {}
    for r in rows:
        in_hist[r["in_degree"]] = in_hist.get(r["in_degree"], 0) + 1
    print("入度分布（节点数）：" + "  ".join(f"{k}->{v}" for k, v in sorted(in_hist.items())))
    widest = max(rows, key=lambda r: r["out_degree"])
    print(f"最宽节点 {widest['id']}：出度 {widest['out_degree']}，其中带条件的 "
          f"{widest['cond_choices']} 条")
    sinks = [r["id"] for r in rows if r["out_degree"] == 0]
    print(f"出度为 0 的节点 {len(sinks)} 个：{sinks}")

    # 整数不变量：好感度初值 ∈ [0,100]
    for c in spec["characters"]:
        init = c["affinity"]["init"]
        assert 0 <= init <= 100, f"{c['id']} init {init} 越界"
    total_out = sum(r["out_degree"] for r in rows)
    print(f"出度之和 {total_out} == 选项数 {len(choices)}：{total_out == len(choices)}")
    assert total_out == len(choices), "出度之和应等于选项数"

    os.makedirs(OUT, exist_ok=True)
    with open(CSV_PATH, "w", encoding="utf-8", newline="") as fh:
        w = csv.DictWriter(fh, fieldnames=["id", "scene", "speaker", "kind",
                                           "out_degree", "in_degree", "cond_choices"])
        w.writeheader()
        w.writerows(rows)
    print(f"wrote out/na_11_1_dialogue_goto.csv rows={len(rows)}")
    print("OK na_11_1_dialogue_node_goto：115 条 goto 全部命中，goto 与效果算子分工清晰")
    return 0


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

spec=雾港夜航  节点 48  选项 115
节点层字段：id=48  scene=48  speaker=48  line=48  line_when=2  line_else=1  choices=48  ending=5
选项层字段：id=115  text=115  when=34  effects=115  goto=115
跳转目标校验：115 / 115 条 goto 指向已声明节点；未命中 0 个 []
effects 段出现过的键：['add', 'grant', 'set']
effects 里出现 goto 的选项：0 个（goto 是 choice 的字段，不是算子）
出度分布（节点数）：0->5  2->16  3->26  5->1
入度分布（节点数）：0->1  1->13  2->4  3->26  4->4
最宽节点 d_dq_2：出度 5，其中带条件的 4 条
出度为 0 的节点 5 个：['e_lit', 'e_dark', 'e_truth', 'e_silence', 'e_loss']
出度之和 115 == 选项数 115：True
wrote out/na_11_1_dialogue_goto.csv rows=48
OK na_11_1_dialogue_node_goto：115 条 goto 全部命中，goto 与效果算子分工清晰

// file: core/test/na_11_1_dialogue_goto.test.ts
// tier: P
// verify: node --test 'core/test/na_11_1_dialogue_goto.test.ts'
// 卷一 11.1：对话节点、选项与跳转 —— 推进的三个约定。
//   (a) 未知选项被拒绝（不是静默走空）；
//   (b) 条件不满足的选项被拒绝（前端不该把它渲染成可点）；
//   (c) 推进是纯函数：返回新状态，入参不被改写；
//   (d) goto 是 choice 的字段，不是效果算子 —— 它不改状态，只决定下一个节点。

import test from "node:test";
import assert from "node:assert/strict";
import { readFileSync } from "node:fs";
import { join, dirname } from "node:path";
import { fileURLToPath } from "node:url";

import { applyChoice, applyEffects, initState, nodeById } from "../src/inkwell/engine.ts";
import type { Effects, Spec, State } from "../src/inkwell/engine.ts";

const HERE = dirname(fileURLToPath(import.meta.url));
const ROOT = join(HERE, "../..");
const spec = JSON.parse(readFileSync(join(ROOT, "config/story_spec.json"), "utf8")) as Spec;

test("未知选项被拒绝：选项 id 不存在时抛错，而不是静默返回原状态", () => {
  const s = initState(spec);
  assert.throws(() => applyChoice(spec, s, "c_does_not_exist"), /unknown choice/);
  assert.throws(() => applyChoice(spec, s, ""), /unknown choice/);
});

test("条件不满足的选项被拒绝（点名 c_tavern_2c 的 hui>=55 门限）", () => {
  const s: State = { ...initState(spec), node: "d_tavern_2" };
  const low: State = { ...s, aff: { ...s.aff, hui: 54 } };
  assert.throws(() => applyChoice(spec, low, "c_tavern_2c"), /unavailable/);
  const ok: State = { ...s, aff: { ...s.aff, hui: 55 } };
  assert.equal(applyChoice(spec, ok, "c_tavern_2c").node, "d_tavern_3");
});

test("推进是纯函数：返回新对象，入参状态逐字段不变", () => {
  const s = initState(spec);
  const before = JSON.stringify(s);
  const next = applyChoice(spec, s, "c_pier_1a");
  assert.notEqual(next, s, "应返回新对象");
  assert.equal(JSON.stringify(s), before, "入参状态不应被改写");
  assert.equal(next.node, "d_pier_2");
  assert.equal(next.flags.knows_yan_missing, 1);
  assert.notEqual(next.path, s.path, "路径应是新数组");
  assert.equal(s.path.length, 1, "入参路径不应被追加");
});

test("goto 是 choice 的字段不是效果算子：effects 里出现 goto 不改变节点", () => {
  const s: State = { ...initState(spec), node: "d_pier_1" };
  const bogus = { set: { met_hai: 1 }, goto: "e_truth" } as unknown as Effects;
  const out = applyEffects(bogus, s);
  assert.equal(out.node, "d_pier_1", "goto 不该出现在效果里，节点不变");
  assert.equal(out.flags.met_hai, 1, "声明过的 set 仍然生效");

  for (const node of spec.dialogue) {
    for (const c of node.choices ?? []) {
      assert.equal(Object.hasOwn(c.effects, "goto"), false, `${c.id} 的 effects 混进了 goto`);
    }
  }
});

test("每条 goto 都指向已声明节点，且出度之和等于选项数", () => {
  let edges = 0;
  for (const node of spec.dialogue) {
    for (const c of node.choices ?? []) {
      assert.doesNotThrow(() => nodeById(spec, c.goto), `${c.id} 的 goto ${c.goto} 不存在`);
      edges += 1;
    }
  }
  assert.equal(edges, 115, `选项边应为 115，实为 ${edges}`);

  const wide = [...spec.dialogue].sort((a, b) => (b.choices?.length ?? 0) - (a.choices?.length ?? 0))[0];
  assert.equal(wide.id, "d_dq_2");
  assert.equal(wide.choices?.length, 5);
  console.log(`选项边 ${edges} 条；最宽节点 ${wide.id} 出度 ${wide.choices?.length}`);
});

选项边 115 条；最宽节点 d_dq_2 出度 5
✔ 未知选项被拒绝：选项 id 不存在时抛错，而不是静默返回原状态 (0.889333ms)
✔ 条件不满足的选项被拒绝（点名 c_tavern_2c 的 hui>=55 门限） (0.234209ms)
✔ 推进是纯函数：返回新对象，入参状态逐字段不变 (0.142209ms)
✔ goto 是 choice 的字段不是效果算子：effects 里出现 goto 不改变节点 (0.153292ms)
✔ 每条 goto 都指向已声明节点，且出度之和等于选项数 (0.675125ms)
ℹ tests 5
ℹ suites 0
ℹ pass 5
ℹ fail 0
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
ℹ duration_ms 770.537209