@remixmate/cli 0.9.1 → 0.9.6

package/dist/manifest.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
-  "version": "0.9.1",
-  "generatedAt": "2026-06-13T02:35:04.526Z",
+  "version": "0.9.6",
+  "generatedAt": "2026-06-15T14:23:52.383Z",
   "skills": [
     {
       "id": "export-jianying",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remixmate/cli",
-  "version": "0.9.1",
+  "version": "0.9.6",
   "description": "AI media generation skills for Claude Code / Codex — 11 skills covering image, video, voice, digital human, web capture, script, template registry, rendering, Jianying export, and video deconstruction.",
   "type": "module",
   "main": "dist/index.js",

package/skills/export-jianying/SKILL.md

@@ -65,15 +65,21 @@ python3 <SkillDir>/scripts/gen_jianying_draft.py \
 
 ### Read from a RenderPlan file (fallback, single-user / local debugging)
 
-When not using the database mode, read a local `render-plan.json`:
+When not using the database mode, read a local RenderPlan file:
 
 ```bash
 python3 <SkillDir>/scripts/gen_jianying_draft.py \
-  --from-render-plan output/render-plan.json \
+  --from-render-plan <path>.render-plan.json \
   --title "My Video"
 ```
 
-The script automatically extracts the following from `render-plan.json`:
+> ⚠️ Don't point `--from-render-plan` at a shared `output/render-plan.json`. That
+> file is NOT produced by the default token-present pipeline (the plan goes to the
+> DB under a jobId), so anything sitting there is likely a stale leftover from an
+> unrelated run. Prefer the `--from-job-id` DB mode, or render with an explicit
+> `--save-render-plan --render-plan-output <path>` first.
+
+The script automatically extracts the following from the RenderPlan:
 - Each scene's visual asset URL (image / video)
 - TTS audio URL and duration
 - Subtitle text

package/skills/export-jianying/version.json

@@ -2,6 +2,6 @@
   "skillName": "export-jianying",
   "repoName": "agent-skill-media-maker",
   "skillId": "554",
-  "version": "V2",
+  "version": "V3",
   "skillDescription": "剪映草稿生成技能，将素材URL打包为剪映可导入的草稿ZIP，支持从 RenderPlan 自动转换（调用 ab-api /file/generateJianYing）。\n\n当用户提到以下任何需求时，立即使用本 skill：\n- 导出剪映、剪映草稿、打包剪映、导入剪映\n- 将素材导出为剪映格式、生成剪映工程\n- 把视频/图片/音频打包成剪映草稿\n- 从 RenderPlan 导出剪映草稿\n\n即使用户没有明确说「剪映」，只要他们想要将素材打包为可在剪映中编辑的草稿格式，也要使用本 skill。"
 }

package/skills/gen-script/SKILL.md

@@ -126,6 +126,37 @@ The agent should show the following in clear Markdown:
 > Reply "continue" to proceed to template matching, or tell me what to change.
 ```
 
+## Agent behavior: user-supplied media for carousel/image-driven templates (`--carousel-items` / `--caption-lines`)
+
+Some templates are **media-driven, not prompt-driven**: their on-screen content comes entirely from media URLs the user already has, and the skill does **not** generate any image. These are the templates whose `capabilities.payloadStyle` is `carousel-caption` (e.g. `adaptive-image-video`, `spotlight-card`).
+
+For these templates the picture comes from `customPayload.carousel.items`, which is filled **only** from the `--carousel-items` flag. If the user gives you images but you do not pass `--carousel-items`, the carousel is empty and the result is a **black, 2-second clip** (with `durationStrategy: fit-caption`, an empty carousel + empty caption degrades to the 1s headline-intro + 1s tail minimum). `gen_script.py` now hard-fails in this case instead of producing the degenerate video.
+
+### Mandatory behavior
+
+When the user selects a `carousel-caption` template (or any template whose `assetRequirements` is image/video-only and whose `payloadStyle` is `carousel-caption`):
+
+1. **Extract every media URL the user provided** (image or video links in the prompt) and pass each one as a separate `--carousel-items <url>` flag — preserve the user's order, and pass the URLs **verbatim** (do not rewrite host/path/query).
+2. If the user wants on-screen text, pass each caption line as `--caption-lines '<text>'`. For purely visual templates like `adaptive-image-video` (no text, `needsNarration: false`), captions are optional.
+3. **Never call gen_script for a `carousel-caption` template without `--carousel-items`.** If the user picked such a template but provided no media, ask them for the image/video URLs first — do not generate an empty carousel.
+4. Do **not** route these user-provided images through `gen-image`; they are existing assets and go straight into the carousel.
+
+### Command example
+
+User: "用模版 adaptive-image-video 生成视频，图片链接为：https://cdn.example.com/a.jpg，https://cdn.example.com/b.jpg，https://cdn.example.com/c.jpg"
+
+```bash
+python3 <SkillDir>/scripts/gen_script.py \
+  --topic "图片轮播视频" \
+  --template-id adaptive-image-video \
+  --carousel-items "https://cdn.example.com/a.jpg" \
+  --carousel-items "https://cdn.example.com/b.jpg" \
+  --carousel-items "https://cdn.example.com/c.jpg"
+```
+
+This template auto-adapts per-image hold time to the image count (1 image = 8s, 2 = 4s each, 3+ = 3s each), so 3 images yields a ~9s video instead of the 2s black clip.
+
+
 ## Test mode: skip asset generation (`--stub-image-url` / `--stub-video-url`)
 
 **Purpose**: during dev / debug the user wants to exercise the whole pipeline without burning gen-image / gen-video quota. In the DSL this becomes: image / video AssetRefs are written as `source:"existing"` + `status:"generated"` + `url:<stub>`, no `payload.prompt`; the downstream `prepare-video-assets` resolver skips the matching atomic skill.
@@ -228,6 +259,8 @@ python3 <SkillDir>/scripts/gen_script.py \
 | `-o` / `--output` | Output DSL file path. | stdout |
 | `--stub-image-url` | Test mode: every image AssetRef is written as existing + generated + this URL, no prompt (env: `STUB_IMAGE_URL`). | — |
 | `--stub-video-url` | Test mode: every video AssetRef is written as existing + generated + this URL, no prompt (env: `STUB_VIDEO_URL`). | — |
+| `--carousel-items` | Repeatable. Media URL placed directly into `customPayload.carousel.items` for `carousel-caption` templates (e.g. `adaptive-image-video`, `spotlight-card`). Bypasses gen-image. **Required** for `carousel-caption` templates when the user supplies images. | — |
+| `--caption-lines` | Repeatable. On-screen typewriter caption line for `carousel-caption` templates → `customPayload.caption.lines`. Supports `**emphasis**`. Optional for purely visual templates. | — |
 
 ## DSL generation principles
 

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

@@ -56,13 +56,6 @@ try:
 except ImportError:
     _HAS_REGISTRY_LOADER = False
 
-try:
-    # Centralized monorepo-path resolver living in template-registry/scripts/;
-    # the import works because the same sys.path.insert above pointed at it.
-    from template_paths import monorepo_template_src_dir as _monorepo_template_src_dir
-except ImportError:
-    _monorepo_template_src_dir = None
-
 VALID_PLATFORMS = ["douyin", "xiaohongshu", "bilibili", "wechat", "youtube", "generic"]
 VALID_RATIOS = ["16:9", "9:16", "1:1", "4:3", "3:4", "21:9"]
 VALID_PURPOSES = ["opening", "point", "example", "explanation", "highlight", "cta", "ending"]
@@ -419,23 +412,98 @@ def _template_needs_image(template_config: dict | None) -> bool:
 
 
 # ═══════════════════════════════════════════════════════════════════════════════
-# Template-as-Contract: input-schema driven DSL assembly
+# Template-as-Contract: capabilities-driven DSL assembly
 # ═══════════════════════════════════════════════════════════════════════════════
 #
-# 当模板目录下存在 input-schema.json 时，gen_script 用该 schema 动态组装 DSL，
-# 无需为每个模板写 if-else 分支。模板作者只需维护 input-schema.json + dsl-example.json。
+# 模板的所有差异都通过 template.json 的 ``capabilities`` 声明（registry 是单一数据源，
+# 内置模板与个人 OSS 模板同源可达）。gen_script 把 capabilities 归一化成一份 contract，
+# 再用同一条流水线组装 DSL —— 不再有 input-schema.json，也不再有 if template_id==X 分支。
+#
+# 归一化 contract 字段（全部可缺省，缺省值保证"未声明能力"的模板走通用图文旁白）：
+#   - needs_narration   bool         capabilities.needsNarration，默认 True
+#   - scene_strategy    str          capabilities.sceneStrategy ∈ {arc, single, fixed}，默认 arc
+#   - fixed_scenes      list[dict]   capabilities.fixedScenes（single/fixed 用；缺省单 opening）
+#   - payload_style     str          capabilities.payloadStyle ∈ {visual-overlay, slide, carousel-caption}
+#   - duration_strategy str          capabilities.durationStrategy ∈ {explicit, fit-caption}
+#   - payload_defaults  dict         capabilities.payloadDefaults（carousel-caption 的轮播/字幕默认值）
+#   - primary_visual_type / default_layout 由 assetRequirements / capabilities 推导
+
+
+def _resolve_contract(template_config: dict | None) -> dict:
+    """把 template.json 的 capabilities 归一化成一份装配 contract。
+
+    宽容读取：capabilities 缺失 / 非 dict（历史脏数据可能是 ``[]``）一律按"未声明"
+    处理，回退到通用图文旁白（arc + visual-overlay + 旁白开），保证没有声明能力的
+    模板与无模板场景行为一致。
+    """
+    caps = (template_config or {}).get("capabilities")
+    caps = caps if isinstance(caps, dict) else {}
 
+    needs_narration = caps.get("needsNarration", True) is not False
+
+    scene_strategy = caps.get("sceneStrategy")
+    if scene_strategy not in ("arc", "single", "fixed"):
+        scene_strategy = "arc"
+
+    primary_visual_type = _template_primary_visual_type(template_config)
+
+    payload_style = caps.get("payloadStyle")
+    if payload_style not in ("visual-overlay", "slide", "carousel-caption"):
+        payload_style = "slide" if primary_visual_type == "none" else "visual-overlay"
+
+    duration_strategy = caps.get("durationStrategy")
+    if duration_strategy not in ("explicit", "fit-caption"):
+        duration_strategy = "explicit"
+
+    fixed_scenes = caps.get("fixedScenes")
+    if not isinstance(fixed_scenes, list) or not fixed_scenes:
+        # single / fixed 未显式给 fixedScenes 时退化为单 opening 场景
+        fixed_scenes = [{"purpose": "opening"}] if scene_strategy in ("single", "fixed") else []
+
+    payload_defaults = caps.get("payloadDefaults")
+    payload_defaults = payload_defaults if isinstance(payload_defaults, dict) else {}
+
+    return {
+        "needs_narration": needs_narration,
+        "scene_strategy": scene_strategy,
+        "fixed_scenes": fixed_scenes,
+        "payload_style": payload_style,
+        "duration_strategy": duration_strategy,
+        "payload_defaults": payload_defaults,
+        "primary_visual_type": primary_visual_type,
+        "default_layout": caps.get("defaultLayout"),
+    }
 
-def _locate_template_dir(template_id: str) -> str | None:
-    """定位模板源码目录（template-library/packages/templates/src/<id>/）。
 
-    路径解析已集中到 ``template_paths.monorepo_template_src_dir``；
-    当 helper 不可用（template-registry/scripts/ 不在 sys.path）时回退到 None,
-    与原始函数"找不到就返回 None"的语义一致。
+def _plan_contract_scenes(
+    contract: dict, topic: str, duration: int, scene_count: int | None, language: str
+) -> list:
+    """按 contract.scene_strategy 规划场景列表。
+
+      - arc    : 沿用 plan_scenes 叙事弧（opening → point* → cta，最少 3 段）。
+      - single : 单场景（默认 opening），整段时长归一个场景。
+      - fixed  : 按 capabilities.fixedScenes 顺序展开，时长均分。
+
+    single / fixed 完全绕开 arc 的"最少 3 段"下限 —— 单图 Ken Burns / 打字机卡片
+    这类模板由此能产出真正的单场景，而不再被强行补到 3 段。``--scenes`` 只对 arc 生效。
     """
-    if _monorepo_template_src_dir is None:
-        return None
-    return _monorepo_template_src_dir(template_id)
+    if contract["scene_strategy"] == "arc":
+        return plan_scenes(topic, duration, scene_count, False, language=language)
+
+    fixed = contract["fixed_scenes"] or [{"purpose": "opening"}]
+    n = len(fixed)
+    per = max(1, round(duration / n))
+    plans = []
+    for i, fs in enumerate(fixed):
+        purpose = fs.get("purpose", "opening") if isinstance(fs, dict) else "opening"
+        if purpose == "opening":
+            label = _localize_label(language, "label_opening")
+        elif purpose == "cta":
+            label = _localize_label(language, "label_cta")
+        else:
+            label = _localize_label(language, "label_point", n=i)
+        plans.append({"purpose": purpose, "duration": per, "label": label})
+    return plans
 
 
 def _plain_len(text: str) -> int:
@@ -503,27 +571,9 @@ def _estimate_fit_caption_duration(custom_payload: dict) -> float:
     return recommended
 
 
-def _load_input_schema(template_id: str) -> dict | None:
-    """Load input-schema.json for a template. Returns None if not found."""
-    tpl_dir = _locate_template_dir(template_id)
-    if not tpl_dir:
-        return None
-    schema_file = os.path.join(tpl_dir, "input-schema.json")
-    if not os.path.isfile(schema_file):
-        return None
-    try:
-        with open(schema_file, "r", encoding="utf-8") as f:
-            return json.load(f)
-    except (OSError, json.JSONDecodeError) as exc:
-        print(f"⚠️  failed to load input-schema.json for {template_id}: {exc}", file=sys.stderr)
-        return None
-
-
-def _build_dsl_from_input_schema(
+def _build_carousel_caption_dsl(
     *,
     template_id: str,
-    template_config: dict,
-    input_schema: dict,
     topic: str,
     headline: str,
     subheadline: str,
@@ -534,22 +584,19 @@ def _build_dsl_from_input_schema(
     style: str,
     ratio: str,
     resolution: str,
-    voice_id: str,
     output_language: str,
     resolved_voice_id: str,
+    narration_enabled: bool,
+    payload_defaults: dict,
+    duration_strategy: str | None,
 ) -> dict:
-    """Schema-driven DSL assembly.
+    """carousel-caption 装配（spotlight-card 类：单场景、图/视频轮播 + 打字机）。
 
-    Uses the template's input-schema.json + defaults to build a complete DSL
-    with the correct customPayload structure. No template-specific if-else.
+    所有差异来自归一化 contract（capabilities.payloadDefaults / durationStrategy /
+    needsNarration），不再读 input-schema.json，也没有 if template_id==X 分支。
+    轮播素材由调用方在 carousel_items 里直接给 URL（existing 资产），不触发 AI 生图。
     """
-    defaults = input_schema.get("defaults", {})
-
-    # 旁白开关：部分模板（如 spotlight-card）是打字机 / 画面驱动，刻意无配音。
-    # 由 input-schema.json 的 narration.enabled 声明，缺省 True 保持其它 schema
-    # 模板的向后兼容。关闭时不产出 gen-voice 音频资产，scene 也不带 audio.narration，
-    # 这样 prepare_video_assets 不会触发 TTS、render_video 也不会按 TTS 拉长场景时长。
-    narration_enabled = bool(input_schema.get("narration", {}).get("enabled", True))
+    defaults = payload_defaults or {}
 
     # ── Build assets from carousel_items ──────────────────────────────────
     assets = []
@@ -620,15 +667,9 @@ def _build_dsl_from_input_schema(
                                      label="", topic=topic, duration=duration)
 
     # ── Effective scene duration ──────────────────────────────────────────
-    # fit-caption 策略（input-schema.sceneStrategy.fixedScenes[].durationStrategy）：
-    # 时长由打字机自然节奏决定，而不是盲取调用方传入的 targetDuration。
+    # fit-caption 策略：时长由打字机自然节奏决定，而不是盲取调用方传入的 targetDuration。
     # 这是 spotlight-card 这类打字机/画面驱动模板的核心——没有旁白来"撑"时长，
     # 必须由 caption 自己定，否则文字打完后画面会静止到 targetDuration。
-    scene_strategy = input_schema.get("sceneStrategy", {})
-    fixed_scenes = scene_strategy.get("fixedScenes", [])
-    duration_strategy = (
-        fixed_scenes[0].get("durationStrategy") if fixed_scenes else None
-    )
     effective_duration = duration
     if duration_strategy == "fit-caption":
         est = _estimate_fit_caption_duration(custom_payload)
@@ -754,9 +795,9 @@ def build_dsl(
     When template_id is provided, loads the template config and adapts the DSL
     structure to match the template's assetRequirements and scene patterns.
 
-    If the template has an input-schema.json AND the caller provides structured
-    inputs (carousel_items / caption_lines), the schema-driven assembly path is
-    used — producing a template-native DSL without any template-specific if-else.
+    模板差异全部来自归一化 contract（capabilities）：payloadStyle=carousel-caption
+    走单场景轮播+打字机装配；其余按 sceneStrategy（arc/single/fixed）+ visual-overlay/
+    slide 走统一场景循环。无 input-schema.json、无 if template_id==X 分支。
 
     headline / subheadline 让作者显式提供画面上的"短主标题 + 副标题"。
     DSL 元字段命名约定：
@@ -767,51 +808,17 @@ def build_dsl(
     注意：subtitle（CC 字幕）由 global.subtitle 与 render-plan.subtitleSegments
     单独承载，与 subheadline 完全是两个东西，命名上刻意分开避免歧义。
     """
-    # Load template config to determine asset requirements
+    # Load template config（registry 单一数据源）→ 归一化 contract
     template_config = _load_template_config(template_id) if template_id else None
+    contract = _resolve_contract(template_config)
 
-    # ── Schema-driven path: if input-schema.json exists AND structured inputs provided ──
-    if template_id and (carousel_items or caption_lines):
-        input_schema = _load_input_schema(template_id)
-        if input_schema and template_config:
-            # Resolve language + voice (same logic as generic path)
-            output_language, template_default_voice_id = _resolve_template_language_meta(template_config)
-            resolved_voice_id = _resolve_voice_id(voice_id, template_default_voice_id, output_language)
-            if resolved_voice_id != voice_id:
-                print(
-                    f"ℹ️  voice resolution: cli={voice_id!r} → resolved={resolved_voice_id!r} "
-                    f"(templateDefault={template_default_voice_id!r}, language={output_language})",
-                    file=sys.stderr,
-                )
-            effective_headline = (headline or "").strip() or topic
-            effective_subheadline = (subheadline or "").strip()
-            print(
-                f"ℹ️  using input-schema driven assembly for template {template_id}",
-                file=sys.stderr,
-            )
-            return _build_dsl_from_input_schema(
-                template_id=template_id,
-                template_config=template_config,
-                input_schema=input_schema,
-                topic=topic,
-                headline=effective_headline,
-                subheadline=effective_subheadline,
-                carousel_items=carousel_items or [],
-                caption_lines=caption_lines or [],
-                duration=duration,
-                platform=platform,
-                style=style,
-                ratio=ratio,
-                resolution=resolution,
-                voice_id=voice_id,
-                output_language=output_language,
-                resolved_voice_id=resolved_voice_id,
-            )
-    primary_visual_type = _template_primary_visual_type(template_config)
-    has_visual = primary_visual_type in ("image", "video")
+    primary_visual_type = contract["primary_visual_type"]
+    payload_style = contract["payload_style"]
+    # visual-overlay 模板才生成视觉素材并用 visuals.background；slide / carousel-caption 不走。
+    has_visual = payload_style == "visual-overlay"
     # 旁白是模板能力（capabilities.needsNarration）。声明为 false 的模板（纯视觉 /
     # BGM-only，如单图 Ken Burns）不分配 gen-voice 素材、场景不写 audio.narration。
-    needs_narration = _template_needs_narration(template_config)
+    needs_narration = contract["needs_narration"]
 
     # ── Resolve template-driven output language + voice ────────────────────
     # outputLanguage is owned by the template (template.json). Missing/invalid
@@ -825,11 +832,56 @@ def build_dsl(
             file=sys.stderr,
         )
 
-    # 缺省值：headline 退回 topic（向后兼容），subheadline 默认空字符串
+    # 缺省值：headline 退回 topic，subheadline 默认空字符串
     effective_headline = (headline or "").strip() or topic
     effective_subheadline = (subheadline or "").strip()
 
-    scene_plans = plan_scenes(topic, duration, scene_count, allow_digital_human, language=output_language)
+    # ── carousel-caption 模板（单场景、图/视频轮播 + 打字机）单独装配并直接返回 ──
+    if payload_style == "carousel-caption":
+        print(
+            f"ℹ️  contract: payloadStyle=carousel-caption for template {template_id}",
+            file=sys.stderr,
+        )
+        # 兜底校验：carousel-caption 模板的画面由 carousel_items（图片/视频 URL）驱动，
+        # 文字由 caption_lines 驱动。两者皆空时会生成一个空轮播 + 空字幕的退化场景——
+        # 渲染出来就是「黑屏 + fit-caption 退化成最短 2s」。这是调用方（agent）忘了
+        # 把用户提供的图片塞进 --carousel-items 的典型表现，必须显式报错而不是静默产出。
+        if not (carousel_items or []) and not (caption_lines or []):
+            print(
+                "❌ carousel-caption template "
+                f"'{template_id}' needs visual or text content, but received neither "
+                "--carousel-items nor --caption-lines.\n"
+                "   This template renders a carousel of user-supplied media; with no items "
+                "it produces a black, minimum-length (2s) clip.\n"
+                "   Fix: pass the user's image/video URLs via --carousel-items "
+                "(repeat the flag per item), e.g.\n"
+                "     gen_script.py --topic <topic> --template-id "
+                f"{template_id} --carousel-items <url1> --carousel-items <url2> ...\n"
+                "   Optionally add --caption-lines '<text>' for on-screen typewriter captions.",
+                file=sys.stderr,
+            )
+            sys.exit(1)
+        return _build_carousel_caption_dsl(
+            template_id=template_id,
+            topic=topic,
+            headline=effective_headline,
+            subheadline=effective_subheadline,
+            carousel_items=carousel_items or [],
+            caption_lines=caption_lines or [],
+            duration=duration,
+            platform=platform,
+            style=style,
+            ratio=ratio,
+            resolution=resolution,
+            output_language=output_language,
+            resolved_voice_id=resolved_voice_id,
+            narration_enabled=needs_narration,
+            payload_defaults=contract["payload_defaults"],
+            duration_strategy=contract["duration_strategy"],
+        )
+
+    # ── 其余模板：统一场景规划（arc 叙事弧 / single / fixed）+ 统一装配循环 ──────
+    scene_plans = _plan_contract_scenes(contract, topic, duration, scene_count, output_language)
 
     assets = []
     scenes = []
@@ -847,8 +899,8 @@ def build_dsl(
             if needs_narration else ""
         )
 
-        # 根据模板 assetRequirements 生成对应类型的视觉素材
-        if primary_visual_type == "image":
+        # 仅 visual-overlay 模板生成视觉素材（slide 无视觉素材，carousel-caption 已提前返回）
+        if has_visual and primary_visual_type == "image":
             if stub_image_url:
                 assets.append({
                     "assetId": visual_asset_id,
@@ -877,7 +929,7 @@ def build_dsl(
                     "status": "planned",
                     "payload": img_payload,
                 })
-        elif primary_visual_type == "video":
+        elif has_visual and primary_visual_type == "video":
             if stub_video_url:
                 assets.append({
                     "assetId": visual_asset_id,
@@ -1036,8 +1088,10 @@ def build_dsl(
             "aspectRatio": ratio,
             "resolution": resolution,
             "fps": 30,
+            # 无配音模板：关闭 CC 字幕（字幕段是 narration→TTS 的派生物），并省略
+            # global.narration，避免下游误判存在旁白。
             "subtitle": {"enabled": needs_narration, "style": "bottom"},
-            "narration": {"voiceId": resolved_voice_id, "speed": 1.0},
+            **({"narration": {"voiceId": resolved_voice_id, "speed": 1.0}} if needs_narration else {}),
             "bgm": {"enabled": True, "volume": 0.12},
         },
         "assets": assets,
@@ -1110,9 +1164,9 @@ Examples:
         default=None,
         help="Media URL for the template's carousel/gallery. Can be repeated: "
              "--carousel-items url1 --carousel-items url2. "
-             "For templates with input-schema.json (e.g. spotlight-card), these URLs "
-             "are placed directly into customPayload.carousel.items as existing assets, "
-             "bypassing AI image generation entirely.",
+             "For carousel-caption templates (capabilities.payloadStyle=carousel-caption, "
+             "e.g. spotlight-card), these URLs are placed directly into "
+             "customPayload.carousel.items as existing assets, bypassing AI image generation entirely.",
     )
     parser.add_argument(
         "--caption-lines",
@@ -1120,8 +1174,9 @@ Examples:
         default=None,
         help="Bottom typewriter text line. Can be repeated: "
              "--caption-lines 'line1' --caption-lines 'line2'. "
-             "For templates with input-schema.json (e.g. spotlight-card), these are placed "
-             "into customPayload.caption.lines. Supports **emphasis** syntax.",
+             "For carousel-caption templates (capabilities.payloadStyle=carousel-caption, "
+             "e.g. spotlight-card), these are placed into customPayload.caption.lines. "
+             "Supports **emphasis** syntax.",
     )
 
     args = parser.parse_args()

package/skills/gen-script/skill.json

@@ -27,7 +27,7 @@
       "carousel_items": {
         "type": "array",
         "items": { "type": "string" },
-        "description": "Media URLs for the template's image/video carousel (e.g. spotlight-card's middle carousel). When provided together with a template_id that has an input-schema.json, these URLs are placed directly into customPayload.carousel.items as existing assets — NO AI image generation is triggered. **Must** pass when the user explicitly provides image/video URLs for carousel-style templates (spotlight-card, etc.). Each element is a full URL string."
+        "description": "Media URLs for the template's image/video carousel (e.g. spotlight-card's middle carousel). When provided together with a template_id whose capabilities.payloadStyle=carousel-caption, these URLs are placed directly into customPayload.carousel.items as existing assets — NO AI image generation is triggered. **Must** pass when the user explicitly provides image/video URLs for carousel-style templates (spotlight-card, etc.). Each element is a full URL string."
       },
       "caption_lines": {
         "type": "array",

package/skills/gen-script/version.json

@@ -2,6 +2,6 @@
   "skillName": "gen-script",
   "repoName": "agent-skill-media-maker",
   "skillId": "474",
-  "version": "V10",
+  "version": "V11",
   "skillDescription": "视频脚本生成技能，将用户主题转化为结构化 Video DSL（JSON），描述视频的完整结构、素材需求与叙事逻辑。\n\n当用户提到以下任何需求时，立即使用本 skill：\n- 帮我写视频脚本、生成视频脚本、视频策划、写分镜脚本\n- 做一个短视频、帮我规划视频内容、生成视频 DSL\n- 把主题转成视频结构、视频内容规划\n\n即使用户没有明确说「生成 DSL」，只要他们想要把一个主题变成视频内容结构，也要使用本 skill。"
 }

package/skills/render-video/SKILL.md

@@ -73,9 +73,28 @@ python3 <SkillDir>/scripts/render_video.py --job-id <jobId>
 When the DB is unavailable, the script accepts a pre-generated RenderPlan file:
 
 ```bash
-python3 <SkillDir>/scripts/render_video.py --render-plan output/render-plan.json
+python3 <SkillDir>/scripts/render_video.py --render-plan <path>.render-plan.json
 ```
 
+> ⚠️ **Do NOT blindly point `--render-plan` at a shared `output/render-plan.json`.**
+> Under the default token-present path, `prepare_video_assets` / `render_video`
+> persist the plan to the **database (jobId)** only — they do **not** write
+> `output/render-plan.json`. Any file sitting there is likely a leftover from a
+> previous, unrelated run (the `output/` dir is gitignored scratch), and rendering
+> it silently produces the wrong video.
+>
+> To get a RenderPlan file on disk, generate it explicitly:
+> ```bash
+> python3 <SkillDir>/scripts/render_video.py --dsl video.dsl.json --template-id <id> \
+>   --resolve-only --save-render-plan --render-plan-output video.render-plan.json
+> ```
+> Or skip the file entirely and render in one shot:
+> `render_video.py --dsl video.dsl.json --template-id <id>`.
+>
+> On load, the script now prints a `↳ plan: templateId=… composition=… duration=… title=…`
+> summary, and warns if the plan file is older than a `--dsl` you also passed —
+> check that line matches what you intend before the render proceeds.
+
 ### Render and upload to Alibaba Cloud OSS (default behavior)
 
 ```bash

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

@@ -1856,6 +1856,35 @@ def auto_bind_template(dsl: dict, template_id: str) -> dict:
     return binding
 
 
+def _log_render_plan_summary(render_plan: dict) -> None:
+    """Print a one-line identity summary of a loaded RenderPlan.
+
+    The two ways to feed an existing plan (``--render-plan <file>`` and
+    ``--job-id <int>``) used to print only the *source* (path / id), never the
+    *content*. When a stale ``output/render-plan.json`` from a previous, unrelated
+    run got picked up, the mismatch was rendered silently. Surfacing
+    templateId / title / duration / scene count here makes a wrong plan obvious
+    at a glance before any render time is spent.
+    """
+    try:
+        template_id = render_plan.get("templateId", "?")
+        title = render_plan.get("title", "")
+        cfg = render_plan.get("renderConfig", {}) or {}
+        fps = cfg.get("fps") or 30
+        total_frames = cfg.get("totalFrames")
+        scenes = len(render_plan.get("timeline", []) or [])
+        comp = (render_plan.get("remotionProps", {}) or {}).get("compositionId", "?")
+        dur = f"{total_frames / fps:.1f}s/{total_frames}f" if total_frames else "?"
+        LogPrint(
+            f"   ↳ plan: templateId={template_id} composition={comp} "
+            f"duration={dur} scenes={scenes}" + (f' title=\"{title}\"' if title else ""),
+            file=sys.stderr,
+        )
+    except Exception:
+        # A summary is a convenience, never a hard dependency of rendering.
+        pass
+
+
 def main():
     parser = argparse.ArgumentParser(
         description="Video render tool — DSL + TemplateBinding → Remotion video.",
@@ -1944,12 +1973,30 @@ Examples:
             sys.exit(1)
         render_plan = json.loads(render_plan_str)
         LogPrint(f"✅ RenderPlan loaded (jobId={args.job_id})", file=sys.stderr)
+        _log_render_plan_summary(render_plan)
     elif args.render_plan:
         if not os.path.exists(args.render_plan):
             LogPrint(f"❌ file does not exist: {args.render_plan}", file=sys.stderr)
             sys.exit(1)
         render_plan = load_json(args.render_plan)
         LogPrint(f"📋 loaded existing RenderPlan: {args.render_plan}", file=sys.stderr)
+        _log_render_plan_summary(render_plan)
+        # 陈旧文件防护：output/render-plan.json 等共享文件名常被上一次别的项目
+        # 的运行残留覆盖（output/ 是 gitignored 调试目录）。当用户同时给了 --dsl
+        # 用以表明"我想渲这个 DSL"，但磁盘上的 plan 比 DSL 还旧时，几乎可以肯定
+        # 加载到的是过期 plan —— 明确警告而不是静默渲染错的东西。
+        if args.dsl and os.path.exists(args.dsl):
+            try:
+                if os.path.getmtime(args.render_plan) < os.path.getmtime(args.dsl):
+                    LogPrint(
+                        f"⚠️  STALE RenderPlan? '{args.render_plan}' is OLDER than the DSL "
+                        f"'{args.dsl}'. You may be rendering a leftover plan from a previous "
+                        "run. Regenerate with --dsl ... --template-id ... (drop --render-plan) "
+                        "if the summary above doesn't match what you expect.",
+                        file=sys.stderr,
+                    )
+            except OSError:
+                pass
     else:
         if not args.dsl and not args.dsl_json:
             LogPrint(

package/skills/render-video/version.json

@@ -2,6 +2,6 @@
   "skillName": "render-video",
   "repoName": "agent-skill-media-maker",
   "skillId": "473",
-  "version": "V18",
+  "version": "V19",
   "skillDescription": "Final-render skill (Phase 3 of the two-phase video pipeline). Loads a persisted RenderPlan by job_id and drives Remotion to produce the final video. Assets must already be generated via prepare_video_assets."
 }