@remixmate/cli 0.9.51 → 0.9.53

package/dist/manifest.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
-  "version": "0.9.51",
-  "generatedAt": "2026-09-27T12:37:01.962Z",
+  "version": "0.9.53",
+  "generatedAt": "2026-09-28T02:19:31.947Z",
   "skills": [
     {
       "id": "doc-parse",
@@ -944,16 +944,19 @@
           },
           "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."
+            "description": "Return this template's full authoring contract instead of the summary list: llmHint in full, customPayloadSchema (every template-specific field incl. the legal slideId values), slotMapping, compositions, variants. Multi-layout templates return slideSchemas as a MENU (per layout: description, field names, card-list key / item fields / maxItems, and whether narration must be split into items) — enough to pick layouts and draft the script. Tool results do not carry over between chat turns: read the menu in the turn that drafts the script; the turn that writes templateData only needs slide_id."
+          },
+          "slide_id": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "With template_id: return the FULL templateData schema for these layouts (the slideIds you chose from the menu). Call this once, right before writing templateData, with every layout the script uses. 'all' returns every layout (large — avoid)."
           },
           "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'."
@@ -982,8 +985,8 @@
         "advanced": [
           "list_templates",
           "template_id",
+          "slide_id",
           "full",
-          "list_examples",
           "filter_tag",
           "filter_aspect",
           "filter_language",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remixmate/cli",
-  "version": "0.9.51",
+  "version": "0.9.53",
   "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",
@@ -36,7 +36,8 @@
     "test:declared-keys": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-declared-keys.py",
     "test:payload-hydration": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-payload-hydration.py",
     "test:sentence-alignment": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-sentence-alignment.py",
-    "test:unit": "npm run -s test:narration-speed && npm run -s test:template-look && npm run -s test:narration-tts && npm run -s test:render-resume && npm run -s test:required-props && npm run -s test:countdown && npm run -s test:prepare-contracts && npm run -s test:image-sequence && npm run -s test:image-prompt-compose && npm run -s test:page-contracts && npm run -s test:declared-keys && npm run -s test:payload-hydration && npm run -s test:sentence-alignment",
+    "test:authoring-budget": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-authoring-budget.py",
+    "test:unit": "npm run -s test:narration-speed && npm run -s test:template-look && npm run -s test:narration-tts && npm run -s test:render-resume && npm run -s test:required-props && npm run -s test:countdown && npm run -s test:prepare-contracts && npm run -s test:image-sequence && npm run -s test:image-prompt-compose && npm run -s test:page-contracts && npm run -s test:declared-keys && npm run -s test:payload-hydration && npm run -s test:sentence-alignment && npm run -s test:authoring-budget",
     "integration": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/integration/regress.py",
     "integration:render": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/integration/render-template-check.py"
   },

package/skills/gen-script/SKILL.md

@@ -39,7 +39,7 @@ Turns a user-supplied **topic** into a **Video DSL v1alpha1** JSON describing wh
 
 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.
+**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). Do not go looking for examples — the authoritative per-template contract ships inside the registry's `template.json`, see below.
 
 ## Agent behavior: DSL generation when a template is selected
 
@@ -52,15 +52,14 @@ The intent is to avoid the failure mode where "the generic DSL looks compatible
 
 ### Mandatory steps
 
-1. Read the requested template's full definition from the registry — `template_registry` with `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.
+1. Read the requested template's full definition from the registry — `template_registry` with `template_id=<the id>` emits that one template's contract. This is the shipping source of truth. Never fetch it twice in one turn. Tool results do **not** carry over between chat turns (each turn only sees the chat text), so the turn that writes `dsl_json` after the user confirms needs only step 3b's `slide_id` call, not the menu again. Do **not** ask for every template's full definition (`list_templates=true` + `full=true`): the whole registry is far more JSON than one tool result can carry, and the call fails instead of returning the contract.
 2. Read its `llmHint` end to end — that is where the template states how its on-screen text and its layouts must be authored.
 3. Read its `customPayloadSchema`: every template-specific field lives there, including the enum of legal `customPayload.slideId` values for multi-layout templates.
-3b. If the template ships `slideSchemas` (multi-layout templates do), **author `templateData` straight from `slideSchemas[slideId]`** — it is the only place the per-layout field names exist. Do not infer them: the same concept is named `name` in one layout, `label` in another and `era` in a third, and a wrong name is dropped in silence (see below).
+3b. If the template ships `slideSchemas` (multi-layout templates do), step 1 returns them as a **menu** — per layout: description, field names, card-list key / item fields / `maxItems`, and a `narration` note. Pick layouts and draft the script from the menu. Then, before writing `templateData`, call `template_registry` once with `template_id` and `slide_id=[every chosen layout]`, and **author `templateData` straight from those `slideSchemas[slideId]`** — it is the only place the per-layout field names exist. Do not infer them: the same concept is named `name` in one layout, `label` in another and `era` in a third, and a wrong name is dropped in silence (see below).
 4. Combine that with the template's `slotMapping`, `requiredProps`, `optionalProps`, `propExtractors`, `assetRequirements`, `supportedAspectRatios`, `supportedDurations`, `constraints`, and `scenePatterns`.
 5. Generate the DSL in the template's native shape — not the generic DSL shape.
 6. Make sure the DSL explicitly contains every template-specific field, e.g. `templateData.words`, `customPayload.slideId`, `visuals.avatar.assetRef`.
-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.
+7. After generation, run the schema check and show the script summary to the user for confirmation.
 
 ### Document-driven templates: pass the source URL, don't author the payload
 
@@ -473,7 +472,7 @@ Apply the following principles when producing the DSL:
 
 1. **Narrative-first**: opening hook → point expansion → CTA close.
 2. **Assets are declared, not executed**: every asset starts as `AssetRef` with `status: planned`; no generation API call from this skill.
-3. **Narration drives duration**: each scene's duration should match its narration reading time (≈ 3–4 zh chars/sec, or ~2 words/sec for English).
+3. **Narration drives duration**: the rendered length of a scene is its narration's reading time plus a short tail, not `scenes[].duration`. Each skeleton placeholder states the scene's budget (e.g. `(8s，整段≤32 字；分行旁白每多一行约少 4 字)`) — write inside it. The budget comes from `video_dsl/runtime/narration_budget.py` (≈4.5 zh chars/s at 1.0× speed, ~0.9s pause per extra narration line, 1.5s tail per scene unless the template declares `capabilities.defaultTailPadSec`). If you go over, report the longer estimated length at script confirmation; `prepare_video_assets` also warns when the estimate exceeds `meta.targetDuration` by more than 30%.
 4. **One complete thought per line — do NOT pre-split at subtitle width.** Separate lines inside `audio.narration.text` with `\n`, and put **one full clause or sentence** on each line (roughly 15–30 Chinese characters, or an equivalent number of English words). A `\n` is a hard cut in the *audio*: TTS treats each line as its own segment and returns a timestamp for it, so lines should fall where a human would actually pause for breath.
 
    **Do not cut mid-phrase to make lines "subtitle-sized".** The renderer splits each line into on-screen subtitles itself, and it does that better than you can from the text alone: it measures the real glyph widths for the actual font size and frame (`HNSW` is not as wide as four Chinese characters), knows how many characters fit on one line of *this* template and aspect ratio, and picks cut points by punctuation strength (sentence end → colon → comma → enumeration comma → space). It also guarantees no wrapping. Pre-splitting takes all of that away and just makes the captions choppy.
@@ -526,4 +525,4 @@ prefix and version — not a short alias:
 |------|---------|
 | `gen_script.py` | Core script — produces the Video DSL JSON from a topic. |
 
-The authoritative per-template contract is the registry's `template.json` (`llmHint` + `customPayloadSchema` + `slideSchemas` + `slotMapping`) — everything you need to author against is in there, so read it rather than inferring field names from the template's name or from another template. `template_registry list_examples=true` lists local reference DSLs when any exist, but that directory does not ship — see *DSL schema* above.
+The authoritative per-template contract is the registry's `template.json` (`llmHint` + `customPayloadSchema` + `slideSchemas` + `slotMapping`) — everything you need to author against is in there, so read it rather than inferring field names from the template's name or from another template.

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

@@ -73,6 +73,14 @@ except ImportError:
     _HAS_ENHANCER = False
     SKELETON_PREFIXES = ("[骨架待填充]", "[skeleton placeholder]")
 
+# 旁白字数预算：写进骨架占位旁白，让模型写脚本时就知道这一场放得下多少字。
+# 守护式导入同上；缺失时占位文案退回不带预算的旧格式。
+try:
+    from video_dsl.runtime import narration_budget as _nb
+    _HAS_BUDGET = True
+except ImportError:
+    _HAS_BUDGET = False
+
 # 场景数上限的唯一实现在 dsl_validator（它同时是门禁方）。守护式导入的理由同上：
 # 共享目录可能不在（单测 / 裁剪安装），那时退回历史常量 20，行为与改动前一致。
 try:
@@ -110,7 +118,8 @@ except ImportError:
 VALID_RATIOS = ["16:9", "9:16", "1:1", "4:3", "3:4", "21:9"]
 VALID_PURPOSES = ["opening", "point", "example", "explanation", "highlight", "cta", "ending"]
 
-CHARS_PER_SECOND = 5.0  # 与 timeline_compiler.py 保持一致（中文约 5 字/秒）
+# 规划用语速 / 行间停顿 / 场景尾巴统一在 video_dsl.runtime.narration_budget。
+# 这里原有的 CHARS_PER_SECOND = 5.0 从未参与计算（只出现在注释里），已删。
 
 # ── Language contract (mirrors apps/ab-skill/src/handlers/template-meta.ts) ──
 # template.json may declare:
@@ -230,20 +239,25 @@ def _localize_label(language, key, **fmt):
         "label_point":   {"zh": "内容要点 {n}", "en": "Point {n}"},
         "label_cta":     {"zh": "结尾 CTA", "en": "Closing CTA"},
         "narration_opening": {
-            "zh": "[骨架待填充] 关于{topic}的开场 Hook({duration}s)",
-            "en": "[skeleton placeholder] Opening hook about {topic} ({duration}s)",
+            "zh": "[骨架待填充] 关于{topic}的开场 Hook({duration}s{budget})",
+            "en": "[skeleton placeholder] Opening hook about {topic} ({duration}s{budget})",
         },
         "narration_point": {
-            "zh": "[骨架待填充] {label}:关于{topic}的一个要点({duration}s)",
-            "en": "[skeleton placeholder] {label}: a point about {topic} ({duration}s)",
+            "zh": "[骨架待填充] {label}:关于{topic}的一个要点({duration}s{budget})",
+            "en": "[skeleton placeholder] {label}: a point about {topic} ({duration}s{budget})",
         },
         "narration_cta": {
-            "zh": "[骨架待填充] 关于{topic}的 CTA 结尾({duration}s)",
-            "en": "[skeleton placeholder] Closing CTA about {topic} ({duration}s)",
+            "zh": "[骨架待填充] 关于{topic}的 CTA 结尾({duration}s{budget})",
+            "en": "[skeleton placeholder] Closing CTA about {topic} ({duration}s{budget})",
+        },
+        # {budget} 由 _budget_suffix 填：「，整段≤32 字；分行每多一行约少 4 字」。
+        "budget_suffix": {
+            "zh": "，整段≤{chars} 字；分行旁白每多一行约少 {per_line} 字",
+            "en": ", ≤{chars} words as one block; ~{per_line} fewer per extra narration line",
         },
         "narration_default": {
-            "zh": "[骨架待填充] 关于{topic}的内容({duration}s)",
-            "en": "[skeleton placeholder] Content about {topic} ({duration}s)",
+            "zh": "[骨架待填充] 关于{topic}的内容({duration}s{budget})",
+            "en": "[skeleton placeholder] Content about {topic} ({duration}s{budget})",
         },
         # NOTE: 这里曾有 "point_description"（"关于{topic}的要点内容"）与
         # "more_about"（"更多关于{topic}的内容"）两条，用来给 no-visual 场景拼画面
@@ -257,6 +271,9 @@ def _localize_label(language, key, **fmt):
     }
     entry = table.get(key, {})
     template = entry.get(language) or entry.get(DEFAULT_LANGUAGE) or ""
+    # 字数预算只有按场景规划的路径才算得出来（轮播 / 按字幕定时长的模板没有
+    # 「每场秒数」这个前提），没给就是不带预算的旧格式。
+    fmt.setdefault("budget", "")
     return template.format(**fmt)
 
 
@@ -363,17 +380,47 @@ def plan_scenes(
     return scenes
 
 
-def estimate_narration_text(label: str, purpose: str, duration: int, topic: str, language: str = DEFAULT_LANGUAGE) -> str:
+def _budget_suffix(duration: int, language: str, speed: float, tail_pad_sec: float | None) -> str:
+    """占位旁白里的字数预算。拿不到预算模块时返回空串（退回旧格式）。
+
+    为什么写进占位文案而不是单独字段：模型填旁白时一定会读到这一句，而骨架多一个
+    字段就得在校验白名单、TTS payload 两头都处理，漏一头就是新的静默问题。
+    """
+    if not _HAS_BUDGET:
+        return ""
+    tail = _nb.DEFAULT_TAIL_PAD_SEC if tail_pad_sec is None else tail_pad_sec
+    lang = "zh" if language == "zh" else "en"
+    chars = _nb.speech_budget(duration, speed, lang, lines=1, tail_pad_sec=tail)
+    per_line = max(1, round(_nb.LINE_PAUSE_SEC * _nb.speech_rate(lang, speed)))
+    return _localize_label(language, "budget_suffix", chars=chars, per_line=per_line)
+
+
+def estimate_narration_text(
+        label: str,
+        purpose: str,
+        duration: int,
+        topic: str,
+        language: str = DEFAULT_LANGUAGE,
+        speed: float = 1.0,
+        tail_pad_sec: float | None = None,
+) -> str:
     """Generate a short skeleton narration hint for a scene.
 
     This returns a *skeleton only* — the agent is expected to replace this
     text with real narration before submitting DSL to prepare_video_assets. We
     deliberately return a short, clearly-placeholder-looking string rather
-    than padding to duration × CHARS_PER_SECOND, because padding with a
+    than padding to the scene's length, because padding with a
     repeating filler sentence historically caused the skeleton to be
     submitted verbatim to TTS (audio narration mismatch bug).
+
+    It does carry the scene's narration *budget* (see narration_budget): the
+    one number the agent needs while writing, and never had — a 2026-09-27
+    session wrote 45–58 chars into 8s scenes and shipped 117s for a 75s target.
     """
-    fmt = {"label": label, "topic": topic, "duration": duration}
+    fmt = {
+        "label": label, "topic": _clip(topic, _PLACEHOLDER_TOPIC_CHARS), "duration": duration,
+        "budget": _budget_suffix(duration, language, speed, tail_pad_sec),
+    }
     if purpose == "opening":
         return _localize_label(language, "narration_opening", **fmt)
     if purpose == "point":
@@ -681,6 +728,32 @@ def _placeholder_text_layers(rules: dict) -> list[dict]:
     return layers
 
 
+# 视频标题 / 占位旁白里引用 topic 的长度上限。topic 是给模型写脚本用的内容提要，
+# 线上常见 200+ 字（2026-09-27 一条会话 250 字），原样拿去当标题或塞进每场占位旁白
+# 都不合适。
+_TITLE_MAX_CHARS = 60
+_PLACEHOLDER_TOPIC_CHARS = 30
+
+
+def _clip(text: str, limit: int) -> str:
+    text = " ".join((text or "").split())
+    return text if len(text) <= limit else text[: limit - 1].rstrip() + "…"
+
+
+def _video_title(headline: str | None, topic: str) -> str:
+    """meta.title：成片的标题。
+
+    它会成为上传点播的标题（render_video 的 upload_title_hint）和脚本产物列表的
+    标题（ab-api artifact_narration.dslTitle）。以前直接等于 topic —— 模型传进来的
+    是一段内容提要，于是作品标题成了「讲解 AI Agent 的核心底层逻辑「Agent Loop」：
+    传统大模型的单次响应 vs…」（render_video 只能截到 128 字兜底）。用户给了
+    headline 就用 headline（折掉换行），没给才退回截短的 topic；完整 topic 仍在
+    meta.topic。
+    """
+    # 画面文案里的 **强调** 标记对标题没有意义，去掉。
+    return _clip((headline or "").replace("**", ""), _TITLE_MAX_CHARS) or _clip(topic, _TITLE_MAX_CHARS)
+
+
 def _normalize_linebreaks(value: str | None) -> str:
     """把画面文字里的**字面量** ``\\n`` 折成真换行。
 
@@ -1121,7 +1194,7 @@ def _build_carousel_caption_dsl(
 
     # ── Narration skeleton ────────────────────────────────────────────────
     narration_text = _localize_label(output_language, "narration_opening",
-                                     label="", topic=topic, duration=duration)
+                                     label="", topic=_clip(topic, _PLACEHOLDER_TOPIC_CHARS), duration=duration)
 
     # ── Effective scene duration ──────────────────────────────────────────
     # fit-caption 策略：时长由打字机自然节奏决定，而不是盲取调用方传入的 targetDuration。
@@ -1173,7 +1246,7 @@ def _build_carousel_caption_dsl(
     dsl = {
         "version": "v1alpha1",
         "meta": {
-            "title": topic,
+            "title": _video_title(headline, topic),
             "topic": topic,
             "headline": effective_headline,
             "subheadline": effective_subheadline,
@@ -1577,6 +1650,7 @@ def build_dsl(
     image_compose = _HAS_ENHANCER and is_compose_mode(image_style_guide)
     image_ratio = image_style_guide.get("ratio") or ratio
 
+    tail_pad_sec = _nb.template_tail_pad_sec(template_config) if _HAS_BUDGET else None
     for idx, plan in enumerate(scene_plans):
         scene_id = f"scene-{idx + 1:02d}"
         # 视觉素材的 assetId 命名遵循类型前缀：image → img-，video → video-
@@ -1586,7 +1660,10 @@ def build_dsl(
             visual_asset_id = f"img-{scene_id}"
         narration_asset_id = f"narration-{scene_id}" if needs_narration else None
         narration_text = (
-            estimate_narration_text(plan["label"], plan["purpose"], plan["duration"], topic, language=output_language)
+            estimate_narration_text(
+                plan["label"], plan["purpose"], plan["duration"], topic, language=output_language,
+                speed=narration_speed, tail_pad_sec=tail_pad_sec,
+            )
             if needs_narration else ""
         )
 
@@ -1828,7 +1905,7 @@ def build_dsl(
     dsl = {
         "version": "v1alpha1",
         "meta": {
-            "title": topic,
+            "title": _video_title(effective_headline if headline else None, topic),
             "topic": topic,
             "headline": effective_headline,
             "subheadline": effective_subheadline,

package/skills/gen-script/version.json

@@ -2,6 +2,6 @@
   "skillName": "gen-script",
   "repoName": "agent-skill-media-maker",
   "skillId": "474",
-  "version": "V17",
+  "version": "V18",
   "skillDescription": "Video-script generation skill. Turns a user-supplied topic into a structured Video DSL (JSON) that describes the full video — scene structure, asset requirements, and narrative flow.\n\nUse this skill as soon as the user mentions any of these intents:\n- Write a video script, generate a video script, plan a video, write storyboards\n- Create a short video, plan video content, generate a Video DSL\n- Turn a topic into a video structure / video content plan\n\nEven when the user does not say \"generate the DSL\", use this skill whenever they want to turn a topic into a structured video plan.\n\n⚠️ Stop-and-confirm gate: after this skill returns a DSL, show the full script and wait for the user's explicit confirmation. Never call `prepare_video_assets` in the same turn."
 }

package/skills/template-registry/README.md

@@ -17,7 +17,7 @@ HTTP 拉取带磁盘缓存（TTL + ETag/304）；瞬时故障时降级复用同
 
 ab-api 响应包装格式 `{code, msg, data}` 由 `registry_loader._fetch_http` 透明拆封;静态 JSON endpoint 也支持(直接返回 registry 文档)。
 
-> 早期文档曾描述本 skill 通过 `@ab-templates/metadata` npm 包 / monorepo 文件消费 registry —— 这些本地来源已移除，运行时只走 ab-api HTTP。monorepo 文件仅供 `check_contracts.py` / `sync_registry.py` 等 monorepo-only 维护脚本使用。
+> 早期文档曾描述本 skill 通过 `@ab-templates/metadata` npm 包 / monorepo 文件消费 registry —— 这些本地来源已移除，运行时只走 ab-api HTTP。配套的 monorepo-only 维护脚本（`check_contracts.py` / `sync_registry.py`）也已随之删除，契约对账改由 template-library 的 `generateManifest` / `validate:contracts` 在上游负责。
 
 ## 新增模板工作流
 

package/skills/template-registry/SKILL.md

@@ -61,7 +61,8 @@ 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. **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.
+2. **Read that template's contract**: run `remixmate template-registry --template-id <id>` 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. Never fetch it twice in one turn. In the chat agent, tool results do **not** carry over between turns, so fetch per turn only what that turn needs: the menu while drafting the script, `--slide-id` while writing `templateData`.
+2b. **Multi-layout templates: expand only the layouts you use.** For templates that ship `slideSchemas`, step 2 returns a per-layout **menu** (description, field names, card-list key / item fields / `maxItems`, and a `narration` note on layouts that must split narration into `items`). Choose layouts and draft the script from the menu; then, right before writing `templateData`, call once more with `--slide-id <id>` for every chosen layout (repeatable) to get their exact field schemas.
 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.
 
@@ -91,13 +92,14 @@ print(json.dumps(binding, ensure_ascii=False, indent=2))
 | Flag | Description | Default |
 |------|-------------|---------|
 | `--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. | — |
+| `--template-id <id>` | Print that template's **full definition** — llmHint in full, `customPayloadSchema`, `slotMapping`, `compositions`, `variants` — as compact JSON. Multi-layout templates return `slideSchemas` as a menu. Repeatable. | — |
+| `--slide-id <slideId>` | With `--template-id`: expand these layouts' full `slideSchemas` (repeatable; `all` = every layout, large). Unknown ids fail with the legal list. | menu |
 | `--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 — summaries, or full definitions under `--template-id` / `--full`. | off |
+| `--json-output` | List mode: emit `{ "templates": [...] }` summaries (or full definitions with `--full`) instead of the table. Detail mode (`--template-id`) is always compact JSON. | off |
 
 ### List vs. detail
 
@@ -105,9 +107,12 @@ A registry row is 4–17 KB of JSON, so dumping every full definition at once ov
 
 ```bash
 remixmate template-registry --list-templates                         # choose
-remixmate template-registry --template-id <templateId> --json-output   # then read its contract
+remixmate template-registry --template-id <templateId>                 # then read its contract (slide menu)
+remixmate template-registry --template-id <templateId> --slide-id key-points --slide-id timeline   # exact schemas of the chosen layouts
 ```
 
+Detail mode used to pretty-print, which nearly doubled the size (html-slide: 37 K → 65 K characters) and pushed the plain call past the agent's tool-result cap — the result was spilled to a file the agent cannot open, so it re-called with other flags, and re-read the whole contract on the next turn too (session review 2026-09-27). Output is now always compact, and `slideSchemas` — two thirds of a multi-layout template — is a menu until you name the layouts.
+
 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

@@ -32,10 +32,27 @@ List vs. detail (why ``--json-output`` no longer dumps everything):
   programmatic callers, guarded by a size check so it can't silently recreate
   the overflow.
 
+Slide menu (why --template-id no longer returns every slideSchemas body):
+  slideSchemas is two thirds of a multi-layout template (html-slide: 24.6 K of
+  37.2 K chars, 26 layouts), while one video uses 5–9 layouts. Returning all of
+  it every time pushed the detail view past the agent's tool-result size cap
+  (the result got spilled to a file the agent cannot open, so it re-called
+  with other flags), and the agent re-read the whole thing on the next turn
+  anyway. So detail mode returns a per-layout *menu* — description, field
+  names, list key / item fields / maxItems, and whether narration must be
+  split into items — which is enough to choose layouts and draft a script;
+  ``--slide-id`` then returns the exact schemas of the chosen layouts for
+  writing ``templateData``. Registry consumers inside the pipeline (validator,
+  render) read the registry directly and are unaffected.
+
 Flags:
   --list-templates                 (accepted; listing is the default verb)
   --template-id <id>               print the FULL definition of this template
-                                   (repeatable); this is the detail verb
+                                   (repeatable); this is the detail verb.
+                                   Multi-layout templates come back with a
+                                   slideSchemas *menu* (see "Slide menu" below)
+  --slide-id <slideId|all>         detail mode: expand these layouts' full
+                                   templateData schemas (repeatable)
   --full                           in list mode, emit full definitions instead
                                    of summaries (size-guarded; prefer
                                    --template-id)
@@ -159,6 +176,96 @@ def _detail_hint(template_id: str = "<templateId>") -> str:
     )
 
 
+# ----- Slide menu (--template-id without --slide-id) -------------------------
+
+_SLIDE_EXPAND_ALL = "all"
+
+
+def _slide_schema_ids(tpl: dict) -> list[str]:
+    ss = tpl.get("slideSchemas")
+    if not isinstance(ss, dict):
+        return []
+    return [k for k, v in ss.items() if not k.startswith("_") and isinstance(v, dict)]
+
+
+def _menu_entry(schema: dict, line_sync_key: str | None) -> dict:
+    """One layout's menu row: enough to pick it and draft a script, not to fill it."""
+    props = schema.get("properties") if isinstance(schema.get("properties"), dict) else {}
+    entry: dict = {}
+    if schema.get("description"):
+        entry["description"] = schema["description"]
+    entry["fields"] = list(props.keys())
+    if schema.get("required"):
+        entry["required"] = schema["required"]
+    # The card list: the line-sync key when declared, else the first array of objects.
+    list_key = line_sync_key if line_sync_key in props else None
+    if list_key is None:
+        for k, v in props.items():
+            if isinstance(v, dict) and v.get("type") == "array" and isinstance(v.get("items"), dict) \
+                    and v["items"].get("type") == "object":
+                list_key = k
+                break
+    if list_key is not None:
+        arr = props[list_key]
+        item = arr.get("items") if isinstance(arr.get("items"), dict) else {}
+        item_props = item.get("properties") if isinstance(item.get("properties"), dict) else {}
+        lst = {"key": list_key, "itemFields": list(item_props.keys())}
+        if item.get("required"):
+            lst["itemRequired"] = item["required"]
+        if "maxItems" in arr:
+            lst["maxItems"] = arr["maxItems"]
+        entry["list"] = lst
+    if line_sync_key:
+        # The single most expensive miss in practice: authoring one narration
+        # block for a layout that lights cards one by one (validator rejects it).
+        entry["narration"] = (
+            f"items — one audio.narration.items line per templateData.{line_sync_key} entry, no text"
+        )
+        static = [k for k, v in props.items() if isinstance(v, dict) and v.get("x-staticHighlight")]
+        if static:
+            entry["narrationStaticAlternative"] = f"set templateData.{static[0]} to keep it static instead"
+    return entry
+
+
+def _apply_slide_view(tpl: dict, slide_ids: list[str] | None) -> dict:
+    """Return tpl with slideSchemas reduced to a menu, or to the requested layouts."""
+    ss = tpl.get("slideSchemas")
+    if not isinstance(ss, dict):
+        return tpl
+    ids = _slide_schema_ids(tpl)
+    out = dict(tpl)
+    if slide_ids and _SLIDE_EXPAND_ALL in slide_ids:
+        out["slideSchemas"] = {k: v for k, v in ss.items() if k != "_comment"}
+        return out
+    line_sync = tpl.get("lineSyncSlides") if isinstance(tpl.get("lineSyncSlides"), dict) else {}
+    if slide_ids:
+        view: dict = {
+            "_view": (
+                f"Full templateData schemas for: {', '.join(slide_ids)}. Copy field names from here. "
+                "Other layouts are omitted — pass their ids in slide_id to read them."
+            ),
+        }
+        if isinstance(ss.get("_shared"), dict):
+            view["_shared"] = ss["_shared"]
+        for sid in slide_ids:
+            view[sid] = ss[sid]
+        out["slideSchemas"] = view
+        return out
+    menu: dict = {
+        "_view": (
+            "MENU ONLY — per-layout summary, not the full schema. Use it to choose layouts and draft the "
+            "script. Before writing templateData, call template_registry again with this template_id and "
+            "slide_id=<each chosen layout> (repeatable) to get their exact field schemas. "
+            "Tool results do not carry over between chat turns: fetch the menu while drafting the script, slide_id while writing templateData."
+        ),
+    }
+    for sid in ids:
+        lk = line_sync.get(sid)
+        menu[sid] = _menu_entry(ss[sid], lk if isinstance(lk, str) else None)
+    out["slideSchemas"] = menu
+    return out
+
+
 # ----- Examples discovery (--list-examples) ---------------------------------
 #
 # Examples live under <SkillDir>/video_dsl/schema/examples/ as `*.dsl.json` and
@@ -217,6 +324,9 @@ def main() -> None:
                     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("--slide-id", action="append", dest="slide_ids", metavar="SLIDE_ID",
+                    help="Detail mode: expand these layouts' full slideSchemas (repeatable; "
+                         "'all' = every layout). Without it multi-layout templates return a menu.")
     ap.add_argument("--full", action="store_true",
                     help="List mode: emit full definitions instead of summaries "
                          "(size-guarded; prefer --template-id).")
@@ -326,13 +436,28 @@ def main() -> None:
             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))
+        if args.slide_ids:
+            wanted = [s for s in args.slide_ids if s != _SLIDE_EXPAND_ALL]
+            known_slides = {sid for t in picked for sid in _slide_schema_ids(t)}
+            if not known_slides:
+                print("⚠️  --slide-id ignored: this template has no slideSchemas (single layout).",
+                      file=sys.stderr)
+            else:
+                unknown = [s for s in wanted if s not in known_slides]
+                if unknown:
+                    print(f"❌ Unknown slide id(s): {', '.join(unknown)}", file=sys.stderr)
+                    print(f"   Legal slide ids: {', '.join(sorted(known_slides))}", file=sys.stderr)
+                    sys.exit(1)
+        picked = [
+            _apply_slide_view(t, [s for s in (args.slide_ids or []) if s in _slide_schema_ids(t)
+                                  or s == _SLIDE_EXPAND_ALL] or None)
+            for t in picked
+        ]
+        # Always compact, with or without --json-output. Every caller is an LLM
+        # tool call: indent=2 nearly doubled the size (html-slide 37 K → 65 K
+        # chars), which alone pushed the plain call past the tool-result cap and
+        # got it spilled to a file the agent cannot read. Humans can `| jq`.
+        print(json.dumps({"templates": picked}, ensure_ascii=False))
         return
 
     visible = [

package/skills/template-registry/skill.json

@@ -12,9 +12,9 @@
     "type": "object",
     "properties": {
       "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." },
+      "template_id": { "type": "string", "description": "Return this template's full authoring contract instead of the summary list: llmHint in full, customPayloadSchema (every template-specific field incl. the legal slideId values), slotMapping, compositions, variants. Multi-layout templates return slideSchemas as a MENU (per layout: description, field names, card-list key / item fields / maxItems, and whether narration must be split into items) — enough to pick layouts and draft the script. Tool results do not carry over between chat turns: read the menu in the turn that drafts the script; the turn that writes templateData only needs slide_id." },
+      "slide_id": { "type": "array", "items": { "type": "string" }, "description": "With template_id: return the FULL templateData schema for these layouts (the slideIds you chose from the menu). Call this once, right before writing templateData, with every layout the script uses. 'all' returns every layout (large — avoid)." },
       "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)." },

package/skills/template-registry/version.json

@@ -2,6 +2,6 @@
   "skillName": "template-registry",
   "repoName": "agent-skill-media-maker",
   "skillId": "475",
-  "version": "V23",
+  "version": "V24",
   "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

@@ -822,6 +822,66 @@ def _check_step_narration_alignment(dsl: dict) -> list[ValidationError]:
     return errors
 
 
+def _check_duration_estimate(dsl: dict) -> list[ValidationError]:
+    """按旁白字数估出的成片时长明显超过 ``meta.targetDuration`` → warning。
+
+    为什么要有:旁白字数决定时长,但没有任何一环在出素材之前核对过。2026-09-27 线上
+    一条 html-slide 会话,确认稿写 75s、每场 8–9s,每场却写了 45–58 字,还有 7 场是
+    分行旁白(每行之间有停顿)—— 成片 116.9s,用户确认的是一个从来不可能兑现的数。
+
+    只报 warning 不拦:走到这里用户已经确认过脚本,再拦只会多一轮来回;它存在的意义
+    是让这件事**有人看见**(模型据此如实告知用户,复盘据此定位)。估算口径见
+    ``narration_budget``。骨架占位旁白还没填时不估 —— 那是另一条检查的事。
+    """
+    try:
+        from . import narration_budget as nb
+    except ImportError:
+        return []
+
+    meta = dsl.get("meta") or {}
+    target = meta.get("targetDuration")
+    if isinstance(target, bool) or not isinstance(target, (int, float)) or target <= 0:
+        return []
+    narration_cfg = ((dsl.get("global") or {}).get("narration") or {})
+    speed = narration_cfg.get("speed")
+    speed = float(speed) if isinstance(speed, (int, float)) and not isinstance(speed, bool) and speed > 0 else 1.0
+    tail = nb.template_tail_pad_sec(_get_template_cfg(_pick_template_id(dsl)))
+
+    total = 0.0
+    narrated = 0
+    overruns: list[tuple[float, str, float, float]] = []
+    for idx, scene in enumerate(dsl.get("scenes", []) or []):
+        narration = (scene.get("audio") or {}).get("narration") or {}
+        lines = nb.narration_lines(narration)
+        if any(line.startswith(("[骨架待填充]", "[skeleton placeholder]")) for line in lines):
+            return []
+        planned = scene.get("duration")
+        planned = float(planned) if isinstance(planned, (int, float)) and not isinstance(planned, bool) else 0.0
+        est = nb.estimate_scene_sec(narration, speed, tail)
+        if est > 0:
+            narrated += 1
+            if planned > 0 and est - planned > 1.0:
+                overruns.append((est - planned, scene.get("id", f"scenes[{idx}]"), est, planned))
+        total += max(est, planned) if est > 0 else planned
+
+    if not narrated or total <= target * (1 + nb.OVERRUN_WARN_RATIO):
+        return []
+
+    overruns.sort(reverse=True)
+    detail = "; ".join(f"{sid} ≈{est:.0f}s (planned {planned:.0f}s)" for _, sid, est, planned in overruns[:5])
+    return [ValidationError(
+        "meta.targetDuration",
+        f"estimated video length ≈{total:.0f}s vs target {target:.0f}s "
+        f"(+{(total / target - 1) * 100:.0f}%) at narration speed {speed:g}× — "
+        f"~{nb.PLAN_CHARS_PER_SEC_1X * speed:.1f} zh chars/s, +{nb.LINE_PAUSE_SEC}s per extra "
+        f"narration line, +{tail:g}s tail per scene. Longest overruns: {detail or 'n/a'}. "
+        "Report the real length to the user (not the target) when you show the result; "
+        "narration drives duration, so to hit the target the narration must get shorter "
+        "or use fewer items.",
+        severity="warning",
+    )]
+
+
 def _check_slide_payload_fields(dsl: dict) -> list[ValidationError]:
     """逐版式校验 ``customPayload.templateData`` 的字段名。
 
@@ -1269,6 +1329,8 @@ def validate_integrity(dsl: dict) -> list[ValidationError]:
     errors += _check_step_narration_alignment(dsl)
     errors += _check_slide_cross_field(dsl)
     errors += _check_text_layer_rules(dsl)
+    # warning,不阻断。见 _check_duration_estimate。
+    errors += _check_duration_estimate(dsl)
     return errors
 
 
@@ -1304,4 +1366,6 @@ def validate_dsl(dsl: dict) -> list[ValidationError]:
     errors += _check_step_narration_alignment(dsl)
     errors += _check_slide_cross_field(dsl)
     errors += _check_text_layer_rules(dsl)
+    # warning,不阻断。见 _check_duration_estimate。
+    errors += _check_duration_estimate(dsl)
     return errors

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

@@ -0,0 +1,129 @@
+"""
+旁白时长预算 —— 规划期（写脚本时）估算「这段旁白念完、这一场实际会有多长」。
+
+为什么单独成模块：以前这个数有三份且互不一致 —— gen_script 的 ``CHARS_PER_SECOND = 5.0``
+（从没参与计算，只出现在注释里）、gen-script SKILL.md 的「3–4 字/秒」、timeline_compiler
+的 5.0（那份是没有 TTS 时间戳时估字幕时长的兜底，语义不同，不归这里管）。没有任何一环
+真的拿旁白字数去核对场景时长，于是 2026-09-27 线上一条会话：确认稿写 75s、每场 8–9s，
+每场却写了 45–58 字，成片 116.9s（+56%），用户确认的时长从一开始就不可能兑现。
+
+模型 = 语速 + 行间停顿 + 场景尾巴，三项都按那条会话的 9 条 TTS 实测标定：
+
+* 语速：纯整段旁白的场景 1.1× 下 ≈ 4.8–5.2 计数字/秒（汉字 + 英文词×2）→ 1.0× 取
+  ``PLAN_CHARS_PER_SEC_1X = 4.5``（略偏保守）；
+* 行间停顿：分行旁白（``narration.items`` / intro / outro）每多一行，TTS 按段合成，
+  段间约 0.9s 的静音 —— 逐项高亮版式同样字数要慢出 30–60%，主要就是它；
+* 场景尾巴：``render_video.adjust_timeline_to_audio`` 在每场音频后补的留白
+  （模板 ``capabilities.defaultTailPadSec``，缺省 1.5s）。9 场就是 13.5s，写脚本时
+  从没人算进去。
+
+样本只有一条会话，所以这些是**规划用**的估计，不是承诺；估不准的方向应当是偏保守
+（宁可让模型少写几个字）。英文语速未标定，先按常见 TTS 语速给。
+"""
+
+from __future__ import annotations
+
+import math
+import re
+from typing import Optional
+
+# 语速（1.0× 下）。中文按「计数字」（见 count_speech_units），英文按词。
+PLAN_CHARS_PER_SEC_1X = 4.5
+PLAN_WORDS_PER_SEC_1X = 2.5  # 未标定
+
+# 分行旁白每一处换行带来的静音。
+LINE_PAUSE_SEC = 0.9
+
+# 必须与 render_video.adjust_timeline_to_audio 的缺省尾巴一致（int(fps * 1.5)）。
+DEFAULT_TAIL_PAD_SEC = 1.5
+
+# 估算总时长超出目标多少才告警。低于这个幅度属于估算误差本身的量级。
+OVERRUN_WARN_RATIO = 0.3
+
+_CJK = re.compile(r"[\u3400-\u9fff\uf900-\ufaff]")
+# 中文旁白里夹的英文词 / 数字组（"AI Agent"、"2026"）。一个英文词 TTS 念出来大约
+# 占两个汉字的时长。
+_LATIN_WORD = re.compile(r"[A-Za-z0-9]+(?:['’.-][A-Za-z0-9]+)*")
+
+
+def count_speech_units(text: str) -> tuple[float, str]:
+    """返回 (计数, 语言)。有汉字按中文计（汉字 + 英文词×2），否则按英文词计。"""
+    if not isinstance(text, str) or not text.strip():
+        return 0.0, "zh"
+    cjk = len(_CJK.findall(text))
+    words = len(_LATIN_WORD.findall(text))
+    if cjk:
+        return float(cjk + 2 * words), "zh"
+    return float(words), "en"
+
+
+def narration_lines(narration: object) -> list[str]:
+    """旁白按 TTS 实际合成的段拆开：分行形态 = intro + items + outro，否则整段 text。
+
+    与 render_video.extract_narration_lines 同口径：有 items 时 text 被整个忽略。
+    """
+    if not isinstance(narration, dict):
+        return []
+    items = narration.get("items")
+    lines: list[str] = []
+    if isinstance(items, list):
+        for x in items:
+            t = x.get("text", "") if isinstance(x, dict) else x
+            if isinstance(t, str) and t.strip():
+                lines.append(t.strip())
+    if lines:
+        for key, at_front in (("intro", True), ("outro", False)):
+            v = narration.get(key)
+            if isinstance(v, str) and v.strip():
+                if at_front:
+                    lines.insert(0, v.strip())
+                else:
+                    lines.append(v.strip())
+        return lines
+    text = narration.get("text")
+    return [text.strip()] if isinstance(text, str) and text.strip() else []
+
+
+def speech_rate(language: str, speed: float) -> float:
+    base = PLAN_CHARS_PER_SEC_1X if language == "zh" else PLAN_WORDS_PER_SEC_1X
+    return base * (speed if speed and speed > 0 else 1.0)
+
+
+def estimate_speech_sec(narration: object, speed: float = 1.0) -> float:
+    """念完这段旁白要多少秒（含分行停顿，不含场景尾巴）。"""
+    lines = narration_lines(narration)
+    if not lines:
+        return 0.0
+    units, language = count_speech_units("\n".join(lines))
+    return units / speech_rate(language, speed) + LINE_PAUSE_SEC * (len(lines) - 1)
+
+
+def template_tail_pad_sec(template_config: Optional[dict]) -> float:
+    """场景尾巴：模板声明的 capabilities.defaultTailPadSec，缺省 1.5s。"""
+    caps = (template_config or {}).get("capabilities") or {}
+    v = caps.get("defaultTailPadSec") if isinstance(caps, dict) else None
+    if isinstance(v, bool) or not isinstance(v, (int, float)) or v < 0:
+        return DEFAULT_TAIL_PAD_SEC
+    return float(v)
+
+
+def estimate_scene_sec(narration: object, speed: float = 1.0, tail_pad_sec: float = DEFAULT_TAIL_PAD_SEC) -> float:
+    """这一场按旁白估出来的时长。没有旁白返回 0（由调用方退回场景自己的 duration）。"""
+    speech = estimate_speech_sec(narration, speed)
+    return speech + tail_pad_sec if speech > 0 else 0.0
+
+
+def speech_budget(
+    duration_sec: float,
+    speed: float = 1.0,
+    language: str = "zh",
+    lines: int = 1,
+    tail_pad_sec: float = DEFAULT_TAIL_PAD_SEC,
+) -> int:
+    """一场 ``duration_sec`` 秒的场景，旁白最多写多少字（中文）/ 词（英文）。
+
+    ``lines`` > 1 时扣掉分行停顿 —— 逐项高亮的版式同样秒数能写的字明显更少。
+    至少返回 1：预算为 0 的场景说明秒数本身就不够，调用方应当提示加时长而不是写空旁白。
+    """
+    available = duration_sec - tail_pad_sec - LINE_PAUSE_SEC * max(lines - 1, 0)
+    return max(1, int(math.floor(available * speech_rate(language, speed))))