@remixmate/cli 0.9.43 → 0.9.45

package/dist/manifest.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
-  "version": "0.9.43",
-  "generatedAt": "2026-09-22T14:20:35.434Z",
+  "version": "0.9.45",
+  "generatedAt": "2026-09-23T05:34:40.922Z",
   "skills": [
     {
       "id": "doc-parse",
@@ -14,7 +14,7 @@
         "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"
+        "Read the page count and speaker notes of a slide deck"
       ],
       "entry": {
         "type": "python",
@@ -437,7 +437,7 @@
           },
           "scenes": {
             "type": "number",
-            "description": "Scene count"
+            "description": "Scene count. Only applies to templates with capabilities.sceneStrategy=arc (the default); single / fixed / countdown templates own their own count. Bounded below by 3 and above by the template's capabilities.maxScenes (default 20) — a clamp is reported on stderr and is NOT an error, so always read the real count back from the returned DSL (scenes[].length) before describing the script to the user. For a template that maps one scene per source page (e.g. ppt-to-video), pass the page count you saw in doc_parse's summary."
           },
           "voice_id": {
             "type": "string",
@@ -451,6 +451,10 @@
             "type": "string",
             "description": "Template id (e.g. html-slide). The template owns outputLanguage and may also declare a defaultVoiceId; both flow into the produced DSL."
           },
+          "source_document_url": {
+            "type": "string",
+            "description": "Source document URL (.pptx) for a template that builds its per-scene picture from that document (capabilities.payloadHydration — today: ppt-to-video). **Must** pass it for such a template: it is recorded at meta.sourceDocument, and prepare_video_assets then fetches the layout itself and fills every scene's customPayload.slide. Pass the same URL you gave doc_parse. You are NOT expected to author or even read that layout data — one page is hundreds of KB, so it never travels through the conversation; without this reference the DSL is rejected downstream after you have already written all the narration."
+          },
           "headline": {
             "type": "string",
             "description": "On-screen headline. Stored at meta.headline and pushed into every scene's textLayers[role=headline] so the template can render it as the top big-text. **Must** be set when the user explicitly provided a headline / main title; without it, headline falls back to the long-form topic and overflows the top text layer. This is on-screen copy, so write it for a viewer who has never heard of the subject — a bare identifier (repo name, file name, product code) is not a title. Length limits, line breaks (\\n) and emphasis syntax are per-template: follow the chosen template's llmHint, which gen_script prints in full on stderr."
@@ -517,6 +521,7 @@
           "voice_id",
           "speed",
           "template_id",
+          "source_document_url",
           "headline",
           "subheadline",
           "carousel_items",
@@ -777,6 +782,10 @@
             "type": "string",
             "description": "Template id. When provided, the script invokes template-registry internally; no separate binding step is needed."
           },
+          "source_document_url": {
+            "type": "string",
+            "description": "Source document URL (.pptx) for a template that builds its per-scene picture from that document (capabilities.payloadHydration — today: ppt-to-video). Normally unnecessary: gen_script already recorded it at meta.sourceDocument when you passed source_document_url there, and the cached skeleton carries it through. Pass it here only to recover when the skeleton lacks the reference — it saves a full gen_script round trip. The layout data is fetched here and written into every scene's customPayload.slide; you neither author nor see it."
+          },
           "binding_json": {
             "type": "string",
             "description": "TemplateBinding JSON as an inline string (alternative to template_id; no file needed)."
@@ -806,6 +815,7 @@
           "dsl_json",
           "dsl",
           "template_id",
+          "source_document_url",
           "binding_json",
           "binding",
           "save_job",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remixmate/cli",
-  "version": "0.9.43",
+  "version": "0.9.45",
   "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",

package/skills/doc-parse/SKILL.md

@@ -13,14 +13,13 @@ description: |
   - 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.
+  You call this skill for the **words** (notes, body text) and for the **page inventory** (how many pages, each page's animation tier and beat count). You do not call it to obtain `customPayload.slide` — that payload never passes through you; see "Using the result".
 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
+  - Read the page count and speaker notes of a slide deck
 ---
 
 # Document Extraction Skill (`doc_parse`)
@@ -50,7 +49,7 @@ That default matters: one page of `layout` with embedded icons can be hundreds o
 
 ## Usage
 
-Whole deck, both layers (what `ppt-to-video` needs):
+Whole deck, both layers. The layout layer is what makes the per-page summary useful — it is where `mode` and the beat count come from, and those drive how you cut the narration:
 
 ```bash
 python3 <SkillDir>/scripts/extract_via_render.py --url "https://oss.example.com/deck.pptx"
@@ -96,7 +95,38 @@ python3 <SkillDir>/scripts/extract_via_render.py --url "https://…/deck.pptx" -
 
 ## 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 picture — you don't. Pass the URL instead.
+
+The `layout` layer is written to a file, and **in the agent runtime you have no file-reading tool** (`Read` / `Bash` / `Glob` are deliberately not exposed — see `mcp-tools.ts`). So the file on disk is not a handoff to you, and `web_read` will not open it either: it only accepts http/https.
+
+That is on purpose. One page of layout with embedded icons runs to hundreds of KB; a 23-page deck is several MB. It would bury everything else in your context and you would still only be copying bytes.
+
+So the picture travels **by reference**:
+
+```bash
+# 1. here: read the words and count the pages
+doc_parse  --url "https://…/deck.pptx"
+
+# 2. pass the SAME url to gen_script, plus one scene per page
+gen_script --template-id ppt-to-video \
+           --source-document-url "https://…/deck.pptx" \
+           --scenes 23
+```
+
+`gen_script` records it at `meta.sourceDocument`, and `prepare_video_assets` then fetches the layout itself and fills every scene's `customPayload.slide` before validation. You never see that data, and you never hand-write it.
+
+What you *do* own from this result:
+
+| You read | You do |
+| --- | --- |
+| page count | pass it as `--scenes` (then read the real count back off the returned DSL) |
+| `rawNotes` / `text` per page | write the narration (see below) |
+| `mode` + beat count per page | cut the narration into that many sentences |
+| `flags` | tell the user which elements the extractor could not reconstruct |
+
+Do not raise `mode`: the verdict comes from the extractor, which can see reconstruction problems you cannot (`modeReason` says why). You may lower it by writing `customPayload.mode`. Raising it requires `trustMeMode: true` and means you have personally checked that page.
+
+> If `prepare_video_assets` ever tells you `customPayload.slide (required)`, the missing thing is not the payload — it is the **reference**. Re-run `gen_script` with `--source-document-url`, or pass `source_document_url` to `prepare_video_assets` to recover without regenerating the script.
 
 **For the words** — `rawNotes` and `text` are two different kinds of raw material, and they need different treatment:
 

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

@@ -2,7 +2,7 @@
 """
 文档抽取脚本 — 通过 ab-render HTTP 接口实现，本地不需要任何 Office/解析依赖。
 
-调用链：
+调用链（实现在共享模块 ``doc_extract``）：
   POST $RENDER_API_URL/extract        → { taskId }
   POST $RENDER_API_URL/extractStatus  → { status, progress, result?, error? }
 
@@ -14,6 +14,11 @@
 直接进对话正文会撑爆上下文，还会让用户在聊天记录里滚过一屏 base64。默认写文件 +
 打一份人能读的摘要；确实要管道传全量时用 --json-output（或只要 content 层）。
 
+⚠️ 关于 layout 层的用法，看清楚这一条：**它不是给你读的**。在 ab-agent 里模型没有
+任何文件读取工具（这是有意的安全收窄），所以落盘的那个文件你打不开。需要 layout 的
+模板（ppt-to-video）按引用取数：把同一个文档 URL 传给 ``gen_script --source-document-url``，
+渲染管线会自己把每一页填进 ``customPayload.slide``。见 SKILL.md「Using the result」。
+
 必要环境变量（由 ab-agent 自动注入）：
   RENDER_API_URL   ab-render 服务地址（默认 https://api-render.remixmate.ai）
   PRIV_TOKEN       ab-api 私有 token
@@ -26,99 +31,22 @@ 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)
+# 共享 Python lib 在 skills/template-registry/scripts/（见 AGENTS.md 的约定）。
+# 抽取的 submit/poll 逻辑住在那里而不是这里，因为渲染管线也要用同一份 —— 见
+# doc_extract 模块头的说明。
+sys.path.insert(
+    0,
+    os.path.abspath(
+        os.path.join(os.path.dirname(__file__), "..", "..", "template-registry", "scripts")
+    ),
+)
 
-
-# ─── 主逻辑 ───────────────────────────────────────────────────────────────────
+from doc_extract import (  # noqa: E402
+    DocExtractError,
+    extract_document,
+    summarize,
+)
 
 
 def main() -> None:
@@ -141,77 +69,46 @@ def main() -> None:
     )
     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()]
+    # 管道模式下 stdout 只能有那一份 JSON，进度行一律走 stderr。
+    def log(msg: str) -> None:
+        print(msg, file=sys.stderr if args.json_output else sys.stdout, flush=True)
 
-    # ── 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)
+    try:
+        result = extract_document(
+            args.url,
+            kind=args.kind,
+            fields=args.fields,
+            slide=args.slide,
+            log=log,
+        )
+    except DocExtractError as exc:
+        # 端点的错误已经是人话（格式不对/超页数/超体积），原样透出，不要再包一层。
+        print(f"❌ {exc}", 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
+    if args.json_output:
+        print(json.dumps(result, ensure_ascii=False))
+        return
 
-    while elapsed < max_wait_sec:
-        time.sleep(poll_interval)
-        elapsed += poll_interval
+    # 默认落盘 + 摘要：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)
 
-        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
+    print("\n✅ 抽取完成\n")
+    print(summarize(result, out_path))
 
-        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 "layout" in (result.get("source") or {}).get("fields", []):
+        # 这段是为了堵住一个具体的失败模式：上一版这里只说"已写入 <文件>"，读到它的
+        # 模型会理所当然地去读那个文件，然后发现自己没有文件读取工具，接着就没有
+        # 第二条路了。所以把下一步明确写出来。
+        print(
+            "\n📎 下一步：**不要去读上面那个文件，也不要手写 slide 节点**。\n"
+            "   画面数据按引用进管线 —— 把同一个文档 URL 传给 gen_script：\n"
+            f"     gen_script --template-id <id> --source-document-url \"{args.url[:100]}\"\n"
+            "   之后 prepare_video_assets 会自己把每一页填进对应场景的 customPayload.slide。\n"
+            "   你要写的是旁白（用上面每页的备注改写）与场景数（= 页数）。"
+        )
 
 
 if __name__ == "__main__":

package/skills/gen-script/SKILL.md

@@ -62,6 +62,35 @@ The intent is to avoid the failure mode where "the generic DSL looks compatible
 7. If `template_registry list_examples=true` does return files locally, read them as an extra sample — never as a substitute for step 1.
 8. After generation, run the schema check and show the script summary to the user for confirmation.
 
+### Document-driven templates: pass the source URL, don't author the payload
+
+Some templates build each scene's picture from a source file rather than from JSON you write. They declare it as `capabilities.payloadHydration` (today: `ppt-to-video`, which fills `customPayload.slide` from a `.pptx`).
+
+For those, pass **`--source-document-url`** — the same URL you gave `doc_parse`:
+
+```bash
+gen_script --template-id ppt-to-video \
+           --source-document-url "https://…/deck.pptx" \
+           --scenes 23 --duration 600
+```
+
+It is recorded at `meta.sourceDocument`, and `prepare_video_assets` fetches the layout itself and fills every scene before validation runs.
+
+Two things follow, and both matter:
+
+- **You cannot supply this payload yourself, so don't try.** One page of layout data is hundreds of KB. It is not in any tool result you can read, and the file `doc_parse` writes is not openable from the agent runtime. `customPayload.slide (required)` on every scene means the *reference* is missing, not the data.
+- **The reference has to be set here, at `gen_script` time.** The agent layer merges your submitted `dsl_json` onto the cached skeleton and keeps `meta` / `global` from the skeleton — so writing `meta.sourceDocument` into `dsl_json` yourself is silently dropped. If you already generated a skeleton without it, either re-run `gen_script` or pass `source_document_url` to `prepare_video_assets`.
+
+Scene count for these templates is **one scene per page**, taken from `doc_parse`'s summary. Such templates raise `capabilities.maxScenes` above the default 20 for exactly this reason.
+
+### Scene count: read it back, never assume it
+
+`--scenes` is a request, not a guarantee. It is clamped to `[3, capabilities.maxScenes]` (default max 20), and a clamp is a **stderr warning, not an error** — the call still succeeds and returns a DSL with a different number of scenes than you asked for.
+
+So after every call, take the scene count from `scenes[]` in the returned DSL. Do not describe scene 21 of a 20-scene DSL to the user. A 23-page deck once got clamped to 20 here; the agent wrote 23 scenes' worth of narration anyway, the user confirmed a 23-scene script, and the mismatch only surfaced three tool calls later as a payload error that said nothing about scene counts.
+
+If the count you need is above the template's maximum, say so and stop — do not quietly ship fewer scenes than the source material has.
+
 ### Multi-layout templates: pick a layout per scene
 
 When a template's `customPayloadSchema.slideId.enum` holds more than one value (today `html-slide` and `html-slide-blackboard`, 16 layouts each), **every scene must name one**, chosen to fit that scene's information shape — a comparison, a timeline, a code walkthrough and a set of numbers are four different layouts.
@@ -94,6 +123,8 @@ Two consequences for the agent:
 - **Forbidden**: reusing a single `slideId` across the whole video on a multi-layout template because it was the first one in the enum.
 - **Forbidden**: the user specified a template, but the agent first generated a generic DSL and then passed `--template-id` to `template-registry` to force-bind it.
 - **Forbidden**: continuing into binding / rendering despite knowing that template-specific fields, scene shapes, or binding details are missing.
+- **Forbidden**: showing the user a confirmation summary whose scene count differs from `scenes[]` in the returned DSL.
+- **Forbidden**: omitting `--source-document-url` for a template that declares `capabilities.payloadHydration`, or trying to hand-write the payload it hydrates.
 - **Forbidden**: silently degrading to a generic DSL because the current script cannot support a template, leaving the failure to the downstream stage.
 
 ### When a template is not yet supported

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

@@ -65,6 +65,27 @@ try:
 except ImportError:
     _HAS_ENHANCER = False
 
+# 场景数上限的唯一实现在 dsl_validator（它同时是门禁方）。守护式导入的理由同上：
+# 共享目录可能不在（单测 / 裁剪安装），那时退回历史常量 20，行为与改动前一致。
+try:
+    from video_dsl.runtime.dsl_validator import (
+        DEFAULT_MAX_SCENES,
+        max_scenes_for_template,
+    )
+except ImportError:
+    DEFAULT_MAX_SCENES = 20
+
+    def max_scenes_for_template(template_config):  # type: ignore[misc]
+        return DEFAULT_MAX_SCENES
+
+# payloadHydration 声明的读取。gen_script 只用它来判断"这个模板需不需要源文件引用"，
+# 真正的取数发生在 render-video 侧（见 payload_hydrator 模块头）。
+try:
+    from payload_hydrator import hydration_spec  # noqa: E402
+    _HAS_HYDRATOR = True
+except ImportError:
+    _HAS_HYDRATOR = False
+
 try:
     from registry_loader import (
         load_registry_data as _load_registry_data,
@@ -257,8 +278,23 @@ def validate_dsl(dsl: dict) -> list:
     return errors_as_strings(validate_structural(dsl))
 
 
-def plan_scenes(topic: str, duration: int, scene_count: int | None, allow_digital_human: bool, language: str = DEFAULT_LANGUAGE) -> list:
-    """Plan scene structure based on topic and constraints."""
+def plan_scenes(
+    topic: str,
+    duration: int,
+    scene_count: int | None,
+    allow_digital_human: bool,
+    language: str = DEFAULT_LANGUAGE,
+    max_scenes: int = DEFAULT_MAX_SCENES,
+) -> list:
+    """Plan scene structure based on topic and constraints.
+
+    ``max_scenes`` 来自模板的 ``capabilities.maxScenes``（见 ``_resolve_contract``）。
+    被 clamp 时**必须出声**：调用方要的场景数和拿到的不一样，而这个差值一路传到
+    下游才会以别的形态爆出来——2026-09-23 线上一份 23 页 PPT 在这里被静默砍到 20，
+    模型接着写了 23 段旁白、让用户确认了 23 个场景，最后 prepare_video_assets 报的是
+    ``scenes[0..19].customPayload.slide (required)``，跟"场景被砍了"半点关系看不出来。
+    """
+    requested = scene_count
     if scene_count is None:
         if duration <= 15:
             scene_count = 3
@@ -269,7 +305,22 @@ def plan_scenes(topic: str, duration: int, scene_count: int | None, allow_digita
         else:
             scene_count = min(10, duration // 8)
 
-    scene_count = max(3, min(scene_count, 20))
+    scene_count = max(3, min(scene_count, max_scenes))
+
+    if requested is not None and requested != scene_count:
+        detail = (
+            f"raised to the {scene_count}-scene minimum"
+            if requested < scene_count
+            else f"clamped to the template's maximum of {max_scenes}"
+        )
+        print(
+            f"⚠️  requested {requested} scene(s) but planned {scene_count}: {detail}.\n"
+            f"   The DSL below has {scene_count} scenes — read the count back from it before "
+            f"showing the script to the user, and do not describe scenes that are not there.\n"
+            f"   If this template needs one scene per source page, raise "
+            f"capabilities.maxScenes in its template.json.",
+            file=sys.stderr,
+        )
 
     scenes = []
     content_scenes = scene_count - 2
@@ -491,6 +542,8 @@ def _template_needs_image(template_config: dict | None) -> bool:
 #   - needs_narration   bool         capabilities.needsNarration，默认 True
 #   - scene_strategy    str          capabilities.sceneStrategy ∈ {arc, single, fixed, countdown}，默认 arc
 #   - fixed_scenes      list[dict]   capabilities.fixedScenes（single/fixed 用；缺省单 opening）
+#   - max_scenes        int          capabilities.maxScenes，默认 20（arc 的 --scenes 上限；
+#                                    "一页一场景"的模板由源文件页数决定场景数，应声明抬高）
 #   - countdown         dict|None    countdown 策略的解析结果（见 countdown_spec 模块；
 #                                    非 countdown 模板为 None）
 #   - payload_style     str          capabilities.payloadStyle ∈ {visual-overlay, slide, carousel-caption}
@@ -553,6 +606,8 @@ def _resolve_contract(template_config: dict | None) -> dict:
         "needs_narration": needs_narration,
         "scene_strategy": scene_strategy,
         "fixed_scenes": fixed_scenes,
+        # 上限读取放共享模块：dsl_validator 的门禁读的是同一个函数。
+        "max_scenes": max_scenes_for_template(template_config),
         # 声明解析放共享模块：render-video 的计划校验要读同一份声明，
         # 两边各抄一遍正是这个功能上一版栽过的跟头。
         "countdown": _resolve_countdown(template_config) if scene_strategy == "countdown" else None,
@@ -675,6 +730,46 @@ def _enforce_supported_duration(
         sys.exit(1)
 
 
+def _record_source_document(
+    dsl: dict,
+    template_config: dict | None,
+    template_id: str | None,
+    source_document_url: str | None,
+) -> None:
+    """把源文件引用写进 ``meta.sourceDocument``，供渲染管线按引用取数。
+
+    这个键必须由**骨架**携带，不能指望模型后面补：ab-agent 的合并层
+    （``applyNarrationToSkeleton``）以骨架为基底，只从模型提交的 dsl_json 里搬
+    narration 与 customPayload，``meta`` / ``global`` 归骨架所有。模型往 dsl_json 里写
+    ``meta.sourceDocument`` 会被静默丢掉。
+
+    模板声明了 ``payloadHydration`` 却没拿到 URL 时在这里就警告，而不是等到
+    prepare_video_assets 才失败 —— 那时模型已经写完全部旁白并让用户确认过了。
+    """
+    if source_document_url:
+        dsl["meta"]["sourceDocument"] = {"url": source_document_url}
+        return
+
+    if not _HAS_HYDRATOR or not template_config:
+        return
+    try:
+        spec = hydration_spec(template_config)
+    except Exception:  # noqa: BLE001 - 模板声明写坏了不该让脚本生成失败
+        return
+    if not spec:
+        return
+
+    print(
+        f"⚠️  template '{template_id}' builds customPayload.{spec['payload_field']} from a source "
+        f"document, but no --source-document-url was given.\n"
+        f"   The skeleton below has no meta.sourceDocument, so prepare_video_assets will refuse it "
+        f"— and it will refuse it *after* you have written every scene's narration and asked the "
+        f"user to confirm.\n"
+        f"   Re-run gen_script with --source-document-url <the same .pptx URL you gave doc_parse>.",
+        file=sys.stderr,
+    )
+
+
 def _plan_contract_scenes(
     contract: dict, topic: str, duration: int, scene_count: int | None, language: str
 ) -> list:
@@ -688,7 +783,11 @@ def _plan_contract_scenes(
     这类模板由此能产出真正的单场景，而不再被强行补到 3 段。``--scenes`` 只对 arc 生效。
     """
     if contract["scene_strategy"] == "arc":
-        return plan_scenes(topic, duration, scene_count, False, language=language)
+        return plan_scenes(
+            topic, duration, scene_count, False,
+            language=language,
+            max_scenes=contract.get("max_scenes", DEFAULT_MAX_SCENES),
+        )
 
     fixed = contract["fixed_scenes"] or [{"purpose": "opening"}]
     n = len(fixed)
@@ -1154,6 +1253,7 @@ def build_dsl(
         caption_lines: list[str] | None = None,
         scene_images: list[str] | None = None,
         item_count: int | None = None,
+        source_document_url: str | None = None,
 ) -> dict:
     """Build a complete Video DSL JSON.
 
@@ -1607,6 +1707,8 @@ def build_dsl(
     if template_id:
         dsl["meta"]["templateId"] = template_id
 
+    _record_source_document(dsl, template_config, template_id, source_document_url)
+
     _enforce_supported_duration(dsl, template_config, template_id)
 
     return dsl
@@ -1628,7 +1730,15 @@ Examples:
     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("--scenes", type=int, default=None, help="Scene count (default: auto-planned). Only applies to arc templates. Bounded below by 3 and above by the template's capabilities.maxScenes (default 20); a clamp is reported on stderr, so read the scene count back from the returned DSL rather than assuming you got what you asked for.")
+    parser.add_argument(
+        "--source-document-url", default=None,
+        help="Source document URL (.pptx) for templates that build their per-scene payload from a "
+             "document (capabilities.payloadHydration, e.g. ppt-to-video). Recorded at "
+             "meta.sourceDocument; prepare_video_assets then fetches the layout itself and fills "
+             "every scene's customPayload. Pass the same URL you gave doc_parse. Without it such a "
+             "template's DSL is rejected downstream.",
+    )
     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(
         "--speed",
@@ -1843,6 +1953,7 @@ Examples:
             caption_lines=args.caption_lines,
             scene_images=args.scene_images,
             item_count=args.item_count,
+            source_document_url=args.source_document_url,
         )
     except ValueError as exc:
         # Covers both a bad --item-count and an unusable countdown declaration