@remixmate/cli 0.9.23 → 0.9.24

package/dist/manifest.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
-  "version": "0.9.23",
-  "generatedAt": "2026-09-06T12:35:46.901Z",
+  "version": "0.9.24",
+  "generatedAt": "2026-09-07T14:49:54.095Z",
   "skills": [
     {
       "id": "export-jianying",
@@ -388,25 +388,25 @@
           },
           "headline": {
             "type": "string",
-            "description": "On-screen headline (recommended 4-12 chars / ~3 words). Stored at meta.headline and pushed into every scene's textLayers[role=headline] so the template can render it as the top big-text. **Must** be set when the user explicitly provided a headline / main title; without it, headline falls back to the long-form topic and overflows the top text layer."
+            "description": "On-screen headline. Stored at meta.headline and pushed into every scene's textLayers[role=headline] so the template can render it as the top big-text. **Must** be set when the user explicitly provided a headline / main title; without it, headline falls back to the long-form topic and overflows the top text layer. This is on-screen copy, so write it for a viewer who has never heard of the subject — a bare identifier (repo name, file name, product code) is not a title. Length limits, line breaks (\\n) and emphasis syntax are per-template: follow the chosen template's llmHint, which gen_script prints in full on stderr."
           },
           "subheadline": {
             "type": "string",
-            "description": "On-screen subheadline (project name / slogan / source, e.g. 'Pixelle-Video'). Stored at meta.subheadline and pushed into every scene's textLayers[role=subheadline] so the template can render it as the top small-text. **Must** be set when the user explicitly provided a subtitle / project name. Note: this is the on-screen subheadline, not the CC subtitle (global.subtitle) — they are independent."
+            "description": "On-screen subheadline: the line under the headline, saying why the viewer should care. Multi-line via \\n. Stored at meta.subheadline and pushed into every scene's textLayers[role=subheadline] as the top small-text. **Must** be set when the user explicitly provided a subtitle / slogan. **Never a bare URL** — text layers are painted on screen, where a link is neither readable nor clickable; say what the thing is instead. How many lines the template keeps, and whether it parses **emphasis**, is declared in that template's llmHint (gen_script prints it in full on stderr). Note: this is the on-screen subheadline, not the CC subtitle (global.subtitle) — they are independent."
           },
           "carousel_items": {
             "type": "array",
             "items": {
               "type": "string"
             },
-            "description": "Media URLs for the template's image/video carousel (e.g. spotlight-card's middle carousel). When provided together with a template_id whose capabilities.payloadStyle=carousel-caption, these URLs are placed directly into customPayload.carousel.items as existing assets — NO AI image generation is triggered. **Must** pass when the user explicitly provides image/video URLs for carousel-style templates (spotlight-card, etc.). Each element is a full URL string."
+            "description": "Media URLs for the template's image/video carousel. When provided together with a template_id whose capabilities.payloadStyle=carousel-caption, these URLs are placed directly into customPayload.carousel.items as existing assets — NO AI image generation is triggered. **Must** pass when the user explicitly provides image/video URLs for such a template. Each element is a full URL string."
           },
           "caption_lines": {
             "type": "array",
             "items": {
               "type": "string"
             },
-            "description": "Bottom typewriter text lines for templates that support a caption/typewriter area (e.g. spotlight-card). Each element is one line of text, max 10 lines. Supports **emphasis** syntax (rendered with accent color). **Must** pass when the user explicitly provides bullet-point text / bottom copy. **Also must pass — written by you — when the user did NOT provide any copy but the template is typewriter-driven** (capabilities.durationStrategy=fit-caption, e.g. spotlight-card): such templates have no narration, so these lines are both the video's content and the thing that decides its duration. Draft them from the material you researched (repo README, page screenshots, the topic). Leaving this empty for a fit-caption template is rejected: nothing auto-generates caption text, and an empty caption renders a titled carousel with no words at all."
+            "description": "On-screen caption lines for templates that declare a caption area (capabilities.payloadDefaults.caption). Each element is one line. Line-count limits and whether **emphasis** is parsed are declared by the template — read its llmHint, which gen_script prints in full on stderr. **Must** pass when the user explicitly provides bullet-point text / bottom copy. **Also must pass — written by you — when the user did NOT provide any copy but the template is typewriter-driven** (capabilities.durationStrategy=fit-caption): such templates have no narration, so these lines are both the video's content and the thing that decides its duration. Draft them from the material you researched (repo README, page screenshots, the topic). Leaving this empty for a fit-caption template is rejected: nothing auto-generates caption text, and an empty caption renders a titled carousel with no words at all."
           },
           "stub_image_url": {
             "type": "string",

package/package.json

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

@@ -45,7 +45,7 @@ The full schema is `template-registry` skill's `video_dsl/schema/video-dsl-v1alp
 
 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:
 
-- `html-slide` depends on `scene.templateData.slideId`.
+- 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.
 
 ### Mandatory steps
@@ -58,6 +58,15 @@ The intent is to reuse the validated example shapes already in the repo and to a
 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.
 
+### 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.
+
+Two consequences for the agent:
+
+- `list_templates`' table truncates `llmHint` to 200 chars for browsing, so the summary you picked the template from is usually **not** the whole rule. `gen_script.py` re-prints the chosen template's `llmHint` in full on stderr before it assembles the DSL — read it there and correct yourself before you show the user a confirmation summary.
+- Multi-line on-screen text uses real newlines. A literal `\n` typed inside shell single quotes arrives as two characters, so `gen_script.py` folds `\n` back into a newline for `--headline` / `--subheadline`; both `'a\nb'` and `$'a\nb'` therefore work.
+
 ### 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/`.
@@ -159,7 +168,7 @@ The agent should show the following in clear Markdown:
 
 ## Agent behavior: user-supplied media for carousel/image-driven templates (`--carousel-items` / `--caption-lines`)
 
-Some templates are **media-driven, not prompt-driven**: their on-screen content comes entirely from media URLs the user already has, and the skill does **not** generate any image. These are the templates whose `capabilities.payloadStyle` is `carousel-caption` (e.g. `adaptive-image-video`, `spotlight-card`).
+Some templates are **media-driven, not prompt-driven**: their on-screen content comes entirely from media URLs the user already has, and the skill does **not** generate any image. These are the templates whose `capabilities.payloadStyle` is `carousel-caption`.
 
 For these templates the picture comes from `customPayload.carousel.items`, which is filled **only** from the `--carousel-items` flag. If the user gives you images but you do not pass `--carousel-items`, the carousel is empty and the result is a **black, 2-second clip** (with `durationStrategy: fit-caption`, an empty carousel + empty caption degrades to the 1s headline-intro + 1s tail minimum). `gen_script.py` now hard-fails in this case instead of producing the degenerate video.
 
@@ -169,26 +178,26 @@ When the user selects a `carousel-caption` template (or any template whose `asse
 
 1. **Extract every media URL the user provided** (image or video links in the prompt) and pass each one as a separate `--carousel-items <url>` flag — preserve the user's order, and pass the URLs **verbatim** (do not rewrite host/path/query).
 2. Pass each on-screen caption line as `--caption-lines '<text>'`. Whether this is optional depends on the template's `capabilities.durationStrategy`, **not** on `needsNarration` (every `carousel-caption` template has `needsNarration: false`):
-   - `durationStrategy: fit-caption` (e.g. `spotlight-card`) → **caption lines are mandatory.** The template has no narration and the typewriter copy is both the content and the clock: it is what the video says *and* what decides how long it runs. **If the user did not supply the copy, write it yourself** from the material you researched (repo README, page screenshots, the topic) and pass it. `gen_script.py` hard-fails on an empty caption for these templates.
-   - `durationStrategy: fit-images` (e.g. `adaptive-image-video` / `image-to-video`) → purely visual, captions genuinely optional; duration comes from the image count.
+   - `durationStrategy: fit-caption` → **caption lines are mandatory.** The template has no narration and the typewriter copy is both the content and the clock: it is what the video says *and* what decides how long it runs. **If the user did not supply the copy, write it yourself** from the material you researched (repo README, page screenshots, the topic) and pass it. `gen_script.py` hard-fails on an empty caption for these templates.
+   - `durationStrategy: fit-images` → purely visual, captions genuinely optional; duration comes from the image count.
 3. **Never call gen_script for a `carousel-caption` template without `--carousel-items`.** If the user picked such a template but provided no media, ask them for the image/video URLs first — do not generate an empty carousel.
 4. Do **not** route these user-provided images through `gen-image`; they are existing assets and go straight into the carousel.
 5. Nothing downstream fills these in for you. `gen_script.py` routes on `capabilities.payloadStyle` alone — omitting the flags does **not** fall back to a generic path that generates images or writes copy; it assembles an empty carousel / empty caption. There is no auto-generation of caption text anywhere in the pipeline.
 
 ### Command example
 
-User: "用模版 adaptive-image-video 生成视频，图片链接为：https://cdn.example.com/a.jpg，https://cdn.example.com/b.jpg，https://cdn.example.com/c.jpg"
+User: "用模版 <template-id> 生成视频，图片链接为：https://cdn.example.com/a.jpg，https://cdn.example.com/b.jpg，https://cdn.example.com/c.jpg"
 
 ```bash
 python3 <SkillDir>/scripts/gen_script.py \
   --topic "图片轮播视频" \
-  --template-id adaptive-image-video \
+  --template-id <template-id> \
   --carousel-items "https://cdn.example.com/a.jpg" \
   --carousel-items "https://cdn.example.com/b.jpg" \
   --carousel-items "https://cdn.example.com/c.jpg"
 ```
 
-This template auto-adapts per-image hold time to the image count (1 image = 8s, 2 = 4s each, 3+ = 3s each), so 3 images yields a ~9s video instead of the 2s black clip.
+Every URL the user gave becomes one carousel item, in order. How long each item holds is the template's business — `fit-images` templates derive it from the item count, `fit-caption` templates from `capabilities.durationModel`; either way you pass the URLs and let the template decide.
 
 
 ## Test mode: skip asset generation (`--stub-image-url` / `--stub-video-url`)
@@ -244,7 +253,7 @@ Env vars `STUB_IMAGE_URL` / `STUB_VIDEO_URL` also work — their priority is low
 5. **Schema validation**: make sure the output DSL conforms to v1alpha1.
 6. **User confirmation**: show the script summary and wait for confirmation, per the rules above.
 
-### Generic-template DSL (image-slide / knowledge-slides, etc.)
+### Generic DSL (no template id, or a template with no special payload)
 
 ```bash
 python3 <SkillDir>/scripts/gen_script.py \
@@ -282,7 +291,7 @@ python3 <SkillDir>/scripts/gen_script.py \
 | `--topic` | Video topic (required unless `--validate`). | — |
 | `--platform` | Target platform: `douyin` / `xiaohongshu` / `bilibili` / `wechat` / `youtube` / `generic`. | `generic` |
 | `--headline` | On-screen main title (4–12 chars / ~3 words). Written to `meta.headline` + `textLayers[role=headline]`. **Pass it whenever the user gave a title** — otherwise headline falls back to the long-form topic and overflows the top text layer. | falls back to `--topic` |
-| `--subheadline` | On-screen subtitle / project name / slogan. Written to `meta.subheadline` + `textLayers[role=subheadline]`. Not the same thing as CC subtitles (`global.subtitle`). | `""` |
+| `--subheadline` | On-screen subtitle / slogan. Written to `meta.subheadline` + `textLayers[role=subheadline]`. Multi-line via `\n`; how many lines survive and whether `**emphasis**` renders is declared per template — see its `llmHint`. Not the same thing as CC subtitles (`global.subtitle`). | `""` |
 | `--duration` | Target duration (seconds). Templates whose `durationStrategy` is `fit-caption` / `fit-narration` recompute the real duration and ignore this value. | `30` |
 | `--style` | Style tag. | — |
 | `--ratio` | Aspect ratio. | `16:9` |
@@ -295,8 +304,8 @@ python3 <SkillDir>/scripts/gen_script.py \
 | `-o` / `--output` | Output DSL file path. | stdout |
 | `--stub-image-url` | Test mode: every image AssetRef is written as existing + generated + this URL, no prompt (env: `STUB_IMAGE_URL`). | — |
 | `--stub-video-url` | Test mode: every video AssetRef is written as existing + generated + this URL, no prompt (env: `STUB_VIDEO_URL`). | — |
-| `--carousel-items` | Repeatable. Media URL placed directly into `customPayload.carousel.items` for `carousel-caption` templates (e.g. `adaptive-image-video`, `spotlight-card`). Bypasses gen-image. **Required** for `carousel-caption` templates when the user supplies images. | — |
-| `--caption-lines` | Repeatable. On-screen typewriter caption line for `carousel-caption` templates → `customPayload.caption.lines` (max 10 lines). Supports `**emphasis**`. **Required** for `durationStrategy: fit-caption` templates (`spotlight-card`) — write the lines yourself if the user did not supply them. Optional only for `fit-images` templates. | — |
+| `--carousel-items` | Repeatable. Media URL placed directly into `customPayload.carousel.items` for `carousel-caption` templates. Bypasses gen-image. **Required** for `carousel-caption` templates when the user supplies images. | — |
+| `--caption-lines` | Repeatable. On-screen caption line for `carousel-caption` templates → `customPayload.caption.lines`. Line limits and `**emphasis**` support are declared per template (see its `llmHint`). **Required** for `durationStrategy: fit-caption` templates — write the lines yourself if the user did not supply them. Optional only for `fit-images` templates. | — |
 
 ## DSL generation principles
 
@@ -338,7 +347,7 @@ prefix and version — not a short alias:
 - **Scene duration mismatch**: adjust the narration length or the scene duration.
 - **Invalid platform**: look at the supported-platform list.
 - **`carousel-caption template ... needs visual or text content`**: you passed neither `--carousel-items` nor `--caption-lines`. Pass the user's media URLs (and caption lines where the template requires them).
-- **`template ... is typewriter-driven ... but --caption-lines is empty`**: a `fit-caption` template (e.g. `spotlight-card`) got no caption. Write the copy yourself if the user did not supply it, then pass one `--caption-lines` per line.
+- **`template ... is typewriter-driven ... but --caption-lines is empty`**: a `fit-caption` template got no caption. Write the copy yourself if the user did not supply it, then pass one `--caption-lines` per line.
 - **`duration Ns is below/above template ... supportedDurations`**: the assembled DSL falls outside the range the template declares it was designed for. Below the minimum usually means the content is too thin (add caption lines / narration / scenes); above the maximum means trimming content or lowering `--duration`. This is enforced at generation time on purpose — a degenerate video still costs full render credits.
 
 ## scripts/ contents

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

@@ -207,9 +207,10 @@ def validate_dsl(dsl: dict) -> list:
     Historical rule set (preserved verbatim by ``validate_structural``):
       version + meta(title) + global presence + scene count 1–20 + each
       scene's ``id`` and ``purpose``. Asset integrity, enum membership and
-      picture-book-en checks are intentionally NOT enforced here — those
-      live in ``validate_dsl`` / ``validate_integrity`` and only run at
-      their respective historical call sites.
+      capabilities-driven checks (e.g. narrationLanguageStrict) are
+      intentionally NOT enforced here — those live in ``validate_dsl`` /
+      ``validate_integrity`` and only run at their respective historical
+      call sites.
     """
     from video_dsl.runtime.dsl_validator import (  # noqa: E402
         validate_structural,
@@ -365,7 +366,7 @@ def _template_primary_visual_type(template_config: dict | None) -> str:
     返回值之一：
       - "image" : 模板要求图片素材（默认通用 DSL 也是图片）
       - "video" : 模板要求视频素材（assetRequirements 含 video 但不含 image）
-      - "none"  : 模板不需要任何视觉素材（如 html-slide 仅 audio）
+      - "none"  : 模板不需要任何视觉素材（assetRequirements 只有 audio）
     """
     if not template_config:
         return "image"  # 默认：通用 DSL 走图片
@@ -388,8 +389,8 @@ def _template_needs_narration(template_config: dict | None) -> bool:
       - 不生成 gen-voice 素材；
       - 场景不写 ``audio.narration``。
     于是骨架的 narrationSceneCount=0，ab-agent 的 prepare_video_assets 预校验
-    会直接放行，不再强制用户为每个场景填旁白（与 spotlight-card 等无配音模板
-    走的是同一条 pass-through 路径）。
+    会直接放行，不再强制用户为每个场景填旁白 —— 所有 needsNarration=false 的模板
+    走的是同一条 pass-through 路径。
 
     兼容历史脏数据：部分模板的 ``capabilities`` 是空列表 ``[]``（而非 dict），
     统一按"未声明"处理 → 返回 True。仅当显式为 JSON ``false`` 时才关闭旁白。
@@ -426,6 +427,8 @@ def _template_needs_image(template_config: dict | None) -> bool:
 #   - payload_style     str          capabilities.payloadStyle ∈ {visual-overlay, slide, carousel-caption}
 #   - duration_strategy str          capabilities.durationStrategy ∈ {explicit, fit-caption}
 #   - payload_defaults  dict         capabilities.payloadDefaults（carousel-caption 的轮播/字幕默认值）
+#   - duration_model    dict|None    capabilities.durationModel（fit-caption 估时用的节奏数值，
+#                                    由模板声明；缺省则不估时，见 _estimate_fit_caption_duration）
 #   - primary_visual_type / default_layout 由 assetRequirements / capabilities 推导
 
 
@@ -469,12 +472,78 @@ def _resolve_contract(template_config: dict | None) -> dict:
         "fixed_scenes": fixed_scenes,
         "payload_style": payload_style,
         "duration_strategy": duration_strategy,
+        "duration_model": caps.get("durationModel"),
         "payload_defaults": payload_defaults,
         "primary_visual_type": primary_visual_type,
         "default_layout": caps.get("defaultLayout"),
     }
 
 
+def _normalize_linebreaks(value: str | None) -> str:
+    """把画面文字里的**字面量** ``\\n`` 折成真换行。
+
+    ``textLayers[].content`` 用真换行分行，但调用方是在拼 shell 命令行的模型：
+    ``--subheadline 'A\\nB'`` 在 POSIX 单引号里传进来的是**反斜杠 + n 两个字符**，
+    不是换行。不折的话它会原样渲进画面（副标题上真的印着一个 ``\\n``），而这既不
+    报错也不出现在确认摘要里 —— 属于"只有渲完看片才发现"的那类坑。
+
+    反过来说，画面文案里没有任何理由需要一个字面 ``\\n``，所以这个折叠是无损的。
+    真换行（``$'a\\nb'`` 或参数里直接带换行）本来就能用，不受影响。
+    """
+    return (value or "").replace("\\n", "\n").strip()
+
+
+def _echo_template_llm_hint(template_config: dict | None, template_id: str | None) -> None:
+    """把模板自己声明的 ``llmHint`` 原样打到 stderr。
+
+    **本函数刻意不认识任何一个具体模板。** 每个模板的画面文字该怎么写（标题写钩子
+    还是写产品名、副标题几行、支持不支持 ``**强调**``）是模板的事实，真源在它自己的
+    ``template.json`` —— 与 ``imageStyleGuide`` 由 ``prompt_enhancer`` 通用消费、
+    ``capabilities`` 由 ``_resolve_contract`` 通用归一化是同一条纪律：**CLI 出机制，
+    模板出内容**。把某个模板的版式规则抄进 skill 文档或这里的分支，等于在 registry
+    之外开第二份会漂移的事实。
+
+    之所以要在这里再打一遍：``list_templates`` 的表格视图把 llmHint 截到 200 字
+    （便于浏览），而真正的写作规范往往长得多（现网最长的已有 1400+ 字）。调用方
+    多半是照着那份被截断的摘要选完模板就直接来调 gen_script 的，规则的后半截它从没
+    见过。这里在装配 DSL 之前把全文补给它，让它能在确认摘要之前自己纠偏。
+    """
+    hint = (template_config or {}).get("llmHint")
+    if isinstance(hint, str) and hint.strip():
+        print(
+            f"ℹ️  template '{template_id}' llmHint (authoring rules declared by the "
+            f"template itself — follow them):\n   {hint.strip()}",
+            file=sys.stderr,
+        )
+
+
+def _warn_on_url_text_layer(headline: str, subheadline: str) -> None:
+    """画面文字整条是一个裸 URL 时出声提醒（不阻断）。
+
+    这是 DSL 层的事实、不是某个模板的版式：``textLayers`` 是**画在画面上**的字，
+    而观众没法点视频里的链接、也很少有人会照着念一串 URL 抄下来。链接的正确去处
+    因模板而异（打字机行、结尾 CTA、简介），所以这里只说"这不该出现在画面标题里"，
+    不替模板规定它该去哪 —— 那句话由模板的 llmHint 自己讲。
+
+    只 warn 不 exit：这是文风问题，照样渲得出一条能看的片子，与"caption 为空渲出
+    黑屏"那种结构性失败不同级。
+    """
+    for flag, value in (("--headline", headline), ("--subheadline", subheadline)):
+        lines = [ln.strip() for ln in (value or "").split("\n") if ln.strip()]
+        if lines and all(
+            ln.startswith(("http://", "https://", "www.", "github.com/")) for ln in lines
+        ):
+            print(
+                f"⚠️  {flag} is nothing but a URL ({value.strip()!r}). "
+                "textLayers are drawn on screen — a link there is unreadable and "
+                "unclickable, and it spends the frame's most-read text on something "
+                "the viewer cannot act on.\n"
+                "   Write what the thing is / why it matters instead, and see the "
+                "template's llmHint above for where the link belongs.",
+                file=sys.stderr,
+            )
+
+
 def _enforce_supported_duration(
     dsl: dict, template_config: dict | None, template_id: str | None
 ) -> None:
@@ -482,8 +551,8 @@ def _enforce_supported_duration(
 
     这条约束此前只在 template-library 的 CI（``check-dsl-examples.mjs``）对仓库里的
     示例 DSL 生效，运行时链路（gen_script → prepare_video_assets → render_video）没有
-    任何一环校验它。于是 spotlight-card（``min: 10``）可以静默产出 5s 成片——模板自己
-    声明"我不是为 5s 设计的"，却没人拦。这里在 DSL 出厂前补上同一道栅栏。
+    任何一环校验它。于是一个声明了 ``supportedDurations.min`` 的模板照样可以静默产出
+    低于下限的成片 —— 模板自己说了"我不是为这么短设计的"，却没人拦。这里在 DSL 出厂前补上同一道栅栏。
 
     越界即报错退出，而不是静默出片：时长不足通常意味着内容（打字机文案 / 旁白 / 场景）
     根本没填够，继续往下走只会烧掉渲染积分换一条废片。
@@ -556,64 +625,93 @@ def _plain_len(text: str) -> int:
     return len((text or "").replace("**", ""))
 
 
-# fit-caption 时长估算常量 —— 与 template-library spotlight-card/utils/timing.ts
-# + estimateDuration.ts 保持同一套数值，避免上游估时与组件实际耗时漂移。
-_MAX_CPS_CAP = 60
-_DEFAULT_TAIL_HOLD_SEC = 1.5
-_TAIL_PADDING_SEC = 1.0
-_HEADLINE_INTRO_SEC = 1.0
-_CAROUSEL_MIN_PER_ITEM_SEC = 2.0
-_CAROUSEL_MIN_PER_VIDEO_SEC = 3.5
+# ── fit-caption 估时 ───────────────────────────────────────────────────────
+#
+# 这里以前钉着一组常量（打字收尾 1.5s、标题入场 1.0s、每张图最少 2.0s …），注释写
+# 明"与 template-library 里那个模板组件的 timing.ts 保持同一套数值"。也就是说
+# **一个具体模板的组件内部节奏被手抄进了 CLI**：模板调一次 tailHold，这边不跟着改
+# 就开始漂，而漂移的表现是"估时和组件实际耗时对不上"，没有任何门禁看得见。
+#
+# 现在数值由模板在 ``capabilities.durationModel`` 里自己声明，本文件只实现算法：
+# 各分量并行、取 max、加收尾留白。没声明的模板不估时（见 _estimate_fit_caption_duration）。
+# 与 ``payloadDefaults`` / ``imageStyleGuide`` 同一条纪律：模板出数值，CLI 出机制。
 
 
-def _estimate_caption_natural_sec(caption: dict) -> float:
+def _estimate_caption_natural_sec(caption: dict, model: dict) -> float:
     """打字机自然节奏耗时（startDelay + 打字 + 行间停顿 + 收尾），秒。"""
-    lines = (caption.get("lines") or [])[:10]
+    max_lines = model.get("maxLines")
+    lines = caption.get("lines") or []
+    if isinstance(max_lines, int) and max_lines > 0:
+        lines = lines[:max_lines]
     if not lines:
         return 0.0
-    natural_cps = max(4, min(80, caption.get("charsPerSec", 28)))
-    line_gap_sec = caption.get("lineGapMs", 350) / 1000.0
-    start_delay_sec = caption.get("startDelayMs", 600) / 1000.0
+    cps = caption.get("charsPerSec", model.get("charsPerSec"))
+    if not cps:
+        return 0.0
+    lo, hi = model.get("charsPerSecMin"), model.get("charsPerSecMax")
+    if lo is not None:
+        cps = max(lo, cps)
+    if hi is not None:
+        cps = min(hi, cps)
+    line_gap_sec = caption.get("lineGapMs", model.get("lineGapMs", 0)) / 1000.0
+    start_delay_sec = caption.get("startDelayMs", model.get("startDelayMs", 0)) / 1000.0
     total_chars = sum(_plain_len(t) for t in lines)
     inter_line_sec = line_gap_sec * max(0, len(lines) - 1)
-    fixed_overhead = start_delay_sec + inter_line_sec + _DEFAULT_TAIL_HOLD_SEC
-    return fixed_overhead + total_chars / natural_cps
+    fixed_overhead = start_delay_sec + inter_line_sec + model.get("tailHoldSec", 0)
+    return fixed_overhead + total_chars / cps
 
 
-def _estimate_carousel_min_sec(carousel: dict) -> float:
+def _estimate_carousel_min_sec(carousel: dict, model: dict) -> float:
     """轮播至少需要的秒数（每张图/视频的最小停留，减去重叠的过渡）。"""
     items = carousel.get("items") or []
     n = len(items)
     if n == 0:
         return 0.0
-    transition_sec = carousel.get("transitionMs", 400) / 1000.0
+    transition_sec = carousel.get("transitionMs", model.get("transitionMs", 0)) / 1000.0
     explicit_pacing = carousel.get("pacing")
     any_explicit = any(it.get("holdSec") is not None for it in items)
     has_default_hold = carousel.get("defaultHoldSec") is not None
     pacing = explicit_pacing or ("fixed" if (any_explicit or has_default_hold) else "auto")
     if pacing == "fixed":
-        default_hold = carousel.get("defaultHoldSec", 3.0)
+        default_hold = carousel.get("defaultHoldSec", model.get("defaultHoldSec", 0))
         total = sum(it.get("holdSec", default_hold) for it in items)
         return total - (n - 1) * transition_sec
-    total = sum(
-        _CAROUSEL_MIN_PER_VIDEO_SEC if it.get("kind") == "video" else _CAROUSEL_MIN_PER_ITEM_SEC
-        for it in items
-    )
+    per_image = model.get("minPerImageSec", 0)
+    per_video = model.get("minPerVideoSec", per_image)
+    total = sum(per_video if it.get("kind") == "video" else per_image for it in items)
     return total - (n - 1) * transition_sec
 
 
-def _estimate_fit_caption_duration(custom_payload: dict) -> float:
+def _estimate_fit_caption_duration(
+    custom_payload: dict, duration_model: dict | None, template_id: str | None
+) -> float:
     """fit-caption 策略：按打字机 + 轮播 + 标题入场推算建议时长（秒）。
 
-    等价于 template-library 的 estimateSpotlightCardDuration().recommendedSec：
-    各组件并行，取 max 再加收尾留白。
+    算法与模板导出的 ``capabilities.durationEstimator`` 等价（各分量并行、取 max、
+    加收尾留白），但**每一个数值都来自模板声明的 ``capabilities.durationModel``**。
+    模板没声明就不估 —— 返回 0，调用方沿用传入的 targetDuration 并收到一条 warning。
+    宁可退回调用方的时长，也不拿一组从别的模板抄来的数字去替这个模板做决定。
     """
-    caption = custom_payload.get("caption") or {}
-    carousel = custom_payload.get("carousel") or {}
-    caption_sec = _estimate_caption_natural_sec(caption)
-    carousel_sec = _estimate_carousel_min_sec(carousel)
-    recommended = max(_HEADLINE_INTRO_SEC, caption_sec, carousel_sec) + _TAIL_PADDING_SEC
-    return recommended
+    if not isinstance(duration_model, dict) or not duration_model:
+        print(
+            f"⚠️  template '{template_id}' declares durationStrategy=fit-caption but no "
+            "capabilities.durationModel, so gen_script cannot compute the fitted "
+            "duration and falls back to the requested --duration.\n"
+            "   Fix in the template (not here): add capabilities.durationModel with the "
+            "component's own pacing numbers (headlineIntroSec / tailPaddingSec / "
+            "caption.{charsPerSec,lineGapMs,startDelayMs,tailHoldSec,maxLines} / "
+            "carousel.{transitionMs,defaultHoldSec,minPerImageSec,minPerVideoSec}).",
+            file=sys.stderr,
+        )
+        return 0.0
+    caption_sec = _estimate_caption_natural_sec(
+        custom_payload.get("caption") or {}, duration_model.get("caption") or {}
+    )
+    carousel_sec = _estimate_carousel_min_sec(
+        custom_payload.get("carousel") or {}, duration_model.get("carousel") or {}
+    )
+    headline_intro = duration_model.get("headlineIntroSec", 0)
+    return max(headline_intro, caption_sec, carousel_sec) + duration_model.get("tailPaddingSec", 0)
 
 
 def _build_carousel_caption_dsl(
@@ -636,8 +734,9 @@ def _build_carousel_caption_dsl(
     narration_enabled: bool,
     payload_defaults: dict,
     duration_strategy: str | None,
+    duration_model: dict | None,
 ) -> dict:
-    """carousel-caption 装配（spotlight-card 类：单场景、图/视频轮播 + 打字机）。
+    """carousel-caption 装配（单场景、图/视频轮播 + 打字机文字）。
 
     所有差异来自归一化 contract（capabilities.payloadDefaults / durationStrategy /
     needsNarration），不再读 input-schema.json，也没有 if template_id==X 分支。
@@ -702,12 +801,21 @@ def _build_carousel_caption_dsl(
         caption_config["lines"] = caption_lines
 
     # ── Build customPayload ───────────────────────────────────────────────
+    #
+    # background / headlineStyle 只在模板自己声明了 payloadDefaults 时才写进去。
+    # 这里原本硬编码着 ``{"preset": "grid-particles"}`` / ``{"pill": True}`` 作为
+    # 兜底 —— 那两个值是**某一个**模板的词汇（一个背景 preset 枚举成员 + 一个它
+    # 顶部装饰的开关）。同为 carousel-caption 但没声明这两个键的模板既不认识也不读
+    # 它们，等于往它的 DSL 里塞两坨死配置（payload 契约门禁只查"声明了却没人消费"，
+    # 查不到"没声明却被硬塞进来"）；而下一个模板如果恰好也有 background、枚举却不同，
+    # 拿到的就是一个它不认识的值。模板的默认值归模板声明，CLI 只负责透传。
     custom_payload = {
-        "background": defaults.get("background", {"preset": "grid-particles"}),
-        "headlineStyle": defaults.get("headlineStyle", {"pill": True}),
         "carousel": carousel_config,
         "caption": caption_config,
     }
+    for key in ("background", "headlineStyle"):
+        if defaults.get(key):
+            custom_payload[key] = defaults[key]
 
     # ── Narration skeleton ────────────────────────────────────────────────
     narration_text = _localize_label(output_language, "narration_opening",
@@ -715,11 +823,11 @@ def _build_carousel_caption_dsl(
 
     # ── Effective scene duration ──────────────────────────────────────────
     # fit-caption 策略：时长由打字机自然节奏决定，而不是盲取调用方传入的 targetDuration。
-    # 这是 spotlight-card 这类打字机/画面驱动模板的核心——没有旁白来"撑"时长，
+    # 这是打字机/画面驱动模板的核心——没有旁白来"撑"时长，
     # 必须由 caption 自己定，否则文字打完后画面会静止到 targetDuration。
     effective_duration = duration
     if duration_strategy == "fit-caption":
-        est = _estimate_fit_caption_duration(custom_payload)
+        est = _estimate_fit_caption_duration(custom_payload, duration_model, template_id)
         if est > 0:
             effective_duration = int(math.ceil(est))
             print(
@@ -728,7 +836,7 @@ def _build_carousel_caption_dsl(
                 file=sys.stderr,
             )
 
-    # ── Build scene (spotlight-card uses a single scene) ──────────────────
+    # ── Build scene (sceneStrategy=single: one scene carries everything) ──
     text_layers = [
         {"role": "headline", "content": headline, "animation": "slide-up"},
     ]
@@ -883,8 +991,10 @@ def build_dsl(
         )
 
     # 缺省值：headline 退回 topic，subheadline 默认空字符串
-    effective_headline = (headline or "").strip() or topic
-    effective_subheadline = (subheadline or "").strip()
+    effective_headline = _normalize_linebreaks(headline) or topic
+    effective_subheadline = _normalize_linebreaks(subheadline)
+    _echo_template_llm_hint(template_config, template_id)
+    _warn_on_url_text_layer(effective_headline, effective_subheadline)
 
     # ── carousel-caption 模板（单场景、图/视频轮播 + 打字机）单独装配并直接返回 ──
     if payload_style == "carousel-caption":
@@ -911,13 +1021,13 @@ def build_dsl(
                 file=sys.stderr,
             )
             sys.exit(1)
-        # 兜底校验 ②：durationStrategy=fit-caption 的模板（spotlight-card 类）由打字机
+        # 兜底校验 ②：durationStrategy=fit-caption 的模板由打字机
         # 文案驱动节奏 —— caption 就是内容本体，不是可选装饰。caption_lines 为空时上面的
         # "两者皆空" 检查放行，产出的却是「顶部标题 + 轮播、底部一个字都没有」的退化片：
         # 估时掉到轮播地板值（2 张图 ≈ 5s），而调用方往往还在确认摘要里描述了一段
         # 根本没进 DSL 的文案，用户在确认环节也看不出来。所以这里必须硬失败。
         # 注意：只卡 fit-caption。carousel-caption 里 durationStrategy=fit-images 的
-        # 纯视觉模板（image-to-video 等）本来就允许无文案，不受影响。
+        # 纯视觉模板本来就允许无文案，不受影响。
         if contract["duration_strategy"] == "fit-caption" and not (caption_lines or []):
             print(
                 "❌ template "
@@ -955,6 +1065,7 @@ def build_dsl(
             narration_enabled=needs_narration,
             payload_defaults=contract["payload_defaults"],
             duration_strategy=contract["duration_strategy"],
+            duration_model=contract["duration_model"],
         )
         _enforce_supported_duration(carousel_dsl, template_config, template_id)
         return carousel_dsl
@@ -1068,8 +1179,9 @@ def build_dsl(
                 text_layers = [
                     {"role": "badge", "content": plan["label"], "animation": "slide-up"},
                 ]
-                # 给所有 point 场景补一个 headline textLayer，让 screen-walkthrough
-                # 等模板的 propExtractors 直接拿到主标题，不再依赖 binding 兜底逻辑。
+                # 给所有 point 场景补一个 headline textLayer：凡是把 titleText 从
+                # textLayers[role=headline] 抽出来的 propExtractors 都能直接拿到主标题，
+                # 不再依赖 binding 的兜底逻辑。
                 text_layers.insert(0, {"role": "headline", "content": effective_headline, "animation": "fade-in"})
                 if effective_subheadline:
                     text_layers.append({"role": "subheadline", "content": effective_subheadline, "animation": "fade-in"})
@@ -1103,18 +1215,25 @@ def build_dsl(
                 }
             scenes.append(scene)
         else:
-            # The "no-visual" branch labels each scene with a layout hint.
-            # Historical fallback was hardcoded "html-slide" — when no template
-            # was specified, every audio-only scene defaulted to html-slide
-            # styling. We replace the hardcoded fallback chain with:
+            # The "no-visual" branch labels each scene with a layout hint:
             #   1. template.capabilities.defaultLayout   ⇐ the template tells
             #      remixmate what layout name it wants on its no-visual scenes
             #   2. template_id                            ⇐ legacy: pass id as
             #      layout name (existing behavior when no capability declared)
-            #   3. "html-slide"                           ⇐ absolute fallback
-            #      for the no-template case (preserves prior behavior)
+            #   3. "text-overlay"                         ⇐ no-template case
+            #
+            # ⚠️ 第 3 档以前硬编码着模板库里某个具体模板的 id —— 没选模板时，每个纯
+            # 音频场景都被贴上那个名字。那是这份脚本唯一一处"认识某个模板"的可执行代码：
+            # 没有模板参与的通用 DSL 不该知道模板库里有谁，模板换名 / 下架都会让这个
+            # 字面量变成谎话。改成 schema 自己的枚举值（Scene.layout 的合法取值是
+            # full-visual / text-overlay / … 这一组，模板 id 从来就不在里面，写进去反而
+            # 会让 dsl_validator 报一条 layout 枚举 warning）。
+            #
+            # 这个字段是纯描述性的：match_template 只把它抄进 binding 的 layoutVariant，
+            # 而 layoutVariant 在 ab-render 与 template-library 里都没有任何读取方
+            # （已核对），渲染走的是 slotMapping / compositionId。所以换值不改成片。
             _layout_cfg = (template_config or {}).get("capabilities") or {}
-            layout = _layout_cfg.get("defaultLayout") or template_id or "html-slide"
+            layout = _layout_cfg.get("defaultLayout") or template_id or "text-overlay"
             text_layers = []
             if plan["purpose"] == "opening":
                 text_layers = [
@@ -1260,19 +1379,20 @@ Examples:
         default=None,
         help="Media URL for the template's carousel/gallery. Can be repeated: "
              "--carousel-items url1 --carousel-items url2. "
-             "For carousel-caption templates (capabilities.payloadStyle=carousel-caption, "
-             "e.g. spotlight-card), these URLs are placed directly into "
+             "For templates declaring capabilities.payloadStyle=carousel-caption, "
+             "these URLs are placed directly into "
              "customPayload.carousel.items as existing assets, bypassing AI image generation entirely.",
     )
     parser.add_argument(
         "--caption-lines",
         action="append",
         default=None,
-        help="Bottom typewriter text line. Can be repeated: "
+        help="On-screen caption line. Can be repeated: "
              "--caption-lines 'line1' --caption-lines 'line2'. "
-             "For carousel-caption templates (capabilities.payloadStyle=carousel-caption, "
-             "e.g. spotlight-card), these are placed into customPayload.caption.lines. "
-             "Supports **emphasis** syntax.",
+             "For templates declaring capabilities.payloadStyle=carousel-caption, "
+             "these are placed into customPayload.caption.lines. "
+             "Line count limits and whether **emphasis** is parsed are declared per "
+             "template — see the chosen template's llmHint.",
     )
 
     args = parser.parse_args()

package/skills/gen-script/skill.json

@@ -58,25 +58,25 @@
       },
       "headline": {
         "type": "string",
-        "description": "On-screen headline (recommended 4-12 chars / ~3 words). Stored at meta.headline and pushed into every scene's textLayers[role=headline] so the template can render it as the top big-text. **Must** be set when the user explicitly provided a headline / main title; without it, headline falls back to the long-form topic and overflows the top text layer."
+        "description": "On-screen headline. Stored at meta.headline and pushed into every scene's textLayers[role=headline] so the template can render it as the top big-text. **Must** be set when the user explicitly provided a headline / main title; without it, headline falls back to the long-form topic and overflows the top text layer. This is on-screen copy, so write it for a viewer who has never heard of the subject — a bare identifier (repo name, file name, product code) is not a title. Length limits, line breaks (\\n) and emphasis syntax are per-template: follow the chosen template's llmHint, which gen_script prints in full on stderr."
       },
       "subheadline": {
         "type": "string",
-        "description": "On-screen subheadline (project name / slogan / source, e.g. 'Pixelle-Video'). Stored at meta.subheadline and pushed into every scene's textLayers[role=subheadline] so the template can render it as the top small-text. **Must** be set when the user explicitly provided a subtitle / project name. Note: this is the on-screen subheadline, not the CC subtitle (global.subtitle) — they are independent."
+        "description": "On-screen subheadline: the line under the headline, saying why the viewer should care. Multi-line via \\n. Stored at meta.subheadline and pushed into every scene's textLayers[role=subheadline] as the top small-text. **Must** be set when the user explicitly provided a subtitle / slogan. **Never a bare URL** — text layers are painted on screen, where a link is neither readable nor clickable; say what the thing is instead. How many lines the template keeps, and whether it parses **emphasis**, is declared in that template's llmHint (gen_script prints it in full on stderr). Note: this is the on-screen subheadline, not the CC subtitle (global.subtitle) — they are independent."
       },
       "carousel_items": {
         "type": "array",
         "items": {
           "type": "string"
         },
-        "description": "Media URLs for the template's image/video carousel (e.g. spotlight-card's middle carousel). When provided together with a template_id whose capabilities.payloadStyle=carousel-caption, these URLs are placed directly into customPayload.carousel.items as existing assets — NO AI image generation is triggered. **Must** pass when the user explicitly provides image/video URLs for carousel-style templates (spotlight-card, etc.). Each element is a full URL string."
+        "description": "Media URLs for the template's image/video carousel. When provided together with a template_id whose capabilities.payloadStyle=carousel-caption, these URLs are placed directly into customPayload.carousel.items as existing assets — NO AI image generation is triggered. **Must** pass when the user explicitly provides image/video URLs for such a template. Each element is a full URL string."
       },
       "caption_lines": {
         "type": "array",
         "items": {
           "type": "string"
         },
-        "description": "Bottom typewriter text lines for templates that support a caption/typewriter area (e.g. spotlight-card). Each element is one line of text, max 10 lines. Supports **emphasis** syntax (rendered with accent color). **Must** pass when the user explicitly provides bullet-point text / bottom copy. **Also must pass — written by you — when the user did NOT provide any copy but the template is typewriter-driven** (capabilities.durationStrategy=fit-caption, e.g. spotlight-card): such templates have no narration, so these lines are both the video's content and the thing that decides its duration. Draft them from the material you researched (repo README, page screenshots, the topic). Leaving this empty for a fit-caption template is rejected: nothing auto-generates caption text, and an empty caption renders a titled carousel with no words at all."
+        "description": "On-screen caption lines for templates that declare a caption area (capabilities.payloadDefaults.caption). Each element is one line. Line-count limits and whether **emphasis** is parsed are declared by the template — read its llmHint, which gen_script prints in full on stderr. **Must** pass when the user explicitly provides bullet-point text / bottom copy. **Also must pass — written by you — when the user did NOT provide any copy but the template is typewriter-driven** (capabilities.durationStrategy=fit-caption): such templates have no narration, so these lines are both the video's content and the thing that decides its duration. Draft them from the material you researched (repo README, page screenshots, the topic). Leaving this empty for a fit-caption template is rejected: nothing auto-generates caption text, and an empty caption renders a titled carousel with no words at all."
       },
       "stub_image_url": {
         "type": "string",