@remixmate/cli 0.9.39 → 0.9.41

package/dist/manifest.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
-  "version": "0.9.39",
-  "generatedAt": "2026-09-21T14:35:49.704Z",
+  "version": "0.9.41",
+  "generatedAt": "2026-10-08T23:39:24.336Z",
   "skills": [
     {
       "id": "doc-parse",
@@ -464,7 +464,7 @@
             "items": {
               "type": "string"
             },
-            "description": "Media URLs for the template's image/video carousel. When provided together with a template_id whose capabilities.payloadStyle=carousel-caption, these URLs are placed directly into customPayload.carousel.items as existing assets — NO AI image generation is triggered. **Must** pass when the user explicitly provides image/video URLs for such a template. Each element is a full URL string."
+            "description": "Media URLs for the template's image/video carousel. When provided together with a template_id whose capabilities.payloadStyle=carousel-caption, these URLs are placed into customPayload.sequence.items when payloadDefaults.sequence is declared, otherwise customPayload.carousel.items, as existing assets — NO AI image generation is triggered. **Must** pass when the user explicitly provides image/video URLs for such a template. Each element is a full URL string."
           },
           "scene_images": {
             "type": "array",
@@ -478,7 +478,7 @@
             "items": {
               "type": "string"
             },
-            "description": "On-screen caption lines for templates that declare a caption area (capabilities.payloadDefaults.caption). Each element is one line. Line-count limits and whether **emphasis** is parsed are declared by the template — read its llmHint, which gen_script prints in full on stderr. **Must** pass when the user explicitly provides bullet-point text / bottom copy. **Also must pass — written by you — when the user did NOT provide any copy but the template is typewriter-driven** (capabilities.durationStrategy=fit-caption): such templates have no narration, so these lines are both the video's content and the thing that decides its duration. Draft them from the material you researched (repo README, page screenshots, the topic). Leaving this empty for a fit-caption template is rejected: nothing auto-generates caption text, and an empty caption renders a titled carousel with no words at all."
+            "description": "On-screen caption lines for templates that declare a caption area (capabilities.payloadDefaults.caption). For image sequences (payloadDefaults.sequence), lines map in order to sequence.items[].caption, with at most one line per image. Otherwise each element is one line. Line-count limits and whether **emphasis** is parsed are declared by the template — read its llmHint, which gen_script prints in full on stderr. **Must** pass when the user explicitly provides bullet-point text / bottom copy. **Also must pass — written by you — when the user did NOT provide any copy but the template is typewriter-driven** (capabilities.durationStrategy=fit-caption): such templates have no narration, so these lines are both the video's content and the thing that decides its duration. Draft them from the material you researched (repo README, page screenshots, the topic). Leaving this empty for a fit-caption template is rejected: nothing auto-generates caption text, and an empty caption renders a titled carousel with no words at all."
           },
           "stub_image_url": {
             "type": "string",
@@ -491,6 +491,11 @@
           "skip_asset_generation": {
             "type": "boolean",
             "description": "All-in-one switch for downstream agents (e.g. template-creator) that only want the DSL shape: every produced AssetRef is marked as already generated with placeholder URLs (image: https://placeholder.local/stub.png, video: stub.mp4, audio: stub.mp3). Implies the equivalent of --stub-image-url + --stub-video-url with sentinel defaults plus the same rewrite for gen-voice / gen-digital-human assets. Useful when the agent only needs to inspect DSL structure or feed it into try_render_local with all assets pre-stubbed."
+          },
+          "item_count": {
+            "type": "integer",
+            "minimum": 1,
+            "description": "Number of content beats, for templates declaring capabilities.sceneStrategy=countdown — the '一个开场 + N 个同类节拍，倒数编号' shape (Top-N lists, '5 个技巧', '7 个常见错误'). Produces one opening plus N scenes counting down from #N to #1. The accepted range and the default are declared by the chosen template (template_registry prints capabilities.countdown and the count field's bounds); a value outside it fails with the template's own numbers in the message. **Pass the count the user asked for, not the total scene count** — `scenes` is the total and the two are cross-checked, so passing the user's 5 here yields 5 beats while passing it as `scenes` would yield 4. The skeleton only carries each beat's index: fill in the real per-scene content before preparing assets. Keep any count stated in headline/subheadline consistent with this value — gen_script warns on a mismatch but never rewrites your copy."
           }
         },
         "required": [
@@ -501,7 +506,9 @@
         "primary": [
           "topic"
         ],
-        "advanced": [],
+        "advanced": [
+          "item_count"
+        ],
         "hidden": [
           "duration",
           "style",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remixmate/cli",
-  "version": "0.9.39",
+  "version": "0.9.41",
   "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",
@@ -28,13 +28,18 @@
     "test:narration-speed": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-narration-speed.py",
     "test:narration-tts": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-narration-tts.py",
     "test:render-resume": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-render-resume.py",
+    "test:required-props": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-required-props.py",
     "test:render-plan": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-render-plan-snapshot.py",
     "test:render-plan:update": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-render-plan-snapshot.py --update",
     "test:contracts": "PYTHONDONTWRITEBYTECODE=1 python3 skills/template-registry/scripts/check_contracts.py",
     "regress": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/regress.py",
     "regress:update": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/regress.py --update",
     "check:render": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/render-template-check.py",
-    "clean": "node scripts/clean.mjs"
+    "clean": "node scripts/clean.mjs",
+    "test:countdown": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-countdown-strategy.py",
+    "test:prepare-contracts": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-prepare-contracts.py",
+    "test:image-sequence": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-image-sequence.py",
+    "test:ranking-count": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-ranking-count.py"
   },
   "keywords": [
     "claude-code",

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

@@ -17,10 +17,13 @@ Environment variables:
 
 import argparse
 import json
+import re
 import math
 import os
 import sys
 import uuid
+from copy import deepcopy
+from urllib.parse import urlsplit
 
 SCHEMA_PATH = os.environ.get(
     "VIDEO_DSL_SCHEMA_PATH",
@@ -41,6 +44,21 @@ _SHARED_SCRIPTS_DIR = os.path.join(
 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)
+        opening_sec as countdown_opening_sec,
+        resolve_count as resolve_countdown_count,
+        resolve_countdown_spec,
+        scene_payload as countdown_scene_payload,
+    )
+    _HAS_COUNTDOWN = True
+except ImportError:
+    _HAS_COUNTDOWN = False
+
 try:
     from video_dsl.runtime.prompt_enhancer import build_enhanced_prompt
     _HAS_ENHANCER = True
@@ -459,16 +477,32 @@ def _template_needs_image(template_config: dict | None) -> bool:
 #
 # 归一化 contract 字段（全部可缺省，缺省值保证"未声明能力"的模板走通用图文旁白）：
 #   - needs_narration   bool         capabilities.needsNarration，默认 True
-#   - scene_strategy    str          capabilities.sceneStrategy ∈ {arc, single, fixed}，默认 arc
+#   - scene_strategy    str          capabilities.sceneStrategy ∈ {arc, single, fixed, countdown}，默认 arc
 #   - fixed_scenes      list[dict]   capabilities.fixedScenes（single/fixed 用；缺省单 opening）
+#   - 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}
+#   - 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 "
+            "from skills/template-registry/scripts/, which is not importable here."
+        )
+    return resolve_countdown_spec(template_config)
+
+
 def _resolve_contract(template_config: dict | None) -> dict:
     """把 template.json 的 capabilities 归一化成一份装配 contract。
 
@@ -482,7 +516,7 @@ def _resolve_contract(template_config: dict | None) -> dict:
     needs_narration = caps.get("needsNarration", True) is not False
 
     scene_strategy = caps.get("sceneStrategy")
-    if scene_strategy not in ("arc", "single", "fixed"):
+    if scene_strategy not in ("arc", "single", "fixed", "countdown"):
         scene_strategy = "arc"
 
     primary_visual_type = _template_primary_visual_type(template_config)
@@ -492,7 +526,7 @@ def _resolve_contract(template_config: dict | None) -> dict:
         payload_style = "slide" if primary_visual_type == "none" else "visual-overlay"
 
     duration_strategy = caps.get("durationStrategy")
-    if duration_strategy not in ("explicit", "fit-caption"):
+    if duration_strategy not in ("explicit", "fit-caption", "fit-images"):
         duration_strategy = "explicit"
 
     fixed_scenes = caps.get("fixedScenes")
@@ -507,6 +541,9 @@ def _resolve_contract(template_config: dict | None) -> dict:
         "needs_narration": needs_narration,
         "scene_strategy": scene_strategy,
         "fixed_scenes": fixed_scenes,
+        # 声明解析放共享模块：render-video 的计划校验要读同一份声明，
+        # 两边各抄一遍正是这个功能上一版栽过的跟头。
+        "countdown": _resolve_countdown(template_config) if scene_strategy == "countdown" else None,
         "payload_style": payload_style,
         "duration_strategy": duration_strategy,
         "duration_model": caps.get("durationModel"),
@@ -751,6 +788,29 @@ def _estimate_fit_caption_duration(
     return max(headline_intro, caption_sec, carousel_sec) + duration_model.get("tailPaddingSec", 0)
 
 
+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"])
+    rule_hold = next((tier["holdSec"] for tier in tiers if count <= tier["maxItems"]), None)
+    if rule_hold is None:
+        raise ValueError("fit-images requires durationModel.sequence.holdSecByCount covering the image count")
+    base_hold = sequence.get("defaultHoldSec", rule_hold)
+    transition_ms = sequence.get("transitionMs", timing.get("transitionMs"))
+    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
+
+
 def _build_carousel_caption_dsl(
     *,
     template_id: str,
@@ -779,7 +839,12 @@ def _build_carousel_caption_dsl(
     needsNarration），不再读 input-schema.json，也没有 if template_id==X 分支。
     轮播素材由调用方在 carousel_items 里直接给 URL（existing 资产），不触发 AI 生图。
     """
-    defaults = payload_defaults or {}
+    defaults = deepcopy(payload_defaults or {})
+    sequence_mode = isinstance(defaults.get("sequence"), dict)
+    if sequence_mode and not carousel_items:
+        raise ValueError("Image sequence needs --carousel-items; caption text alone cannot supply images")
+    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 = []
@@ -787,7 +852,9 @@ def _build_carousel_caption_dsl(
     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 = any(url.lower().endswith(ext) for ext in (".mp4", ".mov", ".webm", ".avi"))
+        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")
         assets.append({
             "assetId": asset_id,
             "type": "video" if is_video else "image",
@@ -854,6 +921,18 @@ 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"] = [
+            {"assetRef": asset_id,
+             **({"caption": caption_lines[index]} if index < len(caption_lines) else {})}
+            for index, (asset_id, _) in enumerate(carousel_asset_ids)
+        ]
+        custom_payload = {"sequence": sequence_config}
+
     # ── Narration skeleton ────────────────────────────────────────────────
     narration_text = _localize_label(output_language, "narration_opening",
                                      label="", topic=topic, duration=duration)
@@ -863,6 +942,10 @@ def _build_carousel_caption_dsl(
     # 这是打字机/画面驱动模板的核心——没有旁白来"撑"时长，
     # 必须由 caption 自己定，否则文字打完后画面会静止到 targetDuration。
     effective_duration = duration
+    if duration_strategy == "fit-images":
+        if not sequence_mode:
+            raise ValueError("fit-images requires capabilities.payloadDefaults.sequence")
+        effective_duration = _estimate_fit_images_duration(custom_payload["sequence"], duration_model)
     if duration_strategy == "fit-caption":
         est = _estimate_fit_caption_duration(custom_payload, duration_model, template_id)
         if est > 0:
@@ -982,6 +1065,61 @@ def _build_custom_payload(template_config: dict | None) -> dict:
     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}] + [
+        {"purpose": "point", "duration": beat_sec, "label": f"#{index}", "countdownIndex": index}
+        for index in range(count, 0, -1)
+    ]
+
+
+def _warn_on_count_mismatch(headline: str, subheadline: str, count: int) -> None:
+    """画面文字里写的数量与实际节拍数不一致时出声提醒（不阻断、不改写）。
+
+    **刻意只 warn 不改写。** 这里曾经有一对 ``_rank_copy`` / ``_rank_title``，是
+    github-repo-rank 的 ``payload.ts`` 里 ``formatRankCopy`` / ``formatRankTitle``
+    的逐行 Python 移植 —— 同样的三个正则，在两个仓库、两种语言里各存一份。那是本文件
+    在 ``_echo_template_llm_hint`` 里写明要避免的事：**CLI 出机制，模板出内容**。标题
+    该怎么写、数量该以什么措辞出现（``Top 5`` / ``前 5 名`` / ``5 个项目``）是模板的
+    版式事实，真源是模板自己。
+
+    去掉那份移植不会让成片出错：模板在渲染时本来就会同步（github-repo-rank 在
+    ``Opening.tsx`` / ``Cover.tsx`` 里做），而且它**必须**保留这个能力 —— 手写 DSL、
+    历史计划、ab-web 改过的标题都不经过 gen_script。CLI 这一份自始至终只影响用户在
+    确认脚本那一步看到的文字，为它复制一套会漂移的正则不值得。
+
+    换成告警的另一个好处：静默改写调用方给的文案本身就不妥（同 ``_warn_on_url_text_layer``
+    的分寸）。把数量告诉它，让它自己把文案写对，比替它改更不容易出意外。
+
+    这里认的措辞（``Top N`` / ``N 个项目`` / ``前 N 名``）只用来**发现不一致**，
+    不用来生成文案，所以它不构成一份需要跟模板同步的版式规则。
+    """
+    pattern = r"(?<![a-zA-Z0-9_])top\s*([0-9]+)(?![a-zA-Z0-9_])|(?:^|[^0-9])([0-9]+)\s*(?:个(?=\s*(?:开源项目|项目|仓库|工具))|(?=\s*名))"
+    for flag, value in (("--headline", headline), ("--subheadline", subheadline)):
+        stated = {int(g) for match in re.finditer(pattern, value or "", flags=re.I)
+                  for g in match.groups() if g is not None}
+        if stated and count not in stated:
+            print(
+                f"⚠️  {flag} says {sorted(stated)} item(s) but --item-count is {count}. "
+                "The rendered beat count follows --item-count, so the on-screen text is the "
+                "part that is wrong.\n"
+                "   Rewrite it to state the count you asked for (or leave the count out "
+                "and let the template append it). gen_script deliberately does not "
+                "rewrite your copy: how this template words a count is declared by the "
+                "template, not by the CLI.",
+                file=sys.stderr,
+            )
+
+
 def build_dsl(
         topic: str,
         duration: int,
@@ -1003,6 +1141,7 @@ def build_dsl(
         carousel_items: list[str] | None = None,
         caption_lines: list[str] | None = None,
         scene_images: list[str] | None = None,
+        item_count: int | None = None,
 ) -> dict:
     """Build a complete Video DSL JSON.
 
@@ -1034,6 +1173,12 @@ def build_dsl(
     # 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"]
+    if countdown is None and item_count is not None:
+        raise ValueError(
+            "--item-count requires a template declaring capabilities.sceneStrategy=countdown"
+        )
+    beat_count = resolve_countdown_count(countdown, item_count, scene_count) if countdown else None
 
     primary_visual_type = contract["primary_visual_type"]
     payload_style = contract["payload_style"]
@@ -1061,6 +1206,8 @@ def build_dsl(
     effective_subheadline = _normalize_linebreaks(subheadline)
     _echo_template_llm_hint(template_config, template_id)
     _warn_on_url_text_layer(effective_headline, effective_subheadline)
+    if beat_count is not None:
+        _warn_on_count_mismatch(effective_headline, effective_subheadline, beat_count)
 
     # ── carousel-caption 模板（单场景、图/视频轮播 + 打字机）单独装配并直接返回 ──
     if payload_style == "carousel-caption":
@@ -1143,7 +1290,10 @@ def build_dsl(
     # 就是它，AI 段能插在任意位置，而不是只能挂在末尾。
     provided_slots = [s.strip() for s in (scene_images or []) if s and s.strip()]
 
-    scene_plans = _plan_contract_scenes(contract, topic, duration, scene_count, output_language)
+    if beat_count is not None:
+        scene_plans = _plan_countdown_scenes(countdown, beat_count, duration, effective_headline)
+    else:
+        scene_plans = _plan_contract_scenes(contract, topic, duration, scene_count, output_language)
 
     # 条目比场景多时**抬高**场景数，让每一条都有地方放。
     #
@@ -1384,6 +1534,12 @@ def build_dsl(
                     text_layers.append({"role": "subheadline", "content": effective_subheadline, "animation": "fade-in"})
 
             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"))
+                )
 
             scene = {
                 "id": scene_id,
@@ -1459,6 +1615,7 @@ Examples:
     parser.add_argument("--style", default="", help="Style tag")
     parser.add_argument("--ratio", default=None, choices=VALID_RATIOS, help="Aspect ratio. When omitted: if --template-id is set, use the template's supportedAspectRatios[0]; otherwise default 16:9.")
     parser.add_argument("--resolution", default="1080p", help="Resolution (default: 1080p)")
+    parser.add_argument("--item-count", type=int, default=None, help="Number of content beats, for templates declaring capabilities.sceneStrategy=countdown (Top-N lists, '5 个技巧', '7 个常见错误'). Produces one opening plus N scenes counting down from #N to #1. Bounds and the default are declared by the template — this flag has no range of its own. Pass the count the user asked for, NOT the total scene count; --scenes is the total and the two are cross-checked.")
     parser.add_argument("--scenes", type=int, default=None, help="Scene count (default: auto-planned)")
     parser.add_argument("--voice-id", default=None, help="Narration voice id. When omitted, the resolver picks template.defaultVoiceId, then the language-keyed fallback (zh→Chinese (Mandarin)_Male_Announcer, en→TBD English voice). gen_voice --list-voices prints the live catalog.")
     parser.add_argument(
@@ -1522,7 +1679,8 @@ Examples:
              "--carousel-items url1 --carousel-items url2. "
              "For templates declaring capabilities.payloadStyle=carousel-caption, "
              "these URLs are placed directly into "
-             "customPayload.carousel.items as existing assets, bypassing AI image generation entirely.",
+             "customPayload.sequence.items when payloadDefaults.sequence is declared, otherwise "
+             "customPayload.carousel.items, as existing assets without AI image generation.",
     )
     parser.add_argument(
         "--scene-images",
@@ -1545,7 +1703,8 @@ Examples:
         help="On-screen caption line. Can be repeated: "
              "--caption-lines 'line1' --caption-lines 'line2'. "
              "For templates declaring capabilities.payloadStyle=carousel-caption, "
-             "these are placed into customPayload.caption.lines. "
+             "these are placed into customPayload.caption.lines, or sequence.items[].caption "
+             "in image order when payloadDefaults.sequence is declared. "
              "Line count limits and whether **emphasis** is parsed are declared per "
              "template — see the chosen template's llmHint.",
     )
@@ -1649,28 +1808,35 @@ Examples:
             file=sys.stderr,
         )
 
-    dsl = build_dsl(
-        topic=args.topic,
-        duration=args.duration,
-        style=args.style,
-        ratio=args.ratio,
-        resolution=args.resolution,
-        voice_id=args.voice_id,
-        speed=args.speed,
-        font_id=args.font_id,
-        font_name=args.font_name,
-        scene_count=args.scenes,
-        allow_digital_human=args.allow_digital_human,
-        allow_ai_video=args.allow_ai_video,
-        template_id=args.template_id,
-        stub_image_url=stub_image_url,
-        stub_video_url=stub_video_url,
-        headline=args.headline,
-        subheadline=args.subheadline,
-        carousel_items=args.carousel_items,
-        caption_lines=args.caption_lines,
-        scene_images=args.scene_images,
-    )
+    try:
+        dsl = build_dsl(
+            topic=args.topic,
+            duration=args.duration,
+            style=args.style,
+            ratio=args.ratio,
+            resolution=args.resolution,
+            voice_id=args.voice_id,
+            speed=args.speed,
+            font_id=args.font_id,
+            font_name=args.font_name,
+            scene_count=args.scenes,
+            allow_digital_human=args.allow_digital_human,
+            allow_ai_video=args.allow_ai_video,
+            template_id=args.template_id,
+            stub_image_url=stub_image_url,
+            stub_video_url=stub_video_url,
+            headline=args.headline,
+            subheadline=args.subheadline,
+            carousel_items=args.carousel_items,
+            caption_lines=args.caption_lines,
+            scene_images=args.scene_images,
+            item_count=args.item_count,
+        )
+    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))
 
     # 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

package/skills/gen-script/skill.json

@@ -61,7 +61,7 @@
         "items": {
           "type": "string"
         },
-        "description": "Media URLs for the template's image/video carousel. When provided together with a template_id whose capabilities.payloadStyle=carousel-caption, these URLs are placed directly into customPayload.carousel.items as existing assets — NO AI image generation is triggered. **Must** pass when the user explicitly provides image/video URLs for such a template. Each element is a full URL string."
+        "description": "Media URLs for the template's image/video carousel. When provided together with a template_id whose capabilities.payloadStyle=carousel-caption, these URLs are placed into customPayload.sequence.items when payloadDefaults.sequence is declared, otherwise customPayload.carousel.items, as existing assets — NO AI image generation is triggered. **Must** pass when the user explicitly provides image/video URLs for such a template. Each element is a full URL string."
       },
       "scene_images": {
         "type": "array",
@@ -75,7 +75,7 @@
         "items": {
           "type": "string"
         },
-        "description": "On-screen caption lines for templates that declare a caption area (capabilities.payloadDefaults.caption). Each element is one line. Line-count limits and whether **emphasis** is parsed are declared by the template — read its llmHint, which gen_script prints in full on stderr. **Must** pass when the user explicitly provides bullet-point text / bottom copy. **Also must pass — written by you — when the user did NOT provide any copy but the template is typewriter-driven** (capabilities.durationStrategy=fit-caption): such templates have no narration, so these lines are both the video's content and the thing that decides its duration. Draft them from the material you researched (repo README, page screenshots, the topic). Leaving this empty for a fit-caption template is rejected: nothing auto-generates caption text, and an empty caption renders a titled carousel with no words at all."
+        "description": "On-screen caption lines for templates that declare a caption area (capabilities.payloadDefaults.caption). For image sequences (payloadDefaults.sequence), lines map in order to sequence.items[].caption, with at most one line per image. Otherwise each element is one line. Line-count limits and whether **emphasis** is parsed are declared by the template — read its llmHint, which gen_script prints in full on stderr. **Must** pass when the user explicitly provides bullet-point text / bottom copy. **Also must pass — written by you — when the user did NOT provide any copy but the template is typewriter-driven** (capabilities.durationStrategy=fit-caption): such templates have no narration, so these lines are both the video's content and the thing that decides its duration. Draft them from the material you researched (repo README, page screenshots, the topic). Leaving this empty for a fit-caption template is rejected: nothing auto-generates caption text, and an empty caption renders a titled carousel with no words at all."
       },
       "stub_image_url": {
         "type": "string",
@@ -88,6 +88,11 @@
       "skip_asset_generation": {
         "type": "boolean",
         "description": "All-in-one switch for downstream agents (e.g. template-creator) that only want the DSL shape: every produced AssetRef is marked as already generated with placeholder URLs (image: https://placeholder.local/stub.png, video: stub.mp4, audio: stub.mp3). Implies the equivalent of --stub-image-url + --stub-video-url with sentinel defaults plus the same rewrite for gen-voice / gen-digital-human assets. Useful when the agent only needs to inspect DSL structure or feed it into try_render_local with all assets pre-stubbed."
+      },
+      "item_count": {
+        "type": "integer",
+        "minimum": 1,
+        "description": "Number of content beats, for templates declaring capabilities.sceneStrategy=countdown — the '一个开场 + N 个同类节拍，倒数编号' shape (Top-N lists, '5 个技巧', '7 个常见错误'). Produces one opening plus N scenes counting down from #N to #1. The accepted range and the default are declared by the chosen template (template_registry prints capabilities.countdown and the count field's bounds); a value outside it fails with the template's own numbers in the message. **Pass the count the user asked for, not the total scene count** — `scenes` is the total and the two are cross-checked, so passing the user's 5 here yields 5 beats while passing it as `scenes` would yield 4. The skeleton only carries each beat's index: fill in the real per-scene content before preparing assets. Keep any count stated in headline/subheadline consistent with this value — gen_script warns on a mismatch but never rewrites your copy."
       }
     },
     "required": [
@@ -98,7 +103,9 @@
     "primary": [
       "topic"
     ],
-    "advanced": [],
+    "advanced": [
+      "item_count"
+    ],
     "hidden": [
       "duration",
       "style",

package/skills/gen-script/version.json

@@ -2,6 +2,6 @@
   "skillName": "gen-script",
   "repoName": "agent-skill-media-maker",
   "skillId": "474",
-  "version": "V12",
+  "version": "V14",
   "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/render-video/scripts/render_video.py

@@ -2089,6 +2089,12 @@ def auto_bind_template(dsl: dict, template_id: str) -> dict:
     selected = match_template.load_full_template(selected)
     LogPrint(f"📋 auto-bound template: {selected.get('name', '')} ({template_id})", file=sys.stderr)
     binding = match_template.build_binding(selected, dsl)
+    from required_props import validate_required_props
+    try:
+        validate_required_props(selected, binding.get("bindings", []))
+    except ValueError as exc:
+        LogPrint(f"❌ {exc}", file=sys.stderr)
+        sys.exit(2)
     return binding
 
 
@@ -2193,6 +2199,10 @@ Examples:
     args = parser.parse_args()
 
     private_token = args.priv_token or os.environ.get("PRIV_TOKEN", "")
+    # The registry loader shares the environment-based auth entry point. Keep
+    # explicit CLI credentials consistent with render_job_client's token.
+    if args.priv_token:
+        os.environ["PRIV_TOKEN"] = private_token
 
     # --save-job 默认开启，但若没有 PRIV_TOKEN 则自动降级为关闭，避免阻塞无 token 的本地调试。
     if args.save_job and not private_token:
@@ -2339,6 +2349,28 @@ Examples:
         render_plan = build_render_plan(dsl, binding)
         render_plan["_dsl_assets"] = dsl.get("assets", [])
 
+    # Job/file mode bypasses auto_bind_template. Validate saved plans too, so a
+    # previously accepted placeholder-only plan cannot silently render again.
+    if args.job_id or args.render_plan:
+        from registry_loader import get_template
+        from required_props import validate_required_props
+        try:
+            template = get_template(render_plan.get("templateId", ""), include_all_statuses=True)
+            if not template:
+                raise ValueError("Cannot validate RenderPlan: template metadata unavailable")
+            validate_required_props(template, render_plan.get("timeline", []))
+        except ValueError as exc:
+            LogPrint(f"❌ {exc}", file=sys.stderr)
+            sys.exit(2)
+
+    from video_dsl.runtime.payload_contract import plan_asset_errors
+    reference_errors = plan_asset_errors(render_plan)
+    if reference_errors:
+        LogPrint("❌ RenderPlan asset references are invalid:", file=sys.stderr)
+        for error in reference_errors[:10]:
+            LogPrint(f"   - {error}", file=sys.stderr)
+        sys.exit(2)
+
     if not args.skip_asset_resolve:
         # Stub mode: short-circuit gen-image / gen-video before counting pending.
         # CLI flag takes precedence; env vars act as fallback with a visible warning

package/skills/render-video/scripts/required_props.py

@@ -0,0 +1,169 @@
+"""Validate template-required scene props before asset generation or rendering.
+
+Binding records missingRequiredProps for diagnostics, but a production caller
+must reject those scenes instead of paying for audio and rendering placeholders.
+Existing RenderPlans need the same check because they bypass binding entirely.
+"""
+
+from __future__ import annotations
+
+import math
+import sys
+from pathlib import Path
+
+# Shared cross-skill lib (see AGENTS.md). Inserted here rather than relying on
+# render_video's module-top setup because this module is imported directly by
+# tests and by prepare-video-assets.
+sys.path.insert(0, str(Path(__file__).resolve().parents[2] / "template-registry" / "scripts"))
+
+from countdown_spec import resolve_countdown_spec  # noqa: E402
+sys.path.insert(0, str(Path(__file__).resolve().parents[2] / "template-registry"))
+from video_dsl.runtime.payload_contract import required_payload_errors  # noqa: E402
+
+
+def _payload_prop(props: dict, key: str):
+    seen: set[int] = set()
+    cursor = props
+    for _ in range(9):
+        if not isinstance(cursor, dict) or id(cursor) in seen:
+            break
+        seen.add(id(cursor))
+        if cursor.get(key) is not None:
+            return cursor[key]
+        cursor = cursor.get("templateData")
+    return None
+
+
+def _required_value_errors(value, schema: dict, path: str) -> list[str]:
+    """Check required values only, using the template's declared shape and bounds.
+
+    This is not a full JSON Schema validator: optional fields and undeclared
+    extensions are left to the existing DSL validators and template runtime.
+    """
+    if value is None or (isinstance(value, str) and not value.strip()):
+        return [path]
+    kind = schema.get("type")
+    number = type(value) in (int, float) and (not isinstance(value, float) or math.isfinite(value))
+    matches = {
+        "object": isinstance(value, dict), "array": isinstance(value, list),
+        "string": isinstance(value, str), "boolean": isinstance(value, bool),
+        "number": number,
+        "integer": number and (isinstance(value, int) or value.is_integer()),
+    }
+    if kind in matches and not matches[kind]:
+        return [f"{path} (expected {kind})"]
+    if number and (kind in ("number", "integer")):
+        if "minimum" in schema and value < schema["minimum"]:
+            return [f"{path} (below minimum)"]
+        if "maximum" in schema and value > schema["maximum"]:
+            return [f"{path} (above maximum)"]
+    if isinstance(value, dict) and kind == "object":
+        properties = schema.get("properties") or {}
+        return [error for key in schema.get("required", [])
+                for error in _required_value_errors(value.get(key), properties.get(key, {}), f"{path}.{key}")]
+    if isinstance(value, list) and kind == "array" and len(value) < schema.get("minItems", 0):
+        return [f"{path} (too few items)"]
+    return []
+
+
+def validate_required_props(template: dict, rows: list[dict]) -> None:
+    """Raise with scene IDs and field names only; never include scene content."""
+    required_by_composition: dict[str, set[str]] = {}
+    # References reuse a concrete slot's composition, so only concrete slots
+    # contribute requirements here. Union if multiple slots share a component.
+    for slot in (template.get("slotMapping") or {}).values():
+        if not isinstance(slot, dict) or not slot.get("compositionId"):
+            continue
+        required_by_composition.setdefault(slot["compositionId"], set()).update(
+            slot.get("requiredProps") or []
+        )
+
+    failures = []
+    for row in rows:
+        required = required_by_composition.get(row.get("compositionId"), set())
+        required = required | set(row.get("missingRequiredProps") or [])
+        props = row.get("props") or {}
+        schema = template.get("customPayloadSchema") or {}
+        missing = [error for key in sorted(required)
+                   for error in _required_value_errors(_payload_prop(props, key), schema.get(key, {}), key)]
+        missing += required_payload_errors(template, props)
+        if missing:
+            failures.append(f"scene {row.get('sceneId', '?')}: {', '.join(missing)}")
+
+    if failures:
+        raise ValueError(
+            "Missing or invalid required template props: " + "; ".join(failures[:10])
+            + (f"; {len(failures)} scenes total" if len(failures) > 10 else "")
+            + ". Fill each scene's customPayload according to the template schema "
+            "and rebuild the RenderPlan. Narration or topic text does not populate card data."
+        )
+
+    _validate_countdown(template, rows)
+
+
+def _index_of(row: dict, spec: dict):
+    """A beat's countdown index, or None when the row carries no usable item.
+
+    Returning None rather than indexing straight into the payload keeps a scene
+    with a missing/malformed item on the countdown error path (which names the
+    scene and says what to fix) instead of an AttributeError from deep inside the
+    validator. Reachable whenever a countdown template's point slot does not list
+    its item prop in requiredProps, so the earlier per-scene check lets it through.
+    """
+    item = _payload_prop(row.get("props") or {}, spec["item_prop"])
+    return item.get(spec["index_prop"]) if isinstance(item, dict) else None
+
+
+def _validate_countdown(template: dict, rows: list[dict]) -> None:
+    """Check a countdown plan's shape before anything is paid for.
+
+    Every prop name here comes from the template's own `capabilities.countdown`
+    declaration, so this function holds no knowledge of ranking, GitHub, or any
+    template id. That matters beyond tidiness: the names used to be hardcoded,
+    which meant a second countdown template calling its count `itemCount` would
+    find no counts at all, fall back to "however many beats are present", and
+    reduce the scene-count check to comparing that number against itself —
+    validation silently gone, with nothing on screen or in the logs to say so.
+    """
+    spec = resolve_countdown_spec(template)
+    if spec is None:
+        return
+    slots = template.get("slotMapping") or {}
+    point_id = (slots.get("point") or {}).get("compositionId")
+    opening_id = (slots.get("opening") or {}).get("compositionId")
+    ending_id = (slots.get("ending") or {}).get("compositionId")
+    points = [row for row in rows if row.get("compositionId") == point_id]
+    count_props = [spec["count_prop"], *spec["legacy_count_props"]]
+    # Keep old plans usable: infer their count when no explicit count was saved.
+    declared = []
+    for row in rows:
+        props = row.get("props") or {}
+        count = next((value for value in (_payload_prop(props, p) for p in count_props)
+                      if value is not None), None)
+        if count is not None:
+            if type(count) is not int or not spec["minimum"] <= count <= spec["maximum"]:
+                raise ValueError(
+                    f"Invalid countdown {spec['count_prop']}: expected an integer from "
+                    f"{spec['minimum']} to {spec['maximum']}"
+                )
+            declared.append(count)
+    count = declared[0] if declared else len(points)
+    if any(value != count for value in declared):
+        raise ValueError(f"Countdown {spec['count_prop']} must be consistent across all scenes")
+    if not spec["minimum"] <= count <= spec["maximum"] or len(points) != count:
+        raise ValueError(
+            f"Countdown scene count does not match {spec['count_prop']}; rebuild one opening "
+            "plus N beats"
+        )
+    indexes = [_index_of(row, spec) for row in points]
+    if indexes != list(range(count, 0, -1)):
+        raise ValueError(
+            f"Countdown scenes must count down from {count} to 1 in "
+            f"{spec['item_prop']}.{spec['index_prop']} without gaps or duplicates"
+        )
+    if not rows or rows[0].get("compositionId") != opening_id or sum(row.get("compositionId") == opening_id for row in rows) != 1:
+        raise ValueError("Countdown requires exactly one opening before the beats")
+    # A separate ending may hold the final beat, but cannot add another index.
+    endings = [row for row in rows if row.get("compositionId") == ending_id]
+    if len(endings) > 1 or (endings and (rows[-1] is not endings[0] or _index_of(endings[0], spec) != 1)):
+        raise ValueError("Countdown ending may only hold the #1 scene after the countdown")

package/skills/render-video/version.json

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

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

@@ -0,0 +1,188 @@
+"""Shared resolver for the ``countdown`` scene strategy.
+
+A countdown is the "one opening, then N beats of the same kind, counting down"
+shape: Top-N lists, "5 个技巧", "7 个常见错误". It sits on the same axis as
+``arc`` / ``single`` / ``fixed`` because it is a *shape*, not a subject — which
+is the whole reason it is not called "ranking" and holds no GitHub-specific
+knowledge.
+
+None of the existing strategies could express it: ``arc`` clamps to at least 3
+scenes, always appends a ``cta``, and numbers its beats upward; ``fixed`` needs a
+static scene list and so cannot take a count at all.
+
+─── Why this module is shared rather than copied ──────────────────────────────
+Two skills need the same answer from the same declaration:
+
+  * ``gen-script``   — to lay out the scenes and write the count into each payload
+  * ``render-video`` — to validate a plan (scene count, countdown completeness)
+    before any asset is paid for
+
+Copying the resolution into both is how the previous iteration of this feature
+went wrong in the other direction (a Python port of the template's copy rules
+living next to the real ones). ``skills/template-registry/scripts/`` is the
+sanctioned home for cross-skill Python — see AGENTS.md.
+
+─── What is declared where ───────────────────────────────────────────────────
+The strategy carries the shape; the template carries every concrete value:
+
+    "capabilities": {
+      "sceneStrategy": "countdown",
+      "countdown": {
+        "countProp": "topN",            // where the count goes in customPayload
+        "itemProp": "item",             // optional, default "item"
+        "indexProp": "rank",            // optional, default "rank"
+        "legacyCountProps": ["totalItems"],
+        "openingSec": 2.5               // optional, default DEFAULT_OPENING_SEC
+      }
+    }
+
+Bounds are deliberately **not** repeated here: they are read from
+``customPayloadSchema[countProp]``'s ``minimum`` / ``maximum`` / ``default``,
+which every template already has to author for its own payload contract. Having
+one number in two places is how they drift.
+
+Declaring the prop *names* is what keeps this module honest. They used to be
+hardcoded, which meant a second countdown template naming its count
+``itemCount`` would silently lose validation entirely: nothing would be found,
+the count would fall back to "however many cards are present", and the
+"scene count matches the count" check would compare that number to itself.
+"""
+
+from __future__ import annotations
+
+#: Opening budget when the template declares none. A generic "an opening is a
+#: beat, not a chapter" value — **not** any one template's measurement. It used
+#: to be 3 hardcoded in gen_script, taken from github-repo-rank's reference film
+#: (2.43s), which put a single template's fact in the CLI.
+DEFAULT_OPENING_SEC = 3
+
+
+class CountdownError(ValueError):
+    """Raised for an unusable countdown declaration.
+
+    A subclass so callers can keep treating it as the ValueError they already
+    handle, while a reader can still see that an authoring mistake and a bad
+    ``--item-count`` are two different things.
+    """
+
+
+def resolve_countdown_spec(template: dict | None) -> dict | None:
+    """Resolve a template's countdown declaration, or None if it is not one.
+
+    Raises CountdownError when ``sceneStrategy=countdown`` is declared but the
+    rest of the contract is missing. Failing loudly here is the point: every
+    downstream check reads these names, so an incomplete declaration must not
+    degrade into "no countdown rules apply".
+    """
+    caps = (template or {}).get("capabilities")
+    caps = caps if isinstance(caps, dict) else {}
+    if caps.get("sceneStrategy") != "countdown":
+        return None
+
+    template_id = (template or {}).get("templateId", "?")
+    cfg = caps.get("countdown")
+    cfg = cfg if isinstance(cfg, dict) else {}
+
+    count_prop = cfg.get("countProp")
+    if not isinstance(count_prop, str) or not count_prop.strip():
+        raise CountdownError(
+            f"Template '{template_id}' declares capabilities.sceneStrategy=countdown but no "
+            "capabilities.countdown.countProp. Declare which customPayload field carries the "
+            "item count (github-repo-rank uses \"topN\")."
+        )
+    count_prop = count_prop.strip()
+
+    schema = (template or {}).get("customPayloadSchema")
+    bounds = schema.get(count_prop) if isinstance(schema, dict) else None
+    if not isinstance(bounds, dict):
+        raise CountdownError(
+            f"Template '{template_id}' declares countdown.countProp='{count_prop}' but "
+            f"customPayloadSchema.{count_prop} is missing. The count's bounds and default are "
+            "read from there, so that one number is not authored twice."
+        )
+
+    maximum, default = bounds.get("maximum"), bounds.get("default")
+    minimum = bounds.get("minimum")
+    minimum = minimum if type(minimum) is int else 1
+    if type(maximum) is not int or type(default) is not int:
+        raise CountdownError(
+            f"Template '{template_id}': customPayloadSchema.{count_prop} must declare integer "
+            "'maximum' and 'default'. Without a maximum the count is unbounded; without a "
+            "default there is no answer for a caller that omits the count."
+        )
+    if not minimum <= default <= maximum:
+        raise CountdownError(
+            f"Template '{template_id}': customPayloadSchema.{count_prop}.default ({default}) is "
+            f"outside its own minimum/maximum ({minimum}–{maximum})."
+        )
+
+    legacy = cfg.get("legacyCountProps")
+    legacy = [p for p in legacy if isinstance(p, str) and p.strip()] if isinstance(legacy, list) else []
+
+    opening_sec = cfg.get("openingSec")
+    if not (type(opening_sec) in (int, float) and opening_sec > 0):
+        opening_sec = DEFAULT_OPENING_SEC
+
+    return {
+        "template_id": template_id,
+        "count_prop": count_prop,
+        "legacy_count_props": legacy,
+        "item_prop": (cfg.get("itemProp") or "item").strip(),
+        "index_prop": (cfg.get("indexProp") or "rank").strip(),
+        "minimum": minimum,
+        "maximum": maximum,
+        "default": default,
+        "opening_sec": float(opening_sec),
+    }
+
+
+def resolve_count(spec: dict, requested: int | None, scene_count: int | None) -> int:
+    """Validate a caller-supplied item count against the template's own bounds.
+
+    ``requested`` is the number of content beats the caller asked for — the same
+    number the user picked. It is deliberately *not* derived from ``scene_count``:
+    a caller passing the user's 5 as a total scene count would produce 4 cards
+    with a self-consistent ``count=4`` written everywhere, which no validator can
+    catch and the user never sees. So the two are cross-checked instead.
+    """
+    count = spec["default"] if requested is None else requested
+    if type(count) is not int or not spec["minimum"] <= count <= spec["maximum"]:
+        raise ValueError(
+            f"item count must be an integer from {spec['minimum']} to {spec['maximum']} "
+            f"(declared by template '{spec['template_id']}')"
+        )
+    if scene_count is not None and scene_count != count + 1:
+        raise ValueError(
+            f"--scenes ({scene_count}) conflicts with the item count ({count}): a countdown is "
+            f"one opening plus N beats, so --scenes would have to be {count + 1}. Pass only one."
+        )
+    return count
+
+
+def opening_sec(spec: dict, count: int, duration: float) -> float:
+    """Seconds for the single opening scene.
+
+    ``openingSec`` is an upper bound, not a fixed value: on a short video it
+    yields to an even split so a long opening budget cannot starve the beats.
+
+    Worth knowing how provisional this is — ``render_video``'s
+    ``adjust_timeline_to_audio`` overwrites every scene's duration with the real
+    narration length once TTS exists. This number shapes the script the user
+    reviews and the duration/cost estimate, not the finished cut.
+    """
+    return min(spec["opening_sec"], duration / (count + 1))
+
+
+def scene_payload(spec: dict, count: int, index: int | None) -> dict:
+    """The countdown part of one scene's customPayload, under declared names.
+
+    ``index`` is None for the opening. For a beat only the index is filled:
+    inventing the rest of the item would put fabricated data on screen, so the
+    caller is expected to fill it with real content before assets are prepared.
+    """
+    payload: dict = {spec["count_prop"]: count}
+    for prop in spec["legacy_count_props"]:
+        payload[prop] = count
+    if index is not None:
+        payload[spec["item_prop"]] = {spec["index_prop"]: index}
+    return payload

package/skills/template-registry/version.json

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

@@ -300,29 +300,17 @@ def _check_asset_enums(dsl: dict) -> list[ValidationError]:
 def _check_scene_asset_refs(dsl: dict) -> list[ValidationError]:
     """render-video 历史:scene 引用的 assetRef 必须在 assets[] 声明过。
 
-    检查范围:
-      - scene.audio.narration.assetRef
-      - scene.visuals.background.assetRef
+    包括 customPayload / templateData 中的嵌套 assetRef 与 global 引用。
     """
     errors: list[ValidationError] = []
     declared = {
         a.get("assetId") for a in (dsl.get("assets") or []) if a.get("assetId")
     }
-    for idx, scene in enumerate(dsl.get("scenes", []) or []):
-        sid = scene.get("id", f"scenes[{idx}]")
-        nar = (scene.get("audio") or {}).get("narration") or {}
-        nar_ref = nar.get("assetRef")
-        if nar_ref and nar_ref not in declared:
-            errors.append(ValidationError(
-                f"scenes[{idx}].audio.narration.assetRef",
-                f"scene '{sid}': narration.assetRef '{nar_ref}' not found in assets[]",
-            ))
-        bg_ref = ((scene.get("visuals") or {}).get("background") or {}).get("assetRef")
-        if bg_ref and bg_ref not in declared:
-            errors.append(ValidationError(
-                f"scenes[{idx}].visuals.background.assetRef",
-                f"scene '{sid}': visuals.background.assetRef '{bg_ref}' not found in assets[]",
-            ))
+    from .payload_contract import asset_references
+    for key in ("scenes", "global"):
+        for path, ref in asset_references(dsl.get(key), key):
+            if ref not in declared:
+                errors.append(ValidationError(path, "assetRef not found in assets[]"))
     return errors
 
 
@@ -742,14 +730,19 @@ def _check_custom_payload_fields(dsl: dict) -> list[ValidationError]:
     tpl = _get_template_cfg(_pick_template_id(dsl))
     if not tpl:
         return []
+    from .payload_contract import required_payload_errors
+    errors: list[ValidationError] = []
+    for idx, scene in enumerate(dsl.get("scenes", []) or []):
+        custom = scene.get("customPayload") or {"templateData": scene.get("templateData")}
+        errors += [ValidationError(f"scenes[{idx}].customPayload", message)
+                   for message in required_payload_errors(tpl, custom)]
     if isinstance(tpl.get("slideSchemas"), dict):
-        return []  # 多版式模板走 _check_slide_payload_fields
+        return errors  # 多版式字段走 _check_slide_payload_fields
     cps = tpl.get("customPayloadSchema")
     if not isinstance(cps, dict) or not cps:
-        return []
+        return errors
 
     root = {"type": "object", "properties": cps}
-    errors: list[ValidationError] = []
     for idx, scene in enumerate(dsl.get("scenes", []) or []):
         custom = scene.get("customPayload")
         if not isinstance(custom, dict) or not custom:
@@ -1054,4 +1047,3 @@ def validate_dsl(dsl: dict) -> list[ValidationError]:
     errors += _check_slide_cross_field(dsl)
     return errors
 
-

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

@@ -0,0 +1,82 @@
+"""Template-declared content requirements and recursive asset references.
+
+Shared by DSL preparation and saved RenderPlan validation. Requirements use a
+small JSON Schema subset; values never appear in diagnostic messages.
+"""
+
+
+def payload_values(props: dict) -> dict:
+    """Flatten templateData wrappers, with non-null outer props taking precedence."""
+    layers, seen = [], set()
+    while isinstance(props, dict) and id(props) not in seen and len(layers) < 10:
+        layers.append(props)
+        seen.add(id(props))
+        props = props.get("templateData")
+    result = {}
+    for layer in reversed(layers):
+        result.update({k: v for k, v in layer.items() if k != "templateData" and v is not None})
+    return result
+
+
+def requirement_errors(value, schema: dict, path: str = "customPayload") -> list[str]:
+    """Enforce type/const/enum/required/properties/items/minItems/anyOf."""
+    errors = []
+    kind = schema.get("type")
+    matches = {"object": isinstance(value, dict), "array": isinstance(value, list),
+               "string": isinstance(value, str)}
+    if kind in matches and not matches[kind]:
+        return [f"{path} (expected {kind})"]
+    if "const" in schema and value != schema["const"]:
+        return [f"{path} (unexpected value)"]
+    if "enum" in schema and value not in schema["enum"]:
+        return [f"{path} (unexpected value)"]
+    if isinstance(value, dict):
+        for key in schema.get("required", []):
+            if value.get(key) is None or value.get(key) == "":
+                errors.append(f"{path}.{key} (required)")
+        for key, child in schema.get("properties", {}).items():
+            if key in value:
+                errors += requirement_errors(value[key], child, f"{path}.{key}")
+    if isinstance(value, list):
+        if len(value) < schema.get("minItems", 0):
+            errors.append(f"{path} (too few items)")
+        if "items" in schema:
+            for index, item in enumerate(value):
+                errors += requirement_errors(item, schema["items"], f"{path}[{index}]")
+    if "anyOf" in schema:
+        branches = [requirement_errors(value, branch, path) for branch in schema["anyOf"]]
+        if not branches or all(branches):
+            alternatives = " OR ".join("; ".join(branch) for branch in branches)
+            errors.append(f"{path} must satisfy one content alternative: {alternatives}")
+    return errors
+
+
+def required_payload_errors(template: dict, props: dict) -> list[str]:
+    caps = template.get("capabilities")
+    schema = caps.get("payloadRequirements") if isinstance(caps, dict) else None
+    return requirement_errors(payload_values(props), schema) if isinstance(schema, dict) else []
+
+
+def asset_references(value, path: str = "", *, bound_props: bool = False):
+    """Walk nested assetRef fields; bound props also use *AssetId names."""
+    if isinstance(value, list):
+        for index, item in enumerate(value):
+            yield from asset_references(item, f"{path}[{index}]", bound_props=bound_props)
+    elif isinstance(value, dict):
+        for key, child in value.items():
+            child_path = f"{path}.{key}" if path else key
+            if key == "assetRef" or (bound_props and key.endswith("AssetId")):
+                if isinstance(child, str) and child.strip():
+                    yield child_path, child
+            else:
+                yield from asset_references(child, child_path, bound_props=bound_props)
+
+
+def plan_asset_errors(plan: dict) -> list[str]:
+    declared = {asset.get("assetId") for asset in plan.get("resolvedAssets", []) if isinstance(asset, dict)}
+    errors = []
+    for index, row in enumerate(plan.get("timeline", [])):
+        for path, ref in asset_references(row.get("props", {}), f"timeline[{index}].props", bound_props=True):
+            if ref not in declared:
+                errors.append(f"{path} references an asset missing from resolvedAssets[]")
+    return errors