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

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

@@ -82,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")
@@ -322,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%"},
@@ -470,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")
@@ -813,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) 降级成不查。
 
@@ -891,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
@@ -911,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:

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

@@ -468,8 +468,21 @@ def plan_scenes(scenes, script=None, plan=None):
     """给 timeline 的每一段补 scene_type / scene_variant / scene_decor / scene_layout / scene_reason。
 
     scenes: K.build_timeline 产出的段列表（有 id/kind/start/end/dur 与剧本原字段）
-    plan:   stylekit.resolve_script_style 的结果（取 chapter_layout 与 style）
+    plan:   stylekit.resolve_script_style / designkit.design_to_plan 的结果
+            （取 chapter_layout / layout_cycle / layout_default 与 style）
     返回 storyboard dict（可直接 json.dump 审计），并把字段就地写进 scenes。
+
+    scene_layout 的取法（先命中先赢）：
+      ① plan["chapter_layout"] 显式指定（按章名查，查不到用 layout_default）；
+      ② plan["layout_cycle"]（≥2 种版式且没有显式 chapter_layout）：按章节首次
+         出现的顺序循环取位，**同一章内版式固定**——防止"全片一张版式"；
+      ③ 都没有：layout_default（与 v1.0.1 完全一致）。
+
+    **没有 chapter 的剧本**：按"每段自成一章"处理（轮换照常推进）。
+    为什么不把空 chapter 当成"全片同一章"：那样 layout_cycle 在常见的不写 chapter
+    的剧本上会退化成"永远 cycle[0]"，功能写了却完全不生效——正是本仓库反复踩过的
+    "号称支持实则失效"。空 chapter 本来就没有"章"的身份可言，逐段轮换既满足
+    "同章内稳定"（每段自成一章，平凡成立），又真的防住同骨架。
     """
     script = script or {}
     plan = plan or {}
@@ -479,6 +492,22 @@ def plan_scenes(scenes, script=None, plan=None):
     prev_variant = {}
     chapter_layout = plan.get("chapter_layout") if isinstance(plan.get("chapter_layout"), dict) else {}
     default_layout = plan.get("layout_default") or "left-stack"
+    # ---- 片内版式轮换（v1.0.2）：design_to_plan 会派生 layout_cycle ----
+    # 为什么需要：没有它时一章只能用一种版式（layout_default），8 段片子 8 屏同骨架 ——
+    # 正好是用户原则 5 说的"同一视频内部大面积/长时间重复"。
+    # 生效条件（两条都不满足就与过去逐字节一致，金帧/既有自检不漂）：
+    #   ① plan 没有显式 chapter_layout（显式指定优先，不能被轮换覆盖）；
+    #   ② layout_cycle 至少 2 种版式（只有一种等于不轮换）。
+    # 同一章内必须稳定（观众视角一章是一段整体），换章才换版式：
+    # 按「章节首次出现的顺序」依次取 cycle[0], cycle[1], … 循环。
+    cycle = plan.get("layout_cycle")
+    if isinstance(cycle, (list, tuple)):
+        cycle = [str(x) for x in cycle if str(x or "").strip()]
+    else:
+        cycle = []
+    use_cycle = (not chapter_layout) and len(cycle) >= 2
+    # key -> 版式（保证同一章内版式不变；无 chapter 时每段自成一章，轮换照常推进）
+    cycle_of = {}
     counter = {}
     rows = []
     for i, s in enumerate(scenes):
@@ -494,7 +523,16 @@ def plan_scenes(scenes, script=None, plan=None):
         variant = variant_of(stype, chapter, k, prev_variant.get(stype))
         prev_variant[stype] = variant
         decor = decor_of(stype, chapter, k)
-        layout = chapter_layout.get(chapter) or default_layout
+        if use_cycle:
+            # 空 chapter 用段号做键：每段自成一"章"，轮换才真的推进
+            # （否则最常见的不写 chapter 的剧本会永远停在 cycle[0]，功能形同虚设）。
+            key = chapter if chapter else "\x00scene:%d" % i
+            if key not in cycle_of:
+                # len(cycle_of) = 这是第几个"不同章节"（0 起），按它取轮换位
+                cycle_of[key] = cycle[len(cycle_of) % len(cycle)]
+            layout = cycle_of[key]
+        else:
+            layout = chapter_layout.get(chapter) or default_layout
         s["scene_type"] = stype
         s["scene_variant"] = int(variant)
         s["scene_decor"] = int(decor)
@@ -527,17 +565,39 @@ def describe(storyboard):
     return "%d 段 / %s" % (len(storyboard.get("scenes") or []), " ".join(parts))
 
 
-def _cli():
-    """自测入口：python grammar.py [film.json] —— 只读，不渲染。"""
+def _cli(argv=None):
+    """自测入口：python grammar.py [film.json] —— 只读，不渲染。
+
+    v1.0.2：加 argparse（在此之前 `--help` 会被当成 film.json 路径，FileNotFoundError，
+    与仓库里其它 17 个脚本的 CLI 约定不一致）。不传 film.json 时仍打印用法与 10 类构图，
+    退出码 0（保持 v0.9 的行为，便于老 CI 探活）。
+    """
+    import argparse
     import json
-    import sys
 
-    if len(sys.argv) < 2:
+    ap = argparse.ArgumentParser(
+        prog="grammar.py",
+        description="场景语法：按内容推导每段的构图类型（只读，不渲染、不需要 timeline）。",
+        epilog="不给 film.json 时只打印用法与 10 类构图说明。")
+    ap.add_argument("film", nargs="?", default=None,
+                    help="film.json 路径；给出时打印该剧本的分镜选型（时长按字数粗估）")
+    a = ap.parse_args(argv)
+
+    if not a.film:
         print("用法: python grammar.py film.json  # 打印该剧本的分镜选型（不需要 timeline）")
         print("场景类型:", " / ".join("%s(%s)" % (t, SCENE_LABELS[t]) for t in SCENE_TYPES))
         return 0
-    script = json.load(open(sys.argv[1], encoding="utf-8"))
+
+    try:
+        with open(a.film, encoding="utf-8") as fp:
+            script = json.load(fp)
+    except OSError as e:
+        ap.error("读不了 film.json：%s（%s）" % (a.film, e))
+    if not isinstance(script, dict):
+        ap.error("film.json 顶层必须是对象：%s" % a.film)
     lines = script.get("lines") or []
+    if not isinstance(lines, list):
+        ap.error("film.json 的 lines 必须是数组：%s" % a.film)
     # 没跑 TTS 时按字数粗估时长（只用于看选型，不是时间轴权威）
     scenes = []
     t = 0.0