@remixmate/cli 0.9.28 → 0.9.30

package/dist/diagnostics.d.ts

@@ -0,0 +1,4 @@
+export declare function traceHeaders(): Record<string, string>;
+export declare function cleanDiagnosticText(value: string): string;
+/** Opt-in line framing for hosts; stdout is exclusively the existing skill protocol. */
+export declare function diagnostic(exitCode: number, durationMs: number, error?: unknown): void;

package/dist/diagnostics.js

@@ -0,0 +1,39 @@
+import { randomBytes, randomUUID } from 'node:crypto';
+export function traceHeaders() {
+    const parent = process.env.AB_TRACEPARENT ?? '';
+    const match = /^00-([a-f0-9]{32})-([a-f0-9]{16})-[a-f0-9]{2}$/.exec(parent);
+    const trace = match && !/^0+$/.test(match[1]) && !/^0+$/.test(match[2]) ? match[1] : randomBytes(16).toString('hex');
+    const header = `00-${trace}-${randomBytes(8).toString('hex')}-01`;
+    process.env.AB_TRACEPARENT = header;
+    process.env.AB_OPERATION_ID ||= randomUUID();
+    return { traceparent: header };
+}
+export function cleanDiagnosticText(value) {
+    let text = value.replace(/https?:\/\/[^\s"'<>]+/g, raw => {
+        try {
+            const url = new URL(raw);
+            return url.origin + url.pathname;
+        }
+        catch {
+            return '[url]';
+        }
+    }).replace(/(Bearer\s+|(?:token|secret|password|api[_-]?key)\s*[=:]\s*)[^\s,;}]+/gi, '$1[redacted]');
+    for (const [key, secret] of Object.entries(process.env)) {
+        if (/TOKEN|SECRET|PASSWORD|API_KEY/i.test(key) && secret && secret.length >= 6)
+            text = text.split(secret).join('[redacted]');
+    }
+    return Buffer.from(text).subarray(0, 2048).toString('utf8');
+}
+/** Opt-in line framing for hosts; stdout is exclusively the existing skill protocol. */
+export function diagnostic(exitCode, durationMs, error) {
+    if (process.env.AB_DIAGNOSTICS !== '1')
+        return;
+    traceHeaders();
+    const outcome = exitCode === 0 ? 'success' : exitCode === 130 ? 'cancelled' : [2, 3, 4].includes(exitCode) ? 'rejected' : 'failure';
+    const record = { schema_version: 1, timestamp: new Date().toISOString(), service: 'remixmate-cli', environment: process.env.APP_ENV ?? 'dev',
+        level: outcome === 'failure' ? 'error' : 'info', event: 'cli.execution.completed', message: 'CLI execution completed', outcome,
+        trace_id: process.env.AB_TRACEPARENT?.split('-')[1], operation_id: process.env.AB_OPERATION_ID,
+        duration_ms: durationMs, attributes: { exit_code: exitCode },
+        error: error instanceof Error ? { type: error.name, message: cleanDiagnosticText(error.message), stack: cleanDiagnosticText(error.stack ?? '') } : undefined };
+    process.stderr.write('__diagnostic_v1__ ' + JSON.stringify(record) + '\n');
+}

package/dist/http.js

@@ -18,6 +18,7 @@
  *   3. process.env.MM_BACKEND_API_URL   — ab-agent's convention (back-compat)
  *   4. https://api.remixmate.com/api    — production default (zero-config)
  */
+import { traceHeaders, cleanDiagnosticText } from './diagnostics.js';
 import { recordBilling } from './billing.js';
 import { resolvePrivToken, NOT_AUTHENTICATED_HINT } from './auth/resolve.js';
 import { attemptAutoLogin } from './auth/auto-login.js';
@@ -73,7 +74,7 @@ function buildHeaders(ctx, extra) {
         headers['x-invoke-agent'] = ctx.agentName;
     if (ctx.conversationId)
         headers['x-conversation-id'] = ctx.conversationId;
-    return { ...headers, ...extra };
+    return { ...headers, ...extra, ...traceHeaders() };
 }
 /**
  * POST JSON to ab-api and return the parsed business payload.
@@ -110,16 +111,16 @@ export async function mmPost(ctx, pathOrUrl, body, opts = {}) {
             throw new SkillError(`${NOT_AUTHENTICATED_HINT}\n   （后端返回 HTTP ${resp.status}）`, EXIT.NOT_AUTHENTICATED);
         }
         if (resp.status >= 500) {
-            throw new SkillError(`❌ API request failed (HTTP ${resp.status}): ${text}`, EXIT.BACKEND_UNREACHABLE);
+            throw new SkillError(`❌ API request failed (HTTP ${resp.status}): [response omitted]`, EXIT.BACKEND_UNREACHABLE);
         }
-        throw new SkillError(`❌ API request failed (HTTP ${resp.status}): ${text}`);
+        throw new SkillError(`❌ API request failed (HTTP ${resp.status}): [response omitted]`);
     }
     let parsed;
     try {
         parsed = JSON.parse(text);
     }
     catch {
-        throw new SkillError(`❌ failed to parse response, body is not JSON: ${text.slice(0, 200)}`);
+        throw new SkillError(`❌ failed to parse response, body is not JSON: [response omitted]`);
     }
     // Before the code check: a charged response is always code=0 today, but a
     // partial-failure envelope that still billed must not lose its billing line.
@@ -130,7 +131,7 @@ export async function mmPost(ctx, pathOrUrl, body, opts = {}) {
         if (parsed.code === 401 || parsed.code === 403) {
             throw new SkillError(`${NOT_AUTHENTICATED_HINT}\n   （后端返回 code=${parsed.code}${parsed.msg ? `: ${parsed.msg}` : ''}）`, EXIT.NOT_AUTHENTICATED);
         }
-        throw new SkillError(`❌ API returned a business error: ${parsed.msg ?? 'unknown error'} (code=${parsed.code})`);
+        throw new SkillError(`❌ API returned a business error: ${cleanDiagnosticText(parsed.msg ?? 'unknown error')} (code=${parsed.code})`);
     }
     return parsed.data ?? undefined;
 }

package/dist/manifest.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
-  "version": "0.9.28",
-  "generatedAt": "2026-09-13T13:40:09.148Z",
+  "version": "0.9.30",
+  "generatedAt": "2026-09-14T14:44:43.104Z",
   "skills": [
     {
       "id": "export-jianying",

package/dist/runner.js

@@ -9,6 +9,7 @@
  *
  * Resolves to the child process's exit code so cli.ts can propagate it.
  */
+import { diagnostic, cleanDiagnosticText, traceHeaders } from './diagnostics.js';
 import { spawn } from 'node:child_process';
 import path from 'node:path';
 import { findSkill, SKILLS_DIR } from './registry.js';
@@ -24,9 +25,14 @@ function tokenFlag(args) {
     return typeof value === 'string' ? value : undefined;
 }
 export async function runSkill(skillName, opts) {
+    const started = performance.now();
+    let exitCode = EXIT.ERROR;
+    let failure;
+    traceHeaders();
     const skill = findSkill(skillName, opts.baseDir ?? SKILLS_DIR);
     if (!skill) {
         process.stderr.write(`❌ skill not found: ${skillName}\n`);
+        diagnostic(EXIT.USAGE, performance.now() - started);
         return EXIT.USAGE;
     }
     try {
@@ -40,24 +46,26 @@ export async function runSkill(skillName, opts) {
             case 'python':
                 // Python children talk to ab-api themselves and print their own billing
                 // footer; nothing was charged through this process.
-                return await runPython(skill, opts.rawArgs, auth);
+                return exitCode = await runPython(skill, opts.rawArgs, auth);
             case 'http':
             case 'builtin':
-                return await runHandler(skill, opts.parsedArgs, auth);
+                return exitCode = await runHandler(skill, opts.parsedArgs, auth);
         }
     }
     catch (err) {
+        failure = err;
         if (err instanceof SkillError) {
-            process.stderr.write(err.message + '\n');
-            return err.exitCode;
+            process.stderr.write(cleanDiagnosticText(err.message) + '\n');
+            return exitCode = err.exitCode;
         }
-        process.stderr.write(`❌ unexpected error: ${err.message}\n`);
+        process.stderr.write(`❌ unexpected error: ${cleanDiagnosticText(err.stack ?? err.message)}\n`);
         return EXIT.ERROR;
     }
     finally {
         // In `finally` because a run can fail *after* a billed step (e.g. the image
         // generated and was charged, then the upload timed out) — spend gets
         // reported either way. No-ops when nothing was charged.
+        diagnostic(exitCode, performance.now() - started, failure);
         emitBillingFooter();
     }
 }
@@ -140,7 +148,7 @@ async function applyTakeContext(skill, opts, auth) {
             `(project ${take.projectId}${take.attempt ? `, attempt ${take.attempt}` : ''})\n`);
     }
     catch (err) {
-        process.stderr.write(`⚠️  无法归属本次产物（内容仍会正常生成，但不会出现在项目里）: ${err.message}\n`);
+        process.stderr.write(`⚠️  无法归属本次产物（内容仍会正常生成，但不会出现在项目里）: ${cleanDiagnosticText(err.message)}\n`);
     }
 }
 async function runPython(skill, rawArgs, auth) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remixmate/cli",
-  "version": "0.9.28",
+  "version": "0.9.30",
   "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 `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.
+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/render-video/scripts/remote_renderer_client.py

@@ -34,6 +34,9 @@ import urllib.error
 import urllib.parse
 import urllib.request
 from typing import Callable, Optional
+from pathlib import Path
+sys.path.insert(0, str(Path(__file__).resolve().parents[2] / "template-registry" / "scripts"))
+from log_diagnostics import trace_headers
 
 DEFAULT_API_BASE_URL = "https://api-render.remixmate.com"
 API_BASE_URL = (
@@ -87,6 +90,7 @@ def _build_headers(private_token: str, content_type: str = "application/json", c
         headers["x-invoke-agent"] = AGENT_NAME
     if conversation_id:
         headers["x-conversation-id"] = conversation_id
+    headers.update(trace_headers())
     return headers
 
 

package/skills/render-video/version.json

@@ -2,6 +2,6 @@
   "skillName": "render-video",
   "repoName": "agent-skill-media-maker",
   "skillId": "473",
-  "version": "V20",
+  "version": "V21",
   "skillDescription": "Final-render skill: loads a persisted RenderPlan by `job_id` and drives the Remotion engine to produce the final video.\n\nUse this skill as soon as the user mentions any of these intents (after assets are already prepared):\n- Render the video, composite the video, export the video\n- Turn the prepared assets into the final clip\n- Render with Remotion\n\nPrerequisite: assets must already be generated via `prepare_video_assets`. This skill never resolves or regenerates assets — pass it a `job_id` from a previous `prepare_video_assets` call.\n\n⚠️ Stop-and-confirm gate: never call this skill until the user has explicitly confirmed the assets prepared by `prepare_video_assets`. If those assets were prepared in the current turn and the user has not replied since, stop and ask instead of rendering."
 }

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

@@ -151,10 +151,26 @@ 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 `--list-templates --json-output` (that mode emits each "
+                "template's full definition; the table view truncates llmHint to 200 chars).",
             )
             return
         print(f"\n{'Template ID':<28} Files")

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

@@ -0,0 +1,32 @@
+"""Portable stdlib-only context and opt-in stderr diagnostics; never writes stdout."""
+import json
+import os
+import re
+import secrets
+import sys
+import time
+import uuid
+from datetime import datetime, timezone
+
+_started = time.monotonic()
+
+def trace_headers():
+    match = re.fullmatch(r'00-([a-f0-9]{32})-([a-f0-9]{16})-[a-f0-9]{2}', os.getenv('AB_TRACEPARENT', ''))
+    tid = match[1] if match and match[1] != '0'*32 and match[2] != '0'*16 else secrets.token_hex(16)
+    parent = f'00-{tid}-{secrets.token_hex(8)}-01'
+    os.environ['AB_TRACEPARENT'] = parent
+    os.environ.setdefault('AB_OPERATION_ID', str(uuid.uuid4()))
+    return {'traceparent': parent}
+
+def diagnostic(exit_code, kind='none', service='remixmate-studio-cli'):
+    if os.getenv('AB_DIAGNOSTICS') != '1':
+        return
+    trace_headers()
+    outcome = 'success' if exit_code == 0 else 'failure' if exit_code == 2 else 'rejected'
+    record = dict(schema_version=1, timestamp=datetime.now(timezone.utc).isoformat().replace('+00:00', 'Z'),
+        level='error' if outcome == 'failure' else 'info', service=service, environment=os.getenv('APP_ENV', 'dev'),
+        event='cli.execution.completed', message='CLI execution completed', outcome=outcome,
+        duration_ms=(time.monotonic()-_started)*1000, trace_id=os.environ['AB_TRACEPARENT'].split('-')[1],
+        operation_id=os.environ['AB_OPERATION_ID'], attributes={'exit_code': exit_code, 'error_kind': kind if re.fullmatch('[a-z_]{1,80}', str(kind)) else 'unknown'})
+    sys.stderr.write('__diagnostic_v1__ ' + json.dumps(record, ensure_ascii=False) + '\n')
+    sys.stderr.flush()

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

@@ -11,6 +11,7 @@ gen_jianying_draft.py 使用。
          两个变量语义相同，保留回退是为兼容只配了其中一个的部署环境。
 """
 
+from log_diagnostics import trace_headers
 import json
 import os
 import sys
@@ -34,6 +35,7 @@ def _make_headers(priv_token: str) -> dict:
     agent_name = os.environ.get("AGENT_NAME", "")
     if agent_name:
         headers["x-invoke-agent"] = agent_name
+    headers.update(trace_headers())
     return headers
 
 

package/skills/template-registry/version.json

@@ -2,6 +2,6 @@
   "skillName": "template-registry",
   "repoName": "agent-skill-media-maker",
   "skillId": "475",
-  "version": "V13",
+  "version": "V14",
   "skillDescription": "Video-template registry skill. Stores every video-template definition and lists the available templates (templateId / name / aspect ratio / style tags).\n\nUse this skill as soon as the user mentions any of these intents:\n- View available templates / list every template\n\nNote: DSL→TemplateBinding is no longer a separate exposed step — once prepare_video_assets receives a template_id it builds the binding internally."
 }

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