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

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

@@ -42,6 +42,17 @@ HERE = Path(__file__).resolve().parent
 # ============================================================================
 
 KINDS = ("hook", "body", "quote", "outro", "emphasis", "calm")   # 也是 voicekit 的语气 id
+
+# 视觉场景类型（v0.9）：决定"这段画面长成什么构图"，与叙事 kind **正交**——
+#   kind 管声线/语气/配乐能量（voicekit / scorekit 读它）；
+#   type 只管构图（assets/scenes.py 的 _DRAWERS 读它）。
+# 所以**不新增 kind 值**：hero/stat/... 不是语气，硬塞进 KINDS 会撞 voicekit 的 tone id
+# （TONE_IDS 与 KINDS 是同一组 6 个）。缺省（不写 lines[].type）= 由 grammar.py 按内容推导。
+SCENE_TYPES = ("hero", "statement", "list", "stat", "compare", "process",
+               "quote", "chapter", "chart", "outro")
+# 与 assets/scenes.py 的 _DRAWERS 键对齐，改一边必须改另一边。
+# （grammar.SCENE_TYPES 是同一组 10 个值，但那份顺序用于"平手取位"；这里只做成员校验，
+#  本元组的顺序只影响报错信息里的枚举列举，不影响判定。三处不要再各写一份新名单。）
 PRESETS = ("ultrafast", "superfast", "veryfast", "faster", "fast",
            "medium", "slow", "slower", "veryslow")
 MUSIC_MODES = ("score", "bed", "file", "off")
@@ -71,7 +82,7 @@ KEY_ALIASES = {
     "cue": "cues", "sfx_cues": "cues", "sound": "sfx", "bgm": "music",
 }
 
-# 不是 film.json 的其他产物（例如 assets/score_demo.json 是 scorekit 报告）——
+# 不是 film.json 的其他产物（例如配乐引擎落盘的 score.json 报告）——
 # 交给本脚本前先认出来，直接 SKIP 而不是按剧本报"缺 title"的错误。
 OTHER_ARTIFACT_KEYS = ("generator", "meas", "reproduce", "sections", "beats",
                        "transitions", "sr", "duration", "score")
@@ -200,6 +211,59 @@ LINE_ITEM_SPEC = {
     },
 }
 
+# ---- v0.9 视觉场景字段的嵌套结构（写法照抄 LINE_ITEM_SPEC）----
+# 这些对象的键由 scenes.py 的 10 个绘制器读：拼错就是"写了不生效"，所以**不**用
+# open=True（那是留给 sfx 配方参数那种真·透传的）。每层列全 props，才能把拼错报成
+# unknown_key（WARN + "是不是想写 X"），把类型写错报成 ERROR。
+# required 与 schema 表里的问号标记一致：必填 = 绘制器没有它就没法画。
+LINE_STAT_SPEC = {                   # type=stat 的数字卡
+    "t": "dict", "required": ["value"],
+    "props": {
+        # 数字或字符串（"92"、">3x"、"1/2" 这类写法只能当字符串）
+        "value": {"t": ("num", "str"), "nonempty": True},
+        "unit": {"t": "str"},
+        "label": {"t": "str"},
+        "note": {"t": "str"},
+    },
+}
+
+LINE_SERIES_SPEC = {                 # type=chart 的数据条
+    "t": "dict", "required": ["label", "value"],
+    "props": {
+        "label": {"t": "str", "nonempty": True},
+        "value": {"t": ("num", "str"), "nonempty": True},
+        "unit": {"t": "str"},
+    },
+}
+
+LINE_STEP_SPEC = {                   # type=process 的流程节点
+    "t": "dict", "required": ["label"],
+    "props": {
+        "label": {"t": "str", "nonempty": True},
+        "note": {"t": "str"},
+    },
+}
+
+# 对比卡的一侧：items 每项可以写字符串，也可以写 {text}（短条目直接写字符串更省事，两种都认）
+LINE_SIDE_SPEC = {
+    "t": "dict",
+    "props": {
+        "head": {"t": "str"},
+        "items": {"t": "list", "item": {
+            "t": ("str", "dict"), "required": ["text"],
+            "props": {"text": {"t": "str", "nonempty": True}},
+        }},
+    },
+}
+
+LINE_SIDES_SPEC = {                  # type=compare 的左右对比（left/right 都可省略）
+    "t": "dict",
+    "props": {
+        "left": LINE_SIDE_SPEC,
+        "right": LINE_SIDE_SPEC,
+    },
+}
+
 LINE_SPEC = {
     "t": "dict", "required": ["text"],
     "props": {
@@ -218,6 +282,16 @@ LINE_SPEC = {
         "persona": {"t": "str"},
         "tone": {"t": "str", "enum": KINDS},
         "voice": {"t": "str"},
+        # ---- v0.9 视觉场景字段（7 个全可选）----
+        # type 缺省由 grammar.py 按内容推导；其余字段是给绘制器的原料，不写就不画。
+        # 注意这些字段与 kind **正交**，不是新 kind：kind 仍只有上面 6 个（voicekit 的语气 id）。
+        "type": {"t": "str", "enum": SCENE_TYPES},
+        "quote": {"t": "str"},
+        "by": {"t": "str"},
+        "stats": {"t": "list", "item": LINE_STAT_SPEC},
+        "series": {"t": "list", "item": LINE_SERIES_SPEC},
+        "steps": {"t": "list", "item": LINE_STEP_SPEC},
+        "sides": LINE_SIDES_SPEC,
     },
 }
 
@@ -248,7 +322,11 @@ SCRIPT_SPEC = {
     "props": {
         "title": {"t": "str", "nonempty_warn": True},
         "end_text": {"t": "str"},
-        "style": {"t": "str", "enum_dynamic": "style"},
+        # v1.0.2: style is deprecated since v1.0.1 (appearance comes from work/design.json).
+        # It used to use enum_dynamic -> _load_styles(); STYLE_IDS is now empty, so it always
+        # emitted a misleading WARN saying stylekit.py was missing (the file was there).
+        # Now it is an inert key: accepted (old scripts must not hard-fail) but reported.
+        "style": {"t": "str", "inert": "v1.0.1 起已废弃：外观由 work/design.json 决定（python propose.py --brief ... 再 --confirm），这里写任何值都不生效"},
         "engine": {"t": "str", "enum": ENGINES},
         "voice": {"t": ("str", "dict"), "open": "dict"},
         "rate": {"t": "str", "pattern": RATE_RE, "example": "+6%"},
@@ -396,22 +474,6 @@ def _check(val, rule, path, rep, ctx):
     if rule.get("inert"):
         rep.warn(path, "这个键**当前不生效**：%s" % rule["inert"], "inert_key")
 
-    if rule.get("enum_dynamic") == "style":
-        styles = ctx.get("styles")
-        if styles is None:
-            if not ctx.get("style_warned"):
-                ctx["style_warned"] = True
-                rep.warn(path, "stylekit.STYLES 不可用（找不到 %s/stylekit.py），"
-                               "跳过 style 枚举校验——只提示，不判错" % str(HERE), "stylekit_missing")
-        else:
-            enum = ["auto"] + list(styles)
-    if enum and isinstance(val, str) and val not in enum:
-        near = _suggest(val, [e for e in enum if isinstance(e, str)])
-        hint = ("；是不是想写 %r？" % near) if near else ""
-        rep.err(path, "枚举错误：%r 不是可用值（可用：%s）%s"
-                % (val, " / ".join(str(e) for e in enum), hint), "bad_enum")
-        return
-
     if isinstance(val, (int, float)) and not isinstance(val, bool):
         if rule.get("positive") and val <= 0:
             rep.err(path, "必须大于 0（收到 %r；bpm 这类字段也可以写 \"auto\"）" % val, "bad_range")
@@ -571,6 +633,29 @@ def check_cross(script, script_path, rep, ctx):
                 "tail_map）。例如 %s: 1.4" % lid),
                 "inert_line_tail")
 
+    # ---- v0.9 场景语法：绘制器的容量上限（超了会被静默截断） ----
+    # 这是本项目最忌讳的一类坑：作者写对了、跑得通、但画面上少了几条，而没有任何提示。
+    # 容量由 assets/scenes.py 的实现决定（stats 取前 3 条、series 前 6 条、steps 前 5 条、
+    # sides 每侧前 3 条），改那边要同步改这里。
+    _CAP = (("stats", 3), ("series", 6), ("steps", 5))
+    for i, ln in enumerate(lines):
+        for fld, cap in _CAP:
+            v = ln.get(fld)
+            if isinstance(v, list) and len(v) > cap:
+                rep.warn("lines[%d].%s" % (i, fld),
+                         "%s 有 %d 条，但 %s 构图只画前 %d 条（其余不会出现在画面上）。"
+                         "要全画请拆成多段，或减到 %d 条以内"
+                         % (fld, len(v), fld, cap, cap), "scene_capacity")
+        sides = ln.get("sides")
+        if isinstance(sides, dict):
+            for side in ("left", "right"):
+                blk = sides.get(side)
+                its = blk.get("items") if isinstance(blk, dict) else None
+                if isinstance(its, list) and len(its) > 3:
+                    rep.warn("lines[%d].sides.%s.items" % (i, side),
+                             "sides.%s 有 %d 条，但左右对比构图每侧只画前 3 条"
+                             % (side, len(its)), "scene_capacity")
+
     # ---- v0.8 video 块：只支持 16:9 横屏 + 下采样输出 ----
     # **不要在这里重写一遍规则**：允许列表 / 宽高比 / 上采样拒绝的权威实现在
     # filmkit.video_plan()。以前这里是第二套手写判据，于是"1600x900"能过 filmcheck
@@ -716,19 +801,6 @@ def _fail(msg, as_json, code=2):
     raise SystemExit(code)
 
 
-def _load_styles():
-    """从 stylekit.STYLES 单向读取风格 id；拿不到返回 None（调用方降级成只 WARN）。"""
-    try:
-        if str(HERE) not in sys.path:
-            sys.path.insert(0, str(HERE))
-        import stylekit                                  # noqa: F401  （只读枚举，不复制）
-        # 优先用公开的 STYLE_IDS（8 套），没有就退回 STYLES 的键（含内部 legacy）
-        ids = list(getattr(stylekit, "STYLE_IDS", ()) or getattr(stylekit, "STYLES", {}).keys())
-        return ids or None
-    except Exception:                                    # noqa: BLE001
-        return None
-
-
 def _load_personas():
     """从 voicekit 单向读取 persona 名与 tone id；拿不到返回 (None, None) 降级成不查。
 
@@ -794,7 +866,7 @@ def main(argv=None):
 
     kind = _classify(data)
     rep = Report()
-    ctx = {"styles": _load_styles(), "style_warned": False, "timeline": None}
+    ctx = {"timeline": None}
     skipped = False
     if kind == "artifact":
         skipped = True
@@ -814,7 +886,6 @@ def main(argv=None):
         "errors": rep.errors,
         "warnings": rep.warnings,
         "counts": {"errors": len(rep.errors), "warnings": len(rep.warnings)},
-        "style_ids": ctx.get("styles"),
         "timeline": ctx.get("timeline"),
     }
 

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

@@ -612,40 +612,101 @@ def fit_sub_lines(text: str, max_lines=2, max_w=1560, size=46, weight="reg",
     return wrap_cn(text, f, max_w), f
 
 
+def subtitle_kwargs(plan):
+    """从已解析的计划里取字幕样式参数（v1.0.2）。
+
+    返回可直接 ``draw_subtitle(..., **kw)`` 的 dict；计划里没有 subtitle 时返回空 dict
+    （= 模块默认值 = 过去写死的行为，老项目逐像素不变）。
+
+    为什么放在 filmkit 而不是 render：**参考帧渲染路径**（qavmaf 的 _draw_ref_frame）
+    与主渲染路径必须用同一份字幕参数，否则同源的两帧字幕字号不同，VMAF 会被
+    系统性拉低（实测：dv 变的 46px 默认 vs 52px 设计，同源参考帧 VMAF 91.3，
+    换了正确参数后回到 96+）。一份实现放这里，两条路径都调它。
+    """
+    sub = plan.get("subtitle") if isinstance(plan, dict) else None
+    if not isinstance(sub, dict):
+        return {}
+    kw = {}
+    if sub.get("size") is not None:
+        kw["size"] = int(sub["size"])
+    if sub.get("y") is not None:
+        kw["y"] = int(sub["y"])
+    if sub.get("align") in ("center", "left"):
+        kw["align"] = sub["align"]
+    if sub.get("plate_alpha") is not None:
+        kw["plate_alpha"] = int(sub["plate_alpha"])
+    if sub.get("radius") is not None:
+        kw["radius"] = int(sub["radius"])
+    if sub.get("color") is not None:
+        kw["color"] = sub["color"]
+    if sub.get("max_lines") is not None:
+        kw["max_lines"] = int(sub["max_lines"])
+    if sub.get("family"):
+        kw["family"] = sub["family"]
+    return kw
+
 def draw_subtitle(img, text: str, alpha=1.0, size=46, y=None, band_w=None,
-                  theme=None, family=None, words=None):
+                  theme=None, family=None, words=None, align="center",
+                  plate_alpha=None, radius=10, color=None, max_lines=2):
     """烧字幕。v0.5.0 加 theme（stylekit 主题）与 family（字体族）；
-    theme=None 时与 v0.4 逐像素一致。v0.8 加 words（按词边界折行）。"""
+    theme=None 时与 v0.4 逐像素一致。v0.8 加 words（按词边界折行）。
+
+    v1.0.2 加 align / plate_alpha / radius / color / max_lines（全部可选，
+    默认值 = 过去写死的行为，所以老调用逐像素不变）。为什么加：字幕样式过去是
+    **模块常量**，任何两条片子的字幕带都一模一样 —— 这正是用户说的"大面积重复"。
+    现在这些参数由 design.json 的 visual.subtitle 决定（见 designkit.subtitle_of）。
+    """
     if not text or alpha <= 0.01:
         return img
     if band_w is None:
         band_w = SUB_BAND[2] - SUB_BAND[0]
     th = theme if isinstance(theme, dict) else None
     fam = family or (th or {}).get("family") or "sans"
-    lines, f = fit_sub_lines(text, max_w=band_w, size=size, family=fam, words=words)
-    lines = lines[:2]                       # 硬约束：最多两行
+    try:
+        max_lines = max(1, min(3, int(max_lines)))
+    except (TypeError, ValueError):
+        max_lines = 2
+    lines, f = fit_sub_lines(text, max_lines=max_lines, max_w=band_w, size=size,
+                             family=fam, words=words)
+    lines = lines[:max_lines]
     lh = int(f.size * 1.32)
-    cx = (SUB_BAND[0] + SUB_BAND[2]) // 2
     total_h = lh * len(lines)
+    if align == "left":
+        cx = SUB_BAND[0] + 34
+    else:
+        cx = (SUB_BAND[0] + SUB_BAND[2]) // 2
     base_y = SUB_BAND[3] - total_h if y is None else y
     base_y = max(SUB_BAND[1], min(base_y, SUB_BAND[3] - total_h))
     d = ImageDraw.Draw(img, "RGBA")
     widest = max(text_w(l, f) for l in lines)
-    bx0 = cx - widest / 2 - 34
-    bx1 = cx + widest / 2 + 34
+    if align == "left":
+        bx0 = cx - 34
+        bx1 = cx + widest + 34
+    else:
+        bx0 = cx - widest / 2 - 34
+        bx1 = cx + widest / 2 + 34
     by0 = base_y - 16
     by1 = base_y + total_h + 16
+    if color is not None:
+        ink_rgb = tuple(int(x) for x in color)[:3]
+    elif th is None:
+        ink_rgb = (245, 248, 252)
+    else:
+        ink_rgb = tuple(th["ink"])
+    ink = tuple(ink_rgb) + (int(255 * alpha),)
     if th is None:
-        plate = (0, 0, 0, int(150 * alpha))
-        ink = (245, 248, 252, int(255 * alpha))
+        _pa = 150 if plate_alpha is None else int(plate_alpha)
+        plate = (0, 0, 0, int(_pa * alpha))
     else:
         # 浅色主题不能"黑底白字"：背板取 bg2 半透，字取 ink
-        plate = tuple(th["bg2"]) + (int(170 * alpha),)
-        ink = tuple(th["ink"]) + (int(255 * alpha),)
-    d.rounded_rectangle([bx0, by0, bx1, by1], radius=10, fill=plate)
+        _pa = 170 if plate_alpha is None else int(plate_alpha)
+        plate = tuple(th["bg2"]) + (int(_pa * alpha),)
+    if plate[3] > 0:
+        d.rounded_rectangle([bx0, by0, bx1, by1], radius=int(radius), fill=plate)
     for i, ln in enumerate(lines):
         lw = text_w(ln, f)
-        d.text((cx - lw / 2, base_y + i * lh), ln, font=f, fill=ink)
+        x = (cx - 34 + 34) if align == "left" else (cx - lw / 2)
+        d.text((x, base_y + i * lh), ln, font=f, fill=ink)
     return img
 
 
@@ -691,7 +752,7 @@ def wav_write(path, samples, sr=SR, channels=None):
 def wav_read(path):
     """读 PCM WAV（16 / 24 / 32-bit），返回 float32 数组：单声道 (n,) / 立体声 (n,2)。
 
-    v0.3.0 起支持 24-bit：scorekit 落盘默认 PCM_24（多 8 dB 动态余量），
+    v0.3.0 起支持 24-bit：musicgen / scorekit 落盘都用 PCM_24（多 8 dB 动态余量），
     而 v0.2 的 wav_write 只写 16-bit。读取端必须两种都吃。
     """
     with wave.open(str(path), "rb") as w:
@@ -947,7 +1008,7 @@ def cue_time(at, scenes=None, total=None):
 
 
 def scenes_anchors(scenes):
-    """给 scorekit 分段用的锚点：[{id, kind, start, end}]。"""
+    """给配乐引擎分段用的锚点：[{id, kind, start, end}]。"""
     return [dict(id=s.get("id"), kind=s.get("kind") or "body",
                  start=float(s["start"]), end=float(s["end"])) for s in scenes]
 
@@ -1434,7 +1495,7 @@ def music_plan(script, has_music_file: bool = False):
     现在 score 与 audio 两个 stage 都用这一份判定，口径不会再打架。
 
     plan 取值：
-      score         scorekit 程序化配乐（work/music.wav）
+      score         现场编排配乐（musicgen -> work/music.wav）；scorekit 仅剩 legacy 原语
       file          外部提供 / 上一轮留下的 work/music.wav
       bed           v0.2 和弦床（music.chords）
       off           明确不要配乐（mode=off/none 或 music.enabled=false）
@@ -1448,8 +1509,21 @@ def music_plan(script, has_music_file: bool = False):
     """
     mus = script.get("music") or {}
     raw = str(mus.get("mode") or "").strip().lower()
-    # v0.5.0：bpm 可以是 "auto"（由 stylekit 按风格梯度和内容指纹决定）。
-    # 这里只判断"有没有 bpm 这个概念"，具体数值由 st_score 解析后传入 scorekit。
+    # v1.0.1 修：设计路径的配乐参数在 script["_style"]["music"] 里（designkit 生成），
+    # 而 film.json 顶层通常**没有** music 块。早先只看顶层，于是"有设计但没写 music"
+    # 被判成 none（本片无配乐）—— 实测设计里 bpm=122/mood=driving，配乐却整段没出。
+    # 现在顶层与设计计划合并：显式写 music 的字段优先（用户能覆盖设计），没写的用设计值。
+    plan_mus = ((script.get("_style") or {}).get("music") or {})
+    if plan_mus:
+        merged = dict(plan_mus)
+        merged.update({k: v for k, v in mus.items() if v is not None})
+        mus = merged
+        if not raw:
+            raw = str(mus.get("mode") or "params").strip().lower()
+            if raw == "params":
+                raw = ""            # params == 默认"按参数现场生成"
+    # v0.5.0：bpm 可以是 "auto"（由风格梯度和内容指纹决定）。
+    # 这里只判断"有没有 bpm 这个概念"，具体数值由 st_score 传给配乐引擎。
     bpm = mus.get("bpm", script.get("bpm"))
     if raw == "auto":
         raw = ""
@@ -1466,14 +1540,14 @@ def music_plan(script, has_music_file: bool = False):
                                 "（把外部配乐拷成 work/music.wav，或删掉 mode=file）")
     if raw in ("score", "programmatic"):
         if bpm in (None, ""):
-            return "missing-bpm", "music.mode=score 但没有 bpm（scorekit 需要 bpm）"
-        return "score", "music.mode=score：scorekit 程序化配乐 bpm=%s" % bpm
+            return "missing-bpm", "music.mode=score 但没有 bpm（配乐引擎需要 bpm）"
+        return "score", "music.mode=score：现场编排配乐 bpm=%s" % bpm
     if raw:
         return "unknown-mode", ("music.mode=%r 不认识（可用：score / bed / file / off，"
                                 "或不写 mode 走兼容链）" % mus.get("mode"))
     # 缺省（v0.2 兼容链）
     if bpm not in (None, ""):
-        return "score", "缺省配乐：有 bpm=%s，用 scorekit 程序化配乐" % bpm
+        return "score", "缺省配乐：有 bpm=%s，现场编排（musicgen）" % bpm
     if has_music_file:
         return "file", "缺省配乐：沿用已有 work/music.wav（外部提供的配乐）"
     if mus.get("chords"):
@@ -1498,63 +1572,42 @@ def resolve_theme(script, scene=None):
     优先级：scene["theme"]（同明暗族才允许） > script 里解析出的风格主题。
     stylekit 不在时退回内置 tech-deep（只为了让老工作目录少一个文件也能跑）。
     """
-    try:
-        ST = _stylekit()
-        plan = script.get("_style")
-        if not isinstance(plan, dict):
-            plan = ST.resolve_script_style(script)
-        th = dict(ST.THEMES[plan["theme_id"]])
-        sid = (scene or {}).get("theme")
-        if sid and sid in ST.THEMES:
-            alt = ST.THEMES[sid]
-            if ST.family_compatible(th, alt):
-                th = dict(alt)
-        return th
-    except Exception:                                       # noqa: BLE001
-        return _FALLBACK_THEME
+    plan = script.get("_style") if isinstance(script, dict) else None
+    if not isinstance(plan, dict):
+        raise ValueError(
+            "resolve_theme：剧本里没有已解析的设计计划（script[_style]）。\n"
+            "  v1.0.1 起本技能不提供任何内置主题：每一版外观都必须现场生成并由人确认。\n"
+            "  请用 python propose.py --brief \"题材\" --script <film.json> --n 3，"
+            "\n  再 --confirm --candidate A 冻结设计；渲染侧走 render.resolve_style(script, work)。")
+    # 设计路径的计划自带完整主题；v1.0.1 起没有内置主题表可回查。
+    th = plan.get("theme")
+    if not isinstance(th, dict) or not th:
+        raise ValueError("resolve_theme：计划里没有 theme 字段（plan 来自 %r）——"
+                         "它不是 designkit/render 产出的计划，取不到主题"
+                         % (plan.get("generator") or plan.get("style"),))
+    # scene["theme"] 覆盖（"这一段换一套命名主题"）已随内置主题表一起消失：
+    # 可选装饰字段，静默忽略（它不是契约字段，为此报错会让老项目无法渲染）。
+    return dict(th)
 
 
 def style_plan(script):
-    """解析剧本的风格计划（含 legacy 判定）。stylekit 缺失时返回 legacy 计划。"""
-    try:
-        ST = _stylekit()
-        plan = script.get("_style")
-        return plan if isinstance(plan, dict) else ST.resolve_script_style(script)
-    except Exception:                                       # noqa: BLE001
-        return {"legacy": True, "style": "legacy", "theme_id": "tech-deep",
-                "music": {"style": "legacy", "bpm": script.get("bpm") or 120.0,
-                          "key": (script.get("music") or {}).get("key") or "Dm",
-                          "mood": "steady",
-                          "seed_effective": int((script.get("music") or {}).get("seed", 7) or 7)},
-                "voice": {"map": {}, "policy": {"auto": False, "jitter": 0.0, "max_distinct": 2}},
-                "pacing": {"lead": float(script.get("lead", 0.62)),
-                           "tail": float(script.get("tail", 0.92)),
-                           "min_dur": float(script.get("min_dur", 3.2)),
-                           "hold": float(script.get("hold", 0.0)),
-                           "item_stagger": 0.32}}
-
-
-# v0.4 的深蓝橙，作为"没装 stylekit 也能出片"的兜底（与 assets/scenes.py 的老 THEME 同值）
-_FALLBACK_THEME = {
-    "id": "tech-deep", "label": "科技深蓝", "keywords": (),
-    "bg": (7, 14, 26), "bg2": (17, 33, 54), "surface": (26, 42, 64),
-    "ink": (240, 245, 252), "muted": (150, 174, 200), "dim": (120, 142, 168),
-    "accent": (243, 132, 60), "accent2": (86, 170, 232),
-    "good": (108, 178, 110), "bad": (226, 96, 92), "rule": (255, 255, 255),
-    "vignette": 0.40, "vignette_tint": (0, 0, 0), "grain": 5.0, "grain_freq": 0.31,
-    "texture": "dots", "texture_alpha": 0.045,
-    "family": "sans",
-    "scale": {"display": (96, "bold"), "heading": (64, "bold"), "sub": (38, "light"),
-              "body": (34, "reg"), "kicker": (28, "bold"), "chip": (27, "reg"),
-              "brand": (23, "reg")},
-    "line_gap": 1.30, "tracking": 0.0,
-    "layout": "left-stack",
-    "card": {"radius": 14, "fill_a": 16, "outline_a": 28, "pad": 34, "h": 96, "gap": 118},
-    "safe_bias": 0,
-    "ease": "out3", "entrance_dx": 0, "entrance_dy": 26, "push": 0.04,
-    "item_stagger": 0.32, "transition": "black", "hud": "chip-left",
-    "qa": {"luma_max": 0.030, "flicker_thresh": 6.0, "dark": True},
-}
+    """取已解析的风格计划；**不做 legacy 回落**（v1.0.2 起 fail-closed）。
+
+    以前这里 except Exception 后返回一份手写的 legacy 计划（120BPM / Dm / 固定节奏），
+    等于把"没有设计"伪装成"老项目正常出片"，也是模板残留（v1.0.1 原则：不提供任何模板）。
+    现在只认一种情况：script["_style"] 已经是计划（render.resolve_style 挂好的）；
+    否则明确报错并给两步迁移指引。
+    """
+    plan = script.get("_style") if isinstance(script, dict) else None
+    if isinstance(plan, dict):
+        return plan
+    raise ValueError(
+        "style_plan：剧本里没有已解析的风格计划（script[_style]）。\n"
+        "  v1.0.1 起没有「不写设计就走老外观」这条兼容路径了。\n"
+        "  正确用法：\n"
+        "    python propose.py --brief \"题材\" --script <film.json> --n 3\n"
+        "    python propose.py --confirm --candidate A\n"
+        "    python render.py --script <film.json> --stage all")
 
 
 # ---------------------------------------------------------------- 程序化音源
@@ -2373,14 +2426,24 @@ def loudness(path):
     return out
 
 
-def detect_black(path, dur=0.4, head=1.2, tail=None):
+def detect_black(path, dur=0.4, head=1.2, tail=None, pix_th=None):
     """长黑帧检测。head/tail 秒内是刻意的淡入淡出，不算问题。
 
     返回 None 表示**检测根本没跑成**（ffmpeg 打不开文件 / blackdetect 失败）。
     这一点必须可区分：旧实现把失败也返回 0，qa 门禁于是把"没查"记成"0 段黑帧 = 通过"。
+
+    pix_th：多"暗"算黑（0..1）。**必须跟着主题底色走**，否则暗色主题会被整片误判。
+    blackdetect 的默认 pix_th 是 0.10，意思是"亮度低于 10% 的像素算黑"；
+    而本项目的近黑金主题底色是 (8,8,10) ≈ 0.031 —— 全片 98% 的像素都在"黑"的阈值以下，
+    于是 blackdetect 把整段正常画面报成"4 段长黑帧"。实测：真实亮度全程 0.05–0.07，
+    一段真正的黑屏都没有，但门禁报了 4 段。
     """
+    if pix_th is None:
+        # 缺省仍取 ffmpeg 自带值，保证老调用方行为不变
+        pix_th = 0.10
+    vf = "blackdetect=d=%s:pic_th=0.98:pix_th=%.4f" % (dur, float(pix_th))
     p = _run([FFMPEG, "-hide_banner", "-nostats", "-i", str(path), "-vf",
-              "blackdetect=d=%s:pic_th=0.98" % dur, "-f", "null", "-"])
+              vf, "-f", "null", "-"])
     if p.returncode != 0:
         return None
     total = media_dur(path)
@@ -2853,7 +2916,19 @@ def qa_report(path, expect_frames=None, ref_png=None, ref_sec=None, ref_img=None
             warns.append("真峰 %.1f dBTP 余量不足（AAC 编码后可能更高）" % lo["TP"])
     else:
         warns.append("未能测到真峰（ebur128 解析失败），责任门禁缺一项")
-    nb = detect_black(path)
+    # 黑帧阈值跟着主题底色走（见 detect_black 的注释）：底色亮度越低，阈值要越低，
+    # 否则"深色主题的正常画面"会被当成整片黑屏。取底色亮度的 0.45 倍，
+    # 下限 0.012（比纯黑略高，仍能抓到真黑），上限 0.10（ffmpeg 默认）。
+    _pix_th = 0.10
+    try:
+        import stylekit as _ST
+        _th = (theme or {}).get("bg") if isinstance(theme, dict) else None
+        if isinstance(_th, (list, tuple)) and len(_th) >= 3:
+            _luma = _ST.luminance(tuple(int(x) for x in _th[:3]))
+            _pix_th = max(0.012, min(0.10, _luma * 0.45))
+    except Exception:                                       # noqa: BLE001
+        _pix_th = 0.10
+    nb = detect_black(path, pix_th=_pix_th)
     if nb is None:
         warns.append("长黑帧检测未执行（ffmpeg blackdetect 失败），本项不能当作通过")
     elif nb > 0: