@remixmate/cli 0.9.38 → 0.9.40

package/dist/manifest.json

@@ -1,8 +1,81 @@
 {
   "schemaVersion": 1,
-  "version": "0.9.38",
-  "generatedAt": "2026-09-21T11:34:27.703Z",
+  "version": "0.9.40",
+  "generatedAt": "2026-09-22T08:04:46.896Z",
   "skills": [
+    {
+      "id": "doc-parse",
+      "toolName": "doc_parse",
+      "tier": "tool",
+      "category": "consuming",
+      "title": "Document Extraction",
+      "summary": "Extract a document (.pptx) into structured data: per-page title and body text, the speaker notes, and — when asked for the layout layer — the exact shapes, coordinates, colors and animation beats of every slide. Runs server-side (ab-render /extract); nothing is installed locally and no model is involved, so the result is deterministic. Two layers via `fields`: `content` is lightweight text (title / text / rawNotes) and is what you want for narration or for summarizing a deck; `layout` additionally returns the slide payload that the ppt-to-video template renders one-to-one from the original file — it embeds every icon as a data URI and is large, so it is written to a file rather than printed.",
+      "triggers": [
+        "Turn this PPT / slide deck into a video",
+        "Extract text or speaker notes from a .pptx",
+        "Use a PowerPoint file as source material",
+        "Get customPayload.slide for ppt-to-video"
+      ],
+      "entry": {
+        "type": "python",
+        "scriptPath": "scripts/extract_via_render.py"
+      },
+      "runtime": "python",
+      "envVars": [
+        "RENDER_API_URL",
+        "PRIV_TOKEN",
+        "CONVERSATION_ID"
+      ],
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "url": {
+            "type": "string",
+            "description": "Direct document URL (http/https). A page link or a share link will not work — pass the file URL itself (e.g. what the asset library returns)."
+          },
+          "kind": {
+            "type": "string",
+            "enum": [
+              "pptx"
+            ],
+            "description": "Document kind. Only pptx today; a binary .ppt must be re-saved as .pptx first."
+          },
+          "fields": {
+            "type": "string",
+            "description": "Comma-separated layers: `content` (title/text/rawNotes — small) and/or `layout` (slide shapes + beats — large, embeds icons). Default `content,layout`. Ask for content only when you just need the words."
+          },
+          "slide": {
+            "type": "number",
+            "description": "Only extract this 1-based page. Omit for the whole deck."
+          },
+          "out": {
+            "type": "string",
+            "description": "Where to write the full JSON result (default ./<name>.extract.json). stdout gets a per-page summary instead."
+          },
+          "json_output": {
+            "type": "boolean",
+            "description": "Pipeline mode — emit the full JSON on stdout. Avoid with the layout layer: it is hundreds of KB of base64 per page."
+          }
+        },
+        "required": [
+          "url"
+        ]
+      },
+      "ui": {
+        "primary": [
+          "url",
+          "fields"
+        ],
+        "advanced": [
+          "slide",
+          "kind"
+        ],
+        "hidden": [
+          "out",
+          "json_output"
+        ]
+      }
+    },
     {
       "id": "export-jianying",
       "toolName": "export_jianying",
@@ -418,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": [
@@ -428,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.38",
+  "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/doc-parse/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: doc-parse
+description: |
+  Document extraction skill — turn a `.pptx` into structured data through the ab-render `/extract` endpoint.
+
+  Two layers, picked with `--fields`:
+  - **content** — per-page `title`, `text[]`, and `rawNotes` (the speaker notes). Small, no base64. This is the narration source material.
+  - **layout** — the full `slide` payload the `ppt-to-video` template renders from: every shape, coordinate, color, clip path and the animation `beats`, plus the `mode` verdict. Large (icons are embedded as data URIs).
+
+  Deterministic: the endpoint parses OOXML, it does **not** call a model. Notes come back verbatim — rewriting them into narration is your job, not the endpoint's.
+
+  Use this skill immediately whenever the user asks for any of:
+  - Turn this PPT / slide deck into a video
+  - Read / extract / summarize a .pptx, pull the text or the speaker notes out of a deck
+  - Use a PowerPoint file as source material for a script
+  - Anything that needs `customPayload.slide` for the `ppt-to-video` template
+
+  Never hand-write `slide` nodes for `ppt-to-video`. A page has dozens of shapes with exact EMU coordinates; transcribing them by eye is guaranteed to drift from the original, and the template's own hint says so.
+triggers:
+  - Turn this PPT / slide deck into a video
+  - Extract text or speaker notes from a .pptx
+  - Use a PowerPoint file as source material
+  - Get customPayload.slide for ppt-to-video
+---
+
+# Document Extraction Skill (`doc_parse`)
+
+Entry script **`scripts/extract_via_render.py`**, pure Python (stdlib only — no Office libraries, no local install).
+
+> Path convention: read the system-injected `Base directory for this skill: <path>` as `<SkillDir>`. Never hardcode an absolute path.
+
+## How it works
+
+```
+POST $RENDER_API_URL/extract        → { taskId }
+POST $RENDER_API_URL/extractStatus  → { status, result? }   (polled for you)
+```
+
+The heavy lifting (download, unzip, OOXML parsing, geometry) happens server-side. The script submits, polls, then **writes the full JSON to a file and prints a per-page summary**.
+
+That default matters: one page of `layout` with embedded icons can be hundreds of KB. Printing it would fill your context with base64 and bury the three facts you actually need — the page's mode, its beat count, and whether it has speaker notes.
+
+## Environment
+
+| Var | Meaning | Default |
+| --- | --- | --- |
+| `RENDER_API_URL` | ab-render base URL (falls back to `REMOTION_RENDER_API_URL`) | `https://api-render.remixmate.ai` |
+| `PRIV_TOKEN` | ab-api private token — **required**, the endpoint refuses anonymous calls | — |
+| `CONVERSATION_ID` | Conversation id, for provenance | — |
+
+## Usage
+
+Whole deck, both layers (what `ppt-to-video` needs):
+
+```bash
+python3 <SkillDir>/scripts/extract_via_render.py --url "https://oss.example.com/deck.pptx"
+```
+
+Text and notes only — summarizing a deck, or writing narration without touching the visuals:
+
+```bash
+python3 <SkillDir>/scripts/extract_via_render.py --url "https://…/deck.pptx" --fields content
+```
+
+One page:
+
+```bash
+python3 <SkillDir>/scripts/extract_via_render.py --url "https://…/deck.pptx" --slide 3
+```
+
+## Output
+
+```jsonc
+{
+  "source": { "url": "…", "name": "deck.pptx", "slideCount": 12, "canvas": [1920, 1080], "fields": ["content","layout"] },
+  "slides": [
+    {
+      "slideIndex": 1,
+      // content 层
+      "title": "产品介绍",
+      "text": ["三大优势", "…"],
+      "rawNotes": "备注页原文，逐字返回，未经改写",
+      // layout 层
+      "mode": "sequenced",
+      "modeReason": "4×1 格点，4 块 + 2 组页面家具",
+      "nodes": [ /* … */ ],
+      "beats": [ { "reveal": ["n12","n13"] } ],
+      "ambientIds": ["n2"],
+      "recommendedSec": 5.3,
+      "background": { "color": "#FFFFFF" },
+      "flags": ["unsupported_geom:rightArrow×3"]
+    }
+  ]
+}
+```
+
+## Using the result
+
+**For the picture** — feed `slides[i]` straight into the template's `customPayload.slide`. Do not edit the coordinates, and do not raise `mode`: the verdict comes from the extractor, which can see reconstruction problems you cannot (`modeReason` says why). You may lower it. Raising it requires `trustMeMode: true` and means you have personally checked that page.
+
+**For the words** — `rawNotes` and `text` are two different kinds of raw material, and they need different treatment:
+
+| Source | What it is | What to do | Can you check yourself? |
+| --- | --- | --- | --- |
+| `rawNotes` | already a script, written to be spoken | re-cut into one sentence per beat, make it spoken-register, drop stage directions (“as you can see here”, “(next slide)”) and non-script items (citations, TODOs) | **yes** — the original is right there |
+| `text` | bullet points, sometimes just keywords | expand into sentences | **no** — there is nothing to check against |
+
+Two rules:
+
+1. **Do not introduce facts that are not on the slide.** This is the user's own deck; inventing content puts words in their mouth.
+2. **Talk about it, don't read it out.** The body text is already on screen. Narrating it verbatim gives the viewer the same sentence three times — on the slide, in the subtitle, and in the voice-over.
+
+When a page had no notes and you wrote the narration from `text`, say so and ask the user to look it over. Do not ship it silently.
+
+## Failure modes
+
+Errors come back as plain sentences; pass them to the user as-is rather than retrying:
+
+- a binary `.ppt` (PowerPoint 97-2003) — it must be re-saved as `.pptx`, the formats are unrelated
+- not a zip at all, or a zip without `ppt/slides/`
+- the deck exceeds the per-call page limit — extract page by page with `--slide`, or split the file
+- the file is too large, or unpacks to too much
+
+`flags` on a page is **not** an error: it records what the extractor refused to reconstruct. Surface it — a silently missing element on screen is worse than a mentioned one.

package/skills/doc-parse/scripts/extract_via_render.py

@@ -0,0 +1,218 @@
+#!/usr/bin/env python3
+"""
+文档抽取脚本 — 通过 ab-render HTTP 接口实现，本地不需要任何 Office/解析依赖。
+
+调用链：
+  POST $RENDER_API_URL/extract        → { taskId }
+  POST $RENDER_API_URL/extractStatus  → { status, progress, result?, error? }
+
+两层产物（--fields）：
+  content   title / text[] / rawNotes —— 正文与备注页，轻量，不含任何 base64
+  layout    slide{nodes,beats,mode,…} —— 坐标形状，带内嵌图标，**体积很大**
+
+默认**不把完整结果打到 stdout**：一页 PPT 的 layout 带上内嵌图标可能几百 KB，
+直接进对话正文会撑爆上下文，还会让用户在聊天记录里滚过一屏 base64。默认写文件 +
+打一份人能读的摘要；确实要管道传全量时用 --json-output（或只要 content 层）。
+
+必要环境变量（由 ab-agent 自动注入）：
+  RENDER_API_URL   ab-render 服务地址（默认 https://api-render.remixmate.ai）
+  PRIV_TOKEN       ab-api 私有 token
+
+可选环境变量：
+  CONVERSATION_ID  对话 ID，用于留痕与产物归属
+"""
+
+import argparse
+import json
+import os
+import sys
+import time
+import urllib.error
+import urllib.request
+
+# ─── 环境变量 ─────────────────────────────────────────────────────────────────
+
+RENDER_API_URL = (
+    os.environ.get("RENDER_API_URL")
+    or os.environ.get("REMOTION_RENDER_API_URL")
+    or "https://api-render.remixmate.ai"
+).rstrip("/")
+PRIV_TOKEN = os.environ.get("PRIV_TOKEN", "")
+CONVERSATION_ID = os.environ.get("CONVERSATION_ID", "")
+
+# ─── HTTP 工具 ────────────────────────────────────────────────────────────────
+
+
+def api_post(path: str, body: dict, timeout: int = 30) -> dict:
+    """向 ab-render 发送 POST 请求，返回解析后的 JSON。"""
+    url = f"{RENDER_API_URL}{path}"
+    data = json.dumps(body).encode()
+
+    headers: dict[str, str] = {
+        "Content-Type": "application/json",
+        "X-Priv-Token": PRIV_TOKEN,
+    }
+    if CONVERSATION_ID:
+        headers["x-conversation-id"] = CONVERSATION_ID
+
+    req = urllib.request.Request(url, data=data, headers=headers, method="POST")
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            return json.loads(resp.read())
+    except urllib.error.HTTPError as e:
+        body_text = e.read().decode(errors="replace")
+        raise RuntimeError(f"HTTP {e.code}: {body_text}") from e
+
+
+def log(msg: str, silent: bool = False) -> None:
+    if not silent:
+        print(msg, flush=True)
+
+
+# ─── 摘要 ─────────────────────────────────────────────────────────────────────
+
+
+def summarize(result: dict, out_path: str | None) -> str:
+    """
+    人能读的一页纸。**这是这个 skill 存在的一半价值** —— 端点给的是全量结构，
+    决定"喂多少进上下文"是入口层的责任（设计文档 §4.4）。
+
+    每页一行：页码、档位、拍数、标题、讲稿来源。档位与拍数决定后面怎么写旁白，
+    讲稿来源决定走严格改写还是扩写，这两件是下一步真正要用的信息。
+    """
+    src = result.get("source", {})
+    lines = [
+        f"共 {src.get('slideCount', '?')} 页，本次抽到 {len(result.get('slides', []))} 页"
+        f"（fields={'+'.join(src.get('fields', []))}）",
+        "",
+    ]
+
+    for s in result.get("slides", []):
+        idx = s.get("slideIndex", "?")
+        bits = [f"第 {idx} 页"]
+
+        if s.get("mode"):
+            beats = len(s.get("beats") or [])
+            bits.append(f"{s['mode']}/{beats} 拍")
+        if s.get("title"):
+            bits.append(f"「{s['title']}」")
+
+        notes = (s.get("rawNotes") or "").strip()
+        if notes:
+            head = notes.replace("\n", " ")[:40]
+            bits.append(f"备注 {len(notes)} 字：{head}…")
+        elif "rawNotes" in s:
+            bits.append("无备注（旁白需按正文扩写）")
+
+        lines.append("  " + " · ".join(bits))
+
+        if s.get("modeReason"):
+            lines.append(f"      判定：{s['modeReason']}")
+        flags = s.get("flags") or []
+        if flags:
+            # flag 是显式的降级记录，不是日志 —— 画面上少一块，这里不说就没人知道为什么。
+            lines.append(f"      ⚠ 降级：{'; '.join(flags[:3])}")
+
+    if out_path:
+        lines += ["", f"完整结果已写入：{out_path}"]
+    return "\n".join(lines)
+
+
+# ─── 主逻辑 ───────────────────────────────────────────────────────────────────
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="Document extraction — calls the ab-render /extract endpoint"
+    )
+    parser.add_argument("--url", required=True, help="Direct document URL (.pptx)")
+    parser.add_argument("--kind", default="pptx", choices=["pptx"], help="Document kind (default pptx)")
+    parser.add_argument("--slide", type=int, help="Only extract this 1-based page")
+    parser.add_argument(
+        "--fields", default="content,layout",
+        help="Comma-separated: content / layout (default both)",
+    )
+    parser.add_argument(
+        "--out", help="Write the full JSON result here (default: ./<name>.extract.json)",
+    )
+    parser.add_argument(
+        "--json-output", action="store_true",
+        help="Pipeline mode: emit the full JSON on stdout (careful: layout is large)",
+    )
+    args = parser.parse_args()
+
+    if not PRIV_TOKEN:
+        print(
+            "❌ PRIV_TOKEN env var is not configured — /extract requires auth.",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    fields = [f.strip() for f in args.fields.split(",") if f.strip()]
+
+    # ── 1. Submit ────────────────────────────────────────────────────────────
+    log(f"[doc-parse] Submitting extraction: {args.url[:80]}", args.json_output)
+
+    body: dict = {"documentUrl": args.url, "kind": args.kind, "fields": fields}
+    if args.slide is not None:
+        body["slide"] = args.slide
+
+    resp = api_post("/extract", body)
+    if resp.get("code") != 0:
+        print(f"❌ submission failed: {resp.get('msg', 'unknown error')}", file=sys.stderr)
+        sys.exit(1)
+
+    task_id: str = resp["data"]["taskId"]
+    log(f"[doc-parse] task accepted, taskId={task_id}", args.json_output)
+
+    # ── 2. Poll ──────────────────────────────────────────────────────────────
+    max_wait_sec = 600
+    poll_interval = 2
+    elapsed = 0
+
+    while elapsed < max_wait_sec:
+        time.sleep(poll_interval)
+        elapsed += poll_interval
+
+        try:
+            status_resp = api_post("/extractStatus", {"taskId": task_id})
+        except Exception as e:  # noqa: BLE001
+            log(f"[doc-parse] polling error (will retry): {e}", args.json_output)
+            continue
+
+        if status_resp.get("code") != 0:
+            log(f"[doc-parse] polling error code (will retry): {status_resp.get('msg')}", args.json_output)
+            continue
+
+        task = status_resp["data"]
+        status = task.get("status", "unknown")
+
+        if status == "succeeded":
+            result = task.get("result") or {}
+
+            if args.json_output:
+                print(json.dumps(result, ensure_ascii=False))
+                return
+
+            # 默认落盘 + 摘要：layout 层直接打进 stdout 会撑爆上下文（见文件头）。
+            out_path = args.out or f"./{(result.get('source') or {}).get('name', 'document')}.extract.json"
+            with open(out_path, "w", encoding="utf-8") as f:
+                json.dump(result, f, ensure_ascii=False, indent=2)
+
+            print("\n✅ 抽取完成\n")
+            print(summarize(result, out_path))
+            return
+
+        if status == "failed":
+            # 端点的错误已经是人话（格式不对/超页数/超体积），原样透出，不要再包一层。
+            print(f"❌ extraction failed: {task.get('error', 'unknown error')}", file=sys.stderr)
+            sys.exit(1)
+
+        log(f"[doc-parse] status={status} elapsed={elapsed}s", args.json_output)
+
+    print(f"❌ extraction timed out (over {max_wait_sec}s)", file=sys.stderr)
+    sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

package/skills/doc-parse/skill.json

@@ -0,0 +1,54 @@
+{
+  "name": "doc-parse",
+  "toolName": "doc_parse",
+  "tier": "tool",
+  "category": "consuming",
+  "title": "Document Extraction",
+  "description": "Extract a document (.pptx) into structured data: per-page title and body text, the speaker notes, and — when asked for the layout layer — the exact shapes, coordinates, colors and animation beats of every slide. Runs server-side (ab-render /extract); nothing is installed locally and no model is involved, so the result is deterministic. Two layers via `fields`: `content` is lightweight text (title / text / rawNotes) and is what you want for narration or for summarizing a deck; `layout` additionally returns the slide payload that the ppt-to-video template renders one-to-one from the original file — it embeds every icon as a data URI and is large, so it is written to a file rather than printed.",
+  "auth": "required",
+  "envVars": [
+    "RENDER_API_URL",
+    "PRIV_TOKEN",
+    "CONVERSATION_ID"
+  ],
+  "entry": {
+    "type": "python",
+    "scriptPath": "scripts/extract_via_render.py"
+  },
+  "parameters": {
+    "type": "object",
+    "properties": {
+      "url": {
+        "type": "string",
+        "description": "Direct document URL (http/https). A page link or a share link will not work — pass the file URL itself (e.g. what the asset library returns)."
+      },
+      "kind": {
+        "type": "string",
+        "enum": ["pptx"],
+        "description": "Document kind. Only pptx today; a binary .ppt must be re-saved as .pptx first."
+      },
+      "fields": {
+        "type": "string",
+        "description": "Comma-separated layers: `content` (title/text/rawNotes — small) and/or `layout` (slide shapes + beats — large, embeds icons). Default `content,layout`. Ask for content only when you just need the words."
+      },
+      "slide": {
+        "type": "number",
+        "description": "Only extract this 1-based page. Omit for the whole deck."
+      },
+      "out": {
+        "type": "string",
+        "description": "Where to write the full JSON result (default ./<name>.extract.json). stdout gets a per-page summary instead."
+      },
+      "json_output": {
+        "type": "boolean",
+        "description": "Pipeline mode — emit the full JSON on stdout. Avoid with the layout layer: it is hundreds of KB of base64 per page."
+      }
+    },
+    "required": ["url"]
+  },
+  "ui": {
+    "primary": ["url", "fields"],
+    "advanced": ["slide", "kind"],
+    "hidden": ["out", "json_output"]
+  }
+}

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."
 }