@remixmate/cli 0.9.31 → 0.9.33

package/dist/manifest.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
-  "version": "0.9.31",
-  "generatedAt": "2026-09-14T15:38:04.716Z",
+  "version": "0.9.33",
+  "generatedAt": "2026-09-16T01:00:58.193Z",
   "skills": [
     {
       "id": "export-jianying",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remixmate/cli",
-  "version": "0.9.31",
+  "version": "0.9.33",
   "description": "AI media generation skills for Claude Code / Codex — 12 skills covering image, video, voice, digital human, web screenshot, web recording, script, template registry, rendering, Jianying export, and video deconstruction.",
   "type": "module",
   "main": "dist/index.js",
@@ -24,6 +24,7 @@
     "test:web-read": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-web-read.py",
     "test:template-pipeline": "PYTHONDONTWRITEBYTECODE=1 node dist/cli.js exec -- python3 scripts/test-template-pipeline.py",
     "test:props-contract": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-props-contract.py",
+    "test:card-array-keys": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-card-array-keys.py",
     "test:narration-speed": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-narration-speed.py",
     "test:render-resume": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-render-resume.py",
     "test:render-plan": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-render-plan-snapshot.py",

package/skills/gen-script/SKILL.md

@@ -55,6 +55,7 @@ The intent is to avoid the failure mode where "the generic DSL looks compatible
 1. Read the requested template's full definition from the registry — `template_registry` with `template_id=<the id>` and `json_output=true` emits that one template whole. This is the shipping source of truth, and unlike the summary list it truncates nothing. Do **not** ask for every template's full definition (`list_templates=true` + `full=true`): the whole registry is far more JSON than one tool result can carry, and the call fails instead of returning the contract.
 2. Read its `llmHint` end to end — that is where the template states how its on-screen text and its layouts must be authored.
 3. Read its `customPayloadSchema`: every template-specific field lives there, including the enum of legal `customPayload.slideId` values for multi-layout templates.
+3b. If the template ships `slideSchemas` (multi-layout templates do), **author `templateData` straight from `slideSchemas[slideId]`** — it is the only place the per-layout field names exist. Do not infer them: the same concept is named `name` in one layout, `label` in another and `era` in a third, and a wrong name is dropped in silence (see below).
 4. Combine that with the template's `slotMapping`, `requiredProps`, `optionalProps`, `propExtractors`, `assetRequirements`, `supportedAspectRatios`, `supportedDurations`, `constraints`, and `scenePatterns`.
 5. Generate the DSL in the template's native shape — not the generic DSL shape.
 6. Make sure the DSL explicitly contains every template-specific field, e.g. `templateData.words`, `customPayload.slideId`, `visuals.avatar.assetRef`.
@@ -69,6 +70,14 @@ When a template's `customPayloadSchema.slideId.enum` holds more than one value (
 
 A missing `slideId` is the quietest failure in the pipeline: the renderer drops the entire `templateData` and draws a single centred title — no error, no log, exit code 0.
 
+### Multi-layout templates: field names are per-layout, never guessable
+
+Picking the layout is only half of it. Each layout reads its own field names out of `templateData`, and a field the layout does not read is **dropped without a word** — that slot renders empty, or shows the component's built-in placeholder text, and the render still reports success.
+
+This has shipped broken videos: a 7-scene deck wrote `items[].title` where `html-slide`'s `feature-grid` reads `name`, `items[].description` where `timeline-axis` reads `detail`, and `title` / `subtitle` / `ctaText` where `closing-cta` reads `headline` / `actionLine` / `ctaLabel` / `ctaUrl`. Five of seven scenes rendered as empty cards and placeholder copy — after paying for TTS and the render.
+
+So: **copy the field names out of `slideSchemas[slideId]`.** The DSL validator now rejects unknown field names before any asset is generated and tells you the declared ones, but that check only fires for templates that ship `slideSchemas` — reading the contract is still the primary move, not the fallback.
+
 ### On-screen text: the rules live in the template, not here
 
 How the on-screen text layers should be *written* — whether the headline is a hook or a product name, how many subheadline lines survive, whether `**emphasis**` is parsed, where a link is allowed to appear — is a property of each template's layout, and its single source of truth is that template's `llmHint` in `template.json`. This skill deliberately does not restate any of it: a copy here would drift from the registry, and the registry is what actually renders.
@@ -476,4 +485,4 @@ prefix and version — not a short alias:
 |------|---------|
 | `gen_script.py` | Core script — produces the Video DSL JSON from a topic. |
 
-The authoritative per-template contract is the registry's `template.json` (`llmHint` + `customPayloadSchema` + `slotMapping`). `template_registry list_examples=true` lists local reference DSLs when any exist, but that directory does not ship — see *DSL schema* above.
+The authoritative per-template contract is the registry's `template.json` (`llmHint` + `customPayloadSchema` + `slideSchemas` + `slotMapping`) — everything you need to author against is in there, so read it rather than inferring field names from the template's name or from another template. `template_registry list_examples=true` lists local reference DSLs when any exist, but that directory does not ship — see *DSL schema* above.

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

@@ -461,12 +461,23 @@ def validate_dsl(dsl: dict) -> list:
       ``global`` presence are intentionally NOT enforced here — by the time
       a DSL reaches render_video those have already been gated upstream, and
       enforcing them again would change historical behavior.
+
+    ``severity="warning"`` 的条目**不阻断**：它们描述的是"能渲染出来但有一处会静默
+    退化"（如黑板版 highlight 不是 title 的子串 → 标题退回单色）。把它们和硬错误混在
+    同一个 fatal 列表里，作者就只能二选一：要么被无关的软问题挡住，要么把整条校验关掉。
+    警告改为打印到 stderr，退出码不受影响。
     """
     from video_dsl.runtime.dsl_validator import (  # noqa: E402
         validate_integrity,
         errors_as_strings,
     )
-    return errors_as_strings(validate_integrity(dsl))
+    found = validate_integrity(dsl)
+    warnings = [e for e in found if getattr(e, "severity", "error") != "error"]
+    if warnings:
+        LogPrint("⚠️  DSL warnings (not blocking):", file=sys.stderr)
+        for w in errors_as_strings(warnings):
+            LogPrint(f"   - {w}", file=sys.stderr)
+    return errors_as_strings([e for e in found if getattr(e, "severity", "error") == "error"])
 
 
 def resolve_dimensions(dsl: dict) -> tuple:
@@ -1245,8 +1256,19 @@ def _auto_highlight_map(entry: dict, narration_asset: Optional[dict], render_pla
     # outro counts toward line_count too; cap item_count at the authored
     # items-array length so trailing outro lines don't spill into card
     # indices.
+    # ⚠️ 这份键表必须与模板侧 utils/slidePayload.ts 的 CARD_ARRAY_KEYS 完全一致：
+    # 两处是同一算法的两份实现（这里是生产路径，那边是摊平 binder 形态下的本地兜底）。
+    # 2026-09-15 修复：此前这里少了 steps / annotations，于是 step-flow 与
+    # code-highlight 拿不到下面那行的上限裁剪，旁白带 outro 行时 highlightMap 会多出
+    # 一个指向数组外的下标 —— 那一行播放期间"全部卡片变暗、没有一张点亮"。
+    # 顺序也有意义：取第一个命中的键，新键一律追加在末尾。
+    # template-library 的 `pnpm validate:contracts` 现在会双向核对这两份表。
     items_key = next(
-        (k for k in ("concepts", "pillars", "eras", "items") if isinstance(tdata.get(k), list)),
+        (
+            k
+            for k in ("concepts", "pillars", "eras", "items", "steps", "annotations")
+            if isinstance(tdata.get(k), list)
+        ),
         None,
     )
     if items_key:

package/skills/template-registry/scripts/list_templates.py

@@ -119,7 +119,7 @@ def _summarize(tpl: dict) -> dict:
     """The "choose a template" view: identity + selection criteria only.
 
     Deliberately excludes the authoring contract (llmHint in full,
-    customPayloadSchema, slotMapping, compositions, variants' style bodies) —
+    customPayloadSchema, slideSchemas, slotMapping, compositions, variants' style bodies) —
     that is what ``--template-id`` returns, one template at a time.
     """
     variants = tpl.get("variants")
@@ -154,8 +154,8 @@ def _summarize(tpl: dict) -> dict:
 def _detail_hint(template_id: str = "<templateId>") -> str:
     return (
         f"Summaries only. Run --template-id {template_id} --json-output for one "
-        "template's full definition (llmHint / customPayloadSchema / slotMapping / "
-        "variants) — that is the per-template authoring contract."
+        "template's full definition (llmHint / customPayloadSchema / slideSchemas / "
+        "slotMapping / variants) — that is the per-template authoring contract."
     )
 
 
@@ -258,6 +258,7 @@ def main() -> None:
                 "contract that does ship is the registry's template.json:\n"
                 "     • llmHint            — how this template's on-screen text and layouts must be authored\n"
                 "     • customPayloadSchema — every template-specific field, incl. the legal slideId values\n"
+                "     • slideSchemas        — for multi-layout templates: what templateData each slideId eats\n"
                 "     • slotMapping        — propExtractors / requiredProps / optionalProps\n"
                 "   Read it with `--template-id <id> --json-output` (one template's full "
                 "definition). Run `--list-templates` first if you need the ids;\n"
@@ -394,7 +395,7 @@ def main() -> None:
     first_id = str(visible[0].get("templateId", "<templateId>"))
     print(
         f"Full definition of one template: --template-id {first_id} --json-output "
-        "(llmHint / customPayloadSchema / slotMapping / variants)",
+        "(llmHint / customPayloadSchema / slideSchemas / slotMapping / variants)",
     )
 
 

package/skills/template-registry/video_dsl/runtime/dsl_validator.py

@@ -20,6 +20,7 @@ DSL 校验器 - 对 Video DSL v1alpha1 做结构校验与标准化。
 处理的模板时**不需要再改 remixmate 代码**。
 """
 
+import difflib
 import re
 from typing import Iterable, Optional
 
@@ -32,6 +33,22 @@ VALID_LAYOUTS = {"full-visual", "split-left-right", "split-top-bottom", "picture
 VALID_ASSET_TYPES = {"image", "video", "audio", "avatar", "subtitle", "bgm"}
 VALID_ASSET_SOURCES = {"existing", "gen-image", "gen-video", "gen-voice", "gen-digital-human"}
 
+# 由 Composition 消费、而非 slide 组件消费的字段。前八个与模板侧
+# utils/slidePayload.ts 的 FRAME_LEVEL_KEYS 同源 ——「整包态」binder 会把它们混进
+# templateData，出现在那里是正当的，不该被当成未声明字段。highlightMap 同理（模板
+# 一般在 slideSchemas._shared 里声明它，这里兜底没声明的情况）。
+_SLIDE_FRAME_LEVEL_KEYS = frozenset({
+    "slideId",
+    "titleText",
+    "subtitleText",
+    "watermarkText",
+    "narrationAssetId",
+    "narrationSrc",
+    "background",
+    "templateData",
+    "highlightMap",
+})
+
 # CJK 汉字范围（简繁通用）+ 常见中文标点
 _CJK_PATTERN = re.compile(r"[一-鿿㐀-䶿＀-￯　-〿]")
 
@@ -438,6 +455,446 @@ def _check_slide_id_chosen(dsl: dict) -> list[ValidationError]:
     return errors
 
 
+def _check_slide_cross_field(dsl: dict) -> list[ValidationError]:
+    """字段之间的一致性 —— 单看任何一个字段都合法,凑在一起才不成立。
+
+    schema 管不了这一类:它逐字段校验类型与枚举,表达不了"这个数必须落在另一个字段的
+    长度内"。三条规则都**静态可判定**,而且失败形态一致 —— 画面少东西、零报错:
+
+      · ``annotations[].line`` 指向不存在的代码行 → 那句旁白期间没有任何一行点亮
+      · ``highlightMap`` 的值越过卡片数组 → 那一行全屏变暗、无一张点亮
+      · 黑板版 ``highlight`` 不是 ``title`` 的子串 → 标题静默退回单色（模板 llmHint
+        自己写明了这个行为，正因为写明了才更该校验）
+
+    与 `_check_slide_payload_fields` 分开是因为那个函数按 schema 逐层递归,这里要的是
+    跨字段视角;混在一起会让两边都难读。
+    """
+    tpl = _get_template_cfg(_pick_template_id(dsl))
+    if not tpl:
+        return []
+    schemas = tpl.get("slideSchemas")
+    if not isinstance(schemas, dict):
+        return []
+    line_sync = {k: v for k, v in (tpl.get("lineSyncSlides") or {}).items()
+                 if isinstance(v, str)}
+
+    errors: list[ValidationError] = []
+
+    for idx, scene in enumerate(dsl.get("scenes", []) or []):
+        sid = scene.get("id", f"scenes[{idx}]")
+        custom = scene.get("customPayload") or {}
+        if not isinstance(custom, dict):
+            continue
+        slide_id = custom.get("slideId") or (custom.get("templateData") or {}).get("slideId")
+        if not isinstance(slide_id, str) or slide_id not in schemas:
+            continue
+        tdata = custom.get("templateData")
+        if not isinstance(tdata, dict):
+            tdata = scene.get("templateData") if isinstance(scene.get("templateData"), dict) else {}
+        if not tdata:
+            continue
+        base = f"scenes[{idx}].customPayload.templateData"
+
+        # ① 注解行号 ≤ 代码行数。`line` 是 1 起算的（契约里写明了）。
+        code = tdata.get("code")
+        annotations = tdata.get("annotations")
+        if isinstance(code, str) and isinstance(annotations, list):
+            total = len(code.split("\n"))
+            for i, note in enumerate(annotations):
+                if not isinstance(note, dict):
+                    continue
+                line = note.get("line")
+                if not isinstance(line, int) or isinstance(line, bool):
+                    continue
+                if line < 1 or line > total:
+                    errors.append(ValidationError(
+                        f"{base}.annotations[{i}].line",
+                        f"scene '{sid}': annotation points at line {line} but the code block has "
+                        f"{total} line(s) — while that narration line plays, no code line lights "
+                        "up at all. Line numbers are 1-based.",
+                    ))
+
+        # ② highlightMap 的值必须落在卡片数组里。
+        hmap = tdata.get("highlightMap")
+        cards_key = line_sync.get(slide_id)
+        cards = tdata.get(cards_key) if cards_key else None
+        if isinstance(hmap, dict) and isinstance(cards, list):
+            for k, v in hmap.items():
+                if not isinstance(v, int) or isinstance(v, bool):
+                    continue
+                if v < 0 or v >= len(cards):
+                    errors.append(ValidationError(
+                        f"{base}.highlightMap.{k}",
+                        f"scene '{sid}': highlightMap sends subtitle line {k} to card index {v}, "
+                        f"but templateData.{cards_key} only has {len(cards)} entries — during that "
+                        "line every card goes dim and none lights up.",
+                    ))
+
+        # ③ 黑板版的 highlight 必须是 title 的子串。字段是否存在由 schema 决定,
+        #    这里不写死模板名 —— 没有声明 highlight 的模板天然跳过。
+        if "highlight" in ((schemas.get(slide_id) or {}).get("properties") or {}):
+            highlight = tdata.get("highlight")
+            title = tdata.get("title")
+            if (
+                isinstance(highlight, str)
+                and highlight.strip()
+                and isinstance(title, str)
+                and highlight not in title
+            ):
+                errors.append(ValidationError(
+                    f"{base}.highlight",
+                    f"scene '{sid}': highlight '{highlight}' is not a substring of title "
+                    f"'{title}' — the two-colour split silently falls back to a single colour.",
+                    severity="warning",
+                ))
+
+    return errors
+
+
+def _check_line_sync_narration(dsl: dict) -> list[ValidationError]:
+    """走逐行高亮的版式,旁白必须是**分行**的,否则整屏一个卡片都不会点亮。
+
+    为什么必须拦:这是"画面看起来没渲染完"的主路径,而且全链路零日志。链条是——
+    旁白只给了整段 ``text``(单卡版式的合法写法)→ 绑定不写 ``narrationLineCount``
+    → ``render_video`` 的 ``_auto_highlight_map`` 在第一个 if 就 return → 没有
+    ``highlightMap`` → 模板侧 ``resolveHighlightMap`` 同样拿不到行数 →
+    ``activeHighlightIndex`` 恒为 -1 → **整场所有卡片停在未点亮态**。
+    连 ``_auto_highlight_map`` 那条 warn 日志都打不出来,因为它在更前面就返回了。
+
+    哪些版式受约束由模板的 ``lineSyncSlides`` 声明,不写死模板名/版式名。
+
+    两个逃生阀(命中任一即放行,都是模板自己声明的能力,不是本函数的特例):
+      - ``templateData.highlightMap`` —— 作者显式给了映射表,那他知道自己在做什么;
+      - schema 里标了 ``x-staticHighlight`` 的字段(如 timeline-axis 的
+        ``progressIndex``、timeline / column-compare 的 ``highlightIndex``)——
+        这些字段的存在本身就是"本屏走静态高亮、不跟旁白走"的声明。
+    """
+    tpl = _get_template_cfg(_pick_template_id(dsl))
+    if not tpl:
+        return []
+    line_sync = {k: v for k, v in (tpl.get("lineSyncSlides") or {}).items()
+                 if isinstance(v, str)}
+    if not line_sync:
+        return []
+    schemas = tpl.get("slideSchemas") if isinstance(tpl.get("slideSchemas"), dict) else {}
+
+    errors: list[ValidationError] = []
+
+    for idx, scene in enumerate(dsl.get("scenes", []) or []):
+        sid = scene.get("id", f"scenes[{idx}]")
+        custom = scene.get("customPayload") or {}
+        if not isinstance(custom, dict):
+            continue
+        slide_id = custom.get("slideId") or (custom.get("templateData") or {}).get("slideId")
+        if not isinstance(slide_id, str) or slide_id not in line_sync:
+            continue
+
+        narration = (scene.get("audio") or {}).get("narration") or {}
+        items = narration.get("items")
+        if isinstance(items, list) and any(
+            (isinstance(x, str) and x.strip()) or isinstance(x, dict) for x in items
+        ):
+            continue  # 有分行旁白，数量对不对交给 _check_narration_items_count
+
+        tdata = custom.get("templateData")
+        if not isinstance(tdata, dict):
+            tdata = scene.get("templateData") if isinstance(scene.get("templateData"), dict) else {}
+
+        if isinstance(tdata.get("highlightMap"), dict) and tdata["highlightMap"]:
+            continue
+
+        static_keys = [
+            k for k, sub in ((schemas.get(slide_id) or {}).get("properties") or {}).items()
+            if isinstance(sub, dict) and sub.get("x-staticHighlight") is True
+        ]
+        if any(tdata.get(k) is not None for k in static_keys):
+            continue
+
+        cards_key = line_sync[slide_id]
+        escape = (
+            f" If this scene is meant to stay static, set one of: {', '.join(sorted(static_keys))}."
+            if static_keys else ""
+        )
+        errors.append(ValidationError(
+            f"scenes[{idx}].audio.narration.items",
+            f"scene '{sid}': layout '{slide_id}' lights its {cards_key} one at a time, driven by "
+            "one narration line per card — but this scene's narration is a single block with no "
+            "'items'. Without per-line narration nothing ever lights up: every card stays in the "
+            "dimmed state for the whole scene and the frame looks half-rendered, with no error "
+            f"and no log. Split the narration into one line per entry of templateData.{cards_key} "
+            "under audio.narration.items." + escape,
+        ))
+
+    return errors
+
+
+def _check_slide_payload_fields(dsl: dict) -> list[ValidationError]:
+    """逐版式校验 ``customPayload.templateData`` 的字段名。
+
+    为什么需要这道门禁:多版式模板里「slideId 决定 templateData 吃哪些字段」这条
+    契约,此前只存在于模板的 React 源码里 —— 而写 DSL 的 agent 只能看到 registry
+    下发的 ``template.json``。字段名猜错(把 ``name`` 写成 ``title``、把 ``detail``
+    写成 ``description``)时组件读到 undefined,要么渲染出内置的占位文案、要么整块
+    空白,**渲染成功、零日志、退出码 0**。真实案例:一份 7 场景的 DSL 里 5 个场景
+    中招,TTS 和渲染的钱全花完才在成片里看出来。
+
+    契约现在写在 ``template.json`` 的 ``slideSchemas`` 里(键 = slideId,值 = 该版式
+    的 JSON Schema),由 template-library 的 ``check:slide-schemas`` 与组件源码双向
+    对账。本函数按它核对每个场景,**未声明的字段名带 "did you mean" 提示** ——
+    收到这条错误的多半正是那个猜错了名字的 agent,直接把正确的名字给它。
+
+    没有声明 ``slideSchemas`` 的模板(全部单版式模板)一律跳过,不产生噪音。
+    """
+    tpl = _get_template_cfg(_pick_template_id(dsl))
+    if not tpl:
+        return []
+    schemas = tpl.get("slideSchemas")
+    if not isinstance(schemas, dict):
+        return []
+
+    tid = tpl.get("templateId", "<unknown>")
+    shared = ((schemas.get("_shared") or {}).get("properties") or {})
+    known_slides = [k for k in schemas if not k.startswith("_")]
+
+    errors: list[ValidationError] = []
+
+    for idx, scene in enumerate(dsl.get("scenes", []) or []):
+        sid = scene.get("id", f"scenes[{idx}]")
+        custom = scene.get("customPayload") or {}
+        if not isinstance(custom, dict):
+            continue
+        data = custom.get("templateData")
+        if not isinstance(data, dict):
+            data = scene.get("templateData")
+        if not isinstance(data, dict):
+            continue
+
+        slide_id = custom.get("slideId") or data.get("slideId")
+        if not isinstance(slide_id, str) or not slide_id:
+            continue  # 「没选版式」由 _check_slide_id_chosen 负责报
+
+        schema = schemas.get(slide_id)
+        if not isinstance(schema, dict):
+            # 版式名写错 —— 同样静默回落到 DefaultSlide,和没写一样致命。
+            errors.append(ValidationError(
+                f"scenes[{idx}].customPayload.slideId",
+                f"scene '{sid}' uses slideId '{slide_id}', which template '{tid}' does not "
+                "register — the frame silently falls back to a single centred title.\n"
+                f"     Available layouts: {', '.join(sorted(known_slides))}",
+            ))
+            continue
+
+        errors += _walk_payload(
+            data,
+            schema,
+            path=f"scenes[{idx}].customPayload.templateData",
+            scene=sid,
+            extra_allowed=shared,
+            # frame 级字段由 Composition 消费,「整包态」binder 会把它们混进
+            # templateData —— 出现在这里是正当的,不算未声明字段。
+            skip_keys=_SLIDE_FRAME_LEVEL_KEYS,
+        )
+
+    return errors
+
+
+def _check_custom_payload_fields(dsl: dict) -> list[ValidationError]:
+    """单版式模板:按 ``customPayloadSchema`` 逐字段核对 ``customPayload``。
+
+    与 `_check_slide_payload_fields` 是同一件事的两种形态 —— 多版式模板的契约按 slideId
+    分支(``slideSchemas``),单版式模板只有一份(``customPayloadSchema``)。多版式模板在
+    这里**跳过**,避免同一份数据被两套规则各报一遍。
+
+    为什么值得做:在此之前,10 个模板里只有 2 个的字段名会被校验,其余 8 个写错字段名
+    照样一路渲染到成片。契约本来就在 ``template.json`` 里躺着,只是没人读。
+    """
+    tpl = _get_template_cfg(_pick_template_id(dsl))
+    if not tpl:
+        return []
+    if isinstance(tpl.get("slideSchemas"), dict):
+        return []  # 多版式模板走 _check_slide_payload_fields
+    cps = tpl.get("customPayloadSchema")
+    if not isinstance(cps, dict) or not cps:
+        return []
+
+    root = {"type": "object", "properties": cps}
+    errors: list[ValidationError] = []
+    for idx, scene in enumerate(dsl.get("scenes", []) or []):
+        custom = scene.get("customPayload")
+        if not isinstance(custom, dict) or not custom:
+            continue
+        errors += _walk_payload(
+            custom,
+            root,
+            path=f"scenes[{idx}].customPayload",
+            scene=scene.get("id", f"scenes[{idx}]"),
+        )
+    return errors
+
+
+def _walk_payload(
+    data: dict,
+    schema: dict,
+    *,
+    path: str,
+    scene: str,
+    extra_allowed: Optional[dict] = None,
+    skip_keys: frozenset = frozenset(),
+    fallback_desc: Optional[str] = None,
+) -> list[ValidationError]:
+    """沿 schema 递归下钻,逐层做「未声明字段 + 缺必填 + 空数组」核对。
+
+    只下钻**描述了形状的**层：schema 节点没有 ``properties`` 就停(那是作者显式开的
+    开放包,如 ppt-to-video 由抽取脚本生成的 ``slide.nodes[]``),不去猜它的字段。
+
+    ⚠️ 这里刻意**不做**类型 / enum / 区间校验 —— 那些由 template-library 的
+    `check:payload` 在仓库侧对 dsl-example 做,已有一份完整实现。运行时这份只管
+    "字段名对不对、该给的给没给",两边职责不重叠,也就不需要在 Python 里再养一份
+    JSON Schema 引擎(这个仓库已经被"同一算法两份实现"坑过不止一次)。
+    """
+    errors = _check_payload_object(
+        data,
+        schema,
+        path=path,
+        scene=scene,
+        extra_allowed=extra_allowed,
+        skip_keys=skip_keys,
+        fallback_desc=fallback_desc,
+    )
+
+    own_desc = schema.get("description") if isinstance(schema.get("description"), str) else None
+
+    for key, sub in (schema.get("properties") or {}).items():
+        if not isinstance(sub, dict):
+            continue
+        value = data.get(key)
+        if sub.get("type") == "object" and sub.get("properties") and isinstance(value, dict):
+            errors += _walk_payload(
+                value, sub, path=f"{path}.{key}", scene=scene,
+                fallback_desc=own_desc or fallback_desc,
+            )
+        elif sub.get("type") == "array" and isinstance(value, list):
+            item_schema = sub.get("items")
+            if not isinstance(item_schema, dict) or not item_schema.get("properties"):
+                continue
+            for i, item in enumerate(value):
+                if isinstance(item, dict):
+                    errors += _walk_payload(
+                        item, item_schema, path=f"{path}.{key}[{i}]", scene=scene,
+                        fallback_desc=own_desc or fallback_desc,
+                    )
+
+    return errors
+
+
+def _check_payload_object(
+    data: dict,
+    schema: dict,
+    *,
+    path: str,
+    scene: str,
+    extra_allowed: Optional[dict] = None,
+    skip_keys: frozenset = frozenset(),
+    fallback_desc: Optional[str] = None,
+) -> list[ValidationError]:
+    """一层对象的「未声明字段 + 缺必填字段 + 空数组」核对。数组元素与顶层共用这一份。"""
+    props = schema.get("properties")
+    if not isinstance(props, dict):
+        return []
+    allowed = set(props) | set(extra_allowed or {})
+    merged_props = {**(extra_allowed or {}), **props}
+
+    errors: list[ValidationError] = []
+
+    for key in data:
+        if key in allowed or key in skip_keys:
+            continue
+        errors.append(ValidationError(
+            f"{path}.{key}",
+            f"scene '{scene}': the slide does not read '{key}' — the value is silently "
+            f"dropped and that slot renders empty (or shows the component's placeholder)."
+            + _suggest_field(key, merged_props, schema, fallback_desc),
+        ))
+
+    for key in schema.get("required") or []:
+        if _is_blank(data.get(key)):
+            errors.append(ValidationError(
+                f"{path}.{key}",
+                f"scene '{scene}': required field '{key}' is missing or empty — without it "
+                "the slide renders its built-in placeholder instead of your content.",
+            ))
+
+    # 空数组 = 空屏。这些数组就是版式的画面主体,给了个 [] 与没给没有区别,
+    # 但 required 判定不出来(键确实在)。用 schema 的 minItems 表达,不写死键名。
+    for key, sub in props.items():
+        if not isinstance(sub, dict) or sub.get("type") != "array":
+            continue
+        min_items = sub.get("minItems")
+        value = data.get(key)
+        if isinstance(min_items, int) and isinstance(value, list) and len(value) < min_items:
+            errors.append(ValidationError(
+                f"{path}.{key}",
+                f"scene '{scene}': '{key}' has {len(value)} entries but this layout needs at "
+                f"least {min_items} — the array is what the slide draws, an empty one renders "
+                "a blank frame.",
+            ))
+
+    return errors
+
+
+def _is_blank(value: object) -> bool:
+    """必填判定：``None`` 与纯空白字符串都算没给。
+
+    为什么空串也算:组件里普遍写成 ``props.title || "占位文案"``,而 ``""`` 是 falsy ——
+    写空串拿到的**同样是占位文案**,不是空白。也就是说空串从来就不是"有意留空"的表达,
+    只是另一种漏填。放行它等于给静默失效留一道后门。
+    """
+    if value is None:
+        return True
+    return isinstance(value, str) and not value.strip()
+
+
+def _suggest_field(
+    wrong: str,
+    props: dict,
+    schema: dict,
+    fallback_desc: Optional[str] = None,
+) -> str:
+    """把写错的字段名换成一句能照着改的提示。三级降级。
+
+    ① **在各字段的 description 里搜「不是 <wrong>」**。写契约时易错点已经写进了描述
+       （``卡片标题（⚠️ 键名是 name，不是 title）``），直接拿错的名字去搜即可。实测对
+       真实事故里那 6 个错误 6/6 命中,而 difflib 是 0/6 —— 因为 title↔name、
+       description↔detail 是**同义词**而非拼写错误,字符串相似度对它们天然无效。
+       这一级还自带维护性:提示与契约同处一地,改字段名时顺手就改了。
+    ② difflib —— 留给真正的拼写错误（``titel`` → ``title``）。
+    ③ 列出全部合法字段,并附上**该版式自己的 description**。后者回答的是"那我该用哪个
+       版式"：demo-concept-overview 的描述里就写着「卡片不支持描述文字,要配说明改用
+       feature-grid」,而这正是写错的人真正需要的下一步。
+    """
+    for name, sub in props.items():
+        desc = (sub or {}).get("description") if isinstance(sub, dict) else None
+        if not isinstance(desc, str):
+            continue
+        # 「不是 title」/「不是 title，」/「不是 `title`」都要认。
+        if re.search(rf"不是\s*[`'\"]?{re.escape(wrong)}[`'\"]?(?![\w-])", desc):
+            return f" This layout calls it '{name}' — {desc}"
+
+    hit = difflib.get_close_matches(wrong, sorted(props), n=1, cutoff=0.6)
+    if hit:
+        return f" Did you mean '{hit[0]}'?"
+
+    tail = f" Declared fields: {', '.join(sorted(props))}."
+    # 走到这一级说明「改个名字」解决不了 —— 多半是这个版式压根没有这种能力。
+    # 把版式自己的说明带出来，那里通常写着该换成哪个版式（demo-concept-overview 的
+    # 描述就写着「卡片不支持描述文字，每项要配一句说明时改用 feature-grid」）。
+    # 嵌套 item 层没有自己的 description，所以由调用方把版式级的那句传进来。
+    slide_desc = schema.get("description") or fallback_desc
+    if isinstance(slide_desc, str) and slide_desc.strip():
+        tail += f" About this layout: {slide_desc}"
+    return tail
+
+
 def _check_narration_language_strict(dsl: dict) -> list[ValidationError]:
     """完整版:模板若声明 ``capabilities.narrationLanguageStrict`` 则强约束旁白语言。
 
@@ -525,6 +982,12 @@ def validate_integrity(dsl: dict) -> list[ValidationError]:
     # render-video 与 prepare_video_assets 都走这条 —— 而"没选版式"正是要在烧掉渲染
     # 积分之前拦住的东西。单版式模板不受影响,见 _check_slide_id_chosen。
     errors += _check_slide_id_chosen(dsl)
+    # 同理:字段名写错同样是「渲染成功但画面是空壳」,必须在烧掉 TTS / 渲染积分
+    # 之前拦住。只对声明了 slideSchemas 的模板生效,见 _check_slide_payload_fields。
+    errors += _check_slide_payload_fields(dsl)
+    errors += _check_custom_payload_fields(dsl)
+    errors += _check_line_sync_narration(dsl)
+    errors += _check_slide_cross_field(dsl)
     return errors
 
 
@@ -553,6 +1016,10 @@ def validate_dsl(dsl: dict) -> list[ValidationError]:
     errors += _check_narration_items_count(dsl)
     errors += _check_narration_language_strict(dsl)
     errors += _check_slide_id_chosen(dsl)
+    errors += _check_slide_payload_fields(dsl)
+    errors += _check_custom_payload_fields(dsl)
+    errors += _check_line_sync_narration(dsl)
+    errors += _check_slide_cross_field(dsl)
     return errors