@remixmate/cli 0.9.39 → 0.9.40

package/dist/manifest.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
-  "version": "0.9.39",
-  "generatedAt": "2026-09-21T14:35:49.704Z",
+  "version": "0.9.40",
+  "generatedAt": "2026-09-22T08:04:46.896Z",
   "skills": [
     {
       "id": "doc-parse",
@@ -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.40",
   "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,16 @@
     "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:ranking-count": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-ranking-count.py"
   },
   "keywords": [
     "claude-code",

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

@@ -17,6 +17,7 @@ Environment variables:
 
 import argparse
 import json
+import re
 import math
 import os
 import sys
@@ -41,6 +42,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,8 +475,10 @@ 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}
 #   - payload_defaults  dict         capabilities.payloadDefaults（carousel-caption 的轮播/字幕默认值）
@@ -469,6 +487,20 @@ def _template_needs_image(template_config: dict | None) -> bool:
 #   - 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 +514,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)
@@ -507,6 +539,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"),
@@ -982,6 +1017,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 +1093,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 +1125,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 +1158,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 +1242,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 +1486,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 +1567,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(
@@ -1649,28 +1758,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

@@ -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": "V13",
   "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,20 @@ 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)
+
     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,166 @@
+"""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
+
+
+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)]
+        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": "V23",
   "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": "V15",
   "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."
 }