@remixmate/cli 0.9.24 → 0.9.25

package/dist/manifest.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
-  "version": "0.9.24",
-  "generatedAt": "2026-09-07T14:49:54.095Z",
+  "version": "0.9.25",
+  "generatedAt": "2026-09-08T15:32:17.519Z",
   "skills": [
     {
       "id": "export-jianying",
@@ -401,6 +401,13 @@
             },
             "description": "Media URLs for the template's image/video 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 such a template. Each element is a full URL string."
           },
+          "scene_images": {
+            "type": "array",
+            "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."
+          },
           "caption_lines": {
             "type": "array",
             "items": {
@@ -441,6 +448,7 @@
           "headline",
           "subheadline",
           "carousel_items",
+          "scene_images",
           "caption_lines",
           "stub_image_url",
           "stub_video_url",

package/package.json

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

package/skills/gen-script/SKILL.md

@@ -200,6 +200,110 @@ python3 <SkillDir>/scripts/gen_script.py \
 Every URL the user gave becomes one carousel item, in order. How long each item holds is the template's business — `fit-images` templates derive it from the item count, `fit-caption` templates from `capabilities.durationModel`; either way you pass the URLs and let the template decide.
 
 
+## Agent behavior: user-supplied images for scene-based templates (`--scene-images`)
+
+The section above covers `carousel-caption` templates. Templates whose `payloadStyle` is
+`visual-overlay` (image-slide and friends) have **real scenes**, each with its own background
+image and its own narration — for those, user-supplied images go through `--scene-images`,
+not `--carousel-items`.
+
+Without this flag the user's images are **ignored entirely** and every scene gets an
+AI-generated picture. That failure is quiet: the video renders fine, it just isn't made of
+the material the user handed you.
+
+### The mapping rule (positional, then AI fills the rest)
+
+Each entry is one scene's visual, and it is either a **URL** (use that existing asset) or the
+literal **`ai`** / **`ai:<prompt>`** (leave that scene to gen-image). Entry i is scene i;
+scenes past the last entry still get a generated image.
+
+```
+--scene-images A --scene-images B          →  scene 1: A, scene 2: B, scene 3+: AI-generated
+--scene-images A --scene-images ai:机房 …  →  scene 1: A, scene 2: AI with the user's prompt
+```
+
+Three consequences worth internalising:
+
+- **Two images still produce a full video.** Do not ask the user to "provide enough images"
+  or pad the list; partial input is the designed case.
+- **Order is meaning, not layout.** Pass the entries in the order the user gave them — an AI
+  scene can sit *between* two of their images, and that placement is the point.
+- **`ai:<prompt>` is the user's own image prompt for that one scene.** Pass it through
+  verbatim; do not rewrite it, and do not apply it to the other scenes. It replaces the
+  prompt that would have been derived from the template, but the template's negative prompt
+  still applies.
+
+When `--scenes` is absent the scene count is **raised, never lowered**, to fit the images:
+more images than the planned scene count grows the plan so none are dropped, but fewer images
+does **not** shrink it — handing over 2 images should not turn a 30s five-scene video into a
+three-scene one. If the template's scene count is fixed (`sceneStrategy: single` / `fixed`)
+and there are still more images than scenes, `gen_script.py` prints a warning naming how many
+went unused — surface that to the user instead of pretending everything was used.
+
+### Reading the image descriptions
+
+Asset lines in the user's message carry a **`desc:` field** describing what is in the picture:
+
+```
+![4519.png](https://cdn.example.com/4519.png) (1920×1080, desc: 一个人背对镜头站在雾中的松林里)
+```
+
+`desc:` is always the **last** item in the metadata parentheses, so everything from `desc:` to
+the closing paren is the description — commas inside it are part of the text.
+
+**Use it when writing narration.** This is the whole point of the field: for a
+`visual-overlay` template you are writing the words that play over *that* picture, and the
+description is the only thing telling you what the viewer will see. Narration that contradicts
+the image is the most visible way this pipeline fails.
+
+Two things `desc:` is **not**:
+
+- It is **not an image-generation prompt.** The asset already exists; never route it through
+  `gen-image`, and never "improve" the picture to match the text.
+- It is **not a headline.** Do not copy it onto the screen as `--headline` /
+  `--subheadline`; it is input for you, not on-screen copy.
+
+A line with no `desc:` simply has no description — do not treat the file name in the alt text
+(`4519.png`) as one.
+
+### Reading `ai:` lines
+
+A line in the asset list may be an **AI scene** rather than an asset:
+
+```
+![a.png](https://cdn.example.com/a.png) (1920×1080, desc: 终端里正在跑安装命令的截图)
+ai: 赛博朋克风格的服务器机房
+![b.png](https://cdn.example.com/b.png) (1920×1080)
+```
+
+That is the user saying "scene 2 is AI-generated, and here is what I want in it". Pass it
+straight through as the second `--scene-images` entry (`ai: 赛博朋克风格的服务器机房`),
+keeping the position. A bare `ai:` with no text means "this scene is AI-generated, you decide
+what it shows" — still pass it, as `ai`, so the position is preserved.
+
+Note the two are different fields on purpose: `desc:` describes an image that **already
+exists** (input for your narration), `ai:` prescribes an image that **does not exist yet**
+(input for gen-image). Never feed a `desc:` into gen-image, and never write narration that
+describes an `ai:` prompt as if it were a picture you have seen.
+
+### Command example
+
+User: "用 image-slide 做一条讲 RAG 的视频，配图用这两张"
++ two asset lines with `desc:`
+
+```bash
+python3 <SkillDir>/scripts/gen_script.py \
+  --topic "三分钟看懂 RAG" \
+  --template-id image-slide \
+  --scene-images "https://cdn.example.com/a.png" \
+  --scene-images "ai: 赛博朋克风格的服务器机房" \
+  --scene-images "https://cdn.example.com/b.png"
+```
+
+Then write each scene's narration against that scene's image description, and pass the
+narration through `prepare_video_assets`'s `dsl_json` as usual.
+
+
 ## 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.
@@ -305,6 +409,7 @@ python3 <SkillDir>/scripts/gen_script.py \
 | `--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. Bypasses gen-image. **Required** for `carousel-caption` templates when the user supplies images. | — |
+| `--scene-images` | Repeatable. One scene's visual for a **`visual-overlay`** template (image-slide etc.), mapped **positionally**. Each entry is a URL (that existing asset) or `ai` / `ai:<prompt>` (that scene goes to gen-image, optionally with the user's own prompt) — so an AI scene can sit anywhere in the order. Scenes past the last entry still get AI images. Scene count is raised (never lowered) to fit the entries when `--scenes` is absent. **Required** whenever the user supplies images for such a template — omitting it silently ignores every image they gave. | — |
 | `--caption-lines` | Repeatable. On-screen caption line for `carousel-caption` templates → `customPayload.caption.lines`. Line limits and `**emphasis**` support are declared per template (see its `llmHint`). **Required** for `durationStrategy: fit-caption` templates — write the lines yourself if the user did not supply them. Optional only for `fit-images` templates. | — |
 
 ## DSL generation principles

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

@@ -313,6 +313,27 @@ def generate_image_prompt(
     return {"prompt": prompts.get(purpose, f"{topic}相关配图{style_suffix}")}
 
 
+def _parse_ai_slot(slot: str) -> tuple[bool, str]:
+    """解析 --scene-images 的一项：是不是 AI 段，以及用户给的提示词。
+
+    返回 ``(is_ai, prompt)``：
+
+      - ``"https://…/a.png"`` → ``(False, "")``  用已有素材
+      - ``"ai"``              → ``(True, "")``   这一段交给 gen-image，提示词由模板推
+      - ``"ai: 深色调机房"``   → ``(True, "深色调机房")``
+
+    大小写不敏感。判定刻意收得很紧（整项等于 ``ai``，或以 ``ai:`` 开头）：URL 才是这个
+    参数的常态，把 ``ai`` 判宽了会让 ``https://ai.example.com/x.png`` 这种正常地址被
+    误当成"生成一段"，用户的图就此消失。
+    """
+    text = (slot or "").strip()
+    if text.lower() == "ai":
+        return True, ""
+    if text[:3].lower() == "ai:":
+        return True, text[3:].strip()
+    return False, ""
+
+
 def _load_template_config(template_id: str) -> dict | None:
     """Load template definition for the given template ID.
 
@@ -947,6 +968,7 @@ def build_dsl(
         subheadline: str | None = None,
         carousel_items: list[str] | None = None,
         caption_lines: list[str] | None = None,
+        scene_images: list[str] | None = None,
 ) -> dict:
     """Build a complete Video DSL JSON.
 
@@ -965,6 +987,11 @@ def build_dsl(
     通过 role=headline / role=subheadline 抽出对应的 props（如 titleText / projectName）。
     注意：subtitle（CC 字幕）由 global.subtitle 与 render-plan.subtitleSegments
     单独承载，与 subheadline 完全是两个东西，命名上刻意分开避免歧义。
+
+    scene_images 是用户**自带的配图**（visual-overlay 模板专用），按顺序占位：第 i 张
+    图给第 i 个场景，没被占到的场景照常走 gen-image 补图。这条规则不是随便定的——
+    见 docs/asset-annotation-design.md §6：另外两种立场（模型自由挑选 / 严格一一对应）
+    都会让"只传两张图"要么失去可预期性，要么直接跑不通。
     """
     # Load template config（registry 单一数据源）→ 归一化 contract
     template_config = _load_template_config(template_id) if template_id else None
@@ -1071,8 +1098,45 @@ def build_dsl(
         return carousel_dsl
 
     # ── 其余模板：统一场景规划（arc 叙事弧 / single / fixed）+ 统一装配循环 ──────
+    #
+    # scene_images 的每一项要么是一条 URL（用已有素材），要么是 `ai` / `ai:<提示词>`
+    # （这一段留给 gen-image）。两者共用同一个位置序列 —— 用户在界面上排出来的顺序
+    # 就是它，AI 段能插在任意位置，而不是只能挂在末尾。
+    provided_slots = [s.strip() for s in (scene_images or []) if s and s.strip()]
+
     scene_plans = _plan_contract_scenes(contract, topic, duration, scene_count, output_language)
 
+    # 条目比场景多时**抬高**场景数，让每一条都有地方放。
+    #
+    # 只抬高、不压低：给 2 张图不该把一条 30s 的片子从 5 段压成 3 段。用户给图表达的是
+    # "这几张都要用上"，不是"整条片子改成这么多段"——按条目数直接改写场景数，会让
+    # "多传了两张图"变成"视频结构被换掉了"，而他根本没要求这个。
+    #
+    # 反过来条目多于场景时必须抬：不抬的话第 N+1 条之后会被静默丢掉，而用户在成片里是
+    # 看不出"我的图去哪了"的。arc 之外的策略场景数由模板钉死，抬不动（下面警告兜底）。
+    if (
+        provided_slots
+        and scene_count is None
+        and contract["scene_strategy"] == "arc"
+        and primary_visual_type == "image"
+        and has_visual
+        and len(provided_slots) > len(scene_plans)
+    ):
+        scene_plans = _plan_contract_scenes(
+            contract, topic, duration, len(provided_slots), output_language
+        )
+
+    # 排完之后仍然装不下的（single / fixed 模板，或用户显式指定了更少的场景数）就明说。
+    # 静默丢弃用户自带的素材是这条链上最难被发现的一类错。
+    if provided_slots and len(provided_slots) > len(scene_plans):
+        print(
+            f"\u26a0\ufe0f  {len(provided_slots)} scene-image entries provided but the template "
+            f"plans only {len(scene_plans)} scene(s); the extra "
+            f"{len(provided_slots) - len(scene_plans)} will not be used. "
+            f"Raise --scenes or pick a template with more scenes.",
+            file=sys.stderr,
+        )
+
     assets = []
     scenes = []
 
@@ -1091,7 +1155,22 @@ def build_dsl(
 
         # 仅 visual-overlay 模板生成视觉素材（slide 无视觉素材，carousel-caption 已提前返回）
         if has_visual and primary_visual_type == "image":
-            if stub_image_url:
+            slot = provided_slots[idx] if idx < len(provided_slots) else ""
+            slot_is_ai, slot_prompt = _parse_ai_slot(slot)
+            if slot and not slot_is_ai:
+                # 用户自带的图排在 stub 之前：stub 是"别烧配额"的测试开关，而用户给的
+                # 图同样一分钱不花，没有理由拿占位图把真素材盖掉。
+                assets.append({
+                    "assetId": visual_asset_id,
+                    "type": "image",
+                    "source": "existing",
+                    "status": "generated",
+                    "url": slot,
+                })
+            # stub 盖得住 AI 段，盖不住用户自带的图。差别在于花不花钱：--stub-image-url
+            # 的全部意义就是"这一趟别调 gen-image"，而 AI 段恰恰是要调的那种；反过来
+            # 用户自带的 URL 一分钱不花，拿占位图把真素材盖掉纯属损失。
+            elif stub_image_url:
                 assets.append({
                     "assetId": visual_asset_id,
                     "type": "image",
@@ -1102,6 +1181,13 @@ def build_dsl(
             else:
                 image_result = generate_image_prompt(plan["purpose"], topic, style, narration_text=narration_text)
 
+                # 用户在 AI 段里写了提示词就用他的。**只替换主体，不动 negativePrompt /
+                # guidanceScale**：那两项是模板的护栏（"不要文字水印、不要变形"），把它们
+                # 一起丢掉会让用户随手写的一句话换来一张带乱码文字的图，而他并没有要求
+                # 关掉护栏——他只是想说这一段画什么。
+                if slot_prompt:
+                    image_result = {**image_result, "prompt": slot_prompt}
+
                 img_payload = {
                     "prompt": image_result["prompt"],
                     "model": os.environ.get("DEFAULT_IMAGE_MODEL", "doubao/doubao-seedream-5-0-260128"),
@@ -1383,6 +1469,20 @@ Examples:
              "these URLs are placed directly into "
              "customPayload.carousel.items as existing assets, bypassing AI image generation entirely.",
     )
+    parser.add_argument(
+        "--scene-images",
+        action="append",
+        default=None,
+        help="One scene's visual for a visual-overlay template (image-slide etc.). "
+             "Can be repeated: --scene-images url1 --scene-images ai --scene-images url2. "
+             "Each entry is either a URL (use that existing asset) or the literal 'ai' / "
+             "'ai:<prompt>' (leave this scene to gen-image, optionally with the user's prompt). "
+             "Mapping is POSITIONAL: the i-th entry is the i-th scene's background, so an AI "
+             "scene can sit anywhere in the order, not just at the end; scenes past the last "
+             "entry still get an AI-generated image. When --scenes is not given the scene count "
+             "is raised (never lowered) to fit the entries. "
+             "Not for carousel-caption templates — those take --carousel-items instead.",
+    )
     parser.add_argument(
         "--caption-lines",
         action="append",
@@ -1504,6 +1604,7 @@ Examples:
         subheadline=args.subheadline,
         carousel_items=args.carousel_items,
         caption_lines=args.caption_lines,
+        scene_images=args.scene_images,
     )
 
     # Post-process for --skip-asset-generation: rewrite all gen-voice / gen-digital-human

package/skills/gen-script/skill.json

@@ -71,6 +71,13 @@
         },
         "description": "Media URLs for the template's image/video 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 such a template. Each element is a full URL string."
       },
+      "scene_images": {
+        "type": "array",
+        "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."
+      },
       "caption_lines": {
         "type": "array",
         "items": {
@@ -111,6 +118,7 @@
       "headline",
       "subheadline",
       "carousel_items",
+      "scene_images",
       "caption_lines",
       "stub_image_url",
       "stub_video_url",