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

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

@@ -37,8 +37,15 @@ BIG_BYTES = 8 << 20          # > 8 MB 走 size+mtime 快路径
 # 早期版本只跟踪"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"]),
+    # voice_plan.json 是 **tts** 阶段写的（render.py 的 st_tts：非 legacy 才写），
+    # 不是 style 写的——v0.7.2 前它被挂在 style.outputs 下，于是单跑 `--stage style`
+    # 之后每次重跑都报「产物 voice_plan.json 不见了」（其实从来没写过），
+    # 开了 --strict-stale 就直接失败，而 --stage style 是全新项目的第一条生产命令。
+    # legacy 剧本本来就不写这个文件：check() 只在「上次记录的是具体指纹、现在没了」
+    # 时才报 output-missing，所以 legacy 下记为 missing 不会被当成永久过时。
+    "style":   dict(sources=["script"], inputs=[], outputs=["style.json"]),
+    "tts":     dict(sources=["script"], inputs=["style.json"],
+                    outputs=["tts.json", "voice_plan.json"]),
     "layout":  dict(sources=["script"],
                     inputs=["tts.json", "style.json", "voice_plan.json"],
                     outputs=["timeline.json", "sub.srt", "sub.ass"]),
@@ -54,8 +61,11 @@ STAGE_IO = {
                     inputs=["timeline.json", "audio.wav", "cues.json"],
                     outputs=["silent.mp4"]),
     "mux":     dict(sources=["script"], inputs=["silent.mp4", "audio.wav"], outputs=[]),
+    # gates.json 不列进 qa 的产物：它由 _finish_gates 在 style/frames/mux/qa 任何一次收尾时
+    # 都会写，不能当"qa 跑过"的证据（否则删掉 qa 记录后它还在，会误判 no-manifest）。
+    # qa/sheet.png（联系表）只在 --stage qa 里生成，才是真凭证。
     "qa":      dict(sources=["script", "scenes"], inputs=[],
-                    outputs=["gates.json", "qa/sheet.png"]),
+                    outputs=["qa/sheet.png", "qa/deep.json"]),
     "stills":  dict(sources=["script", "scenes"], inputs=["timeline.json", "style.json"],
                     outputs=[]),
 }
@@ -123,6 +133,19 @@ def save(work, d):
     return p
 
 
+def _producer_of(art):
+    """work/ 里的产物文件是哪个 stage 写的（由 STAGE_IO 反查，找不到返回 None）。"""
+    for st, io in STAGE_IO.items():
+        if art in (io.get("outputs") or []):
+            return st
+    return None
+
+
+# 硬类型：这些永远参与 --strict-stale 判定（产物丢了 / 源头改了 / 上游自己就过时）
+HARD_KINDS = ("source-changed", "output-missing", "no-manifest", "input-stale")
+SOFT_KINDS = ("input-pending", "source-pending")
+
+
 def _src_fp(kind, sources):
     """源头输入指纹：script=剧本（film.json）、scenes=场景代码（scenes.py）。"""
     p = (sources or {}).get(kind)
@@ -146,32 +169,64 @@ def snapshot(work, stage, sources=None):
     return d["stages"][str(stage)]
 
 
-def check(work, stage, sources=None):
+def _upstream_hard(work, stage, sources=None, _seen=None):
+    """产出某输入的 stage 是否有**硬**问题（源头变了 / 它的输入也变了 / 产物丢了）。
+
+    只取硬类型：软化过的 input-pending 不算（那只说明"它也会重跑"）。
+    递归带上 _seen 防环——STAGE_IO 是 DAG，但用户手改的 manifest 不该把检查器搞成死循环。
+    """
+    if not stage:
+        return []
+    issues = check(work, stage, sources, pending=(), _seen=_seen)
+    return [it["reason"] for it in issues if it.get("kind") in HARD_KINDS]
+
+
+def check(work, stage, sources=None, self_built=False, pending=(), _seen=None):
     """stage 开始前查新鲜度：返回问题列表（每项含 stage / reason / rerun）。
 
+    pending: 本次命令行**已经计划要跑**的 stage 集合（render.py 传 args.stage 展开后的列表）。
+      对本 stage 来说，"自己上次跑完之后上游变了" + "本轮马上就要重跑自己" = 正常待办，
+      不是过时（`--stage frames mux` 里 frames 刚重出 silent.mp4，mux 报"输入变了"是自相矛盾）。
+      这类问题标 kind="input-pending"、soft=True：照实打印，但不参与 --strict-stale 判定。
+      真问题不受影响：上游 stage **自己**过时（它的输入也变了）仍按 input-stale/output-missing 硬报，
+      所以"单独跑 mux、上游 frames 早过时"照样失败。
+
     只报"这一跑真的会读到旧东西"的情况：
       1) 本 stage 的上游输入与上次记录不同（上游被重跑过，或人手改过文件）；
       2) 本 stage 自己的产物比它的输入还旧（上次跑到一半被中断）。
     另一个 stage 的产物变了但**不**是本周 stage 的输入时，不报（跟我们无关）。
+
+    self_built: 这些输入是**本次运行自己刚写出来的**（render.py --stage all 跑在
+    一个刚建的 work/ 上）。此时"manifest 没有本阶段记录"只是因为我们还没跑到它，
+    不是旧产物；报 no-manifest 等于让全新目录的首跑刷一屏假警报（v0.7.2 修）。
     """
     io = STAGE_IO.get(str(stage))
     if io is None:
         return []
+    _seen = set(_seen or ())
+    if str(stage) in _seen:
+        return []
+    _seen.add(str(stage))
     d = load(work)
     stages = d.get("stages") or {}
     rec = stages.get(str(stage))
+    planned = set(str(x) for x in (pending or ()))
     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"]:
+        # 从没记录过这个 stage。判据必须能区分两件事：
+        #   * 「还没跑到它」——分步跑（SKILL.md 主推：--stage style / tts / layout / …）时，
+        #     刚跑完 style，tts 的输入 style.json 当然存在、manifest 里当然没有 tts 记录。
+        #     这**不是**过时，按"输入齐了"报会把这套标准用法整个打成红（--strict-stale 下必然失败）。
+        #   * 「跑过它但查不到记录」——旧版本产物 / 手改 / 复制来的 work 目录。
+        # 区分证据：本 stage **自己声明的产物**已经在 work/ 里。产物在、记录没有，才证明它跑过。
+        # 输入齐全不能当证据（分步跑时本来就齐），输出存在才可以。
+        present_out = [k for k in (io.get("outputs") or []) if _fp(k, work) != "missing"]
+        # stills / mux 的产物不在 work/（mux 写 --out，stills 写 work/stills/），无从证明跑过，
+        # 不冤枉它们；self_built（本次新建的 work/）连 manifest 都刚建，也不报。
+        if not self_built and stages and present_out:
             issues.append(dict(stage=str(stage), kind="no-manifest",
-                               reason="work 里有 %s 但 manifest.json 没有本阶段的记录"
-                                      "（旧版本跑过 / 手改过）" % "、".join(io["inputs"]),
+                               reason="work 里已经有本阶段的产物（%s），但 manifest.json 没有本阶段的记录"
+                                      "（旧版本跑过 / 手改过）" % "、".join(present_out),
                                rerun=RERUN_HINT.get(str(stage), "")))
         return issues
     # 源头先查：剧本 / scenes.py 改了但本 stage 没重跑 -> 产物一定过时
@@ -179,28 +234,69 @@ def check(work, stage, sources=None):
     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)
+        if now == was:
+            continue
+        fname = {"script": "剧本 film.json", "scenes": "画面代码 scenes.py"}.get(kind, kind)
+        if str(stage) in planned:
+            # 源头变了 + 本轮马上就要重跑本阶段 = 正常待办，不是过时。
+            # 不软化的话，「改一句台词 -> --stage all --strict-stale」会在第一个 stage
+            # 直接失败（"没重跑却装了旧内容"——其实马上就要重跑），把主工作流堵死；
+            # 与 inputs 的 input-pending 是同一套语义，只是源头走的是另一个循环。
             issues.append(dict(
-                stage=str(stage), kind="source-changed", file=kind,
-                reason="%s 在本阶段上次跑完之后改过（%s -> %s），但本阶段没有重跑；"
-                       "它现在装的还是旧内容" % (fname, was, now),
+                stage=str(stage), kind="source-pending", file=kind, soft=True,
+                reason="%s 在上次跑本阶段之后变了（%s -> %s）；本阶段本轮会重跑，"
+                       "按新内容重算" % (fname, was, now),
                 rerun=RERUN_HINT.get(str(stage), ""),
             ))
+            continue
+        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:
+        if now == was:
+            continue
+        if str(stage) in planned:
+            # 本阶段本轮就要重跑：拿新输入重算正是它该干的事。照实打一行（不静默），
+            # 但不参与 strict 判定——否则 `--stage frames mux` 这种 stagewatch 自己建议的
+            # 重跑组合，会在 mux 开跑前被自己拦下，strict 下永远出不了片。
+            issues.append(dict(
+                stage=str(stage), kind="input-pending", file=name, soft=True,
+                reason="输入 %s 在上次跑本阶段之后变了（%s -> %s）；本阶段本轮会重跑，"
+                       "按新输入重算" % (name, was, now),
+                rerun=RERUN_HINT.get(str(stage), ""),
+            ))
+            continue
+        # 不由本阶段重算时：还要确认产出这个输入的 stage **自己**没坏。
+        # 上游自己就过时（源头改了 / 它的输入也变了 / 它的产物丢了），那这台旧货是真的不能用。
+        prod = _producer_of(name)
+        ups = _upstream_hard(work, prod, sources, _seen) if prod else []
+        if ups:
+            issues.append(dict(
+                stage=str(stage), kind="input-stale", file=name,
+                reason="输入 %s 变了（%s -> %s），并且产出它的 %s 阶段本身就已经过时：%s"
+                       % (name, was, now, prod, "；".join(ups[:3])),
+                rerun=RERUN_HINT.get(str(stage), ""),
+            ))
+        else:
             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"]
+    # 自己的产物丢了：上次跑到一半被中断 / 被删 / 被挪走（与"输入变了"是两件事，都要报）。
+    # 只报「上次记录到真实指纹、现在没了」的文件：有些产物是**条件性**的（legacy 剧本
+    # 不写 voice_plan.json），它们上次就记为 missing，现在还是 missing，那是正常状态；
+    # 一律按"现在是 missing 就报"会让这类文件变成永久误报（--strict-stale 下直接失败）。
+    rec_out = rec.get("outputs") or {}
+    missing_out = [k for k, was in rec_out.items()
+                   if was not in (None, "missing") and _fp(k, work) == "missing"]
     if missing_out:
         issues.append(dict(stage=str(stage), kind="output-missing",
                            reason="上次跑过本阶段，但产物 %s 不见了（被删 / 被挪 / 磁盘满）"
@@ -209,8 +305,11 @@ def check(work, stage, sources=None):
     return issues
 
 
-def explain(work, stages=None, sources=None):
-    """--explain-stale：把"现在哪些阶段是旧的、为什么、该跑什么"一次说清。"""
+def explain(work, stages=None, sources=None, self_built=False, pending=()):
+    """--explain-stale：把"现在哪些阶段是旧的、为什么、该跑什么"一次说清。
+
+    pending: 本次命令行要跑的 stage 集合（见 check）；--stage explain 不传 = 全按"不重跑"判。
+    """
     d = load(work)
     rows = []
     for st in (stages or STAGE_ORDER):
@@ -218,7 +317,7 @@ def explain(work, stages=None, sources=None):
         if io is None:
             continue
         rec = (d.get("stages") or {}).get(st)
-        issues = check(work, st, sources)
+        issues = check(work, st, sources, self_built=self_built, pending=pending)
         rows.append(dict(stage=st, recorded=bool(rec),
                          at=(rec or {}).get("atText", ""),
                          issues=issues))
@@ -226,40 +325,64 @@ def explain(work, stages=None, sources=None):
 
 
 def report(work, stages=None, strict=False, allow_stale=False, ledger=None, write=None,
-           sources=None):
+           sources=None, self_built=False, pending=()):
     """查 + 打印 + 判定。返回 (errors, warnings)；errors 在 strict 下非空。
 
     ledger: 传 gates.GateLedger 时把结论记进账本（一条汇总 gate）。
     write:  传 callable(str, str) 时按行输出（方便测试捕获）。
+    self_built: 见 check()——本次运行的 work/ 是刚建的，别报"没有记录=过时"。
+    pending: 本次命令行要跑的 stage 集合（见 check）。其中"本阶段会重算"的输入变化
+             标 soft，照实打印但不参与 strict 判定。
     """
     out = write or (lambda level, msg: print(msg))
-    rows = explain(work, stages, sources)
+    rows = explain(work, stages, sources, self_built=self_built, pending=pending)
     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:
+        soft = bool(it.get("soft")) or it.get("kind") in SOFT_KINDS
+        # 两类不要用同一个前缀：soft 是"本轮会重算"的待办，不是过时。用 [stale] 会把
+        # 人吓一跳，也会让"grep [stale] 判红"的 CI 配方误报。
+        msg = (("[待重算] %s: %s" if soft else "[stale] %s: %s") % (st, it["reason"]))
+        if soft:
+            # 本轮会重算的输入变化：照实说，但不算失败。--strict-stale 也不拦。
+            warns.append(msg)
+        elif allow_stale:
             warns.append(msg + "（--allow-stale 已放行，本次结果可能掺旧数据）")
         elif strict:
             errs.append(msg)
         else:
             warns.append(msg)
-        if it.get("rerun"):
+        # 原因行必须打出来：调用方（render.py --stage all）只显示"最小重跑"，
+        # 用户会看到"共 1 处过时"却不知道是哪个 stage、为什么——这正是本模块
+        # 开头承诺的"可以保守，但不能静默"。返回的 warns/errs 是给调用方判定的，
+        # 不代替人读的输出。
+        out(("warn" if soft else "err") if (strict and not allow_stale) else "warn", msg)
+        if it.get("rerun") and not soft:
             out("warn", "   最小重跑: %s" % it["rerun"])
+    hard = [(st, it) for st, it in problems
+            if not (it.get("soft") or it.get("kind") in SOFT_KINDS)]
     if problems:
         out("warn", "")
-        out("warn", "   ↑ 共 %d 处过时。默认只告警；--strict-stale 让它失败，"
-                    "--allow-stale 显式放行（会记进 QC 报告）。" % len(problems))
+        if hard:
+            out("warn", "   ↑ 共 %d 处过时。默认只告警；--strict-stale 让它失败，"
+                        "--allow-stale 显式放行。放行会记进本次门禁账本，"
+                        "交付阶段（qa / mux / all / stills / style）会体现在 QC 报告里。"
+                        % len(hard))
+        else:
+            out("warn", "   ↑ 上面 %d 条都是「本轮会重算」的输入变化（不是过时，不拦 strict）。"
+                        % len(problems))
     if ledger is not None:
         try:
-            if not problems:
-                ledger.ok("stale", "阶段新鲜度", "上游输入与上次记录一致")
+            if not hard:
+                ledger.ok("stale", "阶段新鲜度",
+                          "上游输入与上次记录一致" if not problems
+                          else "%d 处输入会在本轮重算，无需拦" % len(problems))
             elif errs:
-                ledger.fail("stale", "阶段新鲜度", "%d 处过时（--strict-stale）" % len(problems))
+                ledger.fail("stale", "阶段新鲜度", "%d 处过时（--strict-stale）" % len(hard))
             else:
                 ledger.skip("stale", "阶段新鲜度",
                             "%d 处过时，已告警未阻断%s"
-                            % (len(problems), "（--allow-stale）" if allow_stale else ""))
+                            % (len(hard), "（--allow-stale）" if allow_stale else ""))
         except Exception:                                   # noqa: BLE001
             pass
     return errs, warns

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

@@ -37,6 +37,7 @@ from __future__ import annotations
 
 import argparse
 import hashlib
+import re
 import sys
 
 # ============================================================================
@@ -77,6 +78,92 @@ def _rgb(seq):
     return t
 
 
+_HEX_RE = re.compile(r"^#?([0-9a-fA-F]{6}|[0-9a-fA-F]{3})$")
+
+
+def _color_of(v, key):
+    """把 theme_overrides 里的颜色值统一成 (r,g,b)：支持 [r,g,b] 和 "#rrggbb" / "#rgb"。
+
+    为什么必须支持 hex：schemas/film.schema.json 与 references/style-packs.md 的示例
+    就是 {"accent": "#ff8a3d"}，而 JSON 没有元组，照着文档写 hex 是必然的。
+    v0.5 旧实现把字符串原样塞进主题，scenes.py 第一次 int("#") 就崩在渲染期
+    （实测：ink="#ffffff" -> ValueError: invalid literal for int() with base 10: '#'）。
+    """
+    if isinstance(v, str):
+        m = _HEX_RE.match(v.strip())
+        if not m:
+            raise ValueError("theme_overrides.%s 的颜色写法不认识：%r（用 [r,g,b] 或 \"#rrggbb\"）"
+                             % (key, v))
+        h = m.group(1)
+        if len(h) == 3:
+            h = "".join(ch * 2 for ch in h)
+        return (int(h[0:2], 16), int(h[2:4], 16), int(h[4:6], 16))
+    if isinstance(v, (list, tuple)) and len(v) == 3:
+        return _rgb(v)
+    raise ValueError("theme_overrides.%s 必须是颜色（[r,g,b] 或 \"#rrggbb\"），收到 %r"
+                     % (key, v))
+
+
+# 主题里"颜色字段"的白名单（值是 0..255 的 RGB 元组）。不靠"长度 3 的元组"猜：
+# keywords 也是元组（长度 10），将来若加一个正好 3 项的关键词元组就会被误当颜色。
+_THEME_COLOR_KEYS = frozenset(("bg", "bg2", "surface", "ink", "muted", "dim",
+                               "accent", "accent2", "good", "bad", "rule", "vignette_tint"))
+
+
+def apply_theme_overrides(theme, overrides):
+    """把 film.json 的 visual.theme_overrides 合并进主题**并做类型校验**。
+
+    契约（schemas/film.schema.json：只接受主题里已存在的键；references/style-packs.md §3）：
+      - 未知键忽略：以后主题加字段时老剧本不因为它不认识就炸；
+      - 颜色键（值本来是三色元组的那些）接受 [r,g,b] / "#rrggbb" / "#rgb"，统一成元组；
+      - 数值键接受数字或数字字符串；字符串键必须是字符串；
+      - 嵌套结构（card / scale / qa …）不支持覆盖，静默忽略（与 v0.5 一致，避免破坏老配置）；
+        真要改嵌套字段请改风格包。
+    校验只在"值类型不对、旧版会在渲染期崩"的场合抛 ValueError（提前到 --stage style）。
+    返回新的 theme dict（不改入参）。
+    """
+    out = dict(theme or {})
+    for k, v in (overrides or {}).items():
+        if k not in out:
+            continue
+        base = out[k]
+        if k in _THEME_COLOR_KEYS:
+            out[k] = _color_of(v, k)
+            continue
+        if isinstance(base, bool):
+            if not isinstance(v, bool):
+                raise ValueError("theme_overrides.%s 必须是布尔，收到 %r" % (k, v))
+            out[k] = bool(v)
+            continue
+        if isinstance(base, (int, float)):
+            if isinstance(v, bool) or not isinstance(v, (int, float, str)):
+                raise ValueError("theme_overrides.%s 必须是数字，收到 %r" % (k, v))
+            try:
+                num = float(v)
+            except (TypeError, ValueError):
+                raise ValueError("theme_overrides.%s 必须是数字，收到 %r" % (k, v))
+            out[k] = int(round(num)) if isinstance(base, int) else float(num)
+            continue
+        if isinstance(base, dict):
+            # 嵌套结构（card / scale / qa）不支持覆盖。这里保持 v0.5 的**静默忽略**：
+            # 老配置里如果写了这种覆盖，旧版只是没生效、并不会崩；升级后突然报错是破坏性变更。
+            # 想改嵌套字段请改风格包（STYLES/THEMES），见 references/style-packs.md §7。
+            continue
+        if isinstance(base, str):
+            if not isinstance(v, str):
+                raise ValueError("theme_overrides.%s 必须是字符串，收到 %r" % (k, v))
+            if k == "layout" and v not in LAYOUTS:
+                raise ValueError("theme_overrides.layout 未知版式 %r；可用：%s"
+                                 % (v, " / ".join(LAYOUT_IDS)))
+            if k == "hud" and v not in ("chip-left", "corner-line", "none"):
+                raise ValueError("theme_overrides.hud 未知取值 %r；可用：chip-left / corner-line / none"
+                                 % (v,))
+            out[k] = v
+            continue
+        # 其它类型（None 等）：保持原值，不折腾
+    return out
+
+
 def _theme(style_id, label, keywords, palette, material, typ, layout, motion, hud, qa):
     """把主题字段组装成一个扁平 dict（场景代码直接下标取，不嵌套，读起来快）。"""
     p = {k: _rgb(v) for k, v in palette.items()}
@@ -247,7 +334,7 @@ THEMES["lo-fi"] = _theme(
     ("深夜", "学习", "效率", "专注", "写作", "整理", "笔记", "书", "日常", "房间"),
     # 冷调灰绿：和 paper（暖牛皮纸）在色相上分开，不靠"亮度差不多"硬撑
     dict(bg=(232, 238, 236), bg2=(210, 220, 216), surface=(244, 248, 246),
-         ink=(44, 52, 50), muted=(86, 100, 96), dim=(112, 126, 122),
+         ink=(44, 52, 50), muted=(84, 98, 94), dim=(112, 126, 122),
          accent=(20, 86, 84), accent2=(104, 72, 96),
          good=(40, 100, 72), bad=(146, 52, 50), rule=(44, 52, 50)),
     dict(vignette=0.12, vignette_tint=(206, 200, 190), grain=7.0, grain_freq=0.24,
@@ -546,7 +633,11 @@ def score_styles(script):
             score += 1.0 if sid in ("cinema", "paper", "mono") else 0.0
         if prof["hook"] > 0 and prof["outro"] > 0:
             score += 0.5 if sid in ("tech-deep", "vivid", "epic") else 0.0
-        score += (int(fp["style"][:4], 16) % 7) * 0.0001      # 指纹破平
+        # 指纹破平：必须把**风格 id** 混进哈希，否则这一项对所有行是同一个常数，
+        # 等于没破平（v0.8 深审实测：旧写法在"AI 报告"上 tech-deep / magazine 同分 12.0，
+        # 永远按 STYLE_IDS 顺序选 tech-deep）。幅度上限 0.0006 << 最小真实分差 0.5，
+        # 只在精确同分时起作用，且不改变"改错别字不换风格"（指纹只吃标题）。
+        score += (_digest("tiebreak", fp["style"], sid) % 7) * 0.0001
         rows.append((sid, round(score, 4), hits))
     rows.sort(key=lambda r: (-r[1], STYLE_IDS.index(r[0])))
     return rows
@@ -558,7 +649,12 @@ def pick_style(script):
     best_id, best_score, best_hits = rows[0]
     fp = fingerprint(script)
     if best_score >= 1.0:
-        reason = ["关键词命中：%s" % "、".join(dict.fromkeys(best_hits))[:80]]
+        if best_hits:
+            reason = ["关键词命中：%s" % "、".join(dict.fromkeys(best_hits))[:80]]
+        else:
+            # 分数可以只由结构加分（items / 长句 / hook+outro）凑到 1.0 以上，
+            # 这时旧文案会写"关键词命中："后面空一截 —— 等于向用户报告没发生的事。
+            reason = ["无关键词命中，按题材结构加分选中（items / 长句 / hook+outro）"]
     else:
         pool = list(STYLE_IDS)
         best_id = pool[int(fp["tempo"], 16) % len(pool)]
@@ -726,12 +822,18 @@ def resolve_script_style(script):
     else:
         chap_layout = {ch: layouts[i % len(layouts)] for i, ch in enumerate(chapters)}
 
-    theme = dict(THEMES[pack["theme"]])
-    for k, v in (vis.get("theme_overrides") or {}).items():
-        if k in theme and isinstance(v, (int, float, str)):
-            theme[k] = v
-        elif k in theme and isinstance(v, (list, tuple)) and len(v) == 3:
-            theme[k] = _rgb(v)
+    # theme_overrides 走带校验的合并（颜色支持 "#rrggbb"，非法值在这里就报错，
+    # 不要等到 scenes.py 渲到第 300 帧才 int("#") 崩——见 apply_theme_overrides）
+    theme = apply_theme_overrides(THEMES[pack["theme"]], vis.get("theme_overrides"))
+    # visual.layout 是"显式换整片版式"：旧的实现只把它写进 chapter_layout，而
+    # PIL 路线渲染读的是 theme["layout"]、web 路线读 layout_default —— 两条路线都不看
+    # chapter_layout，于是这条文档化的覆盖等于没写（v0.8 深审实测：visual.layout=
+    # split-right 的帧与默认帧 sha256 完全相同）。这里补写 theme["layout"] 与 layout_default，
+    # 让两条路线都跟着走；theme_overrides 更具体，它显式写了 layout 时以它为准。
+    if explicit_layout and "layout" not in (vis.get("theme_overrides") or {}):
+        theme["layout"] = explicit_layout
+    if explicit_layout:
+        chap_layout = {ch: str(theme["layout"]) for ch in chapters}
 
     return {
         "version": 1,
@@ -747,7 +849,7 @@ def resolve_script_style(script):
         # 主题字典随计划一起返回：scenes.py 的 _scene_theme 优先用它（含 theme_overrides），
         # 也方便 render.py 直接传给 draw_subtitle/write_ass，不必再按 id 查一次。
         "theme": theme,
-        "layout_default": layouts[0],
+        "layout_default": str(theme["layout"]) if explicit_layout else layouts[0],
         "chapter_layout": chap_layout,
         "music": {
             "style": music_style,
@@ -770,7 +872,8 @@ def resolve_script_style(script):
 # 七、门禁：主题体检（对比度 / 明暗 / 结构）
 # ============================================================================
 #
-# 阈值不是拍脑袋：以 v0.4 现行主题实测值当基线（ink 16.3 / muted 7.8 / accent 7.0）。
+# 阈值不是拍脑袋：以 v0.4 现行主题实测值当基线（tech-deep：ink 16.3 / muted 7.8 / accent 7.0，
+# 那是旧版按 bg/bg2 中点量的；v0.8 改成按两端最差值量后同一主题是 14.8 / 7.1 / 6.3，仍远高于线）。
 
 LINT_LIMITS = {
     "ink": 7.0,          # 正文级（WCAG AAA 正文线）
@@ -784,18 +887,30 @@ LINT_LIMITS = {
 }
 
 
+def bg_contrast(th, role):
+    """文字色对背景的**最差**对比度：bg/bg2 是上下两端的主渐变（scenes._bg 按行插值），
+    任何一行文字都可能落在两端附近，所以取二者较小值，而不是看中点。
+
+    为什么不能只看中点：lo-fi 的 muted(86,100,96) 对 bg 5.28、对 bg2 只有 4.42，
+    中点平均 4.84 把 AA 4.5 的门槛"平均"过去了 —— 实测过（v0.8 深审），
+    这一版把门槛改成端点最差值，并同时下调 lo-fi 的 muted 到 (84,98,94)
+    （bg 5.44 / bg2 4.56，两端都过）。
+    """
+    return min(contrast(th[role], th["bg"]), contrast(th[role], th["bg2"]))
+
+
 def theme_lint(th):
     """主题体检，返回问题列表（空 = 过）。坏主题在 load 阶段就拦，别等渲完 300 帧。"""
     if not isinstance(th, dict):
         return ["主题不是 dict：%r" % (th,)]
     bad = []
-    bgs = midpoint(th["bg"], th["bg2"])
     for role, need in (("ink", LINT_LIMITS["ink"]), ("muted", LINT_LIMITS["muted"]),
                        ("dim", LINT_LIMITS["dim"]), ("accent", LINT_LIMITS["accent"]),
                        ("accent2", LINT_LIMITS["accent2"])):
-        got = contrast(th[role], bgs)
+        got = bg_contrast(th, role)
         if got < need:
-            bad.append("%s 对背景对比度 %.2f < %.1f" % (role, got, need))
+            bad.append("%s 对背景对比度 %.2f < %.1f（bg/bg2 两端取最差）"
+                       % (role, got, need))
     for role in ("good", "bad"):
         got = contrast(th[role], th["surface"])
         if got < LINT_LIMITS[role]:
@@ -863,7 +978,6 @@ def blend_theme(a, b, p):
 def _describe(sid):
     pack = STYLES[sid]
     th = THEMES[pack["theme"]]
-    bgs = midpoint(th["bg"], th["bg2"])
     lines = [
         "[%s] %s  （theme=%s / layouts=%s）" % (sid, pack["name"], pack["theme"],
                                                 ",".join(pack["layouts"])),
@@ -877,9 +991,10 @@ def _describe(sid):
         % (pack["pacing"]["lead"], pack["pacing"]["tail"], pack["pacing"]["min_dur"]),
         "  palette   : bg=%s bg2=%s ink=%s accent=%s"
         % (th["bg"], th["bg2"], th["ink"], th["accent"]),
-        "  contrast  : ink %.2f / muted %.2f / dim %.2f / accent %.2f"
-        % (contrast(th["ink"], bgs), contrast(th["muted"], bgs),
-           contrast(th["dim"], bgs), contrast(th["accent"], bgs)),
+        # 与 theme_lint 同口径：bg/bg2 两端取最差（旧版打中点值，会掩盖端点不达标）
+        "  contrast  : ink %.2f / muted %.2f / dim %.2f / accent %.2f（bg/bg2 最差端）"
+        % (bg_contrast(th, "ink"), bg_contrast(th, "muted"),
+           bg_contrast(th, "dim"), bg_contrast(th, "accent")),
         "  font      : family=%s display=%spx hud=%s"
         % (th["family"], th["scale"]["display"][0], th["hud"]),
     ]
@@ -900,6 +1015,10 @@ def main(argv=None):
     except Exception:                                   # noqa: BLE001
         pass
     if a.show:
+        # 未知 id 以前是 KeyError traceback，现在给可用清单 + exit 2（与 render.py 的口径一致）
+        if a.show not in STYLES:
+            print("[未知风格] %r；可用：%s" % (a.show, " / ".join(ALL_STYLE_IDS)), file=sys.stderr)
+            return 2
         if a.json:
             import json
             print(json.dumps({"style": STYLES[a.show],

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

@@ -207,8 +207,12 @@ except Exception:                        # noqa: BLE001 — stylekit 缺失时
 # ============================================================================
 # 三、小工具：参数解析/格式化、汉字计数、抖动
 # ============================================================================
-_PCT_RE = re.compile(r"^\s*([+-]?)(\d+)\s*%\s*$")
-_HZ_RE = re.compile(r"^\s*([+-]?)(\d+)\s*Hz\s*$")
+# 允许小数（"+4.5%"）：edge-tts 只收整数百分比，所以解析后按 _round_half_away 取整。
+# 以前正则只认整数，"+4.5%" 解析失败 → 静默回落 0 —— 而 0 与 "+0%" 在 spec_key 里
+# 是**同一个 TTS 缓存键**，于是"把语速从 0 调到 4.5%"完全没生效，还复用了旧音频。
+# 这是配置写对了却不生效里最难查的一类：没有报错、没有日志、听起来就是"没反应"。
+_PCT_RE = re.compile(r"^\s*([+-]?)(\d+(?:\.\d+)?)\s*%\s*$")
+_HZ_RE = re.compile(r"^\s*([+-]?)(\d+(?:\.\d+)?)\s*Hz\s*$")
 
 
 def _round_half_away(v):
@@ -218,24 +222,24 @@ def _round_half_away(v):
 
 
 def parse_pct(v, default=0):
-    """'+4%' -> 4；'-3%' -> -3；数字原样取整；解析失败回落 default。"""
+    """'+4%' -> 4；'-3%' -> -3；'+4.5%' -> 5（取整）；数字原样取整；解析失败回落 default。"""
     if isinstance(v, (int, float)) and not isinstance(v, bool):
         return int(_round_half_away(v))
     m = _PCT_RE.match(str(v if v is not None else ""))
     if not m:
         return int(default)
-    n = int(m.group(2))
+    n = int(_round_half_away(float(m.group(2))))
     return -n if m.group(1) == "-" else n
 
 
 def parse_hz(v, default=0):
-    """'+2Hz' -> 2；解析失败回落 default。"""
+    """'+2Hz' -> 2；'+2.5Hz' -> 3（取整）；解析失败回落 default。"""
     if isinstance(v, (int, float)) and not isinstance(v, bool):
         return int(_round_half_away(v))
     m = _HZ_RE.match(str(v if v is not None else ""))
     if not m:
         return int(default)
-    n = int(m.group(2))
+    n = int(_round_half_away(float(m.group(2))))
     return -n if m.group(1) == "-" else n
 
 
@@ -306,7 +310,11 @@ def _quantize(v, u):
 # ============================================================================
 # 四、文本规则（说什么）：全部确定性，命中即返回理由
 # ============================================================================
-_QUOTE_OPEN = ('"', "\u201c", "\u300c", "\u300e", "\u300a")
+# 引语起始符。**不含书名号 《（《）**：正文里出现"《设计模式》"是书名，不是引用某人在说话。
+# 实测踩过：把 《 算进引语后，"今天我们聊《设计模式》"这句的 tone 被判成 quote，
+# 进而触发 rule:quote:persona，把 persona 从 narrator_male 换成 narrator_female ——
+# 旁白中途换人，听感像换了主播（而这句根本没有人引语）。
+_QUOTE_OPEN = ('"', "\u201c", "\u300c", "\u300e")
 _QUOTE_WORDS = ("他说", "她说", "有人问", "所谓", "据称")
 _NUM_UNITS = ("%", "万", "亿", "年", "倍")
 _TURN_WORDS = ("但是", "然而", "不过", "其实", "问题是")
@@ -861,6 +869,14 @@ def main(argv=None):
         return _cli_list()
     if a.calibrate:
         only = [x.strip() for x in (a.only or "").split(",") if x.strip()] or None
+        if only:
+            unknown = [x for x in only if x not in VOICE_PERSONAS]
+            if unknown:
+                # 以前拼错 persona 会静默变成空集合 -> 打出"所有音色都合成失败（多半是没网）"，
+                # 把配置错误伪装成网络错误。这里先点名校验，给人话可照抄的可用清单。
+                print("[未知 persona] %s；可用：%s"
+                      % ("、".join(unknown), " / ".join(PERSONA_IDS)), file=sys.stderr)
+                return 2
         return calibrate(only, log=print)
     if a.plan:
         return _cli_plan(a.plan)