@remixmate/cli 0.9.44 → 0.9.46

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
@@ -277,7 +328,11 @@ def plan_scenes(topic: str, duration: int, scene_count: int | None, allow_digita
     opening_duration = max(3, round(duration * 0.12))
     ending_duration = max(3, round(duration * 0.12))
     content_total = duration - opening_duration - ending_duration
-    per_content = max(3, round(content_total / content_scenes))
+    # 余数摊到前几段，保证各段加总正好等于 duration。以前是 round(均值) × 段数：
+    # 2026-09-23 线上 ppt-to-video 传 --duration 600 --scenes 23，21 段 × round(21.7)=22
+    # 加总 606s，撞上模板 supportedDurations.max=600 被自己的时长门禁拒掉。
+    # 每段仍有 3s 下限 —— 段数多到摊不开时加总会超出，那是真超出，交给门禁报。
+    base_content, extra_content = divmod(max(content_total, 0), content_scenes)
 
     scenes.append({
         "purpose": "opening",
@@ -288,7 +343,7 @@ def plan_scenes(topic: str, duration: int, scene_count: int | None, allow_digita
     for i in range(content_scenes):
         scenes.append({
             "purpose": "point",
-            "duration": per_content,
+            "duration": max(3, base_content + (1 if i < extra_content else 0)),
             "label": _localize_label(language, "label_point", n=i + 1),
         })
 
@@ -491,6 +546,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 +610,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,
@@ -562,6 +621,7 @@ def _resolve_contract(template_config: dict | None) -> dict:
         "payload_defaults": payload_defaults,
         "primary_visual_type": primary_visual_type,
         "default_layout": caps.get("defaultLayout"),
+        "authored_scenes": caps.get("authoredScenes") is True,
     }
 
 
@@ -675,6 +735,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,10 +788,24 @@ 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)
+    # 非 arc 策略的场景数由模板钉死，--scenes 不生效 —— 但必须出声。2026-09-23 线上
+    # screen-walkthrough 传 --scenes 6 拿回 2 场，没有任何提示，模型只能自己猜为什么。
+    if scene_count is not None and scene_count != n:
+        print(
+            f"⚠️  requested {scene_count} scene(s) but this template's sceneStrategy="
+            f"{contract['scene_strategy']} always plans {n}: --scenes is ignored here.\n"
+            f"   The DSL below has {n} scenes — read the count back from it before showing "
+            f"the script to the user.",
+            file=sys.stderr,
+        )
     per = max(1, round(duration / n))
     plans = []
     for i, fs in enumerate(fixed):
@@ -1154,6 +1268,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 +1722,22 @@ def build_dsl(
     if template_id:
         dsl["meta"]["templateId"] = template_id
 
+    _record_source_document(dsl, template_config, template_id, source_document_url)
+
+    if contract["authored_scenes"]:
+        # 场景表由调用方按用户素材编写（如按操作时间点切录屏），骨架只提供 meta/global。
+        # 这个标记必须由骨架携带：ab-agent 看到它才会整份采用模型提交的 DSL，
+        # 否则它以骨架为基底合并，新增场景、existing 素材、visuals 都会被静默丢掉。
+        dsl["meta"]["authoredScenes"] = True
+        print(
+            f"ℹ️  template '{template_id}' declares capabilities.authoredScenes: the scene list below "
+            f"is only a placeholder.\n"
+            f"   Write the full DSL yourself from the user's material (scenes, assets, visuals, "
+            f"customPayload) and submit all of it to prepare_video_assets — it is used as-is, "
+            f"not merged onto this skeleton. Keep meta.templateId.",
+            file=sys.stderr,
+        )
+
     _enforce_supported_duration(dsl, template_config, template_id)
 
     return dsl
@@ -1628,7 +1759,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 +1982,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

package/skills/gen-script/skill.json

@@ -34,7 +34,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",
@@ -48,6 +48,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."
@@ -114,6 +118,7 @@
       "voice_id",
       "speed",
       "template_id",
+      "source_document_url",
       "headline",
       "subheadline",
       "carousel_items",

package/skills/gen-script/version.json

@@ -2,6 +2,6 @@
   "skillName": "gen-script",
   "repoName": "agent-skill-media-maker",
   "skillId": "474",
-  "version": "V15",
+  "version": "V16",
   "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/prepare-video-assets/skill.json

@@ -33,6 +33,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)."

package/skills/prepare-video-assets/version.json

@@ -2,6 +2,6 @@
   "skillName": "prepare-video-assets",
   "repoName": "agent-skill-media-maker",
   "skillId": "476",
-  "version": "V1",
+  "version": "V3",
   "skillDescription": "Asset-preparation skill: resolves and generates every asset (image / audio / video) referenced by a Video DSL, persists a RenderPlan to the database, and returns a `job_id` for the subsequent `render_video` call.\n\nUse this skill as soon as the user mentions any of these intents:\n- Generate / prepare video assets, resolve assets, render-ready\n- \"Make me a video about X\" (the agent calls gen_script → prepare_video_assets → render_video)\n- Regenerate one asset (image / audio) for a specific scene\n\nNext step: after the user confirms the resolved assets, call `render_video` with the `job_id` returned by this skill.\n\n⚠️ Stop-and-confirm gate: this skill runs only after the user has confirmed the script, and after it returns you must show the resolved assets and wait for the user's explicit confirmation. Never call `render_video` in the same turn."
 }

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

@@ -63,6 +63,7 @@ from video_dsl.runtime.timeline_compiler import (
     split_subtitle,
     split_subtitle_from_lines,
     segment_narration,
+    assign_sentence_indices,
 )
 
 # 字幕末尾标点去除（与 timeline_compiler 中的 _strip_trailing_punct 同逻辑）
@@ -109,7 +110,10 @@ def _rebalance_subtitle_segments(segs: list[dict]) -> list[dict]:
         for p in parts:
             ratio = len(p) / total_chars
             frames = max(int(total_frames * ratio), 1)
+            # `**seg` 而不是只写三个键：切出来的各部分仍属于**同一句**，
+            # 所以 sentenceIndex 等字段要原样继承（见 build_render_plan 处的说明）。
             expanded.append({
+                **seg,
                 "text": _strip_subtitle_trailing_punct(p.strip()),
                 "startFrame": cur_frame,
                 "endFrame": cur_frame + frames,
@@ -507,6 +511,82 @@ def validate_dsl(dsl: dict) -> list:
     return errors_as_strings([e for e in found if getattr(e, "severity", "error") == "error"])
 
 
+def _hydrate_dsl_payload(
+    dsl: dict, template_id: str | None, source_document_url: str | None
+) -> None:
+    """按模板声明把源文件的每一页填进 ``customPayload``（就地改 dsl）。
+
+    只对声明了 ``capabilities.payloadHydration`` 的模板生效（目前 ppt-to-video）；
+    其余模板这里是零成本 no-op —— 声明驱动，不写 ``if template_id == X``（AGENTS.md）。
+
+    失败一律 exit 2 并把「下一步做什么」打全：这条路上所有失败形态的共同点是
+    *数据源没通*，而历史报错说的是"字段没填"，两者要采取的行动完全不同。
+
+    共享模块导入失败（裁剪安装 / 单测环境）时静默跳过：那时 payloadRequirements
+    的校验会照常报必填缺失，行为退回改动前，不会更糟。
+    """
+    try:
+        from payload_hydrator import HydrationError, hydrate_dsl  # noqa: E402
+    except ImportError:
+        return
+
+    try:
+        from registry_loader import get_template  # noqa: E402
+        template = get_template(template_id) if template_id else None
+    except Exception:  # noqa: BLE001 - registry 不可达时退回"不注入"，由校验兜底报错
+        template = None
+    if not template:
+        return
+
+    try:
+        report = hydrate_dsl(
+            dsl,
+            template,
+            override_url=source_document_url,
+            log=lambda msg: LogPrint(f"   {msg}", file=sys.stderr),
+        )
+    except HydrationError as exc:
+        LogPrint(f"❌ {exc}", file=sys.stderr)
+        sys.exit(2)
+
+    for line in report:
+        LogPrint(f"   {line}", file=sys.stderr)
+
+
+def _warn_step_sentence_mismatch(entry: dict, sentence_indices: list[int]) -> None:
+    """动作条数与旁白句数不等时出声。
+
+    为什么值得单独打一条：这一类缺陷**渲得出来**。它不报错、不退非零、renderJob
+    completed、漏斗记 rendered —— 2026-09-23 线上那条鸡兔同笼成片就是这样交付的，
+    10 步板面配 10 句旁白，听起来该一一对应，实际板面在音频中点就走完了。
+    既然成片本身不会告状，那就必须有人在这里说一句。
+
+    只警告不阻断：步数少于句数有时是作者的本意（末尾一句总结不需要新动作）。
+    真正需要拦的是"作者以为一一对应、实际不是"，而那个判断只有作者做得了 ——
+    所以这里给的是两个数字，不是一个结论。
+    """
+    steps = ((entry.get("props") or {}).get("steps")
+             or (entry.get("props") or {}).get("beats"))
+    if not isinstance(steps, list) or not steps:
+        return
+    sentences = (sentence_indices[-1] + 1) if sentence_indices else 0
+    if sentences == 0 or len(steps) == sentences:
+        return
+
+    scene_id = entry.get("sceneId", "?")
+    tail = (
+        f"末尾 {sentences - len(steps)} 句没有对应动作，画面会在那之前就走完并停住"
+        if len(steps) < sentences
+        else f"多出的 {len(steps) - sentences} 个动作会挤在最后一句上"
+    )
+    LogPrint(
+        f"⚠️  scene {scene_id}: {len(steps)} 个讲解动作 vs 旁白 {sentences} 句 —— {tail}。\n"
+        f"   本模板的动作按**句**对齐（第 i 个动作 = 第 i 句的起点）。要一一对应就让两者等数；"
+        f"   要刻意不等，忽略这条即可。",
+        file=sys.stderr,
+    )
+
+
 def resolve_dimensions(dsl: dict) -> tuple:
     ratio = dsl.get("global", {}).get("aspectRatio", "16:9")
     resolution = dsl.get("global", {}).get("resolution", "1080p")
@@ -771,9 +851,13 @@ def build_render_plan(dsl: dict, binding: dict) -> dict:
             local_subs = split_subtitle_from_lines(lines, duration_frames, fps)
         else:
             local_subs = split_subtitle(narration_text, duration_frames, fps)
+        # ⚠️ 平移帧号时**必须保留原有字段**（`**s`），不要只挑三个键重建。
+        # 这里曾经只搬 text/startFrame/endFrame，于是 timeline_compiler 给每段打上的
+        # `sentenceIndex`（模板用它把动作对齐到**句**而不是段）在这一步被静默丢掉 ——
+        # 下游模板拿不到句边界，只能退回按段对齐，也就是那个错位 bug 本身。
         subtitle_segments = [
             {
-                "text": s["text"],
+                **s,
                 "startFrame": s["startFrame"] + current_frame,
                 "endFrame": s["endFrame"] + current_frame,
             }
@@ -1381,14 +1465,24 @@ def adjust_timeline_to_audio(render_plan: dict) -> dict:
 
                 tts_subs = narration_asset.get("ttsSubtitles", [])
                 if tts_subs:
+                    # 句归属必须在 _strip_subtitle_trailing_punct **之前**算：
+                    # 判据就是句末标点，去掉之后所有段都会被认成同一句。
+                    # 这一层是「第 i 个动作对齐第 i 句」类模板（math-principles-expl
+                    # 的 steps、ppt-to-video 的 beats）唯一能拿到句边界的地方 ——
+                    # TTS 行是按停顿切的，段数远多于句数。
+                    sentence_indices = assign_sentence_indices(
+                        [s.get("text") or "" for s in tts_subs]
+                    )
                     entry["subtitleSegments"] = [
                         {
                             "text": _strip_subtitle_trailing_punct(s["text"].strip()),
                             "startFrame": current_frame + int(s["timeBegin"] / 1000.0 * fps),
                             "endFrame": current_frame + int(s["timeEnd"] / 1000.0 * fps),
+                            "sentenceIndex": sentence_indices[i],
                         }
-                        for s in tts_subs
+                        for i, s in enumerate(tts_subs)
                     ]
+                    _warn_step_sentence_mismatch(entry, sentence_indices)
                 else:
                     # No TTS timestamps — re-distribute existing subtitle
                     # lines across the REAL audio duration, by character
@@ -1432,6 +1526,7 @@ def adjust_timeline_to_audio(render_plan: dict) -> dict:
                             # 起点为终点。
                             end_f = scene_dur if i == len(old_subs) - 1 else starts[i + 1]
                             new_subs.append({
+                                **s,
                                 "text": text,
                                 "startFrame": current_frame + start_f,
                                 "endFrame": current_frame + end_f,
@@ -1451,6 +1546,7 @@ def adjust_timeline_to_audio(render_plan: dict) -> dict:
                             ratio = _plain(text) / total_chars
                             seg_frames = max(int(sub_span * ratio), fps // 2)
                             new_subs.append({
+                                **s,
                                 "text": text,
                                 "startFrame": current_frame + cursor,
                                 "endFrame": current_frame + cursor + seg_frames,
@@ -1473,7 +1569,7 @@ def adjust_timeline_to_audio(render_plan: dict) -> dict:
                         rel_start = s["startFrame"] - old_scene_start
                         rel_end = s["endFrame"] - old_scene_start
                         new_subs.append({
-                            "text": s["text"],
+                            **s,
                             "startFrame": current_frame + rel_start,
                             "endFrame": current_frame + rel_end,
                         })
@@ -2177,6 +2273,13 @@ Examples:
     parser.add_argument("--dsl", help="Input DSL file path")
     parser.add_argument("--dsl-json", default=None, help="DSL JSON as an inline string (replaces --dsl; no file needed; preferred for multi-user concurrent flows)")
     parser.add_argument("--template-id", default=None, help="Template id (required unless --render-plan / --job-id is used)")
+    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). Overrides "
+             "meta.sourceDocument in the DSL. The layout data is fetched here and written into "
+             "every scene's customPayload — it is deliberately never routed through the model.",
+    )
     parser.add_argument("--render-plan", help="Existing RenderPlan file path")
     parser.add_argument("--resolve-only", action="store_true", help="Only resolve assets; do not run the render")
     parser.add_argument("--skip-asset-resolve", action="store_true", help="Skip asset resolution")
@@ -2365,6 +2468,18 @@ Examples:
             )
             sys.exit(2)
 
+        # ── 按引用注入模板声明的大 payload（必须在校验之前）─────────────
+        #
+        # ppt-to-video 这类模板的画面数据（customPayload.slide：一整页的节点树、
+        # 坐标、配色、beats）只有一个合法产出方 —— ab-render 的 /extract layout 层，
+        # 而它体积大到不能过模型（一页几百 KB，23 页好几 MB）。所以 DSL 里只带一个
+        # 引用（meta.sourceDocument），在这里把全量取回来填进每个场景。
+        #
+        # 为什么必须在 validate_dsl 之前：那道校验读的就是 capabilities.payloadRequirements
+        # 的必填项。放在后面 = 每次都被自己还没填的字段拒掉（2026-09-23 线上
+        # conv_Sesw2g8oM81 的表现就是 scenes[0..19].customPayload.slide (required)）。
+        _hydrate_dsl_payload(dsl, args.template_id, args.source_document_url)
+
         errors = validate_dsl(dsl)
         if errors:
             LogPrint("❌ DSL validation failed:", file=sys.stderr)

package/skills/render-video/version.json

@@ -2,6 +2,6 @@
   "skillName": "render-video",
   "repoName": "agent-skill-media-maker",
   "skillId": "473",
-  "version": "V25",
+  "version": "V28",
   "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."
 }