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

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

@@ -8,7 +8,7 @@
     tts     逐句合成旁白 + 实测时长（带输入校验的缓存；按声线计划换人换语气）
     layout  由实测时长排时间轴 -> timeline.json / sub.srt / sub.ass（含停留窗口 hold）
     cues    画面提示点 -> work/cues.json（web 引擎从页面导出，pil 引擎从 film.json 生成）
-    score   程序化配乐 -> work/music.wav（scorekit；无则跳过）
+    score   参数化配乐 -> work/music.wav（musicgen；缺了直接报错，不再回退模板引擎）
     sfx     按提示点合成音效轨 -> work/sfx.wav（sfxkit；无则跳过）
     audio   三总线混音（旁白 + 配乐 + 音效，音效响起时配乐让位）-> audio.wav
     frames  逐帧渲染 -> silent.mp4（--engine pil|web；分块并行、断点续跑）
@@ -68,7 +68,7 @@ def _setup_stdio():
 
     只在"非交互"时切（isatty=False）：Windows 下 python render.py ... | tee out.log
     的 stdout 默认是 GBK 代码页，日志里中文全是乱码；真实控制台保持系统编码，
-    交互运行时中文照样正常。与 scorekit / webengine 的入口处理保持同一口径。
+    交互运行时中文照样正常。与 musicgen / webengine 的入口处理保持同一口径。
     """
     for stream in (sys.stdout, sys.stderr):
         try:
@@ -147,8 +147,11 @@ def _web_entry(script):
     if not os.path.exists(entry):
         raise SystemExit(
             "[缺少 web 页面] %s\n"
-            "  把 <SKILL_DIR>/assets/web/ 整个目录拷到项目里（cp -r <SKILL_DIR>/assets/web ./web），"
-            "或在 film.json 里写 web.entry 指向你自己的页面。" % entry)
+            "  web 引擎需要**你自己的页面**（本技能不提供模板）。\n"
+            "  PIL 路线不需要页面，零拷贝就能出片（--engine pil）。\n"
+            "  想先跑通 web 链路可拷示例页：\n"
+            "    cp -r <SKILL_DIR>/assets/web ./web   # 示例页只有 3 段占位场景，不是出片模板\n"
+            "  或在 film.json 里写 web.entry 指向你自己的页面。" % entry)
     return entry
 
 
@@ -296,53 +299,131 @@ def _stylekit():
                          "（skills/video-studio/scripts/stylekit.py）：%s" % e)
 
 
+def _design_path(work):
+    return os.path.join(str(work), "design.json") if work else ""
+
+
+def _plan_from_design(script, work, verbose=True):
+    """v1.0：如果 work/design.json 存在（用户已确认提案），**以它为准**解析计划。
+
+    D3 之后这是唯一主路径：design.json 是"这一版长什么样"的冻结点，剧本只提供台词。
+    返回 None 表示没有 design（调用方回落到 stylekit 的旧解析，P3 会删掉那条路）。
+    """
+    direct = script.get("design")
+    design = None
+    if isinstance(direct, dict):
+        design = direct
+    else:
+        p = _design_path(work)
+        if p and os.path.exists(p):
+            try:
+                with open(p, encoding="utf-8") as fh:
+                    design = json.load(fh)
+            except (OSError, json.JSONDecodeError) as e:
+                raise SystemExit("[design] %s 读不出来：%s（重新 propose.py --confirm 一次）"
+                                 % (p, e)) from e
+    if not isinstance(design, dict):
+        return None
+    try:
+        import designkit as DK
+    except ImportError as e:
+        raise SystemExit("[design] 缺少 designkit.py（%s）——design.json 需要它解析成计划" % e) from e
+    # 骨架版/半成品 designkit 会 import 成功但接口没实现：那种情况必须给一句人话，
+    # 不能让 AttributeError 的 traceback 冒充"渲染器坏了"（v0.9 之前这种误报踩过多次）。
+    missing = [n for n in ("validate_design", "design_to_plan")
+               if not callable(getattr(DK, n, None))]
+    if missing:
+        raise SystemExit("[design] designkit.py 不完整：缺 %s（这个文件还没实现完）"
+                         % "、".join(missing))
+    bad = DK.validate_design(design)
+    if bad:
+        raise SystemExit("[设计体检失败] %s\n  - %s"
+                         % (design.get("id") or "(无 id)", "\n  - ".join(bad)))
+    plan = DK.design_to_plan(design)
+    _apply_audio_overrides(script, plan)
+    if verbose:
+        print("   设计: %s（%s）" % (plan.get("style"), (design.get("pitch") or "")[:60]))
+    return plan
+
+
+def _apply_audio_overrides(script, plan):
+    """把 design.audio 里的音量/音效参数填进 script 的 music/sfx **缺省位**（v1.0.2）。
+
+    为什么需要：design.json 里 audio.music.gain_db / duck_db 与 audio.sfx.enabled /
+    density / gain_db 一直被 validate_design 接受、却从来没有被任何渲染代码读过——
+    用户改了它们，成片一模一样（audit 实测：enabled=false 仍出 8 条音效）。
+
+    优先级（明确且可预期）：**film.json 显式写了的 > design 的值 > 模块内置默认**。
+    只填缺省位，绝不覆盖剧本里的显式写法——用户手里的 film.json 永远是最终裁决权。
+    """
+    ov = plan.get("audio_overrides") if isinstance(plan, dict) else None
+    if not isinstance(ov, dict):
+        return
+    mus_ov = ov.get("music") if isinstance(ov.get("music"), dict) else {}
+    sfx_ov = ov.get("sfx") if isinstance(ov.get("sfx"), dict) else {}
+    mus = script.get("music")
+    if mus_ov:
+        if not isinstance(mus, dict):
+            mus = {}
+            script["music"] = mus
+        for k, v in mus_ov.items():
+            mus.setdefault(k, v)
+    sfx = script.get("sfx")
+    if sfx_ov:
+        if not isinstance(sfx, dict):
+            sfx = {}
+            script["sfx"] = sfx
+        for k, v in sfx_ov.items():
+            sfx.setdefault(k, v)
+
+
 def resolve_style(script, work=None, verbose=True):
     """解析风格计划并挂到 script["_style"] 上（同一进程内各 stage 共享）。
 
+    优先级（v1.0）：
+      1. script["_style"] 已存在（同进程内各 stage 复用）
+      2. work/design.json（用户已确认的提案）—— 这是正式主路径
+      3. stylekit 旧解析（P3 之后会删除；现在保留是为了让未迁移的项目还能跑）
+
     纯函数 + 落盘 work/style.json（审计用：用户能看到"为什么是这套风格"）。
     """
     if isinstance(script.get("_style"), dict):
         return script["_style"]
-    ST = _stylekit()
-    plan = ST.resolve_script_style(script)
-    # 主题体检：坏主题现在拦，不要等渲完 300 帧。
-    # v0.7.2 修：以前只体检**基础主题**（ST.THEMES[theme_id]），而 scenes 实际用的是
-    # plan["theme"]（= 基础主题 + film.json 的 visual.theme_overrides）。于是用 overrides
-    # 把 ink/bg 调成低对比度时，体检照样 PASS，渲完才发现字幕看不清。
-    # 实测：overrides ink=[30,30,30] / bg=[10,10,10] -> 基础主题 lint 为空，
-    #       最终主题 lint = ['ink 与背景对比度 1.09 < 7.0']。
-    bad = ST.theme_lint(plan.get("theme") or ST.THEMES[plan["theme_id"]])
-    if bad:
-        raise SystemExit("[主题体检失败] %s：%s" % (plan["theme_id"], "；".join(bad)))
-    # v0.9：结构签名（视觉语言包）随计划一起解析，并同样在 --stage style 就体检。
-    # 为什么不能等渲染：装饰母题名写错/转场时长越界，都要等渲到第 300 帧才发现，
-    # 而这两类错误恰恰会让整片观感崩掉（转场 1 秒 = 每段都在"糊过去"）。
-    try:
-        plan["language"] = ST.visual_language(plan["style"])
-        vbad = ST.visual_lint(plan["style"])
-    except AttributeError:
-        # 老 stylekit（没有 VISUAL_LANGUAGES）-> 不阻塞渲染，scenes.py 会退到默认语言
-        plan["language"] = None
-        vbad = []
-    if vbad:
-        raise SystemExit("[视觉语言体检失败] %s：%s" % (plan["style"], "；".join(vbad)))
-    script["_style"] = plan
-    if work and verbose:
-        path = os.path.join(work, "style.json")
-        try:
-            os.makedirs(work, exist_ok=True)
-            json.dump(plan, open(path, "w", encoding="utf-8"), ensure_ascii=False, indent=1)
-        except Exception as e:                              # noqa: BLE001
-            print("   [WARN] style.json 落盘失败：%s" % e)
-    return plan
-
-
-def _theme_for(script):
-    """返回当前片的主题字典；legacy 返回 None（= v0.4 的硬编码外观，逐字节兼容）。"""
+    plan = _plan_from_design(script, work, verbose=verbose)
+    if plan is not None:
+        script["_style"] = plan
+        if work and verbose:
+            try:
+                os.makedirs(work, exist_ok=True)
+                with open(os.path.join(work, "style.json"), "w", encoding="utf-8") as fh:
+                    json.dump(plan, fh, ensure_ascii=False, indent=1)
+            except Exception as e:                          # noqa: BLE001
+                print("   [WARN] style.json 落盘失败：%s" % e)
+        return plan
+    # v1.0.1：**没有第三优先级了**。以前这里会回落到 stylekit 的"按关键词自动选风格"，
+    # 那是模板库的核心；删掉模板后这条路径没有意义，必须明确报错。
+    raise SystemExit(
+        "[style] 找不到设计（work/design.json）：\n"
+        "  v1.0.1 起本技能不提供任何内置风格，每一版外观都必须现场生成并由人确认。\n"
+        "  正确做法：\n"
+        "    1) python propose.py --brief \"题材/要求\" --script film.json   # 出 3 个方案\n"
+        "    2) python propose.py --confirm --candidate A                   # 冻结设计\n"
+        "    3) python render.py --script film.json --stage all             # 出片\n"
+        "  （work=%r）" % (work,))
+
+
+def _theme_for(script, work=None):
+    """返回当前片的主题字典；legacy 返回 None（= v0.4 的硬编码外观，逐字节兼容）。
+
+    work **必须传**：design 路径的身份在 work/design.json 里。v1.0.1 之前不传会回落到
+    stylekit 的 auto 分支（已删除），现在不传就直接 SystemExit —— 但"传错 work"仍然值得防：
+    work 指到别的目录时会读到**另一份** design.json，参考帧与成片不同源
+    （历史实测：--stage qa 单独跑 VMAF 1.07，全部内联跑 97.15）。
+    """
     plan = script.get("_style") if isinstance(script.get("_style"), dict) else None
     if plan is not None and plan.get("legacy"):
         return None
-    plan = resolve_style(script)
+    plan = resolve_style(script, work)
     if plan.get("legacy"):
         return None
     # plan["theme"] 是 stylekit 合并过 film.json 的 visual.theme_overrides 之后的最终主题，
@@ -353,7 +434,22 @@ def _theme_for(script):
     th = plan.get("theme")
     if isinstance(th, dict):
         return th
-    return _stylekit().THEMES[plan["theme_id"]]
+    # v1.0：**先看 plan["theme"]**（designkit 生成的计划自带完整 35 字段主题），
+    # 只有老计划（stylekit 解析、没有 theme 字段）才回查内置表。
+    # 早先无条件 THEMES[plan["theme_id"]]，于是设计路径的 theme_id（如 "a-44957fb5"）
+    # 在表里查不到 -> KeyError，整条出片链路在 layout 阶段崩掉。
+    th = plan.get("theme")
+    if isinstance(th, dict) and th:
+        return th
+    # v1.0.1：内置主题表已删除，没有 theme 计划就是"这份 script 没走过 design/propose"。
+    # 明确报错并给迁移指引，不静默回落（静默回落 = 用一套不存在的默认外观出片）。
+    raise SystemExit(
+        "[style] 这份剧本没有可用的主题：\n"
+        "  计划里缺 theme 字段，而内置主题表已在本版删除。\n"
+        "  正确做法：python propose.py --brief \"题材\" --script film.json   # 出方案\n"
+        "            python propose.py --confirm --candidate A               # 冻结 design.json\n"
+        "            python render.py --script film.json --stage all\n"
+        "  （theme_id=%r）" % (plan.get("theme_id"),))
 
 
 def _print_style(plan):
@@ -377,8 +473,24 @@ def _print_style(plan):
               % (mf.get("kind"), tr.get("kind"), float(tr.get("dur") or 0.0),
                  float(ty.get("tracking") or 0.0), ty.get("number"),
                  float(bi.get("x") or 0.0), float(bi.get("y") or 0.0)))
+    # v1.0.2 修：这里以前无条件读 m["style"] —— 而 designkit 自 v1.0.1 起明确不再写
+    # 这个键（配乐风格表已删），于是公开命令 `--stage style` 100% KeyError: "style"。
+    # 现在按「参数化配乐」的真实身份打印：调式 + BPM + 调性 + mood。
+    _music_id = m.get("arranger") or m.get("style") or ("%s %gBPM" % (m.get("scale", "?"), m.get("bpm", 0)))
     print("        配乐: %s  BPM %g（%s）  调性 %s（%s）  mood %s"
-          % (m["style"], m["bpm"], m["bpm_source"], m["key"], m["key_source"], m["mood"]))
+          % (_music_id, m["bpm"], m["bpm_source"], m["key"], m["key_source"], m["mood"]))
+    _sub = plan.get("subtitle") if isinstance(plan.get("subtitle"), dict) else None
+    if _sub:
+        _y = _sub.get("y")
+        print("        字幕: %s %dpx 对齐=%s 背板α=%d 圆角=%d 最多%d行"
+              % ("y=%s" % _y if _y is not None else "底部安全区",
+                 int(_sub.get("size") or 46), _sub.get("align") or "center",
+                 int(_sub.get("plate_alpha") if _sub.get("plate_alpha") is not None else 170),
+                 int(_sub.get("radius") if _sub.get("radius") is not None else 10),
+                 int(_sub.get("max_lines") or 2)))
+    _cyc = plan.get("layout_cycle") or []
+    if len(_cyc) >= 2:
+        print("        版式轮换: %s（按章节轮换，防全片一张版式）" % " -> ".join(map(str, _cyc)))
     if v["map"]:
         print("        旁白: %s" % "  ".join("%s=%s" % kv for kv in sorted(v["map"].items())))
     p = plan["pacing"]
@@ -559,7 +671,9 @@ def st_layout(script, work, lines=None):
     json.dump(tl, open(os.path.join(work, "timeline.json"), "w", encoding="utf-8"),
               ensure_ascii=False, indent=1)
     n_srt = K.write_srt(tl["scenes"], os.path.join(work, "sub.srt"))
-    theme = (K._stylekit().THEMES[plan["theme_id"]] if not plan["legacy"] else None)
+    # 同上：设计计划自带 theme，不能假定 theme_id 一定在内置表里（见 _theme_for 的注释）
+    # v1.0.1：没有内置主题表了，theme 必须由计划自带（design 路径一定有）
+    theme = (plan.get("theme") if not plan["legacy"] else None)
     n_ass = K.write_ass(tl["scenes"], os.path.join(work, "sub.ass"), theme=theme)
     print("   总时长 %.2fs / %d 帧 / %d 段 / srt %d 条 / ass %d 条"
           % (tl["total"], tl["frames"], len(tl["scenes"]), n_srt, n_ass))
@@ -575,6 +689,26 @@ def st_layout(script, work, lines=None):
             print("     %-6s %-7s %r" % (lid, fld, chars))
     for s in tl["scenes"]:
         print("   %-8s %7.2f-%7.2f  %s" % (s["id"], s["start"], s["end"], s["text"][:40]))
+    # ---- 目标时长对账（v1.0.2）----
+    # brief 里写的「2 分钟 / 60 秒」过去只影响 design.structure.segments 与 target_sec，
+    # 而成片时长由 TTS 实测决定 —— 用户以为"我要求了时长"，实际拿到 23s。
+    # 不改时长（截断旁白或拉长留白都是坏做法），但**必须当场说出来差多少**，
+    # 并给出可执行的做法（加台词 / 调 hold / 减台词）。
+    target = (plan or {}).get("target_sec")
+    if target:
+        try:
+            target = float(target)
+        except (TypeError, ValueError):
+            target = None
+    if target and target > 0:
+        diff = float(tl["total"]) - target
+        pct = diff / target * 100.0
+        print("   目标时长 %.1fs / 实际 %.2fs（%+.1fs，%+.0f%%）"
+              % (target, tl["total"], diff, pct))
+        if abs(pct) > 15.0:
+            print("   [WARN] 与目标时长差超过 15%：成片时长由**实测旁白**决定，不收口就要改文案。"
+                  "\n          想变长：加台词或调大 film.json 的 hold / lead / tail；"
+                  "\n          想变短：删减台词（hold 只会加留白，不会缩短旁白）。")
     return tl
 
 
@@ -614,6 +748,15 @@ def st_cues(script, work, tl, engine="pil"):
     # scenes.py 里的 cues() 钩子：允许直接返回 [{at,type,...}] 或调用 bus.add(...)
     n_hook = 0
     mod = None
+    # v1.0.2 修：scenes.py 的 cues() 常要读主题/视觉语言（assets 版就调 resolve_script_style）。
+    # 单跑 `--stage cues` 时前面没有 stage 把 script["_style"] 挂好，钩子就会去解析"设计"
+    # 并直接 raise —— 公开命令 100% 崩，报错还指向"先去提案"（其实设计已确认）。
+    # 这里在调用钩子前解析一次（幂等，已挂 _style 时直接复用）。
+    if script.get("_scenes") and os.path.exists(script["_scenes"]) and not isinstance(script.get("_style"), dict):
+        try:
+            script["_style"] = resolve_style(script, work)
+        except SystemExit:
+            pass                      # 没设计：cues 阶段不因它失败，钩子里真需要会自己报错
     if script.get("_scenes") and os.path.exists(script["_scenes"]):
         try:
             mod = load_module(script["_scenes"])
@@ -683,7 +826,7 @@ def _st_cues_web(script, work):
             tl = json.load(open(tp, encoding="utf-8"))
     except Exception:                                       # noqa: BLE001
         tl = {}
-    style = _web_style_payload(we, script, tl)
+    style = _web_style_payload(we, script, tl, work)
     vp = (tl.get("video") or {})
     data = we.export_cues(entry, style=style,
                           width=int(vp.get("out_w") or K.W),
@@ -693,33 +836,19 @@ def _st_cues_web(script, work):
 
 
 # ---------------------------------------------------------------- 配乐 / 音效
-def st_score(script, work, tl):
-    """程序化配乐 -> work/music.wav（scorekit 不在就跳过，不阻断出片）。
+def _score_with_musicgen(script, work, tl, plan_s, mus):
+    """用参数化编排器出成片配乐（与 previewkit 的样音同一个引擎、同一组参数）。
 
-    配乐来源由 K.music_plan 统一判定（与 st_audio 共用同一份语义）：
-      - mode=off/none 或 enabled=false：不出配乐，也不删已存在的 music.wav
-        （删文件会误删"外部提供的配乐"，而 off 的语义只是"本片不要配乐"）；
-      - mode=bed：走 v0.2 和弦床，不生成 scorekit 产物；
-      - mode=file：外部 work/music.wav，原样交给 audio 阶段；
-      - 缺省：有 bpm 就生成，没有 bpm 沿用已有 music.wav / 和弦床（v0.2 兼容）。
+    为什么不复用 scorekit 那条路：scorekit 的 9 套 MUSIC_STYLES 是**风格表**，
+    而本技能 v1.0.1 起不再提供任何模板 —— 配乐必须由设计里的参数现场生成。
+    musicgen 的六个参数（progressions / motif / drums / voices / mood / sections）
+    全部参与事件展开，实测参数相关性 seed 0.16 / mood 0.32 / voices 0.22，无一是死旋钮。
     """
-    print("== Score")
-    mus = script.get("music") or {}
-    music_path = os.path.join(work, "music.wav")
-    plan, why = K.music_plan(script, has_music_file=os.path.exists(music_path))
-    print("   " + why)
-    if plan in ("off", "bed", "file", "none"):
-        return None
-    if plan in ("missing-file", "missing-bpm", "unknown-mode"):
-        raise SystemExit("[score] " + why)
-    sk = _try_module("scorekit")
-    if sk is None:
-        print("   [WARN] 没有 scorekit.py，跳过配乐（audio 阶段没有 music.wav，本片将无配乐）")
-        return None
-    anchors = K.scenes_anchors(tl["scenes"])
+    print("== Score（musicgen 参数化编排）")
+    mg = _try_module("musicgen")
+    mp = plan_s["music"]
     sections = mus.get("sections")
     if sections:
-        # film.json 允许用 id 表述分段起点，换成绝对秒
         fixed = []
         for s in sections:
             s2 = dict(s)
@@ -727,76 +856,104 @@ def st_score(script, work, tl):
                 s2["start"] = K.cue_time(s2.pop("at"), tl["scenes"])
             fixed.append(s2)
         sections = fixed
-    plan_s = resolve_style(script)
-    mp = plan_s["music"]
-    t0 = time.time()
-    style_arg = None if plan_s["legacy"] else str(mp.get("style") or plan_s["style"])
-    kwargs = dict(bpm=float(mp["bpm"]), key=str(mp["key"] or "Dm"), anchors=anchors,
-                  sections=sections, seed=int(mp["seed_effective"]))
-    # v0.7：内容指纹参与配乐结构变奏（和弦替换 / 动机级数 / 鼓型 ghost，见
-    # references/audio-variation.md §3.3）。只在非 legacy 时传——不传 fingerprint 的
-    # scorekit 认不出这个 kwarg，会走下面的 TypeError 回退链，照样出片只少变奏。
-    # legacy 必须不传：v0.4 的逐样本兼容是硬契约（selfcheck 20/26 条守着）。
-    fp_hex = ""
-    if not plan_s["legacy"]:
-        fp_hex = str((plan_s.get("fingerprint") or {}).get("full") or "")
-    kw_fp = dict(kwargs, fingerprint=fp_hex) if fp_hex else kwargs
-    # scorekit 0.5 起：style/mood + music_plan（一次把 bpm/key/mood/seed 全交出去，
-    # 免得两处默认值打架）+ pace（把过碎的段落并进前一段）。
-    # 旧 scorekit 没有这些 kwargs -> TypeError -> 自动退回老接口，不阻断出片。
-    # 四级回退：带指纹 -> 不带指纹 -> 只有 style/mood -> 最老的签名。
-    pace = {"min_dur": float(plan_s["pacing"]["min_dur"]),
-            "hold": float(plan_s["pacing"]["hold"])}
-    mood_arg = str(mp.get("mood") or "steady")
-    samples = report = None
-    # v0.7.2：多级签名兼容链以前对**任何** TypeError 都继续换签名试，最后统一报
-    # "不接受任何一种已知签名"。scorekit 内部真出 TypeError（例如某个参数是 None 被拿去做
-    # 算术）时，用户会照着"签名不兼容"的方向白找半天。这里区分两类：
-    #   - 报错文本含 "unexpected keyword argument" -> 确实是不认识这个参数，换签名重试；
-    #   - 其它 TypeError -> 是**内部**错误，带上签名与错误信息立刻报，别吞。
-    attempts = (
-        dict(style=style_arg, mood=mood_arg, music_plan=mp, pace=pace, **kw_fp),
-        dict(style=style_arg, mood=mood_arg, music_plan=mp, pace=pace, **kwargs),
-        dict(style=style_arg, mood=mood_arg, **kwargs),
-        dict(**kwargs),
+    kwargs = dict(
+        bpm=float(mp["bpm"]),
+        key=str(mp["key"] or "Dm"),
+        scale=str(mp.get("scale") or "minor"),
+        mood=str(mp.get("mood") or "steady"),
+        # seed_effective 是"内容指纹掺进去之后"的 32 位大数；musicgen 内部按
+        # sha1(seed) 派生，直接给大整数没问题，但统一夹到 2^31-1 内可以保证
+        # 与 scorekit 时代的取模口径一致（老 work/ 目录里的 score.json 能对上）。
+        seed=int(mp.get("seed_effective") or mp.get("seed") or 0) % (2 ** 31 - 1),
+        sections=sections,
     )
-    for attempt in attempts:
-        try:
-            samples, report = sk.render(float(tl["total"]), **attempt)
-            break
-        except TypeError as err:
-            if "unexpected keyword argument" in str(err):
-                continue
-            raise SystemExit(
-                "[score] scorekit.render() 内部报错（不是签名不兼容，别去改调用参数）：%s\n"
-                "  本次签名：%s\n  要看完整 traceback：set RENDER_DEBUG=1 后重跑"
-                % (err, ", ".join(sorted(k for k in attempt if k != "self")))
-            ) from err
-    if samples is None:
-        raise SystemExit("[score] scorekit.render() 不接受任何一种已知签名，无法出配乐"
-                         "（试过 %d 种：从最全的参数到最简）" % len(attempts))
-    if report and not plan_s["legacy"]:
-        print("   配乐风格: %s / mood %s / %s BPM / %s"
-              % (report.get("style") or style_arg, mp.get("mood"),
-                 report.get("bpm"), report.get("key")))
+    # 设计里显式给出的编排参数原样透传（progressions/motif/drums/voices/energy_curve）。
+    # 只在键存在时传：musicgen 对 None 与缺省的处理不同（缺省=自己按 seed 派生）。
+    for key in ("progressions", "motif", "drums", "voices", "energy_curve"):
+        if mp.get(key) is not None:
+            kwargs[key] = mp[key]
+    t0 = time.time()
+    try:
+        samples, report = mg.render(float(tl["total"]), **kwargs)
+    except Exception as e:                                  # noqa: BLE001
+        raise SystemExit(
+            "[score] musicgen.render() 失败：%s\n"
+            "  参数：bpm=%s key=%s scale=%s mood=%s seed=%s\n"
+            "  这是配乐生成的真错误（不是签名不兼容）——先把参数改对，别改成静默跳过。"
+            % (e, kwargs.get("bpm"), kwargs.get("key"), kwargs.get("scale"),
+               kwargs.get("mood"), kwargs.get("seed"))) from e
     out = os.path.join(work, "music.wav")
-    sk.save(out, samples)
+    mg.save(out, samples)
     if report:
         json.dump(report, open(os.path.join(work, "score.json"), "w", encoding="utf-8"),
                   ensure_ascii=False, indent=1)
+    print("   musicgen: %s %s / %s BPM / %s / mood %s / seed %s"
+          % (report.get("key_name") or report.get("key"), report.get("scale"),
+             report.get("bpm"), "", report.get("mood"), report.get("seed")))
     samples_read, _sr = K.wav_read(out)
     print("   music.wav %.2fs  峰值 %.3f  %.1fs" % (
         K.wav_dur(out), float(np.max(np.abs(samples_read))), time.time() - t0))
     return out
 
 
-def _sfx_seed_context(script):
+def st_score(script, work, tl):
+    """参数化配乐 -> work/music.wav（musicgen 现场编排，没有模板可回退）。
+
+    配乐来源由 K.music_plan 统一判定（与 st_audio 共用同一份语义）：
+      - mode=off/none 或 enabled=false：不出配乐，也不删已存在的 music.wav
+        （删文件会误删"外部提供的配乐"，而 off 的语义只是"本片不要配乐"）；
+      - mode=bed：走 v0.2 和弦床，不生成 musicgen 产物；
+      - mode=file：外部 work/music.wav，原样交给 audio 阶段；
+      - 缺省：有 bpm 就生成，没有 bpm 沿用已有 music.wav / 和弦床（v0.2 兼容）。
+
+    需要真的生成配乐时，**只有 musicgen 一条路**：legacy 计划或 musicgen.py 缺失都会
+    明确报错并给迁移指引，不再用 scorekit 的配乐模板兜底（v1.0.1 零模板）。
+    """
+    print("== Score")
+    mus = script.get("music") or {}
+    music_path = os.path.join(work, "music.wav")
+    plan, why = K.music_plan(script, has_music_file=os.path.exists(music_path))
+    print("   " + why)
+    if plan in ("off", "bed", "file", "none"):
+        return None
+    if plan in ("missing-file", "missing-bpm", "unknown-mode"):
+        raise SystemExit("[score] " + why)
+    # v1.0.1：**配乐只有 musicgen 一条路**（参数化编排器，没有风格表）。
+    #
+    # 为什么必须换：v1.0 里 previewkit 用 musicgen 出 12 秒样音，而 st_score 用 scorekit
+    # 出成片音乐 —— 两者是**两个不同的作曲器**，实测同一设计下相关系数 -0.0057（就是两首
+    # 不同的曲子）。用户看样音选方案，成片音乐完全不同，等于"确认"这个动作在音频上失效。
+    #
+    # v1.0.1 把 scorekit 的 9 套 MUSIC_STYLES 风格表整个删了（零模板），它的 render()
+    # 只剩 legacy 逐样本兼容路径。所以这里**不再有 scorekit 回退**：scorekit 一旦回来
+    # 当兜底，成片音乐就又变成一套固定模板，与"每条视频都不一样"直接冲突。
+    plan_s0 = resolve_style(script, work)
+    if plan_s0.get("legacy"):
+        raise SystemExit(
+            "[score] legacy 配乐路径已移除（v1.0.1 零模板）：\n"
+            "  scorekit 的 9 套配乐风格表已删除，legacy 回退会把成片配乐锁死成一套固定模板。\n"
+            "  正确做法（两步）：\n"
+            "    1) python propose.py --brief \"题材/要求\" --script film.json   # 出 3 个方案\n"
+            "    2) python propose.py --confirm --candidate A                   # 冻结 work/design.json\n"
+            "    3) python render.py --script film.json --stage score           # 用 musicgen 现场编排\n"
+            "  （想手写配乐参数：film.json 的 music.bpm / key / mood / sections 仍然有效）")
+    if _try_module("musicgen") is None:
+        raise SystemExit(
+            "[score] 找不到 musicgen.py，无法生成配乐：\n"
+            "  v1.0.1 起配乐只有参数化编排器一条路（scorekit 的风格模板已删除，不再兜底）。\n"
+            "  检查 <SKILL_DIR>/scripts/musicgen.py 是否被拷到工作目录——\n"
+            "  quickstart 的 cp <SKILL_DIR>/scripts/*.py . 会把它一起拷过来；\n"
+            "  只需要旁白/音效时把 film.json 的 music.mode 设为 off 或 file。")
+    return _score_with_musicgen(script, work, tl, plan_s0, mus)
+
+
+def _sfx_seed_context(script, work=None):
     """v0.7：算音效的内容派生上下文 (style, content_fp, key, enabled)。
 
     legacy（没写 style 字段）时返回全 None -> CueBus 走旧的 seed_base + i 路径，
     v0.4 及以前的片子逐样本不变。参考 references/audio-variation.md §3.2 / §4。
     """
-    plan = resolve_style(script)
+    plan = resolve_style(script, work)
     sfx_cfg = script.get("sfx") or {}
     want_content = bool(sfx_cfg.get("content_seed", True))
     if plan.get("legacy") or not want_content:
@@ -809,7 +966,7 @@ def _sfx_seed_context(script):
 def _duck_transition_sfx(samples, cues, scenes, sr=K.SR, depth_db=-3.0, window=2.2):
     """段落边界前的转场音效自动让位（v0.7，契约 §4）。
 
-    配乐在段落交界自己已经有一段过门（scorekit 的 swell / riser / sub_boom），
+    配乐在段落交界自己已经有一段过门（编排器写的 swell / riser / sub_boom），
     sfx 轨再在同一时刻放 whoosh / riser，同一频段叠两层就是"配乐和音效听起来像同一套"。
     做法：对位于 [边界-window, 边界] 内的转场类 cue，在它的时长内乘一个 dB 增益包络。
     只压转场类，不碰 impact / 提示音（那是"该响"的语义重音）。
@@ -877,7 +1034,7 @@ def st_sfx(script, work, tl):
         print("   cues.json 里没有提示点，跳过")
         return None
     sfx_cfg = script.get("sfx") or {}
-    style, content_fp, key = _sfx_seed_context(script)
+    style, content_fp, key = _sfx_seed_context(script, work)
     try:
         samples = bus.build_audio(total=tl["total"],
                                   base_db=sfx_cfg.get("base_db"),
@@ -919,7 +1076,7 @@ def _voice_track(tl, script):
 
 
 def _legacy_music(tl, script):
-    """v0.2 的和弦床（没有 scorekit / music.wav 时的兜底）。"""
+    """v0.2 的和弦床（没有 music.wav 时的兜底）。"""
     mus = script.get("music") or {}
     if not (mus.get("enabled", True) and mus.get("chords")):
         return None
@@ -969,7 +1126,7 @@ def st_audio(tl, work, script):
         print("   配乐: " + why)
     if plan == "score" and music is None:
         # 单独跑 --stage audio 时 score 还没跑过：不混配乐，但必须说清楚为什么
-        print("   [WARN] music 用 scorekit 但 %s 不存在（先跑 --stage score）；本次无配乐"
+        print("   [WARN] music.mode=score 但 %s 不存在（先跑 --stage score）；本次无配乐"
               % music_path)
 
     sfx = None
@@ -988,7 +1145,7 @@ def st_audio(tl, work, script):
         sfx = bus.bus[: int(round(total * K.SR))].copy()
         print("   音效: 旧版转场 whoosh（没有 cues.json）")
 
-    plan_s = resolve_style(script)
+    plan_s = resolve_style(script, work)
     # 风格化的 duck 深度：轻快/极简风格的配乐更"薄"，让位可以浅一点；
     # 电影/史诗要压得更狠。用户显式写 music.duck_db 时永远以用户为准。
     # v0.7：整体 +1 dB —— 旧值（2.0/2.5/3.0/4.5）下配乐只比音效低 1.5 dB、duck 仅 3 dB，
@@ -1071,6 +1228,29 @@ def _run_preflight(script, work, engine, tl=None, skip=False):
     return True
 
 
+# ---------------------------------------------------------------- 字幕样式（v1.0.2）
+_SUB_CACHE = {}
+
+
+def _sub_kw(script):
+    """从已解析的 plan 里取字幕参数（缓存按 script 对象身份，连续帧不重复解析）。
+
+    v1.0.2：字幕样式由 design.json 的 visual.subtitle 决定；参考帧渲染路径
+    （qavmaf._draw_ref_frame）必须调用同一个 filmkit.subtitle_kwargs(plan)，
+    否则两帧字幕参数不同会把同源好片的 VMAF 拉低。
+    """
+    key = id(script)
+    cached = _SUB_CACHE.get(key)
+    if cached is not None:
+        return cached
+    plan = script.get("_style") if isinstance(script.get("_style"), dict) else None
+    kw = K.subtitle_kwargs(plan)
+    if len(_SUB_CACHE) > 8:            # 批量渲染会跨很多 script：别无限长
+        _SUB_CACHE.clear()
+    _SUB_CACHE[key] = kw
+    return kw
+
+
 # ---------------------------------------------------------------- 渲染
 def _render_range(tl, mod, script, f0, f1, out_path, crf, preset, progress=True):
     """渲染 [f0, f1) 帧区间到 out_path。纯函数：同一帧号永远画出同一张图。"""
@@ -1096,7 +1276,8 @@ def _render_range(tl, mod, script, f0, f1, out_path, crf, preset, progress=True)
             _THEME_CACHE.update(k=id(script), th=th)
         _hold = script.get("sub_max_hold")
         frame = K.draw_subtitle(frame, K.sub_at(scenes, t, _hold), theme=th,
-                                words=K.sub_words_at(scenes, t, _hold))
+                                words=K.sub_words_at(scenes, t, _hold),
+                                **_sub_kw(script))
         fade = 1.0
         if t < 0.5:
             fade *= K.ease_out(t / 0.5)
@@ -1148,7 +1329,8 @@ def _seg_usable(path, frames):
 
 def _render_chunk_worker(args):
     """分块渲染工作单元（供 multiprocessing 调用；函数必须模块级可 pickle）。"""
-    (tl_path, scenes_path, script_path, f0, f1, out_path, crf, preset, part_path) = args
+    (tl_path, scenes_path, script_path, f0, f1, out_path, crf, preset, part_path) = args[:9]
+    work = args[9] if len(args) > 9 else ""
     tl = json.load(open(tl_path, encoding="utf-8"))
     script = json.load(open(script_path, encoding="utf-8"))
     script["_total"] = tl["total"]
@@ -1156,9 +1338,15 @@ def _render_chunk_worker(args):
     # scenes._bg() 拿 th["bg"] 当缓存键 -> TypeError: unhashable type: "list"，
     # 于是 --jobs >1 整条并行路径直接崩。计划是**纯函数**，这里按剧本重新解一次，
     # 既拿回元组，也保证子进程的主题与父进程逐字段一致。
+    #
+    # v1.0 修：重解时**必须带上 work**。design 路径的身份在 work/design.json 里，
+    # 不带 work 就只能走 stylekit 的 auto 分支 -> 画出一套完全不同的主题。
+    # 实测后果：--jobs 4 的成片是 tech-deep（偏蓝），而 --jobs 1 / QA 参考帧是
+    # 设计本身的近黑金；两者 MAE 0.059、VMAF 直接掉到 1.49。
+    # 这种"并行度不同就出不同片子"的 bug 最隐蔽——单线程跑一遍永远看不见。
     script.pop("_style", None)
     try:
-        script["_style"] = resolve_style(script, verbose=False)
+        script["_style"] = resolve_style(script, work or None, verbose=False)
     except Exception as e:                                  # noqa: BLE001
         print("   [WARN] 子进程重解风格失败，回退到快照里的 _style：%s" % e)
         script["_style"] = json.load(open(script_path, encoding="utf-8")).get("_style")
@@ -1179,7 +1367,7 @@ def st_frames(tl, work, scenes_mod, script, jobs=1, resume=True, engine="pil"):
     script["_total"] = tl["total"]           # 场景算全局进度条要用
     # 分块 worker 是 spawn 出来的新进程：主题必须随快照走，否则子进程算出的
     # _theme_for 与父进程不一致 -> 拼接处出现"半部片换了配色"。
-    script.setdefault("_style", resolve_style(script))
+    script.setdefault("_style", resolve_style(script, work))
     crf = int(script.get("crf", 18))
     preset = script.get("preset", "medium")
     total_frames = tl["frames"]
@@ -1256,7 +1444,8 @@ def st_frames(tl, work, scenes_mod, script, jobs=1, resume=True, engine="pil"):
             except OSError:
                 pass
         part = os.path.join(seg_dir, "_part_" + os.path.basename(seg))
-        todo.append((tl_path, scenes_path, script_path, f0, f1, seg, crf, preset, part))
+        todo.append((tl_path, scenes_path, script_path, f0, f1, seg, crf, preset, part,
+                     str(work)))
 
     # 旧计划留下的分块不会参与拼接，但会一直占盘：说出来，不静默
     stale = [n for n in os.listdir(seg_dir)
@@ -1298,15 +1487,18 @@ def st_frames(tl, work, scenes_mod, script, jobs=1, resume=True, engine="pil"):
     return silent
 
 
-def _web_style_payload(we, script, tl=None):
+def _web_style_payload(we, script, tl=None, work=None):
     """把风格包解析成 webengine 能吃的 __STYLE__ 载荷（v0.8）。
 
     style=None（legacy 项目 / 解析失败）时返回 None —— webengine 收到 None 连
     add_init_script 都不调，页面行为与 v0.7 逐字节一致（这是兼容性硬要求）。
     """
     try:
-        style_plan = resolve_style(script, verbose=False)
-    except Exception as e:                                  # noqa: BLE001
+        style_plan = resolve_style(script, work, verbose=False)
+    # 必须连 SystemExit 一起接：resolve_style 在"没有设计/主题不过体检"时用 SystemExit
+    # 报错（这是它向 CLI 报用法错误的方式），而 SystemExit 继承自 BaseException，
+    # 只 catch Exception 接不住 —— web 页面会拿着半截载荷渲染，或者整个进程直接退出。
+    except (Exception, SystemExit) as e:                    # noqa: BLE001
         print("   [WARN] web 风格包解析失败，页面用内置配色：%s" % e)
         return None
     if not style_plan or style_plan.get("legacy"):
@@ -1335,7 +1527,7 @@ def _st_frames_web(tl, work, script, jobs=1, resume=True):
     entry = _web_entry(script)
     silent = os.path.join(work, "silent.mp4")
     web = script.get("web") or {}
-    style = _web_style_payload(we, script, tl)
+    style = _web_style_payload(we, script, tl, work)
     vp = tl.get("video") or {}
     canvas_w = int(vp.get("out_w") or K.W)
     canvas_h = int(vp.get("out_h") or K.H)
@@ -1476,8 +1668,15 @@ def _qa_gates(lg, rep, deep, tl, work):
         ns = len(deep.get("sync") or [])
         judged = (deep.get("sync_info") or {}).get("judged")
         sync_note = ("同步查了 %s 条" % judged) if judged is not None else "同步未判（没写 visual_at）"
-        ok9 = nf == 0 and nb == 0 and ns == 0
-        detail9 = "闪烁 %d · 空窗 %d · 同步超差 %d（%s）" % (nf, nb, ns, sync_note)
+        # v1.0.2：门禁要按 **deep.errors** 判，而不是按 flicker 条数。
+        # qa_frames 会把"块内像素有增有减"（文字入场/母题动画/镜头缓推）的候选从
+        # flicker 降级进 warnings（见 FLICKER_AGREE_MIN），此时 flicker 仍非空但已不成问题；
+        # 按条数判会让降级形同虚设（零拷贝首片实测：降级后仍判 fail）。
+        # errors 里同时也包含空窗与同步超差，所以只看 errors 不会漏判。
+        n_err = len([e for e in (deep.get("errors") or []) if e])
+        ok9 = n_err == 0
+        detail9 = "问题 %d 条（闪烁候选 %d 已按符号一致度分档）· 空窗 %d · 同步超差 %d（%s）" % (
+            n_err, nf, nb, ns, sync_note)
         if ok9 and not judged and os.environ.get("QA_REQUIRE_SYNC"):
             # 与 SKILL 的 QA_REQUIRE_SYNC 同义：要求"真的查过"，而不是"没报错"
             lg.fail("G9", "帧级深检（闪烁/空窗/同步超差）",
@@ -1601,8 +1800,19 @@ def _qa_vmaf_gate(lg, film, tl, work, scenes_mod, script, mode=""):
             if cfg["ssim"].get(ckey) is not None:
                 kw[key] = float(cfg["ssim"][ckey])
     print("   [vmaf] 模式=%s（参考帧=场景函数实时渲染，不是成片抽帧）" % m)
+    # qavmaf 是独立解析（它拿不到本进程的 script["_style"]），所以这里把
+    # **冻结设计**一起传下去：参考帧必须与成片同源，否则 VMAF 会掉到个位数。
+    # 实测未修前：design 片被解析成 tech-deep，VMAF 1.50、同源抽查 MAE=0.0384。
+    script_for_vmaf = dict(script or {})
+    dpath = os.path.join(str(work), "design.json")
+    if "design" not in script_for_vmaf and os.path.exists(dpath):
+        try:
+            with open(dpath, encoding="utf-8") as fh:
+                script_for_vmaf["design"] = json.load(fh)
+        except (OSError, json.JSONDecodeError) as e:        # noqa: BLE001
+            print("   [WARN][vmaf] design.json 读不出来，参考帧可能不同源：%s" % e)
     try:
-        res = qv.report(film, tl, scenes_mod, script, mode=m,
+        res = qv.report(film, tl, scenes_mod, script_for_vmaf, mode=m,
                         out_json=os.path.join(str(work), "qa", "vmaf.json"), **kw)
     except Exception as e:                                  # noqa: BLE001
         lg.fail("G11", "全片 VMAF / SSIM 画质", "门禁自身失败：%s" % e)
@@ -1699,7 +1909,7 @@ def _qa_asr_gate(lg, film, work, script, tl=None, cfg=None):
 
 def st_qa(film, tl, work, scenes_mod=None, script=None, vmaf_mode=""):
     print("== QA")
-    th = _theme_for(script) if script is not None else None
+    th = _theme_for(script, work) if script is not None else None
     shots, refs = [], []             # refs: [(frac 下标, PIL 原图)]
     fracs = (0.08, 0.3, 0.55, 0.78)
     ref_script = dict(script) if script is not None else None
@@ -1724,7 +1934,8 @@ def st_qa(film, tl, work, scenes_mod=None, script=None, vmaf_mode=""):
                                            int(round(sec * tl["fps"])))
                 _hold = ref_script.get("sub_max_hold")
                 fr = K.draw_subtitle(fr, K.sub_at(tl["scenes"], sec, _hold), theme=th,
-                                     words=K.sub_words_at(tl["scenes"], sec, _hold))
+                                     words=K.sub_words_at(tl["scenes"], sec, _hold),
+                                     **_sub_kw(ref_script))
                 refs.append((k, fr))
             except Exception as e:      # noqa: BLE001
                 print("   [WARN] 参考帧渲染失败:", e)
@@ -1831,7 +2042,7 @@ def st_stills(tl, work, scenes_mod, script, specs=None):
     print("== Stills")
     script = dict(script)
     script["_total"] = tl["total"]
-    script.setdefault("_style", resolve_style(script))
+    script.setdefault("_style", resolve_style(script, work))
     outdir = os.path.join(work, "stills")
     os.makedirs(outdir, exist_ok=True)
     by_id = {s["id"]: s for s in tl["scenes"]}
@@ -1860,7 +2071,8 @@ def st_stills(tl, work, scenes_mod, script, specs=None):
         _hold = script.get("sub_max_hold")
         fr = K.draw_subtitle(fr, K.sub_at(tl["scenes"], tg, _hold),
                              theme=_theme_for(script),
-                             words=K.sub_words_at(tl["scenes"], tg, _hold))
+                             words=K.sub_words_at(tl["scenes"], tg, _hold),
+                             **_sub_kw(script))
         p = os.path.join(outdir, "%s_%05.1f.png" % (sid, float(lt)))
         fr.save(p)
         made.append(p)
@@ -2122,12 +2334,94 @@ def run_batch(a):
     return 0 if okn == len(results) else 1
 
 
+# ---------------------------------------------------------------- 提案闸（v1.0）
+def _proposal_gate(a):
+    """提案闸：frames 之前必须先有"已确认的设计"。
+
+    D3 之后本项目的主路径是"先提案、再出片"，所以这条闸是语义要求，不是可选装饰。
+    但它默认只警告（0 退出码），加 --require-proposal 才失败——原因只有一条：
+    --stage frames 是开发期高频命令（改一帧看一帧），硬拦会让调试变得没法用。
+
+    判定（propose.proposal_state 的几档）：
+      absent    -> 没有任何提案
+      draft     -> 有提案但没确认
+      confirmed -> 已确认且 design.json 指纹与确认时一致（唯一放行态）
+      stale     -> 确认过但 design.json 被改过（等于没确认）
+    """
+    try:
+        import propose as PP
+    except ImportError:
+        print("[proposal] 没有 propose.py，跳过提案检查（只警告）")
+        return True
+    try:
+        status, detail = PP.proposal_state(a.work)
+    except SystemExit as e:
+        status, detail = "broken", str(e)
+    except Exception as e:                                  # noqa: BLE001
+        status, detail = "broken", "%s: %s" % (type(e).__name__, e)
+
+    if status == "confirmed":
+        print("[proposal] OK  %s" % detail)
+        _LEDGER.ok("proposal", "提案已确认", detail)
+        return True
+
+    msg = "提案闸未通过（%s）：%s" % (status, detail)
+    print("[proposal] WARN  %s" % msg)
+    if status in ("absent", "draft"):
+        print("           先跑：python propose.py --brief \"题材/要求\" --script %s --n 3" % a.script)
+        print("           确认：python propose.py --confirm --candidate A")
+    if bool(getattr(a, "require_proposal", False)):
+        _LEDGER.fail("proposal", "提案未确认", msg)
+        print("\n[提案闸] --require-proposal 下这是失败项：先提案并确认，或去掉该参数")
+        return False
+    _LEDGER.skip("proposal", "提案闸", msg + "（默认只警告；--require-proposal 才失败）")
+    return True
+
+
+# ---------------------------------------------------------------- 场景模块定位
+def _builtin_scenes() -> str:
+    """本技能内置的场景绘制模块路径（装成插件后在包内 skills/video-studio/assets/scenes.py）。"""
+    cand = (Path(__file__).resolve().parent.parent / "assets" / "scenes.py")
+    return str(cand) if cand.exists() else ""
+
+
+def _resolve_scenes(scenes_arg, script_path) -> str:
+    """定位场景模块，按优先级：显式 --scenes > 剧本同目录 scenes.py > 技能内置 scenes.py。
+
+    为什么要这条回退链（v1.0.2）：旧流程要求用户把 assets/scenes.py 拷进工作目录，
+    即「提供一份模板代码」——与 v1.0.1「不提供任何模板」直接冲突，而且用户每部片都得
+    重拷一份 98KB 的绘制代码。现在把内置渲染器当**默认能力**：工作目录里没有 scenes.py
+    时直接用它出片；需要改画面再写自己的 scenes.py（显式指定或用同目录约定）。
+    """
+    if scenes_arg:
+        p = Path(scenes_arg).resolve()
+        if p.exists():
+            return str(p)
+        raise SystemExit(
+            "[缺少场景模块] --scenes 指向的 %s 不存在。\n"
+            "  不写 --scenes 时会自动用剧本同目录的 scenes.py 或技能内置渲染器；"
+
+            "只想用内置的就去掉 --scenes。" % p)
+    cand = Path(script_path).resolve().parent / "scenes.py"
+    if cand.exists():
+        return str(cand)
+    builtin = _builtin_scenes()
+    if builtin:
+        return builtin
+    raise SystemExit(
+        "[缺少场景模块] 找不到 %s，也找不到技能内置渲染器（%s）。\n"
+        "  装成插件时内置渲染器应在 <包>/skills/video-studio/assets/scenes.py；"
+
+        "请检查插件包是否完整，或显式传 --scenes 指向你自己的 scenes.py。" % (cand, _builtin_scenes() or "missing"))
+
+
 # ---------------------------------------------------------------- main
 def main():
     _setup_stdio()
     ap = argparse.ArgumentParser(description="video-studio 编排器")
     ap.add_argument("--script", default="film.json")
-    ap.add_argument("--scenes", default="scenes.py")
+    ap.add_argument("--scenes", default="",
+                    help="场景绘制模块（默认依次找：<剧本目录>/scenes.py、本技能内置的 scenes.py）")
     ap.add_argument("--out", default="out/film.mp4")
     ap.add_argument("--work", default="work")
     ap.add_argument("--stage", default="all", choices=STAGES)
@@ -2152,6 +2446,8 @@ def main():
                     help="过时也照跑（会在 QC 报告里留痕）")
     ap.add_argument("--no-gate", action="store_true",
                     help="跳过人工签核检查（会在 QC 报告里留痕，不算通过）")
+    ap.add_argument("--require-proposal", action="store_true",
+                    help="把'提案未确认'当成失败（默认只警告；先跑 propose.py 再出片）")
     ap.add_argument("--cost", action="store_true",
                     help="每个 stage 往 work/cost.jsonl 记一行实测耗时")
     # ---- v0.8 ----
@@ -2183,7 +2479,7 @@ def main():
     if engine not in ("pil", "web"):
         raise SystemExit("engine 只能是 pil 或 web，收到 %r" % engine)
     script["_engine"] = engine
-    script["_scenes"] = str(Path(a.scenes).resolve())
+    script["_scenes"] = _resolve_scenes(a.scenes, a.script)
 
     # ---- 门禁账本（v0.6.0）----
     global _LEDGER
@@ -2204,8 +2500,15 @@ def main():
         print("[gate] --no-gate：跳过人工签核检查（会在 QC 报告里留痕）")
 
     def _sources():
-        """源头输入：剧本与 scenes.py（改它们等于改了所有下游的依据）。"""
-        return {"script": a.script, "scenes": a.scenes}
+        """源头输入：剧本、scenes.py、冻结设计（改它们等于改了所有下游的依据）。
+
+        design.json 是 v1.0 新增的第三个源头：它由 propose.py --confirm 写出，
+        记录"这一版长什么样"。改设计 = 画面必须重渲，所以它必须进 stagewatch 的
+        源头指纹，否则"改了配色但没重跑 frames"这种事故查不出来。
+        """
+        design = os.path.join(a.work, "design.json")
+        return {"script": a.script, "scenes": a.scenes,
+                "design": design if os.path.exists(design) else ""}
 
     # 本次命令行**计划要跑**的 stage 集合：--stage all 展开成 10 个，单 stage 就是它自己。
     # 用途见 stagewatch.check 的 pending：本阶段马上要用新输入重算，那种"输入变了"不是过时。
@@ -2323,21 +2626,27 @@ def main():
             raise SystemExit("[前置] %s 不是合法 JSON（%s），重新跑 --stage layout" % (tl_p, e)) from e
 
     def load_scenes(strict=True):
-        """加载场景模块：strict=False 时失败只 WARN（qa 缺参考帧也要能跑）。"""
+        """加载场景模块：strict=False 时失败只 WARN（qa 缺参考帧也要能跑）。
+
+        v1.0.2：路径用 main() 里解析好的 script["_scenes"]（显式 --scenes / 剧本同目录 /
+        技能内置三档回退），不能再用原始 a.scenes —— 缺省时它是空串，会变成
+        `load_module("")` 这种 "NoneType has no attribute loader" 的怪错误。
+        """
+        scenes_path = script.get("_scenes") or _resolve_scenes(a.scenes, a.script)
         try:
-            mod = load_module(a.scenes)
+            mod = load_module(scenes_path)
         except Exception as e:                              # noqa: BLE001
             if strict:
                 raise SystemExit("[场景模块加载失败] %s：%s\n"
                                  "  --scenes 要指向定义 draw_frame() 的 scenes.py"
-                                 % (a.scenes, e)) from e
-            print("   [WARN] 场景模块加载失败（%s），跳过场景函数参考帧: %s" % (a.scenes, e))
+                                 % (scenes_path, e)) from e
+            print("   [WARN] 场景模块加载失败（%s），跳过场景函数参考帧: %s" % (scenes_path, e))
             return None
         if not hasattr(mod, "draw_frame"):
             if strict:
                 raise SystemExit("[场景模块错误] %s 没有 draw_frame(scene, t_local, dur, t_global, script, frame)"
-                                 % a.scenes)
-            print("   [WARN] %s 没有 draw_frame()，跳过场景函数参考帧" % a.scenes)
+                                 % scenes_path)
+            print("   [WARN] %s 没有 draw_frame()，跳过场景函数参考帧" % scenes_path)
             return None
         return mod
 
@@ -2362,7 +2671,11 @@ def main():
         print("== Preview（前 %.1fs / %d 帧）" % (n / float(tl["fps"]), n))
         sc2 = dict(script)
         sc2["_total"] = tl["total"]
-        sc2.setdefault("_style", resolve_style(script))
+        # 注意这里之前写成 setdefault(_style, resolve_style(script))：
+        # 对 sc2 做 setdefault 却传 script 的解析结果 —— script 有 _style 时，
+        # setdefault 的第二参数**仍会被求值**（Python 先算参数），等于多做一次无用解析；
+        # 而 script 没有 _style 时又把 work 漏了，单跑 --preview 会报"找不到设计"。
+        sc2.setdefault("_style", resolve_style(script, a.work))
         _render_range(tl, mod, sc2, 0, n, out_mp4, int(script.get("crf", 18)),
                       str(script.get("preset", "medium")), progress=False)
         # 有 audio.wav 就带上声音（没有也能看画面；不阻断）。
@@ -2567,6 +2880,11 @@ def main():
         return 1 if (errs or rc) else 0
 
     if stage in ("all", "frames", "mux"):
+        # ---- 提案闸（v1.0）：出片前必须先有已确认的设计 ----
+        # 放在最前面（before ensure_tl/preflight/st_frames）：渲完再拦等于白渲。
+        if stage in ("all", "frames"):
+            if not _proposal_gate(a):
+                return 1
         tl = tl if stage == "all" else ensure_tl()
         audio = os.path.join(a.work, "audio.wav")
         silent = os.path.join(a.work, "silent.mp4")