@dsh-gis/dsh-video-studio-skill 0.4.0 → 0.6.0

package/skills/video-studio/scripts/selfcheck.py

@@ -28,6 +28,11 @@
  22  （v0.3）webengine 可用时：页面契约齐全（window.renderFrame/getCues/ready）
  23  （v0.3）qa_frames 可用时：能检出注入的单帧闪烁
  24  （v0.4.0）配乐来源：music.mode=off 不读上一轮 work/music.wav（模式判定回归）
+  25  （v0.5.0）风格层：8 套主题全部过对比度门禁，8 类题材能分出 >=6 种风格
+  26  （v0.5.0）legacy 兼容：没写 style 字段必须精确落回 Dm/120/seed7/单声线
+  27  （v0.5.0）内容指纹：同剧本稳定、改标点不换风格、换题材才换
+  28  （v0.5.0）声线计划：4 句样片 >=2 把声音，legacy 仍是单声线
+  29  （v0.5.0）字体族与主题字幕：换族换缓存键，浅色主题不画黑背板
 """
 import argparse
 import io
@@ -514,6 +519,339 @@ def t_qa_frames():
     return "5 个函数齐全"
 
 
+
+def t_style_kits():
+    """25 风格层：8 套主题过对比度门禁 + 自动选风格能把 8 类题材分开。"""
+    import stylekit as ST
+    bad = ST.lint_all()
+    assert not bad, "内置主题没过对比度门禁: %s" % bad
+    topics = {
+        "tech": "AI 算法 模型 数据 架构 开源 编程 大模型 代码 系统",
+        "report": "报告 复盘 年度 总结 研究 分析 调研 白皮书 趋势 发布",
+        "craft": "手工 自然 历史 传统 木 田野 匠 古 茶 手艺 山河",
+        "launch": "活动 上新 招募 挑战 年轻 潮流 种草 福利 开箱 限量",
+        "truth": "观点 为什么 本质 真相 极简 反思 边界 定义 取舍",
+        "story": "故事 记忆 城市 深夜 旅行 纪实 情绪 时代 变迁 命运",
+        "night": "深夜 学习 效率 专注 写作 整理 笔记 书 日常 房间",
+        "epic": "史诗 爆发 冲击 巅峰 决战 荣耀 震撼 传奇 极限 突破",
+    }
+    got = {}
+    for key, text in topics.items():
+        s = {"title": text, "style": "auto",
+             "lines": [{"id": "l01", "kind": "hook", "text": text},
+                       {"id": "l02", "kind": "body", "text": text}]}
+        got[key] = ST.resolve_script_style(s)["style"]
+    assert len(set(got.values())) >= 6, "8 类题材只分出 %d 套风格: %s" % (len(set(got.values())), got)
+    return "%d 套主题 + %d 类题材 -> %d 种风格" % (len(ST.STYLE_IDS), len(topics), len(set(got.values())))
+
+
+def t_style_legacy():
+    """26 legacy 兼容：没写 style 字段必须精确落回 v0.4 的配乐/旁白参数。"""
+    import stylekit as ST
+    s = {"title": "旧项目", "lines": [{"id": "a", "kind": "body", "text": "x"}]}
+    p = ST.resolve_script_style(s)
+    assert p["legacy"] is True, "没有 style 字段却没走 legacy"
+    assert p["music"]["bpm"] == 120.0, "legacy BPM 应为 120，收到 %r" % (p["music"]["bpm"],)
+    assert p["music"]["key"] == "Dm", "legacy 调性应为 Dm，收到 %r" % (p["music"]["key"],)
+    assert p["music"]["seed_effective"] == 7, "legacy seed 应为 7（不做内容派生）"
+    assert p["music"]["seed_from_content"] is False
+    assert p["voice"]["map"] == {}, "legacy 不该有声线映射"
+    assert p["voice"]["policy"]["jitter"] == 0.0 and p["voice"]["policy"]["auto"] is False
+    # legacy 的节奏必须等于 render.py v0.4 的函数默认值，否则"没写 lead 的老剧本"会变节奏
+    assert (p["pacing"]["lead"], p["pacing"]["tail"], p["pacing"]["min_dur"]) == (0.55, 0.85, 3.0), p["pacing"]
+    # 显式 "legacy" 也必须是同一档
+    s2 = dict(s, style="legacy")
+    assert ST.resolve_script_style(s2)["legacy"] is True
+    # 显式风格则必须真的换掉三件套
+    s3 = dict(s, style="cinema")
+    p3 = ST.resolve_script_style(s3)
+    assert p3["legacy"] is False and p3["music"]["bpm"] in ST.STYLES["cinema"]["music"]["bpm_ladder"]
+    assert p3["music"]["key"] in ST.STYLES["cinema"]["music"]["keys"]
+    return "bpm=%g key=%s seed=%d / cinema: bpm=%g key=%s" % (
+        p["music"]["bpm"], p["music"]["key"], p["music"]["seed_effective"],
+        p3["music"]["bpm"], p3["music"]["key"])
+
+
+def t_style_determinism():
+    """27 指纹确定性：同剧本同结果；改错别字不换风格；改题材才换。"""
+    import stylekit as ST
+    base = {"title": "AI 大模型的三年", "style": "auto",
+            "lines": [{"id": "l01", "kind": "hook", "text": "大模型改变了什么"},
+                      {"id": "l02", "kind": "body", "text": "算法和数据的规模一起上去了"}]}
+    a = ST.resolve_script_style(base)
+    b = ST.resolve_script_style(json.loads(json.dumps(base)))
+    assert json.dumps(a, sort_keys=True, default=str) == json.dumps(b, sort_keys=True, default=str), \
+        "同一剧本两次解析结果不同（不确定性）"
+    typo = json.loads(json.dumps(base))
+    typo["lines"][1]["text"] += "。"
+    c = ST.resolve_script_style(typo)
+    assert c["style"] == a["style"], "改一个标点就换了风格: %s -> %s" % (a["style"], c["style"])
+    assert c["music"]["bpm"] == a["music"]["bpm"], "改一个标点就换了 BPM"
+    assert c["fingerprint"]["full"] != a["fingerprint"]["full"], "full 指纹没变（内容派生失效）"
+    other = {"title": "深夜学习指南", "style": "auto",
+             "lines": [{"id": "l01", "kind": "hook", "text": "为什么深夜反而能专注"},
+                       {"id": "l02", "kind": "body", "text": "整理笔记，写作，阅读都更安静"}]}
+    d = ST.resolve_script_style(other)
+    assert d["style"] != a["style"], "换了一部片风格却相同: %s" % d["style"]
+    return "%s -> %s（同一剧本稳定），换片 -> %s" % (a["style"], c["style"], d["style"])
+
+
+def t_voice_plan():
+    """28 声线计划：legacy 保持单声线；风格化时按 kind 换声线且确定性。"""
+    try:
+        import voicekit as VK
+    except Exception:                                       # noqa: BLE001
+        return "skip"
+    import stylekit as ST
+    s = {"title": "AI 大模型", "style": "auto",
+         "lines": [{"id": "l01", "kind": "hook", "text": "大模型改变了什么"},
+                   {"id": "l02", "kind": "body", "text": "算法和数据的规模一起上去了"},
+                   {"id": "l03", "kind": "quote", "text": "他说：这不可能"},
+                   {"id": "l04", "kind": "outro", "text": "它已经在我们身边了"}]}
+    plan = ST.resolve_script_style(s)
+    vp = VK.voice_plan(s, plan)
+    assert len(vp) == 4, "计划行数应为 4，收到 %d" % len(vp)
+    assert json.dumps(vp, sort_keys=True, default=str) == json.dumps(
+        VK.voice_plan(s, plan), sort_keys=True, default=str), "voice_plan 不确定"
+    personas = {r["persona"] for r in vp}
+    assert len(personas) >= 2, "4 句样片只用了一个声线: %s" % personas
+    tones = {r["tone"] for r in vp}
+    assert len(tones) >= 2, "语气档没有变化: %s" % tones
+    for r in vp:
+        for fld in ("voice", "rate", "pitch", "volume", "lead", "tail"):
+            assert r.get(fld) not in (None, ""), "计划行缺 %s: %r" % (fld, r.get("id"))
+    # legacy：单声线、body 语气、无抖动
+    leg = {"title": "旧项目", "lines": [{"id": "a", "kind": "body", "text": "x"}]}
+    lp = ST.resolve_script_style(leg)
+    lvp = VK.voice_plan(leg, lp)
+    assert len({r["voice"] for r in lvp}) == 1, "legacy 出现多声线"
+    assert all(r["tone"] == "body" for r in lvp), "legacy 不该换语气档"
+    return "%d 句 / %d 把声音 / %d 档语气" % (len(vp), len(personas), len(tones))
+
+
+def t_font_family():
+    """29 字体族 + 字幕主题：换族必须换缓存键，主题字幕不能是黑底白字。
+
+    **别把"系统装了几族字体"当成产品缺陷**：CI 的 ubuntu 只装 fonts-noto-cjk，
+    四个族全回退到同一个 NotoSansCJK，宽度必然一样。v0.5.0 的第一版就在这里误报——
+    断言写成"宽度必须不同"，于是 Linux CI 红、Windows 绿。
+    真正要保证的是**机制**：缓存按 family 分键（换族不会串味）；
+    宽度差异只在"系统确实解析出不同字体文件"时才有意义，单族系统跳过并说明。
+    """
+    fams = list(getattr(K, "FAMILY_IDS", ()))
+    assert fams, "filmkit 没有 FONT_FAMILIES（v0.5 字体族没生效）"
+    resolved = {}
+    for fam in fams:
+        f = K.font(40, "bold", fam)
+        assert f is not None, "字体族 %s 加载失败" % fam
+        assert f.size == 40, "字体族 %s 的字号被改写成 %s" % (fam, f.size)
+        resolved[fam] = str(getattr(f, "path", "") or "")
+    # (a) 机制保证：四个族必须是四条独立缓存，且键里带 family（否则 wrap 与绘制会用不同字体）
+    keys = [k for k in K._font_cache if len(k) == 3 and k[0] == 40 and k[1] == "bold"]
+    assert len({k[2] for k in keys}) == len(fams), \
+        "字体缓存键没带 family（换族会串味）: %s" % (keys,)
+    # (b) 语义保证：仅当系统真解析出 >=2 个字体文件时，宽度才必须有差异
+    uniq_files = len(set(resolved.values()))
+    widths = {}
+    for fam in fams:
+        widths[fam] = round(K.text_w("中文测试ABC", K.font(40, "bold", fam)), 3)
+    uniq_w = len(set(widths.values()))
+    if uniq_files >= 2:
+        assert uniq_w >= 2, ("换族没换字形（%d 个字体文件却只有 %d 种宽度）: %s"
+                             % (uniq_files, uniq_w, widths))
+        detail = "%d 个字体族 / %d 个字体文件 / %d 种宽度" % (len(fams), uniq_files, uniq_w)
+    else:
+        # 单族回退（CI 的 fonts-noto-cjk，或极简 Linux 容器）：只验机制，不验宽度
+        detail = "%d 个字体族 / 单族回退（%s）/ 只验缓存分键" % (
+            len(fams), os.path.basename(list(resolved.values())[0]) or "?")
+    # 缓存键必须区分 family（否则 wrap 与绘制会用不同字体，文字溢出安全区）
+    a = K.wrap_cn_cached("这是一句用来测试换行缓存键的话", 40, 300, "reg", "sans")
+    b = K.wrap_cn_cached("这是一句用来测试换行缓存键的话", 40, 300, "reg", "kai")
+    assert isinstance(a, list) and isinstance(b, list)
+    # 旧签名必须仍然可用（用户脚本里有大量 font(46,"reg")）
+    assert K.font(46, "reg") is not None
+    assert K.wrap_cn_cached("旧调用", 40, 500) is not None
+    # 字幕主题：浅色主题不该画黑背板
+    from PIL import Image
+    try:
+        import stylekit as ST
+        th = ST.THEMES["magazine"]
+    except Exception:                                       # noqa: BLE001
+        th = None
+    if th is not None:
+        img = Image.new("RGB", (K.W, K.H), th["bg"])
+        K.draw_subtitle(img, "浅色主题字幕", theme=th)
+        px = img.getpixel((960, int((K.SUB_BAND[1] + K.SUB_BAND[3]) / 2)))
+        assert sum(px) > 200, "浅色主题的字幕背板是深色（%s），说明 theme 没生效" % (px,)
+    img2 = Image.new("RGB", (K.W, K.H), (0, 0, 0))
+    K.draw_subtitle(img2, "旧调用", theme=None)
+    return detail
+
+
+def t_gates():
+    """30 门禁账本 / 签核 / QC 报告：三档状态必须能区分"没查"和"通过"。
+
+    这一条防的是 v0.6.0 自己最容易犯的错——把 skipped 混进 pass。
+    用户看到的"质检通过"必须能区分"我查了 9 项"和"我只查了 3 项"：
+    前者是真知情，后者是假安全感。顺带验签核绑内容指纹：改了剧本旧签核必须失效。
+    """
+    import tempfile
+    import gates as GT
+    w = tempfile.mkdtemp(prefix="sc_gates_")
+    lg = GT.GateLedger(w, {"title": "t", "lines": [{"text": "x"}]}, engine="pil")
+    lg.ok("A", "通过项", "1")
+    lg.fail("B", "失败项", "2")
+    lg.skip("C", "没执行项", "3")
+    c = lg.counts()
+    assert c == {"pass": 1, "fail": 1, "skipped": 1}, c
+    # 三档语义：fail 一定失败；skipped 只在 --strict-gates 下失败
+    assert len(lg.exit_errors()) == 1, "fail 没被算成失败"
+    assert len(lg.exit_errors(strict=True)) == 2, "--strict-gates 没把 skipped 升级成失败"
+    lg.write_json()
+    assert os.path.exists(os.path.join(w, "gates.json")), "gates.json 没落盘"
+    # 签核：没签 = skipped；签了 = pass；内容指纹变了 = skipped（不是 pass！）
+    ch = lg.content_hash
+    st0, _ = GT.signoff_state(w, ch)
+    assert all(v["status"] == "skipped" for v in st0.values()), st0
+    GT.write_signoff(w, "stills", ch, note="看过 sheet")
+    st1, _ = GT.signoff_state(w, ch)
+    assert st1["stills"]["status"] == "pass", st1["stills"]
+    st2, stale = GT.signoff_state(w, "别的指纹")
+    assert st2["stills"]["status"] == "skipped" and "stills" in stale, (st2, stale)
+    # 内容指纹：改剧本 / 换引擎必须变，渲染期私有键（_path/_style）不许影响
+    h1 = GT.content_hash({"title": "a", "lines": []}, engine="pil")
+    h2 = GT.content_hash({"_path": "/x", "title": "a", "lines": []}, engine="pil")
+    h3 = GT.content_hash({"title": "a", "lines": []}, engine="web")
+    assert h1 == h2, "渲染期私有键影响了内容指纹（会导致假失效）"
+    assert h1 != h3, "换引擎了内容指纹却没变（旧签核会错误地继续有效）"
+    # QC 报告：三档都要出现在矩阵里，且 skipped 不能被渲染成"通过"
+    GT.append_cost(w, "frames", 1.5, frames=30)
+    p = GT.write_report(w, os.path.join(w, "out", "QC-REPORT.md"))
+    txt = open(p, encoding="utf-8").read()
+    for must in ("门禁矩阵", "人工签核", "耗时台账", "**skipped**", "**fail**"):
+        assert must in txt, "报告里缺 %r" % must
+    assert "未通过" in txt and "通过" in txt, "报告结论段没区分通过/未通过"
+    # 原子写：不留 .tmp 尾巴
+    assert not [f for f in os.listdir(w) if f.endswith(".tmp")], os.listdir(w)
+    return "三档 1/1/1 + 签核 4 道闸 + 指纹失效 + 报告矩阵"
+
+
+def t_stagewatch():
+    """31 阶段新鲜度：改上游 -> 下游必须报过时；首跑不刷噪声；产物丢失要报。
+
+    这一条防的是 v0.6.0 前的老问题：frames 有分块指纹，其余 stage 全是裸奔
+    （改 style 后 audio 仍读旧 music.wav、改 hold 后 frames 仍用旧 cues.json，都不报错）。
+    """
+    import tempfile
+    import stagewatch as SW
+    w = tempfile.mkdtemp(prefix="sc_sw_")
+    assert all(not r["issues"] for r in SW.explain(w)), "空目录不该报过时"
+
+    def _wf(name, text):
+        p = os.path.join(w, name)
+        d = os.path.dirname(p)
+        if d:
+            os.makedirs(d, exist_ok=True)
+        open(p, "w", encoding="utf-8").write(text)
+
+    _wf("style.json", "s1")
+    _wf("voice_plan.json", "v1")
+    SW.snapshot(w, "style")
+    assert not [i for r in SW.explain(w, ["style"]) for i in r["issues"]], "刚跑完就报过时"
+    _wf("tts.json", "t1")
+    SW.snapshot(w, "tts")
+    # 改 tts 的上游（style.json）-> tts 必须报 input-changed
+    _wf("style.json", "s2")
+    issues = [i for r in SW.explain(w, ["tts"]) for i in r["issues"]]
+    assert any(i["kind"] == "input-changed" for i in issues), issues
+    assert any("render.py" in (i.get("rerun") or "") for i in issues), "过时了却没给重跑命令"
+    # 产物被删 -> 必须报 output-missing
+    os.remove(os.path.join(w, "tts.json"))
+    issues = [i for r in SW.explain(w, ["tts"]) for i in r["issues"]]
+    assert any(i["kind"] == "output-missing" for i in issues), issues
+    # 默认只告警；--strict-stale 才失败
+    errs, warns = SW.report(w, ["tts"], write=lambda lv, m: None)
+    assert not errs and warns, (errs, warns)
+    errs_strict, _ = SW.report(w, ["tts"], strict=True, write=lambda lv, m: None)
+    assert errs_strict, "--strict-stale 没有让过时变成失败"
+    # **源头输入**（剧本 / scenes.py）改了但没重跑 -> 必须报 source-changed。
+    # 这条是 v0.6.0 补的洞：早期只跟踪 stage 之间的产物，"改了台词没重跑 tts" 查不出来，
+    # 而那正是最需要报警的场景（旧 tts 配新剧本 = 配音字幕全错位）。
+    w2 = tempfile.mkdtemp(prefix="sc_sw2_")
+    film = os.path.join(w2, "film.json")
+    scenes = os.path.join(w2, "scenes.py")
+    open(film, "w", encoding="utf-8").write("{\"title\":\"a\"}")
+    open(scenes, "w", encoding="utf-8").write("# v1")
+    src = {"script": film, "scenes": scenes}
+    _wf2 = lambda n, t: open(os.path.join(w2, n), "w", encoding="utf-8").write(t)
+    _wf2("tts.json", "t1")
+    SW.snapshot(w2, "tts", src)
+    issues = [i for r in SW.explain(w2, ["tts"], src) for i in r["issues"]]
+    assert not issues, "刚跑完就报过时：%s" % issues
+    open(film, "w", encoding="utf-8").write("{\"title\":\"b\"}")   # 改剧本
+    issues = [i for r in SW.explain(w2, ["tts"], src) for i in r["issues"]]
+    assert any(i["kind"] == "source-changed" for i in issues), (
+        "改了剧本却没报过时（这正是 v0.6.0 要堵的洞）：%s" % issues)
+    assert any("film.json" in i["reason"] for i in issues), issues
+    # 坏 manifest 不许崩（用户手改坏一个 json 不该让整片跑不动）
+    open(os.path.join(w, "manifest.json"), "w", encoding="utf-8").write("{broken")
+    SW.explain(w)
+    return "改上游/改源头即报过时 + 产物丢失 + strict 升级 + 坏 manifest 不崩"
+
+
+def t_parallel_frames():
+    """32 --jobs >1 的并行路径能真的跑（v0.6.0 修的 pre-existing bug）。
+
+    bug 形状：worker 从 _script_snapshot.json 读剧本，JSON 把主题色元组变成 list，
+    scenes._bg() 拿它当缓存键 -> TypeError: unhashable type: "list"，
+    于是 SKILL 里教的 --stage frames --jobs 4 直接崩。
+    这里**不跑整片**（太慢），只验两条防线：① 主题色能过 JSON 往返当缓存键；
+    ② worker 反序列化后会重解风格（_style 里的颜色回到 tuple）。
+    """
+    import json as _json
+    import tempfile
+    import stylekit as ST
+    th = dict(ST.THEMES["tech-deep"])
+    # ① 防御层：scenes._hashable 把 list 冻结成 tuple
+    scenes = _load_scenes_mod()
+    if scenes is not None and hasattr(scenes, "_hashable"):
+        frozen = scenes._hashable(("baked", th["bg"], th["bg2"]))
+        hash(frozen)                       # 不能抛 unhashable
+        assert isinstance(frozen[1], tuple), "主题色没被冻结成 tuple：%r" % (frozen[1],)
+    # ② 根因层：JSON 往返后，_render_chunk_worker 里必须能拿到 tuple 的 bg
+    round_trip = _json.loads(_json.dumps({"bg": th["bg"]}, ensure_ascii=False))
+    assert isinstance(round_trip["bg"], list), "前提变了：JSON 居然保住了 tuple"
+    w = tempfile.mkdtemp(prefix="sc_par_")
+    snap = os.path.join(w, "snap.json")
+    script = {"title": "t", "style": "tech-deep", "lines": [{"text": "x"}]}
+    script["_style"] = ST.resolve_script_style(script)
+    with open(snap, "w", encoding="utf-8") as fh:
+        _json.dump(script, fh, ensure_ascii=False)
+    back = _json.load(open(snap, encoding="utf-8"))
+    assert isinstance(back["_style"]["theme"]["bg"], list), "前提变了"
+    # 重解风格（render.resolve_style 的纯函数部分）：必须回到 tuple
+    again = ST.resolve_script_style(back)
+    assert isinstance(again["theme"]["bg"], tuple), (
+        "--jobs >1 时主题色仍是 list，_bg() 会 TypeError（这正是被修的 bug）：%r"
+        % (again["theme"]["bg"],))
+    return "主题标量可哈希 + 反序列化后重解回 tuple"
+
+
+def _load_scenes_mod():
+    """加载 assets/scenes.py 模板（找不到就返回 None：CI 里可能只拷 scripts/）。"""
+    import importlib.util
+    here = os.path.dirname(os.path.abspath(__file__))
+    cand = os.path.join(here, "..", "assets", "scenes.py")
+    if not os.path.exists(cand):
+        return None
+    try:
+        spec = importlib.util.spec_from_file_location("sc_assets_scenes", cand)
+        mod = importlib.util.module_from_spec(spec)
+        spec.loader.exec_module(mod)
+        return mod
+    except Exception:                                       # noqa: BLE001
+        return None
+
 CASES = [
     ("1  TTS 缓存校验文本", t_cache_key),
     ("2  sub_window 覆盖长句", t_sub_window),
@@ -539,6 +877,14 @@ CASES = [
     ("22 webengine 页面契约", t_webengine),
     ("23 qa_frames 函数齐全", t_qa_frames),
     ("24 配乐来源判定（off 不读旧配乐）", t_music_plan),
+    ("25 风格层：8 套主题过对比度", t_style_kits),
+    ("26 风格 legacy 兼容", t_style_legacy),
+    ("27 内容指纹确定性", t_style_determinism),
+    ("28 声线计划", t_voice_plan),
+    ("29 字体族与主题字幕", t_font_family),
+    ("30 门禁账本与签核", t_gates),
+    ("31 阶段新鲜度守卫", t_stagewatch),
+    ("32 并行渲染主题序列化", t_parallel_frames),
 ]
 
 

package/skills/video-studio/scripts/stagewatch.py

@@ -0,0 +1,295 @@
+# -*- coding: utf-8 -*-
+"""stagewatch.py — 阶段新鲜度（stale）守卫（v0.6.0）。
+
+解决的是"改了一句台词，旧产物还在用，但不报错"这一类事故。
+
+已经在 `_frames_plan_stamp` 里为一个点做过（改台词 -> 旧分块复用 -> 画面旁白对不上），
+但其余 stage 全是裸奔：
+  * 改 style 后 `--stage audio` 仍读上一轮的 work/music.wav（配乐是旧的）；
+  * 改 hold 后 `--stage frames` 仍用旧 cues.json（音效落位错）；
+  * 单独跑 `--stage audio` 会无条件混入已存在的 work/sfx.wav。
+
+机制：每个 stage 结束时往 `work/manifest.json` 记一行
+    {stage, at, inputs: {name: 指纹}, outputs: {name: 指纹}}
+下次该 stage 开始前，重算**上游 inputs** 与**自己 outputs** 的指纹：
+  * 上游变了 -> 本 stage 的输入过时（会拿旧输入算出新产物）；
+  * 自己的 outputs 变了 -> 下游全部过时。
+两者都只**警告 + 给出最小重跑命令**，默认不阻断（可用 --strict-stale 升级为失败，
+--allow-stale 显式放行并留痕）。这是"门禁可以保守，但不能静默"的同一条原则。
+
+指纹策略：小文件用 sha1（准），大文件用 size+mtime（快）。
+100 MB 的 audio.wav 每 stage 都算 sha1 会让"跑一次 qa"变慢一倍，而它的目的只是
+"发现它被人动过"，size+mtime 足够。
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import time
+
+SCHEMA = 1
+BIG_BYTES = 8 << 20          # > 8 MB 走 size+mtime 快路径
+
+# 每个 stage 的输入与输出（相对 work/ 或绝对路径）。
+# 顺序即依赖顺序：后面的 stage 用前面 stage 的产物。
+# `sources` 是**源头输入**：剧本（film.json）与画面代码（scenes.py）。
+# 早期版本只跟踪"stage 之间的产物"，于是"改了一句台词但没重跑 tts"查不出任何过时——
+# 而那正是最需要它报警的场景（旧 tts 配新剧本 = 配音和字幕全错位）。
+STAGE_IO = {
+    "style":   dict(sources=["script"], inputs=[], outputs=["style.json", "voice_plan.json"]),
+    "tts":     dict(sources=["script"], inputs=["style.json"], outputs=["tts.json"]),
+    "layout":  dict(sources=["script"],
+                    inputs=["tts.json", "style.json", "voice_plan.json"],
+                    outputs=["timeline.json", "sub.srt", "sub.ass"]),
+    "cues":    dict(sources=["script", "scenes"], inputs=["timeline.json"],
+                    outputs=["cues.json"]),
+    "score":   dict(sources=["script"], inputs=["timeline.json", "style.json"],
+                    outputs=["music.wav", "score.json"]),
+    "sfx":     dict(sources=["script"], inputs=["cues.json"], outputs=["sfx.wav"]),
+    "audio":   dict(sources=["script"],
+                    inputs=["tts.json", "timeline.json", "music.wav", "sfx.wav"],
+                    outputs=["audio.wav"]),
+    "frames":  dict(sources=["script", "scenes"],
+                    inputs=["timeline.json", "audio.wav", "cues.json"],
+                    outputs=["silent.mp4"]),
+    "mux":     dict(sources=["script"], inputs=["silent.mp4", "audio.wav"], outputs=[]),
+    "qa":      dict(sources=["script", "scenes"], inputs=[],
+                    outputs=["gates.json", "qa/sheet.png"]),
+    "stills":  dict(sources=["script", "scenes"], inputs=["timeline.json", "style.json"],
+                    outputs=[]),
+}
+STAGE_ORDER = tuple(STAGE_IO)
+
+# 每个 stage 过时后的"最小重跑命令"提示（只提示本 stage + 必要的下游）
+RERUN_HINT = {
+    "style":   "python render.py --stage style tts layout cues score sfx audio frames mux qa",
+    "tts":     "python render.py --stage tts layout cues sfx audio frames mux qa",
+    "layout":  "python render.py --stage layout cues score sfx audio frames mux qa",
+    "cues":    "python render.py --stage cues sfx audio frames mux qa",
+    "score":   "python render.py --stage score audio mux qa",
+    "sfx":     "python render.py --stage sfx audio mux qa",
+    "audio":   "python render.py --stage audio mux qa",
+    "frames":  "python render.py --stage frames mux qa  （分块缓存会被指纹拒绝，需 rm -rf work/segments）",
+    "mux":     "python render.py --stage mux qa",
+    "qa":      "python render.py --stage qa",
+    "stills":  "python render.py --stage stills",
+}
+
+
+def _fp(path, work):
+    """文件指纹：缺失 -> 'missing'；>8MB 用 size+mtime（快），否则 sha1（准）。"""
+    p = path if os.path.isabs(str(path)) else os.path.join(str(work), str(path))
+    try:
+        st = os.stat(p)
+    except OSError:
+        return "missing"
+    if st.st_size > BIG_BYTES:
+        return "sm:%d:%d" % (st.st_size, int(st.st_mtime))
+    try:
+        h = hashlib.sha1()
+        with open(p, "rb") as fh:
+            for blk in iter(lambda: fh.read(1 << 20), b""):
+                h.update(blk)
+        return "sha1:" + h.hexdigest()[:16]
+    except OSError:
+        return "missing"
+
+
+def manifest_path(work):
+    return os.path.join(str(work), "manifest.json")
+
+
+def load(work):
+    p = manifest_path(work)
+    if not os.path.exists(p):
+        return {"schema": SCHEMA, "stages": {}}
+    try:
+        d = json.load(open(p, encoding="utf-8"))
+    except (json.JSONDecodeError, OSError):
+        return {"schema": SCHEMA, "stages": {}, "broken": p}
+    if not isinstance(d, dict) or not isinstance(d.get("stages"), dict):
+        return {"schema": SCHEMA, "stages": {}, "broken": p}
+    return d
+
+
+def save(work, d):
+    os.makedirs(str(work), exist_ok=True)
+    p = manifest_path(work)
+    tmp = "%s.%d.tmp" % (p, os.getpid())
+    with open(tmp, "w", encoding="utf-8") as fh:
+        json.dump(d, fh, ensure_ascii=False, indent=1)
+    os.replace(tmp, p)
+    return p
+
+
+def _src_fp(kind, sources):
+    """源头输入指纹：script=剧本（film.json）、scenes=场景代码（scenes.py）。"""
+    p = (sources or {}).get(kind)
+    return _fp(p, ".") if p else "missing"
+
+
+def snapshot(work, stage, sources=None):
+    """记下某个 stage 的输入/输出指纹（stage 结束时调用）。"""
+    io = STAGE_IO.get(str(stage))
+    if io is None:
+        return None
+    d = load(work)
+    d.setdefault("stages", {})[str(stage)] = dict(
+        at=time.time(),
+        atText=time.strftime("%Y-%m-%d %H:%M:%S"),
+        src={k: _src_fp(k, sources) for k in (io.get("sources") or [])},
+        inputs={k: _fp(k, work) for k in io["inputs"]},
+        outputs={k: _fp(k, work) for k in io["outputs"]},
+    )
+    save(work, d)
+    return d["stages"][str(stage)]
+
+
+def check(work, stage, sources=None):
+    """stage 开始前查新鲜度：返回问题列表（每项含 stage / reason / rerun）。
+
+    只报"这一跑真的会读到旧东西"的情况：
+      1) 本 stage 的上游输入与上次记录不同（上游被重跑过，或人手改过文件）；
+      2) 本 stage 自己的产物比它的输入还旧（上次跑到一半被中断）。
+    另一个 stage 的产物变了但**不**是本周 stage 的输入时，不报（跟我们无关）。
+    """
+    io = STAGE_IO.get(str(stage))
+    if io is None:
+        return []
+    d = load(work)
+    stages = d.get("stages") or {}
+    rec = stages.get(str(stage))
+    issues = []
+    if not isinstance(rec, dict):
+        # 从没跑过这个 stage：只有当"别的 stage 有记录"（说明是接手别人的 work 目录，
+        # 或这套产物是旧版本跑出来的）时才提示；全新目录第一次跑不刷噪声。
+        present = [k for k in io["inputs"]
+                   if _fp(k, work) != "missing"]
+        # 只有"有声明产物"的阶段才谈得上"跑过但没记录"。stills / mux 的产物不在 work 里
+        # （mux 写 --out，stills 写 work/stills/），无从证明跑过，就别冤枉它们过时。
+        if stages and io["outputs"] and len(present) == len(io["inputs"]) and io["inputs"]:
+            issues.append(dict(stage=str(stage), kind="no-manifest",
+                               reason="work 里有 %s 但 manifest.json 没有本阶段的记录"
+                                      "（旧版本跑过 / 手改过）" % "、".join(io["inputs"]),
+                               rerun=RERUN_HINT.get(str(stage), "")))
+        return issues
+    # 源头先查：剧本 / scenes.py 改了但本 stage 没重跑 -> 产物一定过时
+    old_src = rec.get("src") or {}
+    for kind in (io.get("sources") or []):
+        now = _src_fp(kind, sources)
+        was = old_src.get(kind, "missing")
+        if now != was:
+            fname = {"script": "剧本 film.json", "scenes": "画面代码 scenes.py"}.get(kind, kind)
+            issues.append(dict(
+                stage=str(stage), kind="source-changed", file=kind,
+                reason="%s 在本阶段上次跑完之后改过（%s -> %s），但本阶段没有重跑；"
+                       "它现在装的还是旧内容" % (fname, was, now),
+                rerun=RERUN_HINT.get(str(stage), ""),
+            ))
+    old_inputs = rec.get("inputs") or {}
+    for name in io["inputs"]:
+        now = _fp(name, work)
+        was = old_inputs.get(name, "missing")
+        if now != was:
+            issues.append(dict(
+                stage=str(stage), kind="input-changed", file=name,
+                reason="输入 %s 在上次跑本阶段之后变了（%s -> %s），本次会拿**新输入**算，"
+                       "但它下游的产物仍是旧的" % (name, was, now),
+                rerun=RERUN_HINT.get(str(stage), ""),
+            ))
+    # 自己的产物丢了：上次跑到一半被中断 / 被删 / 被挪走（与"输入变了"是两件事，都要报）
+    out_fps = {k: _fp(k, work) for k in (rec.get("outputs") or {})}
+    missing_out = [k for k, v in out_fps.items() if v == "missing"]
+    if missing_out:
+        issues.append(dict(stage=str(stage), kind="output-missing",
+                           reason="上次跑过本阶段，但产物 %s 不见了（被删 / 被挪 / 磁盘满）"
+                                  % "、".join(missing_out),
+                           rerun=RERUN_HINT.get(str(stage), "")))
+    return issues
+
+
+def explain(work, stages=None, sources=None):
+    """--explain-stale：把"现在哪些阶段是旧的、为什么、该跑什么"一次说清。"""
+    d = load(work)
+    rows = []
+    for st in (stages or STAGE_ORDER):
+        io = STAGE_IO.get(st)
+        if io is None:
+            continue
+        rec = (d.get("stages") or {}).get(st)
+        issues = check(work, st, sources)
+        rows.append(dict(stage=st, recorded=bool(rec),
+                         at=(rec or {}).get("atText", ""),
+                         issues=issues))
+    return rows
+
+
+def report(work, stages=None, strict=False, allow_stale=False, ledger=None, write=None,
+           sources=None):
+    """查 + 打印 + 判定。返回 (errors, warnings)；errors 在 strict 下非空。
+
+    ledger: 传 gates.GateLedger 时把结论记进账本（一条汇总 gate）。
+    write:  传 callable(str, str) 时按行输出（方便测试捕获）。
+    """
+    out = write or (lambda level, msg: print(msg))
+    rows = explain(work, stages, sources)
+    problems = [(r["stage"], i) for r in rows for i in r["issues"]]
+    warns, errs = [], []
+    for st, it in problems:
+        msg = ("[stale] %s: %s" % (st, it["reason"]))
+        if allow_stale:
+            warns.append(msg + "（--allow-stale 已放行，本次结果可能掺旧数据）")
+        elif strict:
+            errs.append(msg)
+        else:
+            warns.append(msg)
+        if it.get("rerun"):
+            out("warn", "   最小重跑: %s" % it["rerun"])
+    if problems:
+        out("warn", "")
+        out("warn", "   ↑ 共 %d 处过时。默认只告警；--strict-stale 让它失败，"
+                    "--allow-stale 显式放行（会记进 QC 报告）。" % len(problems))
+    if ledger is not None:
+        try:
+            if not problems:
+                ledger.ok("stale", "阶段新鲜度", "上游输入与上次记录一致")
+            elif errs:
+                ledger.fail("stale", "阶段新鲜度", "%d 处过时（--strict-stale）" % len(problems))
+            else:
+                ledger.skip("stale", "阶段新鲜度",
+                            "%d 处过时，已告警未阻断%s"
+                            % (len(problems), "（--allow-stale）" if allow_stale else ""))
+        except Exception:                                   # noqa: BLE001
+            pass
+    return errs, warns
+
+
+if __name__ == "__main__":
+    import argparse
+    import sys
+    ap = argparse.ArgumentParser(description="阶段新鲜度检查：现在哪些产物是旧的")
+    ap.add_argument("--work", default="work")
+    ap.add_argument("--stage", default="", help="只看某个 stage（缺省 = 全部）")
+    ap.add_argument("--json", action="store_true")
+    a = ap.parse_args()
+    stages = [a.stage] if a.stage else None
+    rows = explain(a.work, stages)
+    if a.json:
+        print(json.dumps(rows, ensure_ascii=False, indent=1))
+        sys.exit(0)
+    bad = 0
+    for r in rows:
+        mark = "OK " if not r["issues"] else "!! "
+        if r["issues"]:
+            bad += 1
+        print("%s%-8s %s" % (mark, r["stage"], r["at"] or "（无记录）"))
+        for it in r["issues"]:
+            print("     -", it["reason"])
+            if it.get("rerun"):
+                print("       最小重跑:", it["rerun"])
+    print()
+    if bad:
+        print("%d 个阶段过时。只想看某个：--stage <名字>；打印机读：--json" % bad)
+        sys.exit(1)
+    print("没有发现过时的阶段（按 manifest.json 记录判断）。")