@remixmate/cli 0.9.71 → 0.9.73

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

@@ -1,19 +1,19 @@
 #!/usr/bin/env python3
-"""
-Video script generator — turns a topic into Video DSL v1alpha1 JSON.
 
-Default behavior:
-  Produces a structured Video DSL JSON to stdout based on the topic, duration,
-  and other constraints.
 
-Usage:
-  python gen_script.py --topic "3 AI hacks that double study efficiency" --duration 30 --ratio "9:16"
-  python gen_script.py --validate --input my-video.dsl.json
 
-Environment variables:
-  VIDEO_DSL_SCHEMA_PATH - DSL schema file path
-    (default: skills/template-registry/video_dsl/schema/video-dsl-v1alpha1.json)
-"""
+
+
+
+
+
+
+
+
+
+
+
+
 
 import argparse
 import json
@@ -30,26 +30,26 @@ SCHEMA_PATH = os.environ.get(
     "skills/template-registry/video_dsl/schema/video-dsl-v1alpha1.json",
 )
 
-# prompt_enhancer 路径动态添加
+
 _TEMPLATE_DSL_DIR = os.path.join(os.path.dirname(__file__), "..", "..", "template-registry", "video_dsl")
 if os.path.isdir(_TEMPLATE_DSL_DIR):
     sys.path.insert(0, os.path.abspath(os.path.join(_TEMPLATE_DSL_DIR, "..")))
 
-# Shared Python lib lives under skills/template-registry/scripts/ — the de-facto
-# cross-skill module location (registry_loader, countdown_spec, etc.). See
-# AGENTS.md for the convention.
+
+
+
 _SHARED_SCRIPTS_DIR = os.path.join(
     os.path.dirname(__file__), "..", "..", "template-registry", "scripts"
 )
 if os.path.isdir(_SHARED_SCRIPTS_DIR):
     sys.path.insert(0, os.path.abspath(_SHARED_SCRIPTS_DIR))
 
-# countdown 策略的声明解析。与下面几个共享依赖同样守护式导入：本文件全篇假定
-# 共享目录**可能**不在（见 _SHARED_SCRIPTS_DIR 的 isdir 判断），硬导入会让共享目录
-# 缺失时连非 countdown 模板一起起不来。缺失只影响 countdown 这一条路，并在真的
-# 用到时明确报错。
+
+
+
+
 try:
-    from countdown_spec import (  # noqa: E402  (needs the sys.path setup above)
+    from countdown_spec import (
         opening_sec as countdown_opening_sec,
         resolve_count as resolve_countdown_count,
         resolve_countdown_spec,
@@ -73,16 +73,16 @@ 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:
     from video_dsl.runtime.dsl_validator import (
         DEFAULT_MAX_SCENES,
@@ -91,13 +91,13 @@ try:
 except ImportError:
     DEFAULT_MAX_SCENES = 20
 
-    def max_scenes_for_template(template_config):  # type: ignore[misc]
+    def max_scenes_for_template(template_config):
         return DEFAULT_MAX_SCENES
 
-# payloadHydration 声明的读取。gen_script 只用它来判断"这个模板需不需要源文件引用"，
-# 真正的取数发生在 render-video 侧（见 payload_hydrator 模块头）。
+
+
 try:
-    from payload_hydrator import hydration_spec  # noqa: E402
+    from payload_hydrator import hydration_spec
     _HAS_HYDRATOR = True
 except ImportError:
     _HAS_HYDRATOR = False
@@ -112,58 +112,58 @@ try:
 except ImportError:
     _HAS_REGISTRY_LOADER = False
 
-    class TemplateStatusGatedError(RuntimeError):  # type: ignore[no-redef]
-        """占位：共享模块不可导入时（单测 / 裁剪安装）永远不会被抛出。"""
+    class TemplateStatusGatedError(RuntimeError):
+        pass
 
 VALID_RATIOS = ["16:9", "9:16", "1:1", "4:3", "3:4", "21:9"]
 VALID_PURPOSES = ["opening", "point", "example", "explanation", "highlight", "cta", "ending"]
 
-# 规划用语速 / 行间停顿 / 场景尾巴统一在 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:
-#   - outputLanguage: "en" | "zh"   default "zh" when missing/invalid
-#   - defaultVoiceId: string        default None when missing/empty
-# Read tolerantly: any failure returns the legacy zh defaults plus a stderr warning.
+
+
+
+
+
+
+
 
 DEFAULT_LANGUAGE = "zh"
 LANGUAGE_TO_META = {"en": "en-US", "zh": "zh-CN"}
 
-# Fallback voices keyed by output language. Mirrors voice-resolver.ts FALLBACK_VOICE.
-# zh keeps the legacy default that's been used everywhere; en is a placeholder
-# until the gen-voice service confirms the right English voice id.
+
+
+
 FALLBACK_VOICE = {
     "zh": "Chinese (Mandarin)_Male_Announcer",
-    # TODO: confirm an English voice id against gen-voice service before shipping.
+
     "en": "english-male-friendly-01",
 }
 
-# ── Narration speed ───────────────────────────────────────────────────────────
-# Written to global.narration.speed; render_video copies it down into the
-# gen-voice asset payload (same route as narration text) and passes it to
-# `gen-voice --speed`. The envelope mirrors gen-voice's own 0.5–2.0 contract;
-# the real per-voice limits (capabilities speedMin/speedMax) are only known at
-# synthesis time, which is several confirmation steps and a few paid image
-# generations later — so an obviously-out-of-range value fails here instead.
+
+
+
+
+
+
+
 DEFAULT_NARRATION_SPEED = 1.0
 SPEED_MIN = 0.5
 SPEED_MAX = 2.0
 
 
 def _resolve_narration_speed(speed):
-    """CLI speed → the value written to global.narration.speed. Total function."""
+
     if speed is None:
         return DEFAULT_NARRATION_SPEED
     return float(speed)
 
 
 def _resolve_template_language_meta(template_config):
-    """Tolerant reader for outputLanguage / defaultVoiceId on a template dict.
 
-    Returns (language, default_voice_id). Never raises. Logs a single stderr
-    warning when fields are present but malformed.
-    """
+
+
+
+
     if not isinstance(template_config, dict):
         return DEFAULT_LANGUAGE, None
     raw_lang = template_config.get("outputLanguage")
@@ -185,10 +185,10 @@ def _resolve_template_language_meta(template_config):
 
 
 def _resolve_voice_id(cli_voice_id, template_default_voice_id, language):
-    """Mirror of voice-resolver.ts resolveVoiceId. Total function.
 
-    Order: explicit CLI override → template defaultVoiceId → language fallback.
-    """
+
+
+
     if isinstance(cli_voice_id, str) and cli_voice_id.strip():
         return cli_voice_id.strip()
     if isinstance(template_default_voice_id, str) and template_default_voice_id.strip():
@@ -197,12 +197,12 @@ def _resolve_voice_id(cli_voice_id, template_default_voice_id, language):
 
 
 def _check_narration_language(narrations, expected):
-    """Non-blocking sanity check: warn when narration looks like the wrong language.
 
-    Skips strings that start with NARRATION_SKELETON_MARKER or its English variant —
-    those are gen_script placeholders the agent will replace with real narration
-    before sending to prepare_video_assets, so a language mismatch on them is expected.
-    """
+
+
+
+
+
     cjk_re = __import__("re").compile(r"[\u4e00-\u9fff]")
     latin_re = __import__("re").compile(r"[A-Za-z]")
     for text in narrations:
@@ -227,13 +227,13 @@ def _check_narration_language(narrations, expected):
 
 
 def _localize_label(language, key, **fmt):
-    """Tiny localization helper for the on-screen / narration default strings.
 
-    Keeps the template-driven outputLanguage as the single source of truth: zh
-    templates keep their legacy Chinese phrasing, en templates emit English. We
-    deliberately keep the table small — anything more elaborate belongs in the
-    LLM prompt, not in this fallback skeleton.
-    """
+
+
+
+
+
+
     table = {
         "label_opening": {"zh": "开场 Hook", "en": "Opening hook"},
         "label_point":   {"zh": "内容要点 {n}", "en": "Point {n}"},
@@ -250,7 +250,7 @@ def _localize_label(language, key, **fmt):
             "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",
@@ -259,10 +259,10 @@ def _localize_label(language, key, **fmt):
             "zh": "[骨架待填充] 关于{topic}的内容({duration}s{budget})",
             "en": "[skeleton placeholder] Content about {topic} ({duration}s{budget})",
         },
-        # NOTE: 这里曾有 "point_description"（"关于{topic}的要点内容"）与
-        # "more_about"（"更多关于{topic}的内容"）两条，用来给 no-visual 场景拼画面
-        # 文案。两条都已删除：topic 长度不受控，拼进画面必然溢出，而正确的文案来源
-        # 是调用方给的 --headline / --subheadline。
+
+
+
+
         "follow_us": {"zh": "关注我们", "en": "Follow us"},
         "video_description": {
             "zh": "关于「{topic}」的{duration}秒短视频",
@@ -271,8 +271,8 @@ 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)
 
@@ -285,17 +285,17 @@ def load_schema():
 
 
 def validate_dsl(dsl: dict) -> list:
-    """Structural DSL validation — delegates to the unified validator.
-
-    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
-      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
+
+
+
+
+
+
+
+
+
+
+    from video_dsl.runtime.dsl_validator import (
         validate_structural,
         errors_as_strings,
     )
@@ -310,14 +310,14 @@ def plan_scenes(
     language: str = DEFAULT_LANGUAGE,
     max_scenes: int = DEFAULT_MAX_SCENES,
 ) -> list:
-    """Plan scene structure based on topic and constraints.
-
-    ``max_scenes`` 来自模板的 ``capabilities.maxScenes``（见 ``_resolve_contract``）。
-    被 clamp 时**必须出声**：调用方要的场景数和拿到的不一样，而这个差值一路传到
-    下游才会以别的形态爆出来——2026-09-23 线上一份 23 页 PPT 在这里被静默砍到 20，
-    模型接着写了 23 段旁白、让用户确认了 23 个场景，最后 prepare_video_assets 报的是
-    ``scenes[0..19].customPayload.slide (required)``，跟"场景被砍了"半点关系看不出来。
-    """
+
+
+
+
+
+
+
+
     requested = scene_count
     if scene_count is None:
         if duration <= 15:
@@ -352,10 +352,10 @@ def plan_scenes(
     opening_duration = max(3, round(duration * 0.12))
     ending_duration = max(3, round(duration * 0.12))
     content_total = duration - opening_duration - ending_duration
-    # 余数摊到前几段，保证各段加总正好等于 duration。以前是 round(均值) × 段数：
-    # 2026-09-23 线上 ppt-to-video 传 --duration 600 --scenes 23，21 段 × round(21.7)=22
-    # 加总 606s，撞上模板 supportedDurations.max=600 被自己的时长门禁拒掉。
-    # 每段仍有 3s 下限 —— 段数多到摊不开时加总会超出，那是真超出，交给门禁报。
+
+
+
+
     base_content, extra_content = divmod(max(content_total, 0), content_scenes)
 
     scenes.append({
@@ -381,11 +381,11 @@ def plan_scenes(
 
 
 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
@@ -404,19 +404,19 @@ def estimate_narration_text(
         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 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": _clip(topic, _PLACEHOLDER_TOPIC_CHARS), "duration": duration,
         "budget": _budget_suffix(duration, language, speed, tail_pad_sec),
@@ -430,17 +430,17 @@ def estimate_narration_text(
     return _localize_label(language, "narration_default", **fmt)
 
 
-# 骨架标记：出现此前缀说明 narration 仍是 gen_script 原始骨架，未被 agent 填充真实内容
+
 NARRATION_SKELETON_MARKER = SKELETON_PREFIXES[0]
 
 
 def generate_image_prompt(
         purpose: str, topic: str, style: str, narration_text: str = "", style_guide: dict | None = None
 ) -> dict:
-    """Generate image prompt for a scene.
 
-    Returns dict with keys: prompt, and optionally negativePrompt, guidanceScale.
-    """
+
+
+
     if _HAS_ENHANCER:
         return build_enhanced_prompt(
             purpose=purpose,
@@ -450,7 +450,7 @@ def generate_image_prompt(
             style_guide=style_guide,
         )
 
-    # 降级：无 enhancer 时使用原逻辑
+
     style_suffix = f"，{style}风格" if style else ""
     prompts = {
         "opening": f"{topic}主题概念图，吸引眼球的视觉效果{style_suffix}，高清大图",
@@ -461,18 +461,18 @@ def generate_image_prompt(
 
 
 def _parse_ai_slot(slot: str) -> tuple[bool, str]:
-    """解析 --scene-images 的一项：是不是 AI 段，以及用户给的提示词。
 
-    返回 ``(is_ai, prompt)``：
 
-      - ``"https://…/a.png"`` → ``(False, "")``  用已有素材
-      - ``"ai"``              → ``(True, "")``   这一段交给 gen-image，提示词由模板推
-      - ``"ai: 深色调机房"``   → ``(True, "深色调机房")``
 
-    大小写不敏感。判定刻意收得很紧（整项等于 ``ai``，或以 ``ai:`` 开头）：URL 才是这个
-    参数的常态，把 ``ai`` 判宽了会让 ``https://ai.example.com/x.png`` 这种正常地址被
-    误当成"生成一段"，用户的图就此消失。
-    """
+
+
+
+
+
+
+
+
+
     text = (slot or "").strip()
     if text.lower() == "ai":
         return True, ""
@@ -482,23 +482,23 @@ def _parse_ai_slot(slot: str) -> tuple[bool, str]:
 
 
 def _load_template_config(template_id: str) -> dict | None:
-    """Load template definition for the given template ID.
-
-    解析顺序：
-      1. 通过 registry_loader 从 ab-api（单一数据源，URL 取
-         VIDEO_TEMPLATE_REGISTRY_URL 或按 MM_API_BASE_URL 推导）加载，按 templateId 匹配。
-      2. 兜底：旧路径 template-registry/video_dsl/templates/<id>/template.json
-         （仅在仓库还残留旧目录时使用）。
-    返回完整 template dict（含 supportedAspectRatios / assetRequirements / slotMapping 等），
-    找不到时返回 None。
-
-    ⚠️ 一个例外**不走**兜底：模板存在、但被状态门控挡在可见集合外（``beta`` 而本进程
-    没开 ENABLE_BETA_TEMPLATES）时 ``TemplateStatusGatedError`` 原样上抛。下面那些
-    ``_template_*`` / ``_resolve_contract`` 读到 None 会一路退回通用默认值 —— arc 三段式、
-    默认 layout、空 customPayload，而且 llmHint 根本不会打给模型。对「id 不存在」这是
-    合理容错，对「模板在线但本进程看不见」则是把配置问题伪装成一条能跑通的废片。
-    """
-    # 优先使用 registry_loader（这是模板元数据的唯一权威来源）
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
     if _HAS_REGISTRY_LOADER:
         try:
             return _get_template(template_id)
@@ -510,7 +510,7 @@ def _load_template_config(template_id: str) -> dict | None:
                 file=sys.stderr,
             )
 
-    # 兜底：旧的本地目录布局
+
     legacy_dir = os.path.join(
         os.path.dirname(__file__), "..", "..", "template-registry", "video_dsl", "templates"
     )
@@ -522,11 +522,11 @@ def _load_template_config(template_id: str) -> dict | None:
 
 
 def _template_supported_ratio(template_config: dict | None) -> str | None:
-    """Return template 的首选宽高比。
 
-    如果模板声明了 supportedAspectRatios，返回数组首项作为推荐值；
-    否则返回 None，由调用方使用全局默认（16:9）。
-    """
+
+
+
+
     if not template_config:
         return None
     ratios = template_config.get("supportedAspectRatios") or []
@@ -537,15 +537,15 @@ def _template_supported_ratio(template_config: dict | None) -> str | None:
 
 
 def _template_primary_visual_type(template_config: dict | None) -> str:
-    """从模板的 assetRequirements 推导每个 scene 的主要视觉素材类型。
 
-    返回值之一：
-      - "image" : 模板要求图片素材（默认通用 DSL 也是图片）
-      - "video" : 模板要求视频素材（assetRequirements 含 video 但不含 image）
-      - "none"  : 模板不需要任何视觉素材（assetRequirements 只有 audio）
-    """
+
+
+
+
+
+
     if not template_config:
-        return "image"  # 默认：通用 DSL 走图片
+        return "image"
     requirements = template_config.get("assetRequirements") or []
     if "image" in requirements:
         return "image"
@@ -555,22 +555,22 @@ def _template_primary_visual_type(template_config: dict | None) -> str:
 
 
 def _template_needs_narration(template_config: dict | None) -> bool:
-    """模板是否需要旁白（TTS）。
-
-    默认 True —— 保持历史行为：每个场景挂一个 gen-voice 素材 + 写入
-    ``audio.narration`` 骨架，由 agent 后续填真实文案。
-
-    模板可通过 ``capabilities.needsNarration=false`` 声明"纯视觉 / 无旁白"
-    （如单图 Ken Burns、BGM-only 展示）。此时 gen_script：
-      - 不生成 gen-voice 素材；
-      - 场景不写 ``audio.narration``。
-    于是骨架的 narrationSceneCount=0，ab-agent 的 prepare_video_assets 预校验
-    会直接放行，不再强制用户为每个场景填旁白 —— 所有 needsNarration=false 的模板
-    走的是同一条 pass-through 路径。
-
-    兼容历史脏数据：部分模板的 ``capabilities`` 是空列表 ``[]``（而非 dict），
-    统一按"未声明"处理 → 返回 True。仅当显式为 JSON ``false`` 时才关闭旁白。
-    """
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
     caps = (template_config or {}).get("capabilities")
     if not isinstance(caps, dict):
         return True
@@ -578,46 +578,46 @@ def _template_needs_narration(template_config: dict | None) -> bool:
 
 
 def _template_needs_image(template_config: dict | None) -> bool:
-    """Check if a template requires image assets.
 
-    If assetRequirements is defined and does NOT include 'image', images are not needed.
-    """
+
+
+
     if template_config is None:
-        return True  # default: generate images for generic DSL
+        return True
     requirements = template_config.get("assetRequirements", [])
     return "image" in requirements
 
 
-# ═══════════════════════════════════════════════════════════════════════════════
-# Template-as-Contract: capabilities-driven DSL assembly
-# ═══════════════════════════════════════════════════════════════════════════════
-#
-# 模板的所有差异都通过 template.json 的 ``capabilities`` 声明（registry 是单一数据源，
-# 内置模板与个人 OSS 模板同源可达）。gen_script 把 capabilities 归一化成一份 contract，
-# 再用同一条流水线组装 DSL —— 不再有 input-schema.json，也不再有 if template_id==X 分支。
-#
-# 归一化 contract 字段（全部可缺省，缺省值保证"未声明能力"的模板走通用图文旁白）：
-#   - needs_narration   bool         capabilities.needsNarration，默认 True
-#   - scene_strategy    str          capabilities.sceneStrategy ∈ {arc, single, fixed, countdown}，默认 arc
-#   - fixed_scenes      list[dict]   capabilities.fixedScenes（single/fixed 用；缺省单 opening）
-#   - max_scenes        int          capabilities.maxScenes，默认 20（arc 的 --scenes 上限；
-#                                    "一页一场景"的模板由源文件页数决定场景数，应声明抬高）
-#   - countdown         dict|None    countdown 策略的解析结果（见 countdown_spec 模块；
-#                                    非 countdown 模板为 None）
-#   - payload_style     str          capabilities.payloadStyle ∈ {visual-overlay, slide, carousel-caption}
-#   - duration_strategy str          capabilities.durationStrategy ∈ {explicit, fit-caption, fit-images}
-#   - 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 推导
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
 
 
 def _resolve_countdown(template_config: dict | None) -> dict:
-    """countdown 声明解析；共享模块缺失时明确报错而不是静默换一种形状。
 
-    退回 ``arc`` 会是最坏的处理：一个倒数模板会拿到「至少 3 段 + 末尾 cta + 升序编号」
-    的场景表，既没有数量也没有倒数索引，然后一路通过到渲染。
-    """
+
+
+
+
     if not _HAS_COUNTDOWN:
         raise ValueError(
             "capabilities.sceneStrategy=countdown needs the shared countdown_spec module "
@@ -627,12 +627,12 @@ def _resolve_countdown(template_config: dict | None) -> dict:
 
 
 def _resolve_contract(template_config: dict | None) -> dict:
-    """把 template.json 的 capabilities 归一化成一份装配 contract。
 
-    宽容读取：capabilities 缺失 / 非 dict（历史脏数据可能是 ``[]``）一律按"未声明"
-    处理，回退到通用图文旁白（arc + visual-overlay + 旁白开），保证没有声明能力的
-    模板与无模板场景行为一致。
-    """
+
+
+
+
+
     caps = (template_config or {}).get("capabilities")
     caps = caps if isinstance(caps, dict) else {}
 
@@ -654,7 +654,7 @@ def _resolve_contract(template_config: dict | None) -> dict:
 
     fixed_scenes = caps.get("fixedScenes")
     if not isinstance(fixed_scenes, list) or not fixed_scenes:
-        # single / fixed 未显式给 fixedScenes 时退化为单 opening 场景
+
         fixed_scenes = [{"purpose": "opening"}] if scene_strategy in ("single", "fixed") else []
 
     payload_defaults = caps.get("payloadDefaults")
@@ -664,10 +664,10 @@ def _resolve_contract(template_config: dict | None) -> dict:
         "needs_narration": needs_narration,
         "scene_strategy": scene_strategy,
         "fixed_scenes": fixed_scenes,
-        # 上限读取放共享模块：dsl_validator 的门禁读的是同一个函数。
+
         "max_scenes": max_scenes_for_template(template_config),
-        # 声明解析放共享模块：render-video 的计划校验要读同一份声明，
-        # 两边各抄一遍正是这个功能上一版栽过的跟头。
+
+
         "countdown": _resolve_countdown(template_config) if scene_strategy == "countdown" else None,
         "payload_style": payload_style,
         "duration_strategy": duration_strategy,
@@ -676,21 +676,21 @@ def _resolve_contract(template_config: dict | None) -> dict:
         "primary_visual_type": primary_visual_type,
         "default_layout": caps.get("defaultLayout"),
         "authored_scenes": caps.get("authoredScenes") is True,
-        # 画面文字契约（dsl_validator 按 error 执行）；骨架据此为每个必填 role 留占位
+
         "text_layer_rules": caps.get("textLayerRules") if isinstance(caps.get("textLayerRules"), dict) else None,
-        # arc 叙事弧的收尾场景用途（缺省 cta）。绘本收尾是 ending（寓意页），不是「关注我们」
+
         "arc_closing_purpose": caps.get("arcClosingPurpose") if isinstance(caps.get("arcClosingPurpose"), str) else None,
-        # 骨架里 transitions.default 的取值；缺省 fade（历史行为）
+
         "default_transition": caps.get("defaultTransition") if isinstance(caps.get("defaultTransition"), str) else None,
     }
 
 
 def _slot_reads_visual(template_config: dict | None, purpose: str) -> bool:
-    """这个用途的版式会不会显示背景素材（slotMapping 里有没有读 visuals.background.assetRef）。
 
-    不显示的版式（如绘本的 ending 寓意页）不该规划图片：素材照样会被生成、扣积分，
-    却永远不上屏。模板没声明 slotMapping 时按「会显示」处理，保持历史行为。
-    """
+
+
+
+
     mapping = (template_config or {}).get("slotMapping")
     if not isinstance(mapping, dict) or not mapping:
         return True
@@ -709,12 +709,12 @@ def _slot_reads_visual(template_config: dict | None, purpose: str) -> bool:
 
 
 def _placeholder_text_layers(rules: dict) -> list[dict]:
-    """模板声明了 capabilities.textLayerRules 时，骨架的文字层 = 每个必填 role 一条占位。
 
-    通用骨架给的是「内容要点 N」「关注我们」这类文案，对有文字契约的模板全是错的，
-    而且留着一个没声明的 role（badge）只会让模型以为那里要填东西。占位带骨架前缀，
-    dsl_validator 会拒绝原样提交；带上语言要求，模型不用再去 llmHint 里找。
-    """
+
+
+
+
+
     language = rules.get("language") if isinstance(rules.get("language"), dict) else {}
     hints = {"en": "English text for this page", "zh": "本页中文译文"}
     layers = []
@@ -728,9 +728,9 @@ 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
 
@@ -741,48 +741,48 @@ def _clip(text: str, limit: int) -> str:
 
 
 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`` 折成真换行。
 
-    ``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(
@@ -793,16 +793,16 @@ def _echo_template_llm_hint(template_config: dict | None, template_id: str | Non
 
 
 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(
@@ -822,16 +822,16 @@ def _warn_on_url_text_layer(headline: str, subheadline: str) -> None:
 def _enforce_supported_duration(
     dsl: dict, template_config: dict | None, template_id: str | None
 ) -> None:
-    """校验成片总时长落在模板自己声明的 ``supportedDurations`` 区间内。
 
-    这条约束此前只在 template-library 的 CI（``check-dsl-examples.mjs``）对仓库里的
-    示例 DSL 生效，运行时链路（gen_script → prepare_video_assets → render_video）没有
-    任何一环校验它。于是一个声明了 ``supportedDurations.min`` 的模板照样可以静默产出
-    低于下限的成片 —— 模板自己说了"我不是为这么短设计的"，却没人拦。这里在 DSL 出厂前补上同一道栅栏。
 
-    越界即报错退出，而不是静默出片：时长不足通常意味着内容（打字机文案 / 旁白 / 场景）
-    根本没填够，继续往下走只会烧掉渲染积分换一条废片。
-    """
+
+
+
+
+
+
+
+
     sd = (template_config or {}).get("supportedDurations")
     if not isinstance(sd, dict):
         return
@@ -870,16 +870,16 @@ def _record_source_document(
     template_id: str | None,
     source_document_url: str | None,
 ) -> None:
-    """把源文件引用写进 ``meta.sourceDocument``，供渲染管线按引用取数。
 
-    这个键必须由**骨架**携带，不能指望模型后面补：ab-agent 的合并层
-    （``applyNarrationToSkeleton``）以骨架为基底，只从模型提交的 dsl_json 里搬
-    narration 与 customPayload，``meta`` / ``global`` 归骨架所有。模型往 dsl_json 里写
-    ``meta.sourceDocument`` 会被静默丢掉。
 
-    模板声明了 ``payloadHydration`` 却没拿到 URL 时在这里就警告，而不是等到
-    prepare_video_assets 才失败 —— 那时模型已经写完全部旁白并让用户确认过了。
-    """
+
+
+
+
+
+
+
+
     if source_document_url:
         dsl["meta"]["sourceDocument"] = {"url": source_document_url}
         return
@@ -888,7 +888,7 @@ def _record_source_document(
         return
     try:
         spec = hydration_spec(template_config)
-    except Exception:  # noqa: BLE001 - 模板声明写坏了不该让脚本生成失败
+    except Exception:
         return
     if not spec:
         return
@@ -907,15 +907,15 @@ def _record_source_document(
 def _plan_contract_scenes(
     contract: dict, topic: str, duration: int, scene_count: int | None, language: str
 ) -> list:
-    """按 contract.scene_strategy 规划场景列表。
 
-      - arc    : 沿用 plan_scenes 叙事弧（opening → point* → cta，最少 3 段）。
-      - single : 单场景（默认 opening），整段时长归一个场景。
-      - fixed  : 按 capabilities.fixedScenes 顺序展开，时长均分。
 
-    single / fixed 完全绕开 arc 的"最少 3 段"下限 —— 单图 Ken Burns / 打字机卡片
-    这类模板由此能产出真正的单场景，而不再被强行补到 3 段。``--scenes`` 只对 arc 生效。
-    """
+
+
+
+
+
+
+
     if contract["scene_strategy"] == "arc":
         plans = plan_scenes(
             topic, duration, scene_count, False,
@@ -929,8 +929,8 @@ def _plan_contract_scenes(
 
     fixed = contract["fixed_scenes"] or [{"purpose": "opening"}]
     n = len(fixed)
-    # 非 arc 策略的场景数由模板钉死，--scenes 不生效 —— 但必须出声。2026-09-23 线上
-    # screen-walkthrough 传 --scenes 6 拿回 2 场，没有任何提示，模型只能自己猜为什么。
+
+
     if scene_count is not None and scene_count != n:
         print(
             f"⚠️  requested {scene_count} scene(s) but this template's sceneStrategy="
@@ -954,24 +954,24 @@ def _plan_contract_scenes(
 
 
 def _plain_len(text: str) -> int:
-    """剥离 **强调** 标记后的纯字符数（与渲染端 emphasis.plainLength 等价）。"""
+
     return len((text or "").replace("**", ""))
 
 
-# ── 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, model: dict) -> float:
-    """打字机自然节奏耗时（startDelay + 打字 + 行间停顿 + 收尾），秒。"""
+
     max_lines = model.get("maxLines")
     lines = caption.get("lines") or []
     if isinstance(max_lines, int) and max_lines > 0:
@@ -995,7 +995,7 @@ def _estimate_caption_natural_sec(caption: dict, model: dict) -> float:
 
 
 def _estimate_carousel_min_sec(carousel: dict, model: dict) -> float:
-    """轮播至少需要的秒数（每张图/视频的最小停留，减去重叠的过渡）。"""
+
     items = carousel.get("items") or []
     n = len(items)
     if n == 0:
@@ -1018,13 +1018,13 @@ def _estimate_carousel_min_sec(carousel: dict, model: dict) -> float:
 def _estimate_fit_caption_duration(
     custom_payload: dict, duration_model: dict | None, template_id: str | None
 ) -> float:
-    """fit-caption 策略：按打字机 + 轮播 + 标题入场推算建议时长（秒）。
 
-    算法与模板导出的 ``capabilities.durationEstimator`` 等价（各分量并行、取 max、
-    加收尾留白），但**每一个数值都来自模板声明的 ``capabilities.durationModel``**。
-    模板没声明就不估 —— 返回 0，调用方沿用传入的 targetDuration 并收到一条 warning。
-    宁可退回调用方的时长，也不拿一组从别的模板抄来的数字去替这个模板做决定。
-    """
+
+
+
+
+
+
     if not isinstance(duration_model, dict) or not duration_model:
         print(
             f"⚠️  template '{template_id}' declares durationStrategy=fit-caption but no "
@@ -1048,11 +1048,11 @@ def _estimate_fit_caption_duration(
 
 
 def _estimate_fit_images_duration(sequence: dict, model: dict | None, fps: int = 30) -> float:
-    """Apply template-declared image timing, in frames just like the renderer.
 
-    Hold tiers and transition margins belong to durationModel.sequence; never
-    infer them from a template id or silently use the caller's target duration.
-    """
+
+
+
+
     timing = (model or {}).get("sequence", {})
     tiers = timing.get("holdSecByCount", [])
     count = len(sequence["items"])
@@ -1064,7 +1064,7 @@ def _estimate_fit_images_duration(sequence: dict, model: dict | None, fps: int =
     margin = timing.get("minHoldMarginFrames")
     if transition_ms is None or margin is None:
         raise ValueError("fit-images requires sequence transitionMs and durationModel.sequence.minHoldMarginFrames")
-    # Python round uses ties-to-even; JS Math.round uses floor(x + 0.5).
+
     min_frames = max(2, math.floor(transition_ms / 1000 * fps + 0.5)) + margin
     return sum(max(min_frames, math.floor(item.get("holdSec", base_hold) * fps + 0.5))
                for item in sequence["items"]) / fps
@@ -1092,12 +1092,12 @@ def _build_carousel_caption_dsl(
     duration_strategy: str | None,
     duration_model: dict | None,
 ) -> dict:
-    """carousel-caption 装配（单场景、图/视频轮播 + 打字机文字）。
 
-    所有差异来自归一化 contract（capabilities.payloadDefaults / durationStrategy /
-    needsNarration），不再读 input-schema.json，也没有 if template_id==X 分支。
-    轮播素材由调用方在 carousel_items 里直接给 URL（existing 资产），不触发 AI 生图。
-    """
+
+
+
+
+
     defaults = deepcopy(payload_defaults or {})
     sequence_mode = isinstance(defaults.get("sequence"), dict)
     if sequence_mode and not carousel_items:
@@ -1105,12 +1105,12 @@ def _build_carousel_caption_dsl(
     if sequence_mode and len(caption_lines) > len(carousel_items):
         raise ValueError("Image sequence has more --caption-lines than images; use at most one caption per image")
 
-    # ── Build assets from carousel_items ──────────────────────────────────
+
     assets = []
     carousel_asset_ids = []
     for idx, url in enumerate(carousel_items):
         asset_id = f"carousel-img-{idx + 1:02d}"
-        # Determine if URL is a video (basic heuristic on extension)
+
         is_video = urlsplit(url).path.lower().endswith((".mp4", ".mov", ".webm", ".avi"))
         if sequence_mode and is_video:
             raise ValueError("Image sequence requires image URLs in --carousel-items, not video URLs")
@@ -1123,7 +1123,7 @@ def _build_carousel_caption_dsl(
         })
         carousel_asset_ids.append((asset_id, "video" if is_video else "image"))
 
-    # ── Narration asset (可选；仅在模板声明 narration.enabled 时产出) ───────
+
     narration_asset_id = "narration-scene-01"
     if narration_enabled:
         assets.append({
@@ -1136,7 +1136,7 @@ def _build_carousel_caption_dsl(
             },
         })
 
-    # ── Build carousel config ─────────────────────────────────────────────
+
     carousel_defaults = defaults.get("carousel", {})
     carousel_config = {
         "items": [],
@@ -1153,25 +1153,25 @@ def _build_carousel_caption_dsl(
             item["muted"] = True
         carousel_config["items"].append(item)
 
-    # ── Build caption config ──────────────────────────────────────────────
+
     caption_defaults = defaults.get("caption", {})
     caption_config = {
         "lines": caption_lines if caption_lines else [],
         **caption_defaults,
     }
-    # Override lines explicitly (defaults shouldn't clobber user-provided lines)
+
     if caption_lines:
         caption_config["lines"] = caption_lines
 
-    # ── Build customPayload ───────────────────────────────────────────────
-    #
-    # background / headlineStyle 只在模板自己声明了 payloadDefaults 时才写进去。
-    # 这里原本硬编码着 ``{"preset": "grid-particles"}`` / ``{"pill": True}`` 作为
-    # 兜底 —— 那两个值是**某一个**模板的词汇（一个背景 preset 枚举成员 + 一个它
-    # 顶部装饰的开关）。同为 carousel-caption 但没声明这两个键的模板既不认识也不读
-    # 它们，等于往它的 DSL 里塞两坨死配置（payload 契约门禁只查"声明了却没人消费"，
-    # 查不到"没声明却被硬塞进来"）；而下一个模板如果恰好也有 background、枚举却不同，
-    # 拿到的就是一个它不认识的值。模板的默认值归模板声明，CLI 只负责透传。
+
+
+
+
+
+
+
+
+
     custom_payload = {
         "carousel": carousel_config,
         "caption": caption_config,
@@ -1180,9 +1180,9 @@ def _build_carousel_caption_dsl(
         if defaults.get(key):
             custom_payload[key] = defaults[key]
 
-    # The carousel-caption capability also covers full-frame image sequences.
-    # Its declared sequence defaults select that payload shape; do not send
-    # carousel entrance/exit or a typewriter caption block to such components.
+
+
+
     if sequence_mode:
         sequence_config = defaults["sequence"]
         sequence_config["items"] = [
@@ -1192,14 +1192,14 @@ def _build_carousel_caption_dsl(
         ]
         custom_payload = {"sequence": sequence_config}
 
-    # ── Narration skeleton ────────────────────────────────────────────────
+
     narration_text = _localize_label(output_language, "narration_opening",
                                      label="", topic=_clip(topic, _PLACEHOLDER_TOPIC_CHARS), duration=duration)
 
-    # ── Effective scene duration ──────────────────────────────────────────
-    # fit-caption 策略：时长由打字机自然节奏决定，而不是盲取调用方传入的 targetDuration。
-    # 这是打字机/画面驱动模板的核心——没有旁白来"撑"时长，
-    # 必须由 caption 自己定，否则文字打完后画面会静止到 targetDuration。
+
+
+
+
     effective_duration = duration
     if duration_strategy == "fit-images":
         if not sequence_mode:
@@ -1215,7 +1215,7 @@ def _build_carousel_caption_dsl(
                 file=sys.stderr,
             )
 
-    # ── Build scene (sceneStrategy=single: one scene carries everything) ──
+
     text_layers = [
         {"role": "headline", "content": headline, "animation": "slide-up"},
     ]
@@ -1239,7 +1239,7 @@ def _build_carousel_caption_dsl(
             },
         }
 
-    # ── Assemble full DSL ─────────────────────────────────────────────────
+
     effective_headline = headline or topic
     effective_subheadline = subheadline or ""
 
@@ -1261,8 +1261,8 @@ def _build_carousel_caption_dsl(
             "aspectRatio": ratio,
             "resolution": resolution,
             "fps": 30,
-            # 无配音模板：关闭 CC 字幕（字幕段是 narration→TTS 的派生物），
-            # 并省略 global.narration，避免下游误判存在旁白。
+
+
             "subtitle": {"enabled": narration_enabled, "style": "bottom"},
             **({"narration": {"voiceId": resolved_voice_id, "speed": narration_speed}} if narration_enabled else {}),
             **({"font": {"fontId": font_id, **({"fontName": font_name} if font_name else {})}} if font_id else {}),
@@ -1276,26 +1276,26 @@ def _build_carousel_caption_dsl(
     return dsl
 
 
-# 「作者还没选版式」的显式标记。
-#
-# 为什么是哨兵而不是留空:slideId 缺失会静默回落到 DefaultSlide —— 渲染成功、零日志、
-# 退出码 0，画面只剩一行居中标题，正是要消灭的失效形态。哨兵让下游能区分「作者没选」
-# 与「作者选了但拼错」，两者的修法不同。dsl_validator 见到它会硬拒绝（同名常量在
-# video_dsl/runtime/dsl_validator.py，两处字面量必须一致）。
+
+
+
+
+
+
 SLIDE_ID_SENTINEL = "__CHOOSE_SLIDE__"
 
 
 def _is_multi_slide_template(template_config: dict | None) -> bool:
-    """模板是否注册了多个可选版式 —— 由模板自己声明，不看模板 id。
 
-    判据是 ``customPayloadSchema.slideId.enum`` 有没有超过一个取值：有得挑才谈得上
-    「该挑哪个」。dsl_validator 的 ``_check_slide_id_chosen`` 用的是同一条判据，两侧
-    因此不会对同一个模板给出相反的结论。
 
-    **刻意不写死模板 id**：哪个模板有几种版式是模板自己的事实，真源在它的
-    ``template.json``；把名单抄进 CLI，模板改名 / 新增多版式模板都要跟着发一次 npm，
-    而漏发的表现是"这个模板又开始只出一种版式了"——正是本次要修的那个形态。
-    """
+
+
+
+
+
+
+
+
     schema = (template_config or {}).get("customPayloadSchema")
     if not isinstance(schema, dict):
         return False
@@ -1305,34 +1305,34 @@ def _is_multi_slide_template(template_config: dict | None) -> bool:
 
 
 def _build_custom_payload(template_config: dict | None) -> dict:
-    """骨架阶段的 customPayload —— **不猜版式、不拼画面文案**。
 
-    这个函数曾经按 purpose 写死两种 slideId（opening / cta → demo-concept-overview，
-    其余 → demo-single-concept），于是 16 种注册版式里只有 2 种会被用到，且与内容
-    形态完全无关 —— 线上「不论选题版式永远一样」就是这么来的。它还往
-    templateData.description 里拼 "关于{topic}的要点内容"，topic 长度不受控，画面
-    溢出是必然的。
 
-    现在分两档：
 
-      - 多版式模板 → 只放哨兵，等 agent 按内容挑版式并填 templateData；
-      - 其余 no-visual 模板 → 空载荷。这些模板只有一种版式，没有可挑的东西，而注入
-        它们 schema 不认识的字段只会把真正要的 slide / statement / item 挤掉。
-    """
+
+
+
+
+
+
+
+
+
+
+
     if _is_multi_slide_template(template_config):
         return {"slideId": SLIDE_ID_SENTINEL, "templateData": {}}
     return {}
 
 
 def _plan_countdown_scenes(spec: dict, count: int, duration: float, headline: str) -> list:
-    """``sceneStrategy=countdown``：一个开场 + N 个同类节拍，倒数编号，没有 cta。
-
-    为什么不能复用 ``arc``：``plan_scenes`` 写死了「至少 3 个场景」（Top 1 只需要 2 个）、
-    无条件在末尾 append 一个 ``cta``（榜单类模板往往不要片尾），而且 ``content_scenes
-    = scene_count - 2``、编号从 #1 升序 —— 倒数要的正好相反。``fixed`` 则要一份静态
-    场景表，表达不了动态的 N。所以 countdown 是 sceneStrategy 轴上的第四种形状，
-    而不是某个模板的特例。
-    """
+
+
+
+
+
+
+
+
     head_sec = countdown_opening_sec(spec, count, duration)
     beat_sec = (duration - head_sec) / count
     return [{"purpose": "opening", "duration": head_sec, "label": headline}] + [
@@ -1342,15 +1342,15 @@ def _plan_countdown_scenes(spec: dict, count: int, duration: float, headline: st
 
 
 def _warn_on_count_mismatch(spec: dict, headline: str, subheadline: str, count: int) -> None:
-    """画面文字里写的数量与实际节拍数不一致时出声提醒（不阻断、不改写）。
 
-    **刻意只 warn 不改写。** 标题该怎么写、数量以什么措辞出现是模板的版式事实，
-    模板在渲染时本来就会同步；手写 DSL、历史计划、ab-web 改过的标题都不经过
-    gen_script，所以这里替它改既不必要，也会静默改掉调用方给的文案。
 
-    认哪些措辞由模板的 ``countdown.countPatterns`` 声明（见 countdown_spec），
-    CLI 不内置任何词表；没声明的模板不做这项检查。
-    """
+
+
+
+
+
+
+
     for flag, value in (("--headline", headline), ("--subheadline", subheadline)):
         stated = countdown_stated_counts(spec, value)
         if stated and count not in stated:
@@ -1367,11 +1367,11 @@ def _warn_on_count_mismatch(spec: dict, headline: str, subheadline: str, count:
 
 
 def _template_background_presets(template_config: dict | None) -> list[str]:
-    """模板在 ``customPayloadSchema.background.preset`` 声明的背景取值（没声明 = 空表）。
 
-    背景词汇是**模板自己的**：同样叫「网格」，不同模板的取值名各不相同，默认值也
-    各不相同。所以这里只读声明，不在 CLI 里维护任何取值表。
-    """
+
+
+
+
     schema = (template_config or {}).get("customPayloadSchema") or {}
     background = schema.get("background") if isinstance(schema, dict) else None
     props = background.get("properties") if isinstance(background, dict) else None
@@ -1380,6 +1380,68 @@ def _template_background_presets(template_config: dict | None) -> list[str]:
     return [str(v) for v in enum] if isinstance(enum, list) else []
 
 
+
+
+
+
+
+
+
+TEMPLATE_SOURCES = ("user-explicit", "user-confirmed", "auto")
+CONFIRMED_TEMPLATE_SOURCES = ("user-explicit", "user-confirmed")
+
+
+class TemplateSelectionError(ValueError):
+    pass
+
+
+def _template_selection(
+    template_id: str | None,
+    source: str | None,
+    candidates: list[str] | None,
+) -> dict | None:
+
+
+
+
+
+    cands: list[str] = []
+    for c in candidates or []:
+        c = (c or "").strip()
+        if c and c not in cands:
+            cands.append(c)
+
+    if not source:
+        if cands:
+            raise TemplateSelectionError("--template-candidates needs --template-source.")
+        return None
+    if not template_id:
+        raise TemplateSelectionError("--template-source needs --template-id: it records how that template was chosen.")
+    if source == "auto":
+        listed = ", ".join(cands) if cands else template_id
+        raise TemplateSelectionError(
+            f"template {template_id!r} was picked by the agent and the user has not confirmed it yet.\n"
+            f"   Stop here and ask the user to choose: list the candidates ({listed}) with one line on why "
+            f"each fits and its detail-page link (template_registry pageUrl), recommended one first. End the turn.\n"
+            f"   After the user picks one, call gen_script again with --template-source user-confirmed "
+            f"(and the same --template-candidates)."
+        )
+    if source not in CONFIRMED_TEMPLATE_SOURCES:
+        raise TemplateSelectionError(
+            f"--template-source must be one of {', '.join(TEMPLATE_SOURCES)} (got {source!r})."
+        )
+    if source == "user-confirmed" and cands and template_id not in cands:
+        raise TemplateSelectionError(
+            f"--template-id {template_id!r} is not among --template-candidates ({', '.join(cands)}). "
+            f"If the user named a template outside the shortlist, that is --template-source user-explicit."
+        )
+
+    selection: dict = {"source": source}
+    if cands:
+        selection["candidates"] = cands
+    return selection
+
+
 def _apply_look(
     dsl: dict,
     template_config: dict | None,
@@ -1387,18 +1449,18 @@ def _apply_look(
     variant: str | None,
     background_preset: str | None,
 ) -> None:
-    """把用户选的视觉风格 / 背景样式写进 DSL（就地改）。
 
-    这两个值以前没有任何一跳能落进管线：复刻弹窗让用户选了，gen_script 却只写模板
-    默认背景，merge 模式又只替换旁白——成片照出、不报错，用户只觉得「好像没生效」。
 
-    - ``--variant`` → ``meta.templateVariant``：match_template 把它当**显式**选择，
-      优先于 meta.style 的模糊匹配，最终成为 inputProps.variantId；
-    - ``--background-preset`` → 每个场景 ``customPayload.background.preset``：
-      customPayload 原样透传给模板，模板读的正是这个字段。保留模板默认背景里的其它键。
 
-    取值不在模板声明里就直接退出：静默丢掉用户的选择，正是这里要修的那个 bug。
-    """
+
+
+
+
+
+
+
+
+
     if not variant and not background_preset:
         return
     if not template_id or template_config is None:
@@ -1457,34 +1519,34 @@ def build_dsl(
         item_count: int | None = None,
         source_document_url: str | None = None,
 ) -> dict:
-    """Build a complete Video DSL JSON.
-
-    When template_id is provided, loads the template config and adapts the DSL
-    structure to match the template's assetRequirements and scene patterns.
-
-    模板差异全部来自归一化 contract（capabilities）：payloadStyle=carousel-caption
-    走单场景轮播+打字机装配；其余按 sceneStrategy（arc/single/fixed）+ visual-overlay/
-    slide 走统一场景循环。无 input-schema.json、无 if template_id==X 分支。
-
-    headline / subheadline 让作者显式提供画面上的"短主标题 + 副标题"。
-    DSL 元字段命名约定：
-      - meta.headline    画面上的主标题（建议 4-12 字）。默认退回 topic
-      - meta.subheadline 画面上的副标题（项目名 / 一句标语 / 来源）。默认 ""
-    模板的 textLayers[role=headline|subheadline] 会取这两个字段，propExtractors
-    通过 role=headline / role=subheadline 抽出对应的 props（如 titleText / projectName）。
-    注意：subtitle（CC 字幕）由 global.subtitle 与 render-plan.subtitleSegments
-    单独承载，与 subheadline 完全是两个东西，命名上刻意分开避免歧义。
-
-    scene_images 是用户**自带的配图**（visual-overlay 模板专用），按顺序占位：第 i 张
-    图给第 i 个场景，没被占到的场景照常走 gen-image 补图。这条规则不是随便定的——
-    见 docs/product/creation/asset-annotation-design.md §6：另外两种立场（模型自由挑选 / 严格一一对应）
-    都会让"只传两张图"要么失去可预期性，要么直接跑不通。
-
-    speed 是旁白语速倍率，落在 global.narration.speed（不给 = 1.0）。它**不写进
-    gen-voice 资产的 payload**——与旁白文本同一条规矩：唯一来源在 DSL 上，
-    render_video 在调 TTS 前按 assetRef 回查注入，免得两处存一个值各自漂移。
-    """
-    # Load template config（registry 单一数据源）→ 归一化 contract
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
     template_config = _load_template_config(template_id) if template_id else None
     contract = _resolve_contract(template_config)
     countdown = contract["countdown"]
@@ -1496,15 +1558,15 @@ def build_dsl(
 
     primary_visual_type = contract["primary_visual_type"]
     payload_style = contract["payload_style"]
-    # visual-overlay 模板才生成视觉素材并用 visuals.background；slide / carousel-caption 不走。
+
     has_visual = payload_style == "visual-overlay"
-    # 旁白是模板能力（capabilities.needsNarration）。声明为 false 的模板（纯视觉 /
-    # BGM-only，如单图 Ken Burns）不分配 gen-voice 素材、场景不写 audio.narration。
+
+
     needs_narration = contract["needs_narration"]
 
-    # ── Resolve template-driven output language + voice ────────────────────
-    # outputLanguage is owned by the template (template.json). Missing/invalid
-    # values fall back to "zh" so old templates keep their current behavior.
+
+
+
     output_language, template_default_voice_id = _resolve_template_language_meta(template_config)
     resolved_voice_id = _resolve_voice_id(voice_id, template_default_voice_id, output_language)
     narration_speed = _resolve_narration_speed(speed)
@@ -1515,7 +1577,7 @@ def build_dsl(
             file=sys.stderr,
         )
 
-    # 缺省值：headline 退回 topic，subheadline 默认空字符串
+
     effective_headline = _normalize_linebreaks(headline) or topic
     effective_subheadline = _normalize_linebreaks(subheadline)
     _echo_template_llm_hint(template_config, template_id)
@@ -1523,16 +1585,16 @@ def build_dsl(
     if beat_count is not None:
         _warn_on_count_mismatch(countdown, effective_headline, effective_subheadline, beat_count)
 
-    # ── carousel-caption 模板（单场景、图/视频轮播 + 打字机）单独装配并直接返回 ──
+
     if payload_style == "carousel-caption":
         print(
             f"ℹ️  contract: payloadStyle=carousel-caption for template {template_id}",
             file=sys.stderr,
         )
-        # 兜底校验：carousel-caption 模板的画面由 carousel_items（图片/视频 URL）驱动，
-        # 文字由 caption_lines 驱动。两者皆空时会生成一个空轮播 + 空字幕的退化场景——
-        # 渲染出来就是「黑屏 + fit-caption 退化成最短 2s」。这是调用方（agent）忘了
-        # 把用户提供的图片塞进 --carousel-items 的典型表现，必须显式报错而不是静默产出。
+
+
+
+
         if not (carousel_items or []) and not (caption_lines or []):
             print(
                 "❌ carousel-caption template "
@@ -1548,13 +1610,13 @@ def build_dsl(
                 file=sys.stderr,
             )
             sys.exit(1)
-        # 兜底校验 ②：durationStrategy=fit-caption 的模板由打字机
-        # 文案驱动节奏 —— caption 就是内容本体，不是可选装饰。caption_lines 为空时上面的
-        # "两者皆空" 检查放行，产出的却是「顶部标题 + 轮播、底部一个字都没有」的退化片：
-        # 估时掉到轮播地板值（2 张图 ≈ 5s），而调用方往往还在确认摘要里描述了一段
-        # 根本没进 DSL 的文案，用户在确认环节也看不出来。所以这里必须硬失败。
-        # 注意：只卡 fit-caption。carousel-caption 里 durationStrategy=fit-images 的
-        # 纯视觉模板本来就允许无文案，不受影响。
+
+
+
+
+
+
+
         if contract["duration_strategy"] == "fit-caption" and not (caption_lines or []):
             print(
                 "❌ template "
@@ -1597,11 +1659,11 @@ def build_dsl(
         _enforce_supported_duration(carousel_dsl, template_config, template_id)
         return carousel_dsl
 
-    # ── 其余模板：统一场景规划（arc 叙事弧 / single / fixed）+ 统一装配循环 ──────
-    #
-    # scene_images 的每一项要么是一条 URL（用已有素材），要么是 `ai` / `ai:<提示词>`
-    # （这一段留给 gen-image）。两者共用同一个位置序列 —— 用户在界面上排出来的顺序
-    # 就是它，AI 段能插在任意位置，而不是只能挂在末尾。
+
+
+
+
+
     provided_slots = [s.strip() for s in (scene_images or []) if s and s.strip()]
 
     if beat_count is not None:
@@ -1609,14 +1671,14 @@ def build_dsl(
     else:
         scene_plans = _plan_contract_scenes(contract, topic, duration, scene_count, output_language)
 
-    # 条目比场景多时**抬高**场景数，让每一条都有地方放。
-    #
-    # 只抬高、不压低：给 2 张图不该把一条 30s 的片子从 5 段压成 3 段。用户给图表达的是
-    # "这几张都要用上"，不是"整条片子改成这么多段"——按条目数直接改写场景数，会让
-    # "多传了两张图"变成"视频结构被换掉了"，而他根本没要求这个。
-    #
-    # 反过来条目多于场景时必须抬：不抬的话第 N+1 条之后会被静默丢掉，而用户在成片里是
-    # 看不出"我的图去哪了"的。arc 之外的策略场景数由模板钉死，抬不动（下面警告兜底）。
+
+
+
+
+
+
+
+
     if (
         provided_slots
         and scene_count is None
@@ -1629,8 +1691,8 @@ def build_dsl(
             contract, topic, duration, len(provided_slots), output_language
         )
 
-    # 排完之后仍然装不下的（single / fixed 模板，或用户显式指定了更少的场景数）就明说。
-    # 静默丢弃用户自带的素材是这条链上最难被发现的一类错。
+
+
     if provided_slots and len(provided_slots) > len(scene_plans):
         print(
             f"\u26a0\ufe0f  {len(provided_slots)} scene-image entries provided but the template "
@@ -1643,9 +1705,9 @@ def build_dsl(
     assets = []
     scenes = []
 
-    # 模板的生图指南。compose 模式（imageStyleGuide.mode == "compose"）下骨架里的
-    # payload.prompt 只是「画面主体」占位 —— 画风 / 配色 / 负向词由 render_video 在旁白
-    # 定稿后统一拼上，这里若先拼一份完整 prompt，agent 会以为写好了，或在它上面叠写。
+
+
+
     image_style_guide = resolve_style_guide(template_config) if _HAS_ENHANCER else {}
     image_compose = _HAS_ENHANCER and is_compose_mode(image_style_guide)
     image_ratio = image_style_guide.get("ratio") or ratio
@@ -1653,7 +1715,7 @@ def build_dsl(
     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-
+
         if primary_visual_type == "video":
             visual_asset_id = f"video-{scene_id}"
         else:
@@ -1667,16 +1729,16 @@ def build_dsl(
             if needs_narration else ""
         )
 
-        # 本场景的版式不显示背景素材（如绘本 ending）→ 不规划视觉素材，免得白生成
+
         scene_has_visual = has_visual and _slot_reads_visual(template_config, plan["purpose"])
 
-        # 仅 visual-overlay 模板生成视觉素材（slide 无视觉素材，carousel-caption 已提前返回）
+
         if scene_has_visual and primary_visual_type == "image":
             slot = provided_slots[idx] if idx < len(provided_slots) else ""
             slot_is_ai, slot_prompt = _parse_ai_slot(slot)
             if slot and not slot_is_ai:
-                # 用户自带的图排在 stub 之前：stub 是"别烧配额"的测试开关，而用户给的
-                # 图同样一分钱不花，没有理由拿占位图把真素材盖掉。
+
+
                 assets.append({
                     "assetId": visual_asset_id,
                     "type": "image",
@@ -1684,9 +1746,9 @@ def build_dsl(
                     "status": "generated",
                     "url": slot,
                 })
-            # stub 盖得住 AI 段，盖不住用户自带的图。差别在于花不花钱：--stub-image-url
-            # 的全部意义就是"这一趟别调 gen-image"，而 AI 段恰恰是要调的那种；反过来
-            # 用户自带的 URL 一分钱不花，拿占位图把真素材盖掉纯属损失。
+
+
+
             elif stub_image_url:
                 assets.append({
                     "assetId": visual_asset_id,
@@ -1704,10 +1766,10 @@ def build_dsl(
                         narration_text=narration_text, style_guide=image_style_guide,
                     )
 
-                # 用户在 AI 段里写了提示词就用他的。**只替换主体，不动 negativePrompt /
-                # guidanceScale**：那两项是模板的护栏（"不要文字水印、不要变形"），把它们
-                # 一起丢掉会让用户随手写的一句话换来一张带乱码文字的图，而他并没有要求
-                # 关掉护栏——他只是想说这一段画什么。
+
+
+
+
                 if slot_prompt:
                     image_result = {**image_result, "prompt": slot_prompt}
 
@@ -1738,16 +1800,16 @@ def build_dsl(
                     "url": stub_video_url,
                 })
             else:
-                # 视频素材：复用 image prompt 生成器作为兜底，再追加 "视频/动态" 关键词
-                # 模型 / 时长 / 比例都遵循 gen-video 校验规则（Seedance 2.0：4-15s）
+
+
                 image_result = generate_image_prompt(plan["purpose"], topic, style, narration_text=narration_text)
                 video_prompt = image_result["prompt"]
-                # 视频时长按 gen-video 的 4-15s 区间截断
+
                 video_duration = max(4, min(int(plan["duration"]), 15))
                 vid_payload = {
                     "prompt": video_prompt,
-                    # 写别名而不是带日期的模型 ID：真源是 ab-api 的能力目录，
-                    # 版本号换代时这里不该跟着改（seedance → 当前的 Seedance 2.0）
+
+
                     "model": os.environ.get("DEFAULT_VIDEO_MODEL", "seedance"),
                     "ratio": ratio,
                     "duration": video_duration,
@@ -1760,10 +1822,10 @@ def build_dsl(
                     "payload": vid_payload,
                 })
 
-        # narration text 不再在 audio asset 的 payload 里冗余存放——
-        # 唯一来源是下游 scenes[].audio.narration.text，render_video 在
-        # 调用 TTS skill 前会按 assetRef 回查 scene 文本注入。
-        # 模板声明 needsNarration=false 时，完全不生成 gen-voice 素材。
+
+
+
+
         if needs_narration:
             assets.append({
                 "assetId": narration_asset_id,
@@ -1788,9 +1850,9 @@ def build_dsl(
                 text_layers = [
                     {"role": "badge", "content": plan["label"], "animation": "slide-up"},
                 ]
-                # 给所有 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"})
@@ -1820,37 +1882,37 @@ def build_dsl(
                     "narration": {
                         "text": narration_text,
                         "assetRef": narration_asset_id,
-                        # 骨架标记：scenes[].audio.narration.text 同样需要被真实旁白替换
+
                         "needsFill": True,
                     },
                 }
             scenes.append(scene)
         else:
-            # 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. "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 "text-overlay"
-            # ⚠️ 画面文字用 effective_headline / effective_subheadline，与上面的
-            # has_visual 分支同源。这两条分支长期分叉：visual 分支一直用的是
-            # --headline，no-visual 分支却渲染裸 topic —— SKILL.md 写着"用户给了标题
-            # 就传 --headline，否则 headline 会回落成长 topic 并撑破顶部文字层"，
-            # agent 照做了，这条分支没兑现。调用方把整篇提纲当 topic 传进来时，成片
-            # 必然是一屏文字墙，而 meta.headline 里存的又是对的，只看 meta 查不出来。
+
+
+
+
+
+
             text_layers = []
             if plan["purpose"] == "opening":
                 text_layers = [
@@ -1874,8 +1936,8 @@ def build_dsl(
 
             custom_payload = _build_custom_payload(template_config)
             if beat_count is not None:
-                # Field names come from the template's countdown declaration — this
-                # function does not know what a "rank" or a "topN" is.
+
+
                 custom_payload.update(
                     countdown_scene_payload(countdown, beat_count, plan.get("countdownIndex"))
                 )
@@ -1887,8 +1949,8 @@ def build_dsl(
                 "layout": layout,
                 "textLayers": text_layers,
             }
-            # 单版式模板的载荷是空 dict —— 写一个空 customPayload 只会让 agent 以为
-            # 这里有个需要填的结构，干脆不写这个键。
+
+
             if custom_payload:
                 scene["customPayload"] = custom_payload
             if needs_narration:
@@ -1896,7 +1958,7 @@ def build_dsl(
                     "narration": {
                         "text": narration_text,
                         "assetRef": narration_asset_id,
-                        # 骨架标记：scenes[].audio.narration.text 同样需要被真实旁白替换
+
                         "needsFill": True,
                     },
                 }
@@ -1914,15 +1976,15 @@ def build_dsl(
             "outputLanguage": output_language,
             "style": style or "",
             "description": _localize_label(output_language, "video_description", topic=topic, duration=duration),
-            # compose 模式：留一个空位让 agent 写全书共用的角色外观设定，每张图都会逐字注入
+
             **({"characterSheet": ""} if image_compose and has_visual else {}),
         },
         "global": {
             "aspectRatio": ratio,
             "resolution": resolution,
             "fps": 30,
-            # 无配音模板：关闭 CC 字幕（字幕段是 narration→TTS 的派生物），并省略
-            # global.narration，避免下游误判存在旁白。
+
+
             "subtitle": {"enabled": needs_narration, "style": "bottom"},
             **({"narration": {"voiceId": resolved_voice_id, "speed": narration_speed}} if needs_narration else {}),
             **({"font": {"fontId": font_id, **({"fontName": font_name} if font_name else {})}} if font_id else {}),
@@ -1930,7 +1992,7 @@ def build_dsl(
         },
         "assets": assets,
         "scenes": scenes,
-        # 模板声明了 capabilities.defaultTransition 就用它（绘本 = none：淡入会露出黑底）
+
         "transitions": {"default": contract["default_transition"] or "fade", "duration": 0.5},
     }
 
@@ -1940,9 +2002,9 @@ def build_dsl(
     _record_source_document(dsl, template_config, template_id, source_document_url)
 
     if contract["authored_scenes"]:
-        # 场景表由调用方按用户素材编写（如按操作时间点切录屏），骨架只提供 meta/global。
-        # 这个标记必须由骨架携带：ab-agent 看到它才会整份采用模型提交的 DSL，
-        # 否则它以骨架为基底合并，新增场景、existing 素材、visuals 都会被静默丢掉。
+
+
+
         dsl["meta"]["authoredScenes"] = True
         print(
             f"ℹ️  template '{template_id}' declares capabilities.authoredScenes: the scene list below "
@@ -2025,6 +2087,19 @@ Examples:
     parser.add_argument("--allow-digital-human", action="store_true", help="Allow digital-human assets")
     parser.add_argument("--allow-ai-video", action="store_true", help="Allow AI-generated video assets")
     parser.add_argument("--template-id", default=None, help="Template id. The template owns outputLanguage and may declare a defaultVoiceId.")
+    parser.add_argument(
+        "--template-source", default=None, choices=TEMPLATE_SOURCES,
+        help="How --template-id was chosen, recorded at meta.templateSelection.source. "
+             "user-explicit: the user named this template (id, name, detail-page prompt, or an earlier turn). "
+             "user-confirmed: you recommended it and the user confirmed in the chat. "
+             "auto: you picked it and the user has not confirmed — gen_script refuses and tells you to ask first. "
+             "Requires --template-id.",
+    )
+    parser.add_argument(
+        "--template-candidates", action="append", default=None,
+        help="Template ids you offered the user (repeatable), recommended first. Recorded at "
+             "meta.templateSelection.candidates. With user-confirmed, --template-id must be one of them.",
+    )
     parser.add_argument("--validate", action="store_true", help="Validate-only mode: only validate the input DSL")
     parser.add_argument("--input", "-i", help="Input DSL file path (required for validate mode)")
     parser.add_argument(
@@ -2125,10 +2200,25 @@ Examples:
         )
         sys.exit(1)
 
-    # ── 模板感知的 ratio 自动推导 ────────────────────────────────────────────
-    # 用户没显式传 --ratio 时：
-    #   1. 若指定了 --template-id，取模板 supportedAspectRatios[0]（避免横竖屏不匹配）
-    #   2. 否则回退默认 16:9
+
+    try:
+        template_selection = _template_selection(
+            args.template_id, args.template_source, args.template_candidates,
+        )
+    except TemplateSelectionError as exc:
+        print(f"❌ {exc}", file=sys.stderr)
+        sys.exit(1)
+    if args.template_id and template_selection is None:
+        print(
+            "ℹ️  --template-source not given: how this template was chosen is not recorded. "
+            "If the user did not name it, stop and let them confirm it before writing the script.",
+            file=sys.stderr,
+        )
+
+
+
+
+
     resolved_ratio = args.ratio
     if resolved_ratio is None:
         if args.template_id:
@@ -2158,8 +2248,8 @@ Examples:
     if args.speed is not None:
         print(f"   narration speed: {args.speed}x", file=sys.stderr)
 
-    # CLI flag takes precedence; env vars act as fallback with a visible warning
-    # so silent cross-session leakage is always observable.
+
+
     stub_image_url = args.stub_image_url
     stub_video_url = args.stub_video_url
     if stub_image_url is None:
@@ -2173,11 +2263,11 @@ Examples:
             print(f"⚠️  STUB_VIDEO_URL env var detected ({env_v}); using it as the video stub. Prefer passing --stub-video-url explicitly, or unset the env var.", file=sys.stderr)
         stub_video_url = env_v
 
-    # --skip-asset-generation 是为下游"只想要 DSL shape"的 agent 设计的
-    # 一键开关：等价于 --stub-image-url + --stub-video-url + 把 gen-voice 资产
-    # 也写成 source=existing + status=generated。当用户没显式提供 stub URL 时
-    # 用一组 sentinel 占位（https://placeholder.local/...），模板创作 / 调试场景
-    # 不会真的去 fetch 这些 URL。
+
+
+
+
+
     if args.skip_asset_generation:
         if not stub_image_url:
             stub_image_url = "https://placeholder.local/stub.png"
@@ -2215,9 +2305,9 @@ Examples:
             source_document_url=args.source_document_url,
         )
     except ValueError as exc:
-        # Covers both a bad --item-count and an unusable countdown declaration
-        # (CountdownError subclasses ValueError), so an authoring mistake surfaces
-        # as a message instead of a traceback.
+
+
+
         parser.error(str(exc))
 
     try:
@@ -2231,19 +2321,22 @@ Examples:
     except ValueError as exc:
         parser.error(str(exc))
 
-    # Post-process for --skip-asset-generation: rewrite all gen-voice / gen-digital-human
-    # assets to be already-generated stubs. Image / video are already covered by the
-    # stub_image_url / stub_video_url params threaded through build_dsl above.
+    if template_selection:
+        dsl.setdefault("meta", {})["templateSelection"] = template_selection
+
+
+
+
     if args.skip_asset_generation:
         _AUDIO_STUB = "https://placeholder.local/stub.mp3"
-        _VIDEO_STUB = stub_video_url  # same sentinel for digital-human placeholder
+        _VIDEO_STUB = stub_video_url
         for asset in dsl.get("assets", []):
             src = asset.get("source")
             if src in ("gen-voice",):
                 asset["source"] = "existing"
                 asset["status"] = "generated"
                 asset["url"] = _AUDIO_STUB
-                # payload 留作 reference（renderer 不会再读它，因为 status=generated）
+
             elif src in ("gen-digital-human",):
                 asset["source"] = "existing"
                 asset["status"] = "generated"
@@ -2256,7 +2349,7 @@ Examples:
             print(f"   - {err}", file=sys.stderr)
         sys.exit(1)
 
-    # Non-blocking language sanity check — only narrations from scenes[].
+
     expected_language = dsl.get("meta", {}).get("outputLanguage", DEFAULT_LANGUAGE)
     if expected_language in ("en", "zh"):
         narrations_for_check = [
@@ -2279,8 +2372,8 @@ if __name__ == "__main__":
     try:
         main()
     except TemplateStatusGatedError as exc:
-        # 状态门控挡住了一个确实在线的模板。这是配置问题，不是调用方参数错误，
-        # 所以给一条可执行的提示而不是 traceback —— 并且**必须**非零退出：静默
-        # 退回通用骨架正是这次要消灭的失败形态。
+
+
+
         print(f"❌ {exc}", file=sys.stderr)
         sys.exit(1)