@remixmate/cli 0.9.49 → 0.9.51

package/skills/gen-script/skill.json

@@ -34,7 +34,7 @@
       },
       "scenes": {
         "type": "number",
-        "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."
+        "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 (capabilities.payloadHydration), pass the page count you saw in doc_parse's summary."
       },
       "voice_id": {
         "type": "string",
@@ -44,13 +44,21 @@
         "type": "number",
         "description": "Narration speech rate, 0.5-2.0 (default 1.0). Stored at global.narration.speed and applied when prepare_video_assets synthesizes the voice-over. **Must** pass when the user picked a speech rate — a template's 语速 / speed parameter arrives as a multiplier like 1.1, and without this flag it is silently dropped and the narration comes back at 1.0. Above ~1.3 subtitle alignment drifts and the delivery sounds mechanical; suggest shortening the script instead of raising it further."
       },
+      "variant": {
+        "type": "string",
+        "description": "Template visual variant id (a key of the template's variants; template_registry lists them as variantIds). Written to meta.templateVariant, which beats the fuzzy `style` match. **Must** pass when the user picked a style: the replicate card shows it as `名字（id）` — e.g. `视觉风格: 紫色科技（tech-purple）` or `板面颜色: 黑板（black-board）` → pass the id in the parentheses. Without it the choice is silently dropped. Requires template_id; an id the template does not declare is rejected."
+      },
+      "background_preset": {
+        "type": "string",
+        "description": "Scene background preset, one of the template's customPayloadSchema.background.preset values. Written to every scene's customPayload.background.preset. **Must** pass when the user picked a background: the replicate card shows `背景样式: 纯色（solid）` → pass `solid`. Without it the scene keeps the template default. Requires template_id; unsupported values are rejected. `image` / `video` also need customPayload.background.assetRef on each scene."
+      },
       "template_id": {
         "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."
+        "description": "Template id (from template_registry). 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."
+        "description": "Source document URL (.pptx) for a template that builds its per-scene picture from that document (capabilities.payloadHydration). **Must** pass it for such a template: it is recorded at meta.sourceDocument, and prepare_video_assets then fetches the layout itself and fills the customPayload field the template declares (payloadHydration.payloadField) on every scene. 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",
@@ -72,7 +80,7 @@
         "items": {
           "type": "string"
         },
-        "description": "Per-scene visuals for a visual-overlay template (image-slide etc.) — the counterpart of carousel_items for templates that have real scenes. Each element is EITHER a full URL (use that existing asset for the scene, no gen-image call) OR the literal string 'ai' / 'ai:<prompt>' (leave that scene to gen-image; the text after the colon, when present, is the user's own image prompt for it). Mapping is POSITIONAL: element i is scene i, so an AI scene can sit anywhere in the order — pass ['url1','ai','url2'] verbatim when the user arranged it that way. Scenes past the last element still get an AI-generated image, so 2 images still produce a full video. When `scenes` is not set the scene count is raised (never lowered) to fit the elements, so nothing the user arranged is dropped and handing over fewer images does not shrink the video. **Must** pass when the user supplies images for such a template — otherwise their images are ignored entirely and every scene is AI-generated. Do NOT pass for carousel-caption templates; those take carousel_items."
+        "description": "Per-scene visuals for a visual-overlay template (capabilities.payloadStyle=visual-overlay) — the counterpart of carousel_items for templates that have real scenes. Each element is EITHER a full URL (use that existing asset for the scene, no gen-image call) OR the literal string 'ai' / 'ai:<prompt>' (leave that scene to gen-image; the text after the colon, when present, is the user's own image prompt for it). Mapping is POSITIONAL: element i is scene i, so an AI scene can sit anywhere in the order — pass ['url1','ai','url2'] verbatim when the user arranged it that way. Scenes past the last element still get an AI-generated image, so 2 images still produce a full video. When `scenes` is not set the scene count is raised (never lowered) to fit the elements, so nothing the user arranged is dropped and handing over fewer images does not shrink the video. **Must** pass when the user supplies images for such a template — otherwise their images are ignored entirely and every scene is AI-generated. Do NOT pass for carousel-caption templates; those take carousel_items."
       },
       "caption_lines": {
         "type": "array",
@@ -117,6 +125,8 @@
       "scenes",
       "voice_id",
       "speed",
+      "variant",
+      "background_preset",
       "template_id",
       "source_document_url",
       "headline",

package/skills/gen-script/version.json

@@ -2,6 +2,6 @@
   "skillName": "gen-script",
   "repoName": "agent-skill-media-maker",
   "skillId": "474",
-  "version": "V16",
+  "version": "V17",
   "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.md

@@ -73,7 +73,7 @@ The asset resolver invokes the following skills based on `AssetRef` declarations
 ```bash
 python3 <SkillDir>/scripts/prepare_video_assets.py \
   --dsl-json '<DSL_JSON_STRING>' \
-  --template-id html-slide
+  --template-id <templateId>
 ```
 
 - `<DSL_JSON_STRING>` is the JSON the agent received from `gen_script` — pass inline; **do not** write it to disk.
@@ -86,7 +86,7 @@ python3 <SkillDir>/scripts/prepare_video_assets.py \
 ```bash
 python3 <SkillDir>/scripts/prepare_video_assets.py \
   --dsl my-video.dsl.json \
-  --template-id html-slide
+  --template-id <templateId>
 ```
 
 `--template-id` automatically calls template-registry internally; or pass `--binding my-video.binding.json` if you have a pre-generated binding.
@@ -162,7 +162,7 @@ During dev / debug the user may want to exercise the pipeline without burning ge
 ```bash
 python3 <SkillDir>/scripts/prepare_video_assets.py \
   --dsl-json '<DSL_JSON_STRING>' \
-  --template-id picture-book-en \
+  --template-id <templateId> \
   --stub-image-url "https://cdn.example.com/placeholder.jpg"
 ```
 

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

@@ -35,7 +35,7 @@
       },
       "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."
+        "description": "Source document URL (.pptx) for a template that builds its per-scene picture from that document (capabilities.payloadHydration). 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 the customPayload field the template declares (payloadHydration.payloadField) on every scene; you neither author nor see it."
       },
       "binding_json": {
         "type": "string",

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

@@ -2,6 +2,6 @@
   "skillName": "prepare-video-assets",
   "repoName": "agent-skill-media-maker",
   "skillId": "476",
-  "version": "V3",
+  "version": "V4",
   "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

@@ -7,8 +7,8 @@
   编译时间线，最终调用 Remotion 渲染引擎输出视频。
 
 用法:
-  python render_video.py --dsl video.dsl.json --template-id screen-walkthrough
-  python render_video.py --dsl video.dsl.json --template-id screen-walkthrough --resolve-only
+  python render_video.py --dsl video.dsl.json --template-id <templateId>
+  python render_video.py --dsl video.dsl.json --template-id <templateId> --resolve-only
   python render_video.py --render-plan video.render-plan.json
 
 环境变量:
@@ -53,7 +53,7 @@ _SHARED_LIB_DIR = os.path.join(os.path.dirname(__file__), "..", "..", "template-
 # Single sys.path setup for both cross-skill import surfaces of the shared lib:
 #   - <shared>            for `video_dsl.runtime.*`
 #   - <shared>/scripts    for `registry_loader`, `match_template`,
-#                          `render_job_client`, `template_paths`
+#                          `render_job_client`, `countdown_spec`
 # Each deeper function used to repeat its own sys.path.insert; consolidating
 # here keeps the module's import side-effects in one place and matches
 # Python's "set up sys.path once at module top" idiom.
@@ -516,7 +516,7 @@ def _hydrate_dsl_payload(
 ) -> None:
     """按模板声明把源文件的每一页填进 ``customPayload``（就地改 dsl）。
 
-    只对声明了 ``capabilities.payloadHydration`` 的模板生效（目前 ppt-to-video）；
+    只对声明了 ``capabilities.payloadHydration`` 的模板生效；
     其余模板这里是零成本 no-op —— 声明驱动，不写 ``if template_id == X``（AGENTS.md）。
 
     失败一律 exit 2 并把「下一步做什么」打全：这条路上所有失败形态的共同点是
@@ -573,9 +573,12 @@ def _compose_image_prompts(dsl: dict, template_id: str | None) -> None:
         LogPrint(f"   {line}", file=sys.stderr)
 
 
-def _warn_step_sentence_mismatch(entry: dict, sentence_indices: list[int]) -> None:
+def _warn_step_sentence_mismatch(entry: dict, sentence_indices: list[int], step_field: Optional[str]) -> None:
     """动作条数与旁白句数不等时出声。
 
+    动作数组放在哪个字段由模板的 ``capabilities.stepAlignment.payloadField`` 声明
+    （``step_field``）；没声明的模板不检查。
+
     为什么值得单独打一条：这一类缺陷**渲得出来**。它不报错、不退非零、renderJob
     completed、漏斗记 rendered —— 2026-09-23 线上那条鸡兔同笼成片就是这样交付的，
     10 步板面配 10 句旁白，听起来该一一对应，实际板面在音频中点就走完了。
@@ -585,8 +588,9 @@ def _warn_step_sentence_mismatch(entry: dict, sentence_indices: list[int]) -> No
     真正需要拦的是"作者以为一一对应、实际不是"，而那个判断只有作者做得了 ——
     所以这里给的是两个数字，不是一个结论。
     """
-    steps = ((entry.get("props") or {}).get("steps")
-             or (entry.get("props") or {}).get("beats"))
+    if not step_field:
+        return
+    steps = (entry.get("props") or {}).get(step_field)
     if not isinstance(steps, list) or not steps:
         return
     sentences = (sentence_indices[-1] + 1) if sentence_indices else 0
@@ -1360,7 +1364,12 @@ def resolve_assets(render_plan: dict, private_token: str, max_retries: int, time
     return render_plan
 
 
-def _auto_highlight_map(entry: dict, narration_asset: Optional[dict], render_plan: dict) -> None:
+def _auto_highlight_map(
+    entry: dict,
+    narration_asset: Optional[dict],
+    render_plan: dict,
+    line_sync: dict[str, str],
+) -> None:
     """Auto-fill ``templateData.highlightMap`` for any template that uses
     structured ``{intro, items, outro}`` narration and ships per-line cards.
 
@@ -1371,6 +1380,10 @@ def _auto_highlight_map(entry: dict, narration_asset: Optional[dict], render_pla
     this auto-fill. Adding a new template that follows the same pattern needs
     NO change to this function.
 
+    ``line_sync`` is the template's ``lineSyncSlides`` declaration (slideId →
+    card-array key). It caps the map at the card count so trailing outro lines
+    don't point past the last card; slides it doesn't list get no cap.
+
     Skipped silently when:
       - narration asset has no narrationLineCount (structured form wasn't used)
       - author already supplied a highlightMap (explicit wins)
@@ -1405,23 +1418,13 @@ def _auto_highlight_map(entry: dict, narration_asset: Optional[dict], render_pla
     intro_lines = int(narration_asset.get("narrationIntroLines") or 0)
     item_count = line_count - intro_lines
     # outro counts toward line_count too; cap item_count at the authored
-    # items-array length so trailing outro lines don't spill into card
-    # indices.
-    # ⚠️ 这份键表必须与模板侧 utils/slidePayload.ts 的 CARD_ARRAY_KEYS 完全一致：
-    # 两处是同一算法的两份实现（这里是生产路径，那边是摊平 binder 形态下的本地兜底）。
-    # 2026-09-15 修复：此前这里少了 steps / annotations，于是 step-flow 与
-    # code-highlight 拿不到下面那行的上限裁剪，旁白带 outro 行时 highlightMap 会多出
-    # 一个指向数组外的下标 —— 那一行播放期间"全部卡片变暗、没有一张点亮"。
-    # 顺序也有意义：取第一个命中的键，新键一律追加在末尾。
-    # template-library 的 `pnpm validate:contracts` 现在会双向核对这两份表。
-    items_key = next(
-        (
-            k
-            for k in ("concepts", "pillars", "eras", "items", "steps", "annotations")
-            if isinstance(tdata.get(k), list)
-        ),
-        None,
-    )
+    # card-array length so trailing outro lines don't spill into card
+    # indices. 数组键读模板的 lineSyncSlides 声明（按 slideId），CLI 不保留键表副本
+    # —— 以前这里有一份模板 CARD_ARRAY_KEYS 的手抄，已经漂移过两次。
+    slide_id = props.get("slideId") or tdata.get("slideId")
+    items_key = line_sync.get(slide_id) if isinstance(slide_id, str) else None
+    if items_key and not isinstance(tdata.get(items_key), list):
+        items_key = None
     if items_key:
         item_count = min(item_count, len(tdata[items_key]))
 
@@ -1440,21 +1443,25 @@ def _auto_highlight_map(entry: dict, narration_asset: Optional[dict], render_pla
     })
 
 
-def _template_default_tail_pad_frames(template_id: str, fps: int) -> int | None:
+def _timing_template(template_id: str) -> dict:
+    """排轴阶段要读的模板声明；取不到就返回空 dict，走全局默认，不因为这个挡渲染。"""
+    if not template_id:
+        return {}
+    try:
+        from registry_loader import get_template  # type: ignore
+        return get_template(template_id, include_all_statuses=True) or {}
+    except Exception:  # noqa: BLE001
+        return {}
+
+
+def _template_default_tail_pad_frames(tpl: dict, fps: int) -> int | None:
     """模板声明的旁白尾巴默认值（``capabilities.defaultTailPadSec``），换算成帧。
 
     场景自己的 ``customPayload.tailPadSec`` 仍然优先；这里只替换全局 1.5s 兜底。
     为什么要模板级：逐场景设置靠模型照着 llmHint 抄，实际经常漏 —— 2026-09-24
     线上《狼来了》绘本每页结尾 1.9s 空白，86s 里 15s 没有声音。
     """
-    if not template_id:
-        return None
-    try:
-        from registry_loader import get_template  # type: ignore
-        tpl = get_template(template_id, include_all_statuses=True)
-    except Exception:  # noqa: BLE001 - 取不到模板就走全局默认，不因为这个挡渲染
-        return None
-    value = ((tpl or {}).get("capabilities") or {}).get("defaultTailPadSec")
+    value = (tpl.get("capabilities") or {}).get("defaultTailPadSec")
     if isinstance(value, bool) or not isinstance(value, (int, float)) or value < 0:
         return None
     return int(round(float(value) * fps))
@@ -1469,7 +1476,11 @@ def adjust_timeline_to_audio(render_plan: dict) -> dict:
     assets_map = {a["assetId"]: a for a in render_plan["resolvedAssets"]}
     current_frame = 0
     adjusted = 0
-    default_tail_pad = _template_default_tail_pad_frames(render_plan.get("templateId", ""), fps)
+    from video_dsl.runtime.dsl_validator import line_sync_slides, step_alignment_field
+    timing_tpl = _timing_template(render_plan.get("templateId", ""))
+    line_sync = line_sync_slides(timing_tpl)
+    step_field = step_alignment_field(timing_tpl)
+    default_tail_pad = _template_default_tail_pad_frames(timing_tpl, fps)
     if default_tail_pad is None:
         default_tail_pad = int(fps * 1.5)
 
@@ -1533,7 +1544,7 @@ def adjust_timeline_to_audio(render_plan: dict) -> dict:
                         }
                         for i, s in enumerate(tts_subs)
                     ]
-                    _warn_step_sentence_mismatch(entry, sentence_indices)
+                    _warn_step_sentence_mismatch(entry, sentence_indices, step_field)
                 else:
                     # No TTS timestamps — re-distribute existing subtitle
                     # lines across the REAL audio duration, by character
@@ -1605,7 +1616,7 @@ def adjust_timeline_to_audio(render_plan: dict) -> dict:
                             cursor += seg_frames
                         entry["subtitleSegments"] = new_subs
 
-        _auto_highlight_map(entry, narration_asset, render_plan)
+        _auto_highlight_map(entry, narration_asset, render_plan, line_sync)
 
         # Re-anchor subtitles for scenes that weren't handled in the narration block above.
         # This covers scenes without narration or with invalid duration.
@@ -1873,6 +1884,11 @@ def _persist_plan_checkpoint(render_plan: dict, job_id: Optional[int], private_t
         LogPrint(f"   ⚠️  RenderPlan checkpoint failed (jobId={job_id}): {exc}", file=sys.stderr)
 
 
+
+def _builtin_dynamic_render_enabled() -> bool:
+    """内置模板是否也走 /renderDraft（Phase 3b 路由翻转开关，默认关）。"""
+    return os.environ.get("REMIXMATE_BUILTIN_DYNAMIC_RENDER", "").strip().lower() in {"1", "true", "yes", "on"}
+
 def render_with_remote_api(
     render_plan: dict,
     output_path: str,
@@ -1941,6 +1957,13 @@ def render_with_remote_api(
     status_path = "/renderStatus"
 
     source_oss_key = None
+    # 内置模板是否也走动态渲染（Phase 3b 路由翻转，ab-platform/docs/
+    # template-authoring-page-review.md §7.2）。默认关：翻转依赖 ab-render 以服务身份取
+    # 内置源码（DRAFT_BUILTIN_SOURCE_TOKEN ↔ ab-api ab_render.service_token），服务端没配好
+    # 就打开，普通用户渲染内置模板会全部失败。服务端就绪后设 REMIXMATE_BUILTIN_DYNAMIC_RENDER=1；
+    # 回退 = 取消该变量，内置模板回到 /render。
+    builtin_dynamic = _builtin_dynamic_render_enabled()
+    is_builtin_dynamic = False
     template_id = render_plan.get("templateId", "")
     if template_id:
         try:
@@ -1950,8 +1973,12 @@ def render_with_remote_api(
             # 是另一个模板的画面。
             _meta = get_template(template_id, include_all_statuses=True)
             if _meta and not _meta.get("isBuiltin"):
-                # hasSource 是新字段；sourceOssKey 兼容尚未升级的 ab-api
-                source_oss_key = _meta.get("hasSource") or _meta.get("sourceOssKey")
+                source_oss_key = _meta.get("hasSource")
+            elif _meta and builtin_dynamic:
+                # 内置模板：客户端拿不到也不需要 sourceOssKey（源码保护），只要知道
+                # 它在 registry 里；ab-render 按 templateKey 以服务身份取包。
+                source_oss_key = True
+                is_builtin_dynamic = True
         except Exception:
             source_oss_key = None
 
@@ -1970,6 +1997,10 @@ def render_with_remote_api(
         # 不传则 ab-render 退回截首帧 / 不渲。
         if cover_composition_id:
             payload["coverCompositionId"] = cover_composition_id
+        if is_builtin_dynamic:
+            # 与预构建 /render 的 MainVideo 语义对齐：不把 entry.props 摊平到顶层
+            # （摊平会让同名键覆盖平台注入的 typography / variantId 等）。
+            payload["spreadEntryProps"] = False
         render_path = "/renderDraft"
         status_path = "/renderDraftStatus"
     else:
@@ -1988,6 +2019,8 @@ def render_with_remote_api(
     if pending_resume:
         # 续跑：下面那堆"正在提交"的日志会误导人，跳过
         LogPrint(f"🎬 Remote render task already exists, will resume polling", file=sys.stderr)
+    elif is_builtin_dynamic:
+        LogPrint(f"   Builtin template (dynamic bundle): {template_id}", file=sys.stderr)
     elif source_oss_key:
         LogPrint(f"   Private template (OSS dynamic bundle): {template_id}", file=sys.stderr)
     else:
@@ -2295,8 +2328,8 @@ def main():
         formatter_class=argparse.RawDescriptionHelpFormatter,
         epilog="""
 Examples:
-  python render_video.py --dsl video.dsl.json --template-id html-slide
-  python render_video.py --dsl video.dsl.json --template-id html-slide --resolve-only
+  python render_video.py --dsl video.dsl.json --template-id <templateId>
+  python render_video.py --dsl video.dsl.json --template-id <templateId> --resolve-only
   python render_video.py --render-plan video.render-plan.json
         """,
     )
@@ -2306,7 +2339,7 @@ Examples:
     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 "
+             "document (capabilities.payloadHydration). 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.",
     )
@@ -2500,8 +2533,8 @@ Examples:
 
         # ── 按引用注入模板声明的大 payload（必须在校验之前）─────────────
         #
-        # ppt-to-video 这类模板的画面数据（customPayload.slide：一整页的节点树、
-        # 坐标、配色、beats）只有一个合法产出方 —— ab-render 的 /extract layout 层，
+        # 按引用注入的模板画面数据（payloadHydration.payloadField 指定的字段：一整页
+        # 的节点树、坐标、配色、beats）只有一个合法产出方 —— ab-render 的 /extract layout 层，
         # 而它体积大到不能过模型（一页几百 KB，23 页好几 MB）。所以 DSL 里只带一个
         # 引用（meta.sourceDocument），在这里把全量取回来填进每个场景。
         #

package/skills/render-video/version.json

@@ -2,6 +2,6 @@
   "skillName": "render-video",
   "repoName": "agent-skill-media-maker",
   "skillId": "473",
-  "version": "V29",
+  "version": "V31",
   "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/README.md

@@ -30,17 +30,8 @@ ab-api 响应包装格式 `{code, msg, data}` 由 `registry_loader._fetch_http`
 
 ## 契约一致性
 
-template-library 仓库内置契约验证器,确保:
-
-- 每个 `template.json` 中引用的 `compositionId` 都存在于 remotion-renderer 的 `manifest.ts`
-- manifest 中的每个 compositionId 都被某个 `template.json` 引用
-- 所有 `template.json` 通过 JSON Schema 校验
-
-本地可运行 `check_contracts.py` 做跨仓库一致性检查(从 monorepo `<repo>/remotion-renderer/src/core/compositions/manifest.ts` 读 manifest):
-
-```bash
-python3 <SkillDir>/scripts/check_contracts.py
-```
+模板契约（schema、compositionId、slideSchemas、lineSyncSlides 等）由 template-library
+仓库自己的 `pnpm check:all` 校验。本仓不保留任何模板级校验或模板数据副本。
 
 ## 共享 Python 模块
 
@@ -48,12 +39,10 @@ python3 <SkillDir>/scripts/check_contracts.py
 
 | 模块 | 谁在用 | 作用 |
 |---|---|---|
-| `template_paths.py` | registry_loader / template_binder / gen-script / check_contracts | 统一计算 monorepo / template-library 路径,代替 4 个 caller 各自数 `..` |
 | `registry_loader.py` | template-registry / match_template / render-video / gen-script / dsl_validator | 加载 registry(HTTP + cache + file) |
 | `match_template.py` | render-video(`auto_bind_template`) | DSL → TemplateBinding 算法 |
 | `render_job_client.py` | render-video / export-jianying | ab-api renderJob HTTP 客户端 |
-| `check_contracts.py` | 维护脚本 | template-library ↔ remotion-renderer 契约校验 |
-| `sync_registry.py` | 维护脚本 | 把 registry 摘要落盘供 LLM prompt 使用 |
+| `countdown_spec.py` | gen-script / render-video | 解析 `capabilities.countdown` 声明 |
 
 sibling skill 通过 `sys.path.insert(0, "<…>/template-registry/scripts")` 然后直接 `import` 模块名,模式见 `render_video.py` 顶部的"Single sys.path setup"段。
 

package/skills/template-registry/SKILL.md

@@ -25,23 +25,7 @@ Stores every video-template definition, loads a template by **template-id**, and
 
 Template metadata is authored in the standalone **template-library** monorepo, published to ab-api, and served to the CLI over HTTP. At runtime template-registry loads the registry from a single source — the ab-api endpoint (see the env table below) — which returns every template definition (full slotMapping, compositions, etc.) including the caller's private/tenant templates.
 
-> The `template-library/packages/metadata/registry.json` file below is the authoring layout in the monorepo. It is **not** read at runtime anymore; only monorepo-only maintenance tooling (`check_contracts.py`, `sync_registry.py`) touches it directly.
-
-```
-template-library/packages/
-├── templates/src/
-│   ├── html-slide/        # Knowledge-board template
-│   │   ├── Composition.tsx
-│   │   └── template.json
-│   ├── image-slide/       # Basic image + narration template (includes the tech variant)
-│   │   └── ...
-│   ├── picture-book-en/   # English picture-book video template
-│   │   └── ...
-│   └── screen-walkthrough/ # Screen-recording walkthrough template
-│       └── ...
-└── metadata/
-    └── registry.json      # Aggregated registry (every template.json merged)
-```
+> Each template's `template.json` (authored in template-library, aggregated into `registry.json` there) is the single source of truth for everything template-specific: `llmHint`, `capabilities`, `customPayloadSchema`, `slideSchemas`, `slotMapping`. This skill and the rest of the CLI only implement the generic mechanisms those declarations drive — they never name individual templates, so read the template's own definition (see *Steps*) instead of looking for per-template rules here.
 
 ## Agent behavior: image URL handling
 
@@ -89,20 +73,6 @@ the registry is loaded **only** from the ab-api HTTP endpoint — explicit `VIDE
 remixmate template-registry --list-templates
 ```
 
-### Sync the registry cache (optional, used for offline / LLM prompt)
-
-```bash
-python3 <SkillDir>/scripts/sync_registry.py
-```
-
-`sync_registry.py` and `check_contracts.py` are **maintenance helpers** for template-library, not skill entry points. Keep invoking them directly via `python3`.
-
-### Verify template / Remotion contract consistency
-
-```bash
-python3 <SkillDir>/scripts/check_contracts.py
-```
-
 ### Build a binding locally (debug only, not part of the render pipeline)
 
 ```python
@@ -111,7 +81,7 @@ sys.path.insert(0, "<SkillDir>/scripts")
 from match_template import build_binding, load_full_template, load_registry
 
 dsl = json.load(open("my-video.dsl.json"))
-template = next(t for t in load_registry() if t["templateId"] == "image-slide")
+template = next(t for t in load_registry() if t["templateId"] == "<templateId>")
 binding = build_binding(load_full_template(template), dsl)
 print(json.dumps(binding, ensure_ascii=False, indent=2))
 ```
@@ -135,7 +105,7 @@ A registry row is 4–17 KB of JSON, so dumping every full definition at once ov
 
 ```bash
 remixmate template-registry --list-templates                         # choose
-remixmate template-registry --template-id html-slide --json-output   # then read its contract
+remixmate template-registry --template-id <templateId> --json-output   # then read its contract
 ```
 
 This mirrors the list/detail split described in `scripts/registry_loader.py` (P1.2), realized CLI-side so it holds even while the backend still serves one merged registry payload.
@@ -151,7 +121,7 @@ This mirrors the list/detail split described in `scripts/registry_loader.py` (P1
    - Two forms are supported: `{ from: "textLayers", role: "..." }` matches a textLayer by role; `{ from: "a.b.c" }` reads a value from the scene by dotted path.
 2. **`customPayload` full-field pass-through (no allowlist check)**
    - First `scene.customPayload.templateData.*` is injected; then `scene.customPayload.*` (except `templateData` itself). The latter overrides same-named values from the former, but neither can override fields already produced by propExtractors.
-   - This is the channel for templates such as html-slide that define their own sub-schema and need to pass `slideId` / `items` / `highlightMap`, etc.
+   - This is the channel for templates that define their own sub-schema (multi-layout templates pass `slideId`, their per-layout `templateData`, `highlightMap`, etc.).
    - `scene.templateData` (without the `customPayload` wrapper) is also recognized as a `templateData` source — equivalent shorthand.
    - **Note**: `requiredProps` / `optionalProps` are currently **just template-schema documentation**; they trigger no implicit pass-through. A field reaches `props` either through a propExtractor or through `customPayload`.
 
@@ -165,11 +135,11 @@ This mirrors the list/detail split described in `scripts/registry_loader.py` (P1
 
 **Common pitfall**: writing the same field in both `propExtractors` and `customPayload` — when they collide, `propExtractors` wins. Keep each field in exactly one place. `build_binding` now **detects this**: any prop name that is both declared in `propExtractors` and hit by `customPayload` pass-through (top-level, or `templateData` when the extractor reads from elsewhere) is recorded on the binding row as `dualChannelProps` and printed as a stderr warning; `test-template-pipeline.py` surfaces it as a non-fatal authoring warning. A field placed in its extractor's own declared source (e.g. extractor `from:"templateData.slideId"` + value in `templateData.slideId`) is **not** flagged — that is the legitimate source, not a double-write.
 
-> Historical issue: an early html-slide `point` slot declared `slideId` as `propExtractors.slideId={from:"templateData.slideId"}` and also marked it as `requiredProps`. But every existing DSL wrote `slideId` at `customPayload.slideId` (top-level, not inside templateData), so the propExtractor returned nothing and rendering fell back to the generic layout. The convention now is unified: **slideId flows through customPayload top-level pass-through**, propExtractors no longer declares it. New templates must follow the same convention.
+> Convention: **`slideId` flows through `customPayload` top-level pass-through**; templates do not declare it in `propExtractors`. An earlier template did both, the extractor read `templateData.slideId` while every DSL wrote `customPayload.slideId`, and every scene silently fell back to the generic layout.
 
-## Narration for multi-card scenes (html-slide template)
+## Narration for multi-card scenes (`lineSyncSlides`)
 
-When `html-slide` selects `demo-concept-overview` / `feature-grid` / `timeline` / `column-compare` (all "many-card sequential highlight" slides), you **must** use structured narration to avoid highlight/audio drift:
+A template that highlights cards one by one in step with the narration declares which layouts do so in `lineSyncSlides` (`slideId` → the `templateData` array holding the cards). For those layouts you **must** use structured narration, one line per card, to avoid highlight/audio drift:
 
 ```jsonc
 "audio": {
@@ -189,13 +159,13 @@ When `html-slide` selects `demo-concept-overview` / `feature-grid` / `timeline`
 ```
 
 Rules:
-- `items.length` must equal `customPayload.templateData.<concepts|items>.length` (demo-concept-overview uses `concepts`; the other three slides use `items`), otherwise `dsl_validator` rejects it.
-- Do not write `templateData.highlightMap`; `render_video.py` builds it automatically from the per-line timestamps that TTS returns.
+- `items.length` must equal the length of `customPayload.templateData[lineSyncSlides[slideId]]`, otherwise `dsl_validator` rejects it.
+- Do not write `templateData.highlightMap`; `render_video.py` builds it automatically from the per-line timestamps that TTS returns (capped at the declared card array's length). Template-specific exceptions (e.g. how an `outro` line should map) are in the template's `llmHint`.
 - If the author explicitly provides a `highlightMap`, the system keeps it as-is.
 - The legacy flat `narration.text` form still works but the author then has to keep `highlightMap` in sync with the subtitle segmentation (error-prone, not recommended).
 - `narration.languageBoost` (optional, also accepted at `global.narration`) pins the TTS language hint (`auto` / `Chinese` / `English` / …). Leave it unset unless auto-detection gets it wrong — the service applies its own default, and a scene-level value overrides the global one, exactly like `speed`.
 
-## Image sources (picture-book-en and every other template)
+## Image sources
 
 Image assets support two source forms:
 
@@ -232,16 +202,9 @@ Image assets support two source forms:
 - Local paths (`./image.png`, `/tmp/...`) are forbidden; HTTPS URLs only.
 - Both forms can be mixed inside the same DSL — each asset decides independently.
 
-## Picture-book narration rule (picture-book-en template)
-
-With `picture-book-en`, **narration reads English only, never Chinese**:
+## Template-declared narration and text-layer constraints
 
-- `audio.narration.text` and the corresponding `gen-voice` asset's `payload.text` **must contain only the English source** (ASCII letters + standard English punctuation); any CJK character or Chinese punctuation is forbidden.
-- The Chinese translation appears only on screen via `textLayers[role=subheadline].content` (mapped to `chineseTitle` / `chineseText`); it never enters TTS.
-- Layout is fixed:
-  - **Cover**: top half is the title area (English `englishTitle` on top in a large round-bold font; Chinese `chineseTitle` below in a smaller font); bottom half is the cover image / video.
-  - **Content page**: top half is the text area (English `englishText` on top in a large round-bold font; Chinese `chineseText` below); bottom half is the illustration.
-- `textLayers` role mapping is mandatory: `role=headline` carries the English text, `role=subheadline` carries the Chinese text.
+Some templates constrain what narration or on-screen text may contain — e.g. `capabilities.narrationLanguageStrict` (narration and its `gen-voice` text must be in one language) and `capabilities.textLayerRules` (which `textLayers` roles are required, and in which language). `dsl_validator` enforces the declarations; the template's `llmHint` explains how to write for them.
 
 ## Error handling