@remixmate/cli 0.9.29 → 0.9.31

package/dist/manifest.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
-  "version": "0.9.29",
-  "generatedAt": "2026-09-14T08:49:05.207Z",
+  "version": "0.9.31",
+  "generatedAt": "2026-09-14T15:38:04.716Z",
   "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.29",
+  "version": "0.9.31",
   "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

@@ -37,26 +37,37 @@ Turns a user-supplied **topic** into a **Video DSL v1alpha1** JSON describing wh
 
 ## DSL schema
 
-The full schema is `template-registry` skill's `video_dsl/schema/video-dsl-v1alpha1.json`; examples live in `video_dsl/schema/examples/` (locate them through `template-registry`'s `Base directory for this skill`).
+The full schema is `template-registry` skill's `video_dsl/schema/video-dsl-v1alpha1.json`.
+
+**Per-template reference DSLs do not ship with this package.** `video_dsl/schema/examples/` is a local-only directory: it is absent from the published npm package (and has never existed in the repo), so `template_registry list_examples=true` normally returns nothing. Do not read "no examples found" as "this template is unsupported" — the authoritative per-template contract ships inside the registry's `template.json`, see below.
 
 ## Agent behavior: DSL generation when a template is selected
 
-**When the user explicitly specifies a template id, the agent must first read the existing `*.dsl.json` and `*.binding.json` examples in `template-registry`'s `video_dsl/schema/examples/`, then generate the DSL in the template's native shape using both those examples and the template's `template.json`. The agent must not generate the DSL from scratch ignoring the examples, and must not produce a generic DSL first and rely on `template-registry` to force-match the template later.**
+**When the user explicitly specifies a template id, the agent must first read that template's full definition from the registry, then generate the DSL in the template's native shape. The agent must not generate the DSL from scratch ignoring the template definition, and must not produce a generic DSL first and rely on `template-registry` to force-match the template later.**
 
-The intent is to reuse the validated example shapes already in the repo and to avoid the failure mode where "the generic DSL looks compatible on the surface, but is missing template-specific fields, has the wrong nesting, or binds incorrectly — only to fail later at binding or render time". Examples:
+The intent is to avoid the failure mode where "the generic DSL looks compatible on the surface, but is missing template-specific fields, has the wrong nesting, or binds incorrectly — only to fail later at binding or render time". Examples:
 
-- A template may require fields the generic DSL never emits (a slide id, a word list, an avatar assetRef) — its own `dsl-example.json` is the only place that shows which.
-- Different templates' `binding.json` may reflect different `slotMapping` choices, asset-binding styles, and scene organization.
+- A template may require fields the generic DSL never emits (a slide id, a word list, an avatar assetRef). `customPayloadSchema` is what declares them.
+- Templates differ in `slotMapping` choices, asset-binding styles, and scene organization.
 
 ### Mandatory steps
 
-1. Visit `template-registry/video_dsl/schema/examples/` and locate the closest existing `*.dsl.json` and `*.binding.json` for the requested template.
-2. Read those examples and understand the actual DSL shape, the `templateData` fields, the scene organization, and the binding style the template uses.
-3. Read the template's `template.json`.
-4. Combine the examples and `template.json` to understand the template's `slotMapping`, `requiredProps`, `optionalProps`, `propExtractors`, `assetRequirements`, `supportedAspectRatios`, and `scenePatterns`.
-5. Generate the DSL using the example's shape and the template's native requirements — not the generic DSL shape.
-6. Make sure the DSL explicitly contains every template-specific field, e.g. `templateData.words`, `templateData.slideId`, `visuals.avatar.assetRef`.
-7. After generation, run the schema check and show the script summary to the user for confirmation.
+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.
+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`.
+7. If `template_registry list_examples=true` does return files locally, read them as an extra sample — never as a substitute for step 1.
+8. After generation, run the schema check and show the script summary to the user for confirmation.
+
+### Multi-layout templates: pick a layout per scene
+
+When a template's `customPayloadSchema.slideId.enum` holds more than one value (today `html-slide` and `html-slide-blackboard`, 16 layouts each), **every scene must name one**, chosen to fit that scene's information shape — a comparison, a timeline, a code walkthrough and a set of numbers are four different layouts.
+
+`gen_script.py` cannot make that choice: it emits the placeholder `"slideId": "__CHOOSE_SLIDE__"`, and the DSL validator rejects any DSL that still carries it, listing the legal values in the error. Replace every placeholder, and do not reuse one layout for the whole video.
+
+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.
 
 ### On-screen text: the rules live in the template, not here
 
@@ -69,23 +80,26 @@ Two consequences for the agent:
 
 ### Hard constraints
 
-- **Forbidden**: the user specified a template, but the agent generated the DSL without reading any of the existing examples under `template-registry/video_dsl/schema/examples/`.
-- **Forbidden**: only reading `template.json` while ignoring the existing `*.dsl.json` and `*.binding.json` examples.
+- **Forbidden**: the user specified a template, but the agent generated the DSL without reading that template's full `template.json` (`llmHint` + `customPayloadSchema` included).
+- **Forbidden**: leaving any `"__CHOOSE_SLIDE__"` placeholder in the DSL, or shipping scenes with no `customPayload.slideId` on a multi-layout template.
+- **Forbidden**: reusing a single `slideId` across the whole video on a multi-layout template because it was the first one in the enum.
 - **Forbidden**: the user specified a template, but the agent first generated a generic DSL and then passed `--template-id` to `template-registry` to force-bind it.
 - **Forbidden**: continuing into binding / rendering despite knowing that template-specific fields, scene shapes, or binding details are missing.
 - **Forbidden**: silently degrading to a generic DSL because the current script cannot support a template, leaving the failure to the downstream stage.
 
 ### When a template is not yet supported
 
-If `template-registry/video_dsl/schema/examples/` has no matching example for the requested template, or `gen_script.py` cannot yet build the required DSL shape, the agent must clearly tell the user "this template is not yet supported for auto-generation from existing examples" and explain what key fields, structure, or binding info are missing. Possible next steps:
+"No examples found" is **not** this case — see the note under *DSL schema*; examples do not ship, and `template.json` is the contract.
+
+This case is: the template's `customPayloadSchema` / `slotMapping` demands a shape `gen_script.py` cannot build and the agent cannot hand-assemble. Then say clearly that the template is not yet supported for auto-generation, and name the fields, structure or binding info that are missing. Possible next steps:
 
-1. Ask the user to switch to a template that has an example and is already supported.
-2. Have the agent take the closest `*.dsl.json` / `*.binding.json` as a reference and hand-craft the required DSL structure for this template, then show it to the user for confirmation.
+1. Ask the user to switch to a template whose shape is already supported.
+2. Hand-craft the required DSL structure from `customPayloadSchema` and `slotMapping`, then show it to the user for confirmation.
 3. Stop the flow and wait for the user to decide, rather than emitting a DSL that "looks like it matches but cannot render".
 
 ### Design principle
 
-When the user specifies a template, `gen-script`'s goal is no longer "produce a generally-compatible DSL" but "produce a template-native DSL based on the existing examples in `template-registry`".
+When the user specifies a template, `gen-script`'s goal is no longer "produce a generally-compatible DSL" but "produce a template-native DSL that satisfies that template's own declared contract".
 
 ## Authentication & environment
 
@@ -462,4 +476,4 @@ prefix and version — not a short alias:
 |------|---------|
 | `gen_script.py` | Core script — produces the Video DSL JSON from a topic. |
 
-The authoritative DSL examples live under `template-registry/video_dsl/schema/examples/`; list them with `template_registry list_examples=true`.
+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.

package/skills/gen-script/scripts/gen_script.py

@@ -196,12 +196,11 @@ def _localize_label(language, key, **fmt):
             "zh": "[骨架待填充] 关于{topic}的内容({duration}s)",
             "en": "[skeleton placeholder] Content about {topic} ({duration}s)",
         },
-        "point_description": {
-            "zh": "关于{topic}的要点内容",
-            "en": "A key point about {topic}",
-        },
+        # NOTE: 这里曾有 "point_description"（"关于{topic}的要点内容"）与
+        # "more_about"（"更多关于{topic}的内容"）两条，用来给 no-visual 场景拼画面
+        # 文案。两条都已删除：topic 长度不受控，拼进画面必然溢出，而正确的文案来源
+        # 是调用方给的 --headline / --subheadline。
         "follow_us": {"zh": "关注我们", "en": "Follow us"},
-        "more_about": {"zh": "更多关于{topic}的内容", "en": "More about {topic}"},
         "video_description": {
             "zh": "关于「{topic}」的{duration}秒短视频",
             "en": "A {duration}s short video about \"{topic}\"",
@@ -938,33 +937,52 @@ def _build_carousel_caption_dsl(
     return dsl
 
 
-def _build_custom_payload(purpose: str, topic: str, label: str, idx: int, total_scenes: int, language: str = DEFAULT_LANGUAGE) -> dict:
-    """Build customPayload with slideId and templateData for template-native scenes."""
-    if purpose == "opening":
-        return {
-            "slideId": "demo-concept-overview",
-            "templateData": {
-                "title": topic,
-            },
-        }
-    elif purpose == "cta":
-        return {
-            "slideId": "demo-concept-overview",
-            "templateData": {
-                "title": topic,
-            },
-        }
-    else:
-        palette = ["#6C5CE7", "#00B894", "#E17055", "#0984E3", "#FDCB6E", "#A29BFE", "#FF7675"]
-        return {
-            "slideId": "demo-single-concept",
-            "templateData": {
-                "icon": "💡",
-                "title": label,
-                "description": _localize_label(language, "point_description", topic=topic),
-                "accentColor": palette[idx % len(palette)],
-            },
-        }
+# 「作者还没选版式」的显式标记。
+#
+# 为什么是哨兵而不是留空:slideId 缺失会静默回落到 DefaultSlide —— 渲染成功、零日志、
+# 退出码 0，画面只剩一行居中标题，正是要消灭的失效形态。哨兵让下游能区分「作者没选」
+# 与「作者选了但拼错」，两者的修法不同。dsl_validator 见到它会硬拒绝（同名常量在
+# video_dsl/runtime/dsl_validator.py，两处字面量必须一致）。
+SLIDE_ID_SENTINEL = "__CHOOSE_SLIDE__"
+
+
+def _is_multi_slide_template(template_config: dict | None) -> bool:
+    """模板是否注册了多个可选版式 —— 由模板自己声明，不看模板 id。
+
+    判据是 ``customPayloadSchema.slideId.enum`` 有没有超过一个取值：有得挑才谈得上
+    「该挑哪个」。dsl_validator 的 ``_check_slide_id_chosen`` 用的是同一条判据，两侧
+    因此不会对同一个模板给出相反的结论。
+
+    **刻意不写死模板 id**：哪个模板有几种版式是模板自己的事实，真源在它的
+    ``template.json``；把名单抄进 CLI，模板改名 / 新增多版式模板都要跟着发一次 npm，
+    而漏发的表现是"这个模板又开始只出一种版式了"——正是本次要修的那个形态。
+    """
+    schema = (template_config or {}).get("customPayloadSchema")
+    if not isinstance(schema, dict):
+        return False
+    slide_schema = schema.get("slideId")
+    enum = slide_schema.get("enum") if isinstance(slide_schema, dict) else None
+    return isinstance(enum, list) and len(enum) > 1
+
+
+def _build_custom_payload(template_config: dict | None) -> dict:
+    """骨架阶段的 customPayload —— **不猜版式、不拼画面文案**。
+
+    这个函数曾经按 purpose 写死两种 slideId（opening / cta → demo-concept-overview，
+    其余 → demo-single-concept），于是 16 种注册版式里只有 2 种会被用到，且与内容
+    形态完全无关 —— 线上「不论选题版式永远一样」就是这么来的。它还往
+    templateData.description 里拼 "关于{topic}的要点内容"，topic 长度不受控，画面
+    溢出是必然的。
+
+    现在分两档：
+
+      - 多版式模板 → 只放哨兵，等 agent 按内容挑版式并填 templateData；
+      - 其余 no-visual 模板 → 空载荷。这些模板只有一种版式，没有可挑的东西，而注入
+        它们 schema 不认识的字段只会把真正要的 slide / statement / item 挤掉。
+    """
+    if _is_multi_slide_template(template_config):
+        return {"slideId": SLIDE_ID_SENTINEL, "templateData": {}}
+    return {}
 
 
 def build_dsl(
@@ -1346,11 +1364,19 @@ def build_dsl(
             # （已核对），渲染走的是 slotMapping / compositionId。所以换值不改成片。
             _layout_cfg = (template_config or {}).get("capabilities") or {}
             layout = _layout_cfg.get("defaultLayout") or template_id or "text-overlay"
+            # ⚠️ 画面文字用 effective_headline / effective_subheadline，与上面的
+            # has_visual 分支同源。这两条分支长期分叉：visual 分支一直用的是
+            # --headline，no-visual 分支却渲染裸 topic —— SKILL.md 写着"用户给了标题
+            # 就传 --headline，否则 headline 会回落成长 topic 并撑破顶部文字层"，
+            # agent 照做了，这条分支没兑现。调用方把整篇提纲当 topic 传进来时，成片
+            # 必然是一屏文字墙，而 meta.headline 里存的又是对的，只看 meta 查不出来。
             text_layers = []
             if plan["purpose"] == "opening":
                 text_layers = [
-                    {"role": "headline", "content": topic, "animation": "fade-in"},
+                    {"role": "headline", "content": effective_headline, "animation": "fade-in"},
                 ]
+                if effective_subheadline:
+                    text_layers.append({"role": "subheadline", "content": effective_subheadline, "animation": "fade-in"})
             elif plan["purpose"] == "point":
                 text_layers = [
                     {"role": "headline", "content": plan["label"], "animation": "slide-up"},
@@ -1358,10 +1384,11 @@ def build_dsl(
             elif plan["purpose"] == "cta":
                 text_layers = [
                     {"role": "headline", "content": _localize_label(output_language, "follow_us"), "animation": "zoom-in"},
-                    {"role": "subheadline", "content": _localize_label(output_language, "more_about", topic=topic), "animation": "fade-in"},
                 ]
+                if effective_subheadline:
+                    text_layers.append({"role": "subheadline", "content": effective_subheadline, "animation": "fade-in"})
 
-            custom_payload = _build_custom_payload(plan["purpose"], topic, plan["label"], idx, len(scene_plans), language=output_language)
+            custom_payload = _build_custom_payload(template_config)
 
             scene = {
                 "id": scene_id,
@@ -1369,8 +1396,11 @@ def build_dsl(
                 "duration": plan["duration"],
                 "layout": layout,
                 "textLayers": text_layers,
-                "customPayload": custom_payload,
             }
+            # 单版式模板的载荷是空 dict —— 写一个空 customPayload 只会让 agent 以为
+            # 这里有个需要填的结构，干脆不写这个键。
+            if custom_payload:
+                scene["customPayload"] = custom_payload
             if needs_narration:
                 scene["audio"] = {
                     "narration": {

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, 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 / 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.")
@@ -151,10 +241,28 @@ def main() -> None:
             print(json.dumps({"examples": examples}, ensure_ascii=False))
             return
         if not examples:
+            # 这**不是**异常状态,而是常态:该目录从未进过仓库,也就从未随包发布过。
+            #
+            # 旧文案("This package may have shipped without reference examples;
+            # check the cli source repo or upgrade @remixmate/cli")把常态说成了事故,
+            # 而 gen-script 的 SKILL.md 又把「先读这里的参考 DSL」列为强制第一步 ——
+            # 于是线上 agent 每次都在这里撞空,然后退回 gen_script 的骨架照抄,连模板
+            # 自己声明的版式都不去看。升级 CLI 修不了它,因为没有哪一版带过这些文件。
+            #
+            # 真正随包到达调用方的逐模板契约是 registry 里的 template.json,所以这里
+            # 直接把人指过去,而不是让它以为"该模板不受支持"。
             print(
-                f"⚠️  No examples found under {_EXAMPLES_DIR}.\n"
-                "   This package may have shipped without reference examples; "
-                "check the cli source repo or upgrade @remixmate/cli.",
+                f"ℹ️  No local reference DSLs under {_EXAMPLES_DIR} — that directory is "
+                "optional and is not part of the published package.\n"
+                "   This does NOT mean the template is unsupported. The per-template "
+                "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"
+                "     • 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"
+                "   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")
@@ -185,13 +293,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:
@@ -217,12 +386,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 / 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

@@ -380,6 +380,64 @@ def _check_narration_items_count(dsl: dict) -> list[ValidationError]:
     return errors
 
 
+# gen_script 写进骨架的「作者还没选版式」哨兵。
+#
+# 两处必须是同一个字面量,而 gen-script 与 template-registry 是两个独立 skill 目录、
+# 没有共享模块可以 import,所以这里复制一份。改动需同步 gen_script.py 的
+# ``SLIDE_ID_SENTINEL``(那边的注释也指回这里)。
+SLIDE_ID_SENTINEL = "__CHOOSE_SLIDE__"
+
+
+def _check_slide_id_chosen(dsl: dict) -> list[ValidationError]:
+    """多版式模板的每个场景都必须显式选一个 ``customPayload.slideId``。
+
+    为什么需要这道门禁:slideId 缺失(或还是哨兵)时,渲染端会静默回落到
+    ``DefaultSlide`` —— 渲染成功、零日志、退出码 0,画面只剩一行居中标题。这是整条
+    管线里最安静的失效方式,看起来"像是模板本来就长这样",只有付完渲染的钱才会发现。
+
+    **判定「是不是多版式模板」不写死模板 id**,而是看模板自己声明的
+    ``customPayloadSchema.slideId.enum`` 有没有超过一个取值 —— 有得挑才要求挑。
+    单版式模板(枚举只有一项或压根没声明)不拦:那里没有可选的东西,报错只会变成
+    修不掉的常驻噪音。
+
+    报错文案直接把该模板全部可选 slideId 列出来,因为收到这条错误的调用方多半
+    正是那个"不知道有哪些版式"的 agent。
+    """
+    tpl = _get_template_cfg(_pick_template_id(dsl))
+    if not tpl:
+        return []
+    schema = tpl.get("customPayloadSchema")
+    if not isinstance(schema, dict):
+        return []
+    slide_schema = schema.get("slideId")
+    enum = slide_schema.get("enum") if isinstance(slide_schema, dict) else None
+    if not isinstance(enum, list) or len(enum) <= 1:
+        return []
+
+    tid = tpl.get("templateId", "<unknown>")
+    choices = ", ".join(str(x) for x in enum)
+    errors: list[ValidationError] = []
+    for idx, scene in enumerate(dsl.get("scenes", []) or []):
+        sid = scene.get("id", f"scenes[{idx}]")
+        custom = scene.get("customPayload") or {}
+        slide_id = custom.get("slideId") or (custom.get("templateData") or {}).get("slideId")
+        if isinstance(slide_id, str) and slide_id and slide_id != SLIDE_ID_SENTINEL:
+            continue
+        reason = (
+            "still holds the gen_script placeholder"
+            if slide_id == SLIDE_ID_SENTINEL
+            else "has no slideId"
+        )
+        errors.append(ValidationError(
+            f"scenes[{idx}].customPayload.slideId",
+            f"scene '{sid}' {reason} — template '{tid}' registers several layouts and "
+            "one must be chosen per scene, otherwise the whole templateData is dropped "
+            "and the frame silently renders a single centred title.\n"
+            f"     Pick the one that matches this scene's information shape: {choices}",
+        ))
+    return errors
+
+
 def _check_narration_language_strict(dsl: dict) -> list[ValidationError]:
     """完整版:模板若声明 ``capabilities.narrationLanguageStrict`` 则强约束旁白语言。
 
@@ -463,6 +521,10 @@ def validate_integrity(dsl: dict) -> list[ValidationError]:
     errors += _check_asset_duplicates(dsl)
     errors += _check_scene_asset_refs(dsl)
     errors += _check_narration_items_count(dsl)
+    # 新增(非历史规则):多版式模板必须逐场景选定 slideId。放进 integrity 集合是因为
+    # render-video 与 prepare_video_assets 都走这条 —— 而"没选版式"正是要在烧掉渲染
+    # 积分之前拦住的东西。单版式模板不受影响,见 _check_slide_id_chosen。
+    errors += _check_slide_id_chosen(dsl)
     return errors
 
 
@@ -490,6 +552,7 @@ def validate_dsl(dsl: dict) -> list[ValidationError]:
     errors += _check_assetbindings_deprecation(dsl)
     errors += _check_narration_items_count(dsl)
     errors += _check_narration_language_strict(dsl)
+    errors += _check_slide_id_chosen(dsl)
     return errors