@remixmate/cli 0.9.30 → 0.9.32

package/dist/manifest.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
-  "version": "0.9.30",
-  "generatedAt": "2026-09-14T14:44:43.104Z",
+  "version": "0.9.32",
+  "generatedAt": "2026-09-15T01:33:27.056Z",
   "skills": [
     {
       "id": "export-jianying",
@@ -833,7 +833,7 @@
       "tier": "orchestration",
       "category": "authoring",
       "title": "Video Template Registry",
-      "summary": "List all available video templates (templateId / name / aspect ratio / style tags). Template-to-DSL binding is no longer exposed as a separate step — once prepare_video_assets receives a template_id it runs the full DSL→RenderPlan pipeline internally.",
+      "summary": "List all available video templates (templateId / name / aspect ratio / style tags), or read one template's full definition with template_id. Listing returns summaries; pass template_id to get that template's authoring contract (llmHint / customPayloadSchema / slotMapping / variants). Template-to-DSL binding is no longer exposed as a separate step — once prepare_video_assets receives a template_id it runs the full DSL→RenderPlan pipeline internally.",
       "triggers": [
         "View available templates / list every template"
       ],
@@ -853,11 +853,19 @@
         "properties": {
           "list_templates": {
             "type": "boolean",
-            "description": "List available templates (default behavior; also implied when other flags are passed)."
+            "description": "List available templates as summaries — templateId / name / description / aspect ratios / language / status / styleTags / variantIds / key capabilities / a truncated llmHint (default behavior; also implied when other flags are passed)."
+          },
+          "template_id": {
+            "type": "string",
+            "description": "Return this template's FULL definition instead of the summary list: llmHint in full, customPayloadSchema (every template-specific field incl. the legal slideId values), slotMapping, compositions, variants. This is the per-template authoring contract — read it before writing DSL for that template."
+          },
+          "full": {
+            "type": "boolean",
+            "description": "List mode only: emit full definitions for every listed template instead of summaries. Rejected when the result would be too large for one tool result — prefer template_id, or narrow with the filter_* parameters."
           },
           "list_examples": {
             "type": "boolean",
-            "description": "List the *.dsl.json / *.binding.json reference examples shipped under template-registry/video_dsl/schema/examples/, grouped by templateId. Useful for downstream agents (e.g. a creation agent) that want to read a template's reference shape before producing new DSL."
+            "description": "List the *.dsl.json / *.binding.json reference examples under template-registry/video_dsl/schema/examples/, grouped by templateId. That directory is optional and is not part of the published package, so this is normally empty — to read a template's reference shape, use template_id instead (the registry's own contract)."
           },
           "filter_tag": {
             "type": "string",
@@ -877,7 +885,7 @@
           },
           "json_output": {
             "type": "boolean",
-            "description": "Emit a JSON result ({ templates: [...] } or { examples: [...] }) instead of the human-readable table."
+            "description": "Emit a JSON result instead of the human-readable table: { templates: [...] } — summaries, or full definitions when template_id / full is set — or { examples: [...] }."
           }
         },
         "required": []
@@ -886,6 +894,8 @@
         "primary": [],
         "advanced": [
           "list_templates",
+          "template_id",
+          "full",
           "list_examples",
           "filter_tag",
           "filter_aspect",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remixmate/cli",
-  "version": "0.9.30",
+  "version": "0.9.32",
   "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",

package/skills/gen-script/SKILL.md

@@ -52,9 +52,10 @@ The intent is to avoid the failure mode where "the generic DSL looks compatible
 
 ### Mandatory steps
 
-1. Read the requested template's full definition from the registry — `template_registry` with `list_templates=true` and `json_output=true` emits each template whole. This is the shipping source of truth, and unlike the table view it truncates nothing.
+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/template-registry/SKILL.md

@@ -77,8 +77,9 @@ the registry is loaded **only** from the ab-api HTTP endpoint — explicit `VIDE
 > The Python binding logic that maps DSL → TemplateBinding lives in `scripts/match_template.py` but is **not exposed as a CLI** — it is only consumed as a Python library by `render-video`'s `render_video.py` via `import match_template`.
 
 1. **List available templates**: run `remixmate template-registry --list-templates` to view the templates in the registry along with their supported aspect ratios / style tags, and decide which `templateId` to pick.
-2. **Write the DSL**: when generating the Video DSL, put the chosen `templateId` into `meta.templateId` (the canonical location). Use `meta.templateVariant` / `renderHints.templateVariant` to explicitly select a variant. The legacy `renderHints.templatePreference[0]` is still tolerated by `match_template.py` and `dsl_validator._pick_template_id` during transition, but new authors should write `meta.templateId`.
-3. **Produce the TemplateBinding**: there is no standalone CLI for DSL → TemplateBinding; `prepare_video_assets` calls `match_template.build_binding(template, dsl)` inline during the asset-resolution pipeline and embeds the binding into the RenderPlan it hands to the renderer — no separate `*.binding.json` file is written.
+2. **Read that template's contract**: run `remixmate template-registry --template-id <id> --json-output` for the full definition (llmHint, `customPayloadSchema` with the legal `slideId` values, `slotMapping`, `variants`). The list view only carries a 200-char llmHint preview, which is not enough to author against.
+3. **Write the DSL**: when generating the Video DSL, put the chosen `templateId` into `meta.templateId` (the canonical location). Use `meta.templateVariant` / `renderHints.templateVariant` to explicitly select a variant. The legacy `renderHints.templatePreference[0]` is still tolerated by `match_template.py` and `dsl_validator._pick_template_id` during transition, but new authors should write `meta.templateId`.
+4. **Produce the TemplateBinding**: there is no standalone CLI for DSL → TemplateBinding; `prepare_video_assets` calls `match_template.build_binding(template, dsl)` inline during the asset-resolution pipeline and embeds the binding into the RenderPlan it hands to the renderer — no separate `*.binding.json` file is written.
 
 > Design trade-off: collapsing the binding step into the asset-prep pipeline (no CLI, no on-disk artifact) avoids binding files drifting between the agent, the database, and the file system; any hand-edited `.binding.json` would never be consumed by the renderer anyway. For local debugging you can still `import match_template.build_binding` from Python.
 
@@ -119,12 +120,25 @@ print(json.dumps(binding, ensure_ascii=False, indent=2))
 
 | Flag | Description | Default |
 |------|-------------|---------|
-| `--list-templates` | List every available template (currently the only CLI verb). | — |
+| `--list-templates` | List every available template as a **summary** (templateId / name / description / aspect ratios / language / status / styleTags / variantIds / the `capabilities` keys that drive authoring — `payloadStyle` / `needsNarration` / `durationStrategy` / `narrationDriver` — and llmHint truncated to 200 chars). | — |
+| `--template-id <id>` | Print that template's **full definition** — llmHint in full, `customPayloadSchema`, `slotMapping`, `compositions`, `variants`. Repeatable. | — |
+| `--full` | List mode: emit full definitions instead of summaries. Refuses when the result would exceed 60 K characters. | off |
 | `--filter-tag` | Keep only templates whose `styleTags` match this substring (case-insensitive). | none |
 | `--filter-aspect` | Keep only templates declaring this aspect ratio (e.g. `9:16`). | none |
 | `--filter-language` | Keep only templates whose `contentLanguage` includes this code (`zh`/`en`); language-agnostic templates always show. | none |
 | `--include-beta` | Also show `status: beta` templates (same effect as `ENABLE_BETA_TEMPLATES=1`). | off |
-| `--json-output` | Emit `{ "templates": [...] }` instead of the table. | off |
+| `--json-output` | Emit `{ "templates": [...] }` instead of the table — summaries, or full definitions under `--template-id` / `--full`. | off |
+
+### List vs. detail
+
+A registry row is 4–17 KB of JSON, so dumping every full definition at once overflows an LLM tool result (the caller sees "exceeds maximum allowed tokens" instead of the contract it asked for). The list verb therefore returns summaries — enough to *choose* a template — and `--template-id` returns the one definition you need to *author* for it:
+
+```bash
+remixmate template-registry --list-templates                         # choose
+remixmate template-registry --template-id html-slide --json-output   # then read its contract
+```
+
+This mirrors the list/detail split described in `scripts/registry_loader.py` (P1.2), realized CLI-side so it holds even while the backend still serves one merged registry payload.
 
 ## Props extraction rules
 

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

@@ -13,8 +13,32 @@ TS↔Python duplication; this is now the only place the list verb is realized.
 The DSL → TemplateBinding logic stays in ``match_template.py`` and is invoked
 in-process by ``render-video``; it is intentionally NOT exposed as a CLI verb.
 
+List vs. detail (why ``--json-output`` no longer dumps everything):
+  A registry row is 4–17 KB of JSON (customPayloadSchema + slotMapping +
+  variants dominate), so ``--list-templates --json-output`` over a real
+  registry produced a six-figure-character blob. Every caller of this CLI is
+  an LLM tool call, and that blob overflowed the tool-result budget outright —
+  the agent got an "exceeds maximum allowed tokens" error instead of the
+  template definition it asked for, i.e. the mode that existed *to* read a
+  template's contract was the one mode that could never be read.
+
+  So the list verb emits **summaries** (identity + how to choose: name,
+  description, aspects, language, status, tags, variant ids, the capability
+  keys that drive authoring, a truncated llmHint) and ``--template-id <id>``
+  emits the **full definition** of the one
+  template the agent picked. That is the shape ``registry_loader``'s P1.2 note
+  already anticipated, realized CLI-side so it works before the backend
+  list/detail endpoints exist. ``--full`` still dumps whole definitions for
+  programmatic callers, guarded by a size check so it can't silently recreate
+  the overflow.
+
 Flags:
-  --list-templates                 (accepted; listing is the only verb)
+  --list-templates                 (accepted; listing is the default verb)
+  --template-id <id>               print the FULL definition of this template
+                                   (repeatable); this is the detail verb
+  --full                           in list mode, emit full definitions instead
+                                   of summaries (size-guarded; prefer
+                                   --template-id)
   --list-examples                  list *.dsl.json / *.binding.json reference
                                    examples grouped by templateId (consumed
                                    by downstream agents that want to read a
@@ -44,9 +68,19 @@ from registry_loader import (  # noqa: E402
     EXIT_NOT_AUTHENTICATED,
     RegistryAuthError,
     RegistryUnreachableError,
+    get_template,
     list_templates as load_visible_templates,
 )
 
+# Summary llmHint budget: enough to tell templates apart when choosing, far
+# short of the multi-KB authoring contract (read that with --template-id).
+_SUMMARY_HINT_CHARS = 200
+
+# Upper bound for a multi-template full dump (--full). ~60 K chars ≈ 20 K
+# tokens: still large, but inside a tool-result budget, and the message it
+# fails with names the flag that replaces it.
+_MAX_FULL_DUMP_CHARS = 60_000
+
 
 def _matches(tpl: dict, tag: str | None, aspect: str | None, language: str | None) -> bool:
     if tag:
@@ -74,6 +108,57 @@ def _status_of(tpl: dict) -> str:
     return "stable"
 
 
+def _truncate(text: object, limit: int) -> str | None:
+    if not isinstance(text, str) or not text.strip():
+        return None
+    text = text.strip()
+    return text if len(text) <= limit else text[: limit - 3] + "..."
+
+
+def _summarize(tpl: dict) -> dict:
+    """The "choose a template" view: identity + selection criteria only.
+
+    Deliberately excludes the authoring contract (llmHint in full,
+    customPayloadSchema, slideSchemas, slotMapping, compositions, variants' style bodies) —
+    that is what ``--template-id`` returns, one template at a time.
+    """
+    variants = tpl.get("variants")
+    # Only the scalar capability keys that change how a caller *drives* the
+    # template (narration vs typewriter caption, who decides duration). The
+    # rest of `capabilities` — payloadDefaults above all — is bulk that scales
+    # with the registry, so it stays in the detail view.
+    caps = tpl.get("capabilities") if isinstance(tpl.get("capabilities"), dict) else {}
+    caps_summary = {
+        k: caps[k]
+        for k in ("payloadStyle", "needsNarration", "durationStrategy", "narrationDriver")
+        if k in caps
+    }
+    summary = {
+        "templateId": tpl.get("templateId"),
+        "name": tpl.get("name"),
+        "description": tpl.get("description"),
+        "status": _status_of(tpl),
+        "supportedAspectRatios": tpl.get("supportedAspectRatios") or [],
+        "contentLanguage": tpl.get("contentLanguage") or [],
+        "styleTags": tpl.get("styleTags") or [],
+        "variantIds": sorted(variants.keys()) if isinstance(variants, dict) else [],
+        "capabilities": caps_summary,
+        "llmHintPreview": _truncate(tpl.get("llmHint"), _SUMMARY_HINT_CHARS),
+    }
+    hint = tpl.get("llmHint")
+    if isinstance(hint, str) and len(hint.strip()) > _SUMMARY_HINT_CHARS:
+        summary["llmHintTruncated"] = True
+    return summary
+
+
+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 / slideSchemas / "
+        "slotMapping / variants) — that is the per-template authoring contract."
+    )
+
+
 # ----- Examples discovery (--list-examples) ---------------------------------
 #
 # Examples live under <SkillDir>/video_dsl/schema/examples/ as `*.dsl.json` and
@@ -129,7 +214,12 @@ def main() -> None:
         description="List available video templates from the registry.",
     )
     ap.add_argument("--list-templates", action="store_true",
-                    help="List every available template (the only CLI verb).")
+                    help="List every available template (summaries; the default verb).")
+    ap.add_argument("--template-id", action="append", dest="template_ids", metavar="ID",
+                    help="Print this template's FULL definition (repeatable).")
+    ap.add_argument("--full", action="store_true",
+                    help="List mode: emit full definitions instead of summaries "
+                         "(size-guarded; prefer --template-id).")
     ap.add_argument("--list-examples", action="store_true",
                     help="List reference examples (*.dsl.json / *.binding.json) grouped by templateId.")
     ap.add_argument("--filter-tag", help="Keep templates whose styleTags match this substring.")
@@ -168,9 +258,12 @@ 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 `--list-templates --json-output` (that mode emits each "
-                "template's full definition; the table view truncates llmHint to 200 chars).",
+                "   Read it with `--template-id <id> --json-output` (one template's full "
+                "definition). Run `--list-templates` first if you need the ids;\n"
+                "   that view is summaries only — pointing it at the whole registry "
+                "returns more JSON than a tool result can carry.",
             )
             return
         print(f"\n{'Template ID':<28} Files")
@@ -201,13 +294,74 @@ def main() -> None:
         print(f"❌ {exc}", file=sys.stderr)
         sys.exit(1)
 
+    # ----- detail mode (--template-id) ---------------------------------------
+    #
+    # Explicit ids win over --filter-*: the caller already chose, and silently
+    # returning nothing because a stale filter excluded the pick would read as
+    # "template does not exist".
+    if args.template_ids:
+        by_id = {t.get("templateId"): t for t in templates}
+        picked: list[dict] = []
+        missing: list[str] = []
+        for tid in args.template_ids:
+            tpl = by_id.get(tid)
+            if tpl is None:
+                missing.append(tid)
+            else:
+                picked.append(tpl)
+        if missing:
+            for tid in missing:
+                # Distinguish "gated out by status" from "does not exist" —
+                # otherwise a beta template reads as a typo and the caller
+                # retries the id instead of passing --include-beta.
+                gated = get_template(tid, include_all_statuses=True)
+                if gated is not None:
+                    print(
+                        f"❌ Template '{tid}' exists but its status is "
+                        f"'{_status_of(gated)}' — pass --include-beta to read it.",
+                        file=sys.stderr,
+                    )
+                else:
+                    print(f"❌ Unknown template id: '{tid}'", file=sys.stderr)
+            known = ", ".join(sorted(str(t.get("templateId")) for t in templates))
+            print(f"   Available ids: {known}", file=sys.stderr)
+            sys.exit(1)
+        if args.json_output:
+            print(json.dumps({"templates": picked}, ensure_ascii=False))
+        else:
+            # Pretty-printed rather than tabular: the whole point of detail mode
+            # is the nested contract (customPayloadSchema / slotMapping), which
+            # a table cannot show.
+            print(json.dumps({"templates": picked}, ensure_ascii=False, indent=2))
+        return
+
     visible = [
         t for t in templates
         if _matches(t, args.filter_tag, args.filter_aspect, args.filter_language)
     ]
 
     if args.json_output:
-        print(json.dumps({"templates": visible}, ensure_ascii=False))
+        if args.full:
+            payload = json.dumps({"templates": visible}, ensure_ascii=False)
+            if len(payload) > _MAX_FULL_DUMP_CHARS and len(visible) > 1:
+                print(
+                    f"❌ Full definitions for {len(visible)} template(s) are "
+                    f"{len(payload):,} characters — past the {_MAX_FULL_DUMP_CHARS:,}-char "
+                    "cap, and past what a tool result can carry.\n"
+                    "   Read one template at a time with `--template-id <id> --json-output`, "
+                    "or narrow with --filter-tag / --filter-aspect / --filter-language.",
+                    file=sys.stderr,
+                )
+                sys.exit(1)
+            print(payload)
+            return
+        print(json.dumps(
+            {
+                "templates": [_summarize(t) for t in visible],
+                "detailHint": _detail_hint(),
+            },
+            ensure_ascii=False,
+        ))
         return
 
     if not visible:
@@ -233,12 +387,16 @@ def main() -> None:
         status = _status_of(tpl).ljust(8)
         tags = ", ".join((tpl.get("styleTags") or [])[:5])
         print(f"{tid} {name} {ratios} {lang} {status} {tags}")
-        hint = tpl.get("llmHint")
+        hint = _truncate(tpl.get("llmHint"), _SUMMARY_HINT_CHARS)
         if hint:
-            hint = hint if len(hint) <= 200 else hint[:197] + "..."
             print(f"{' ' * 22}   ↳ {hint}")
 
     print(f"\n{len(visible)} template(s) shown")
+    first_id = str(visible[0].get("templateId", "<templateId>"))
+    print(
+        f"Full definition of one template: --template-id {first_id} --json-output "
+        "(llmHint / customPayloadSchema / slideSchemas / slotMapping / variants)",
+    )
 
 
 if __name__ == "__main__":

package/skills/template-registry/skill.json

@@ -4,20 +4,22 @@
   "tier": "orchestration",
   "category": "authoring",
   "title": "Video Template Registry",
-  "description": "List all available video templates (templateId / name / aspect ratio / style tags). Template-to-DSL binding is no longer exposed as a separate step — once prepare_video_assets receives a template_id it runs the full DSL→RenderPlan pipeline internally.",
+  "description": "List all available video templates (templateId / name / aspect ratio / style tags), or read one template's full definition with template_id. Listing returns summaries; pass template_id to get that template's authoring contract (llmHint / customPayloadSchema / slotMapping / variants). Template-to-DSL binding is no longer exposed as a separate step — once prepare_video_assets receives a template_id it runs the full DSL→RenderPlan pipeline internally.",
   "auth": "required",
   "envVars": ["PRIV_TOKEN", "VIDEO_TEMPLATE_REGISTRY_URL", "MM_API_BASE_URL", "VIDEO_TEMPLATE_REGISTRY_HTTP_METHOD"],
   "entry": { "type": "python", "scriptPath": "scripts/list_templates.py" },
   "parameters": {
     "type": "object",
     "properties": {
-      "list_templates": { "type": "boolean", "description": "List available templates (default behavior; also implied when other flags are passed)." },
-      "list_examples": { "type": "boolean", "description": "List the *.dsl.json / *.binding.json reference examples shipped under template-registry/video_dsl/schema/examples/, grouped by templateId. Useful for downstream agents (e.g. a creation agent) that want to read a template's reference shape before producing new DSL." },
+      "list_templates": { "type": "boolean", "description": "List available templates as summaries — templateId / name / description / aspect ratios / language / status / styleTags / variantIds / key capabilities / a truncated llmHint (default behavior; also implied when other flags are passed)." },
+      "template_id": { "type": "string", "description": "Return this template's FULL definition instead of the summary list: llmHint in full, customPayloadSchema (every template-specific field incl. the legal slideId values), slotMapping, compositions, variants. This is the per-template authoring contract — read it before writing DSL for that template." },
+      "full": { "type": "boolean", "description": "List mode only: emit full definitions for every listed template instead of summaries. Rejected when the result would be too large for one tool result — prefer template_id, or narrow with the filter_* parameters." },
+      "list_examples": { "type": "boolean", "description": "List the *.dsl.json / *.binding.json reference examples under template-registry/video_dsl/schema/examples/, grouped by templateId. That directory is optional and is not part of the published package, so this is normally empty — to read a template's reference shape, use template_id instead (the registry's own contract)." },
       "filter_tag": { "type": "string", "description": "Show only templates whose styleTags contain (or are contained in) this string. Case-insensitive. E.g. 'tech' / '科普' / 'walkthrough'." },
       "filter_aspect": { "type": "string", "description": "Show only templates that declare this aspect ratio. E.g. '9:16' / '16:9' / '1:1'." },
       "filter_language": { "type": "string", "description": "Show only templates whose contentLanguage includes this code ('zh' or 'en'). Templates with no declared language are always shown (treated as language-agnostic)." },
       "include_beta": { "type": "boolean", "description": "Also list templates with status='beta'. Default off (only 'stable' shows). The ENABLE_BETA_TEMPLATES env var has the same effect process-wide." },
-      "json_output": { "type": "boolean", "description": "Emit a JSON result ({ templates: [...] } or { examples: [...] }) instead of the human-readable table." }
+      "json_output": { "type": "boolean", "description": "Emit a JSON result instead of the human-readable table: { templates: [...] } — summaries, or full definitions when template_id / full is set — or { examples: [...] }." }
     },
     "required": []
   }

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,137 @@ def _check_slide_id_chosen(dsl: dict) -> list[ValidationError]:
     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
+
+        base = f"scenes[{idx}].customPayload.templateData"
+        errors += _check_payload_object(
+            data,
+            schema,
+            path=base,
+            scene=sid,
+            extra_allowed=shared,
+            # frame 级字段由 Composition 消费,「整包态」binder 会把它们混进
+            # templateData —— 出现在这里是正当的,不算未声明字段。
+            skip_keys=_SLIDE_FRAME_LEVEL_KEYS,
+        )
+
+        # 卡片数组:用户真正会写错的地方在这一层(items[].title vs items[].name)。
+        for key, sub in (schema.get("properties") or {}).items():
+            if not isinstance(sub, dict) or sub.get("type") != "array":
+                continue
+            item_schema = sub.get("items")
+            if not isinstance(item_schema, dict) or not item_schema.get("properties"):
+                continue
+            value = data.get(key)
+            if not isinstance(value, list):
+                continue
+            for i, item in enumerate(value):
+                if not isinstance(item, dict):
+                    continue
+                errors += _check_payload_object(
+                    item, item_schema, path=f"{base}.{key}[{i}]", scene=sid,
+                )
+
+    return errors
+
+
+def _check_payload_object(
+    data: dict,
+    schema: dict,
+    *,
+    path: str,
+    scene: str,
+    extra_allowed: Optional[dict] = None,
+    skip_keys: frozenset = frozenset(),
+) -> list[ValidationError]:
+    """一层对象的「未声明字段 + 缺必填字段」核对。数组元素与顶层共用这一份。"""
+    props = schema.get("properties")
+    if not isinstance(props, dict):
+        return []
+    allowed = set(props) | set(extra_allowed or {})
+
+    errors: list[ValidationError] = []
+
+    for key in data:
+        if key in allowed or key in skip_keys:
+            continue
+        hint = difflib.get_close_matches(key, sorted(allowed), n=1, cutoff=0.6)
+        suggestion = (
+            f" Did you mean '{hint[0]}'?" if hint
+            else f" Declared fields: {', '.join(sorted(allowed))}."
+        )
+        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)."
+            f"{suggestion}",
+        ))
+
+    for key in schema.get("required") or []:
+        if data.get(key) is None:
+            errors.append(ValidationError(
+                f"{path}.{key}",
+                f"scene '{scene}': required field '{key}' is missing — without it the slide "
+                "renders its built-in placeholder instead of your content.",
+            ))
+
+    return errors
+
+
 def _check_narration_language_strict(dsl: dict) -> list[ValidationError]:
     """完整版:模板若声明 ``capabilities.narrationLanguageStrict`` 则强约束旁白语言。
 
@@ -525,6 +673,9 @@ 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)
     return errors
 
 
@@ -553,6 +704,7 @@ 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)
     return errors