@remixmate/cli 0.12.7 → 0.12.8

package/dist/manifest.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
-  "version": "0.12.7",
-  "generatedAt": "2026-10-20T11:33:13.520Z",
+  "version": "0.12.8",
+  "generatedAt": "2026-10-20T23:46:18.482Z",
   "skills": [
     {
       "id": "doc-parse",
@@ -592,7 +592,38 @@
           },
           "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."
+            "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` need the user's file: pass it as background_asset (which also sets the preset)."
+          },
+          "sequence_preset": {
+            "type": "string",
+            "description": "Image-sequence style preset, one of the template's customPayloadSchema.sequence.preset values (image-to-video: vlog / news / poster / cinematic / fast-cut). Written to customPayload.sequence.preset; the preset sets transitions, motion, text layout and pacing (fast-cut shortens every image to 1.5s, and the scene duration follows). **Must** pass when the user picked a style preset: the replicate card shows `风格预设: 快剪（fast-cut）` → pass `fast-cut`; `none` keeps the template defaults. Without it the choice is silently dropped. Only for templates declaring capabilities.payloadDefaults.sequence; unsupported values are rejected."
+          },
+          "sequence_fit": {
+            "type": "string",
+            "description": "How image-sequence media fill the frame, one of customPayloadSchema.sequence.fit (cover = fill the frame and crop, contain = show the whole picture over a blurred backdrop). Written to customPayload.sequence.fit and beats the preset's own fit. **Must** pass when the user picked it: `显示方式: 完整显示（contain）` → pass `contain`; `auto` keeps the template / preset default. Only for templates declaring capabilities.payloadDefaults.sequence."
+          },
+          "background_asset": {
+            "type": "string",
+            "description": "URL of the user's background image or video (the replicate card's 背景素材 / 背景图片 asset line → its URL). Added as an existing asset and referenced from every scene's customPayload.background (assetRef for an image, videoAssetRef for a video; .mp4/.mov/.webm/.m4v count as video); the background preset becomes image / video, so background_preset can be omitted. **Must** pass when the user gave a background file — without it a preset of image / video renders the template's plain default. Requires template_id; rejected when the template has no background of that kind."
+          },
+          "payload": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "Template-specific card choices as `KEY=VALUE`, written to every scene's customPayload and locked so the dsl_json you save cannot overwrite them. KEY is a dotted path into the template's customPayloadSchema (e.g. `grade=四年级`, `watermarkText=WorkBuddy 实战课`, `preset=course`, `carousel.fit=cover`, `templateData.revealMode=progressive`, `cardStyle.championFx=false`); VALUE is the id inside the card line's parentheses, or the text verbatim for free-text fields. Booleans take true/false, numbers are range-checked, enums are checked — an undeclared key or value is rejected with the allowed list. **Must** pass every card line that the system prompt maps to a payload key; without it the choice is silently dropped. Requires template_id."
+          },
+          "motion": {
+            "type": "string",
+            "enum": [
+              "static",
+              "kenburns-in",
+              "kenburns-out",
+              "pan-left",
+              "pan-right",
+              "float"
+            ],
+            "description": "Camera motion for every scene (scenes[].animationHints.motion), replacing the skeleton's alternating push-in / pull-out. **Must** pass when the user picked one: `运镜效果: 缓慢推近（kenburns-in）` → `kenburns-in`."
           },
           "font_id": {
             "type": "string",
@@ -639,7 +670,7 @@
             "items": {
               "type": "string"
             },
-            "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 into customPayload.sequence.items when payloadDefaults.sequence is declared, otherwise 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."
+            "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 into customPayload.sequence.items when payloadDefaults.sequence is declared, otherwise 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. Image sequences (payloadDefaults.sequence) accept video URLs too (.mp4/.mov/.webm): gen_script probes each clip's real length, marks it type=video and plays it whole and muted; an unreadable video is rejected."
           },
           "scene_images": {
             "type": "array",
@@ -653,7 +684,7 @@
             "items": {
               "type": "string"
             },
-            "description": "On-screen caption lines for templates that declare a caption area (capabilities.payloadDefaults.caption). For image sequences (payloadDefaults.sequence), lines map in order to sequence.items[].caption, with at most one line per image. Otherwise each element is one line. Line-count limits and whether **emphasis** is parsed are declared by the template — read its llmHint, which gen_script prints in full on stderr. **Must** pass when the user explicitly provides bullet-point text / bottom copy. **Also must pass — written by you — when the user did NOT provide any copy but the template is typewriter-driven** (capabilities.durationStrategy=fit-caption): such templates have no narration, so these lines are both the video's content and the thing that decides its duration. Draft them from the material you researched (repo README, page screenshots, the topic). Leaving this empty for a fit-caption template is rejected: nothing auto-generates caption text, and an empty caption renders a titled carousel with no words at all."
+            "description": "On-screen caption lines for templates that declare a caption area (capabilities.payloadDefaults.caption). For image sequences (payloadDefaults.sequence), lines map in order to sequence.items[].caption, with at most one line per image. A replicate asset line's `(… desc: <text>)` suffix is the user's caption for that image: pass it here in the same order (use an empty string for images without one). Otherwise each element is one line. Line-count limits and whether **emphasis** is parsed are declared by the template — read its llmHint, which gen_script prints in full on stderr. **Must** pass when the user explicitly provides bullet-point text / bottom copy. **Also must pass — written by you — when the user did NOT provide any copy but the template is typewriter-driven** (capabilities.durationStrategy=fit-caption): such templates have no narration, so these lines are both the video's content and the thing that decides its duration. Draft them from the material you researched (repo README, page screenshots, the topic). Leaving this empty for a fit-caption template is rejected: nothing auto-generates caption text, and an empty caption renders a titled carousel with no words at all."
           },
           "stub_image_url": {
             "type": "string",
@@ -693,6 +724,11 @@
           "speed",
           "variant",
           "background_preset",
+          "sequence_preset",
+          "sequence_fit",
+          "background_asset",
+          "payload",
+          "motion",
           "font_id",
           "font_name",
           "list_fonts",

package/package.json

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

@@ -253,8 +253,9 @@ When the user selects a `carousel-caption` template (or any template whose `asse
    - `durationStrategy: fit-caption` → **caption lines are mandatory.** The template has no narration and the typewriter copy is both the content and the clock: it is what the video says *and* what decides how long it runs. **If the user did not supply the copy, write it yourself** from the material you researched (repo README, page screenshots, the topic) and pass it. `gen_script.py` hard-fails on an empty caption for these templates.
    - `durationStrategy: fit-images` → purely visual, captions genuinely optional; duration comes from the image count.
 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.
-5. Nothing downstream fills these in for you. `gen_script.py` routes on `capabilities.payloadStyle` alone — omitting the flags does **not** fall back to a generic path that generates images or writes copy; it assembles an empty carousel / empty caption. There is no auto-generation of caption text anywhere in the pipeline.
+4. Image sequences (`payloadDefaults.sequence`, e.g. image-to-video) take videos as well: pass the clip URL in `--carousel-items` like an image. gen_script probes its real length and writes `type: "video"` + `sourceDurationSec`, so the scene is timed by the clip, not as a 3-second still. A replicate asset line `![name](url) (…, desc: <text>)` carries the user's caption for that item — pass it as the matching `--caption-lines` entry (empty string for items without one).
+5. Do **not** route these user-provided images through `gen-image`; they are existing assets and go straight into the carousel.
+6. Nothing downstream fills these in for you. `gen_script.py` routes on `capabilities.payloadStyle` alone — omitting the flags does **not** fall back to a generic path that generates images or writes copy; it assembles an empty carousel / empty caption. There is no auto-generation of caption text anywhere in the pipeline.
 
 ### Command example
 
@@ -480,7 +481,12 @@ python3 <SkillDir>/scripts/gen_script.py \
 | `--voice-id` | Narration voice id. | resolved from template + language fallback |
 | `--speed` | Narration speech rate (0.5–2.0), written to `global.narration.speed` and applied when `prepare_video_assets` calls gen-voice. Pass it whenever the user picked a speed (the replicate form's 语速 field sends one). Above ~1.3 subtitle alignment drifts and the delivery turns mechanical — shorten the script instead. | `1.0` |
 | `--variant` | Template visual variant id (a key of the template's `variants`; `template-registry --list-templates` prints them as `variantIds`). Written to `meta.templateVariant`, which takes precedence over the fuzzy `--style` match, and the variant's own `imageStyleGuide` is what the skeleton's image prompts / `negativePrompt` are built from (pass it to `gen_script` rather than setting `meta.templateVariant` afterwards, or the prompts keep the template's default look). Pass it whenever the user picked a style — the replicate card shows it as `名字（id）`, e.g. `视觉风格: 紫色科技（tech-purple）`; pass the id in the parentheses. Requires `--template-id`; unknown ids are rejected. | template default |
-| `--background-preset` | Scene background preset, one of the template's `customPayloadSchema.background.preset` values. Written to every scene's `customPayload.background.preset` (other keys of the template's default background are kept). Pass it whenever the user picked a background, e.g. `背景样式: 纯色（solid）` → `solid`. `image` / `video` also need `customPayload.background.assetRef`. Requires `--template-id`; unsupported values are rejected. | template default |
+| `--background-preset` | Scene background preset, one of the template's `customPayloadSchema.background.preset` values. Written to every scene's `customPayload.background.preset` (other keys of the template's default background are kept). Pass it whenever the user picked a background, e.g. `背景样式: 纯色（solid）` → `solid`. `image` / `video` need the user's file: pass `--background-asset` (which sets the preset itself). Requires `--template-id`; unsupported values are rejected. | template default |
+| `--sequence-preset` | Image-sequence style preset, one of the template's `customPayloadSchema.sequence.preset` values (image-to-video: `vlog` / `news` / `poster` / `cinematic` / `fast-cut`). Written to `customPayload.sequence.preset`; the template's declared defaults are then left out so they do not shadow the preset, and the scene duration uses the preset's pacing (`durationModel.sequence.presets`). Pass it whenever the user picked a preset, e.g. `风格预设: 快剪（fast-cut）` → `fast-cut`; `none` = template defaults. | template defaults |
+| `--sequence-fit` | Image-sequence fill mode, one of `customPayloadSchema.sequence.fit` (`cover` fill and crop / `contain` whole picture over a blurred backdrop), written to `customPayload.sequence.fit`; beats the preset's fit. `auto` = template / preset default. | template / preset default |
+| `--background-asset` | URL of the user's background image or video (`.mp4/.mov/.webm/.m4v` → video). Added as existing asset `asset-background`; every scene's `customPayload.background` gets `preset: image` + `assetRef`, or `preset: video` + `videoAssetRef`. Conflicts with a different `--background-preset`; rejected when the template's background enum lacks that kind. | none |
+| `--payload KEY=VALUE` | Template-specific card choice, repeatable. `KEY` is a dotted path in `customPayloadSchema` (or `capabilities.frameLevelKeys`), e.g. `grade=四年级`, `watermarkText=…`, `preset=course`, `carousel.fit=cover`, `caption.charsPerSec=20`, `templateData.revealMode=progressive`. Value is converted to the declared type (true/false, numbers) and checked against enum / range; undeclared keys are rejected. Written to every scene with sibling keys kept, applied before fit-caption duration estimation. | template default |
+| `--motion` | Camera motion for every scene (`animationHints.motion`): `static` / `kenburns-in` / `kenburns-out` / `pan-left` / `pan-right` / `float`. | skeleton alternates in / out |
 | `--font-id` | Font library key (`font.uniq_id`), written to `global.font.fontId`; ab-render resolves and installs the real font at render time. Pass it whenever the user picked a font — the replicate card shows it as `名字（id）`, e.g. `字体: <名字>（<uniqId>）`; pass the id in the parentheses. Never pass a CSS family or the display name: an unknown key falls back to the template font with no error. | template font |
 | `--font-name` | Display name of the picked font → `global.font.fontName` (display only, never used for rendering). Pass it with `--font-id`. | — |
 | `--list-fonts` | Print the live font library (`/font/page`: id, name, lang, category, license) and exit; no script is generated and `--topic` is not needed. The ids it prints are the only valid `--font-id` values — use it when the user asks which fonts exist or names a font without its id. | — |
@@ -497,6 +503,8 @@ python3 <SkillDir>/scripts/gen_script.py \
 | `--scene-images` | Repeatable. One scene's visual for a **`visual-overlay`** template, 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. | — |
 
+Values written by `--background-preset`, `--background-asset`, `--payload` and `--motion` are listed in `meta.lockedScenePaths` (scene-relative paths such as `customPayload.carousel.fit`, `animationHints.motion`). When the agent later saves its own `dsl_json` in merge mode, ab-agent restores those paths from this skeleton after merging, so a model-written `carousel` / `templateData` / `background` object cannot wipe a card choice. Do not hand-write these keys in `dsl_json`; pass the flag.
+
 ## DSL generation principles
 
 Apply the following principles when producing the DSL:

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

@@ -1089,15 +1089,63 @@ def _estimate_fit_images_duration(sequence: dict, model: dict | None, fps: int =
     rule_hold = next((tier["holdSec"] for tier in tiers if count <= tier["maxItems"]), None)
     if rule_hold is None:
         raise ValueError("fit-images requires durationModel.sequence.holdSecByCount covering the image count")
-    base_hold = sequence.get("defaultHoldSec", rule_hold)
-    transition_ms = sequence.get("transitionMs", timing.get("transitionMs"))
+
+
+    preset_timing = (timing.get("presets") or {}).get(sequence.get("preset")) or {}
+    base_hold = sequence.get("defaultHoldSec", preset_timing.get("defaultHoldSec", rule_hold))
+    transition_ms = sequence.get("transitionMs", preset_timing.get("transitionMs", timing.get("transitionMs")))
     margin = timing.get("minHoldMarginFrames")
     if transition_ms is None or margin is None:
         raise ValueError("fit-images requires sequence transitionMs and durationModel.sequence.minHoldMarginFrames")
 
     min_frames = max(2, math.floor(transition_ms / 1000 * fps + 0.5)) + margin
-    return sum(max(min_frames, math.floor(item.get("holdSec", base_hold) * fps + 0.5))
-               for item in sequence["items"]) / fps
+
+    def item_frames(item: dict) -> int:
+        if item.get("type") == "video":
+
+            return max(1, math.floor(item.get("holdSec", item["sourceDurationSec"]) * fps + 0.5))
+        return max(min_frames, math.floor(item.get("holdSec", base_hold) * fps + 0.5))
+
+    return sum(item_frames(item) for item in sequence["items"]) / fps
+
+
+def _probe_sequence_video_duration(url: str) -> float | None:
+
+
+
+
+
+    probe_dir = os.path.join(os.path.dirname(__file__), "..", "..", "render-video", "scripts")
+    if os.path.isdir(probe_dir) and os.path.abspath(probe_dir) not in sys.path:
+        sys.path.insert(0, os.path.abspath(probe_dir))
+    try:
+        from _video_probe import probe_video_duration
+    except ImportError:
+        return None
+    return probe_video_duration(url)
+
+
+def _sequence_choice(sequence_schema: dict, key: str, value: str | None, flag: str,
+                     template_id: str, passthrough: str) -> str | None:
+
+
+
+
+
+    if not value or value == passthrough:
+        return None
+    prop = (sequence_schema.get("properties") or {}).get(key) or {}
+    allowed = [str(v) for v in prop.get("enum") or []]
+    if value not in allowed:
+        raise ValueError(
+            f"{flag} {value!r} is not supported by template {template_id!r}; "
+            f"choose one of: {', '.join(allowed + [passthrough]) if allowed else '(this template has no such option)'}"
+        )
+    return value
+
+
+
+PayloadWrites = list[tuple[list[str], object]]
 
 
 def _build_carousel_caption_dsl(
@@ -1121,6 +1169,10 @@ def _build_carousel_caption_dsl(
     payload_defaults: dict,
     duration_strategy: str | None,
     duration_model: dict | None,
+    sequence_schema: dict | None = None,
+    sequence_preset: str | None = None,
+    sequence_fit: str | None = None,
+    payload_writes: PayloadWrites | None = None,
 ) -> dict:
 
 
@@ -1134,16 +1186,30 @@ def _build_carousel_caption_dsl(
         raise ValueError("Image sequence needs --carousel-items; caption text alone cannot supply images")
     if sequence_mode and len(caption_lines) > len(carousel_items):
         raise ValueError("Image sequence has more --caption-lines than images; use at most one caption per image")
+    if not sequence_mode and (sequence_preset not in (None, "none") or sequence_fit not in (None, "auto")):
+        raise ValueError(f"--sequence-preset / --sequence-fit only apply to image-sequence templates; {template_id!r} is not one")
+    if sequence_mode:
+        sequence_preset = _sequence_choice(sequence_schema or {}, "preset", sequence_preset,
+                                           "--sequence-preset", template_id, "none")
+        sequence_fit = _sequence_choice(sequence_schema or {}, "fit", sequence_fit,
+                                        "--sequence-fit", template_id, "auto")
 
 
     assets = []
     carousel_asset_ids = []
+    video_seconds: dict[str, float] = {}
     for idx, url in enumerate(carousel_items):
         asset_id = f"carousel-img-{idx + 1:02d}"
 
         is_video = urlsplit(url).path.lower().endswith((".mp4", ".mov", ".webm", ".avi"))
         if sequence_mode and is_video:
-            raise ValueError("Image sequence requires image URLs in --carousel-items, not video URLs")
+            seconds = _probe_sequence_video_duration(url)
+            if not seconds or seconds <= 0:
+                raise ValueError(
+                    f"Cannot read the duration of video {url!r}; an image sequence needs it to time the clip. "
+                    f"Check the URL is reachable, or leave this video out."
+                )
+            video_seconds[asset_id] = round(float(seconds), 3)
         assets.append({
             "assetId": asset_id,
             "type": "video" if is_video else "image",
@@ -1214,15 +1280,25 @@ def _build_carousel_caption_dsl(
 
 
     if sequence_mode:
-        sequence_config = defaults["sequence"]
+
+
+
+        sequence_config = {"preset": sequence_preset} if sequence_preset else defaults["sequence"]
+        if sequence_fit:
+            sequence_config["fit"] = sequence_fit
         sequence_config["items"] = [
             {"assetRef": asset_id,
-             **({"caption": caption_lines[index]} if index < len(caption_lines) else {})}
-            for index, (asset_id, _) in enumerate(carousel_asset_ids)
+             **({"type": "video", "sourceDurationSec": video_seconds[asset_id]} if kind == "video" else {}),
+             **({"caption": caption_lines[index]} if index < len(caption_lines) and caption_lines[index] else {})}
+            for index, (asset_id, kind) in enumerate(carousel_asset_ids)
         ]
         custom_payload = {"sequence": sequence_config}
 
 
+
+    _write_payload(custom_payload, payload_writes or [])
+
+
     narration_text = _localize_label(output_language, "narration_opening",
                                      label="", topic=_clip(topic, _PLACEHOLDER_TOPIC_CHARS), duration=duration)
 
@@ -1472,12 +1548,29 @@ def _template_selection(
     return selection
 
 
+
+
+
+
+
+LOCKED_SCENE_PATHS_KEY = "lockedScenePaths"
+BACKGROUND_ASSET_ID = "asset-background"
+_VIDEO_EXTENSIONS = (".mp4", ".mov", ".webm", ".avi", ".m4v")
+
+
+def _lock_scene_path(dsl: dict, path: str) -> None:
+    locks = dsl.setdefault("meta", {}).setdefault(LOCKED_SCENE_PATHS_KEY, [])
+    if path not in locks:
+        locks.append(path)
+
+
 def _apply_look(
     dsl: dict,
     template_config: dict | None,
     template_id: str | None,
     variant: str | None,
     background_preset: str | None,
+    background_asset: str | None = None,
 ) -> None:
 
 
@@ -1491,10 +1584,17 @@ def _apply_look(
 
 
 
-    if not variant and not background_preset:
+
+
+
+
+    if not variant and not background_preset and not background_asset:
         return
     if not template_id or template_config is None:
-        raise ValueError("--variant / --background-preset need --template-id: the allowed values come from the template.")
+        raise ValueError(
+            "--variant / --background-preset / --background-asset need --template-id: "
+            "the allowed values come from the template."
+        )
 
     if variant:
         variants = list((template_config.get("variants") or {}).keys())
@@ -1505,6 +1605,22 @@ def _apply_look(
             )
         dsl.setdefault("meta", {})["templateVariant"] = variant
 
+    asset_url = (background_asset or "").strip()
+    if asset_url:
+        kind = "video" if urlsplit(asset_url).path.lower().endswith(_VIDEO_EXTENSIONS) else "image"
+        if background_preset and background_preset != kind:
+            raise ValueError(
+                f"--background-preset {background_preset!r} conflicts with --background-asset, which is "
+                f"{'a video' if kind == 'video' else 'an image'}; drop --background-preset or pass {kind!r}."
+            )
+        if kind not in _template_background_presets(template_config):
+            raise ValueError(
+                f"template {template_id!r} has no {kind} background, so --background-asset cannot be "
+                f"{'a video' if kind == 'video' else 'an image'}; "
+                f"its backgrounds are: {', '.join(_template_background_presets(template_config)) or '(none)'}"
+            )
+        background_preset = kind
+
     if background_preset:
         presets = _template_background_presets(template_config)
         if background_preset not in presets:
@@ -1512,19 +1628,175 @@ def _apply_look(
                 f"--background-preset {background_preset!r} is not supported by template {template_id!r}; "
                 f"choose one of: {', '.join(presets) or '(this template has no background option)'}"
             )
+
+        ref_key = "videoAssetRef" if background_preset == "video" else "assetRef"
         for scene in dsl.get("scenes", []):
             payload = scene.setdefault("customPayload", {})
             existing = payload.get("background") if isinstance(payload.get("background"), dict) else {}
-            payload["background"] = {**existing, "preset": background_preset}
-        if background_preset in ("image", "video"):
+            background = {**existing, "preset": background_preset}
+            if asset_url:
+                background[ref_key] = BACKGROUND_ASSET_ID
+            payload["background"] = background
+        _lock_scene_path(dsl, "customPayload.background.preset")
+        if asset_url:
+            dsl.setdefault("assets", []).append({
+                "assetId": BACKGROUND_ASSET_ID,
+                "type": background_preset,
+                "source": "existing",
+                "status": "generated",
+                "url": asset_url,
+            })
+            _lock_scene_path(dsl, f"customPayload.background.{ref_key}")
+        elif background_preset in ("image", "video"):
             print(
-                f"ℹ️  background preset {background_preset!r} needs a user asset: set "
-                f"customPayload.background.assetRef on each scene to that asset's id, "
-                f"otherwise the template falls back to its default background.",
+                f"ℹ️  background preset {background_preset!r} needs a user asset: pass --background-asset "
+                f"<url>, otherwise the template falls back to its default background.",
                 file=sys.stderr,
             )
 
 
+_TRUE_WORDS = ("true", "1", "yes", "on", "开", "是", "显示")
+_FALSE_WORDS = ("false", "0", "no", "off", "关", "否", "隐藏")
+
+
+def _payload_node(template_config: dict, parts: list[str], spec: str) -> dict:
+
+
+
+
+
+
+
+    schema = template_config.get("customPayloadSchema") or {}
+    frame = ((template_config.get("capabilities") or {}).get("frameLevelKeys") or {}).get("keys") or []
+    head = parts[0]
+    if isinstance(schema, dict) and isinstance(schema.get(head), dict):
+        node = schema[head]
+    elif head in frame:
+        node = {}
+    else:
+        declared = sorted(set(k for k in schema if not k.startswith("_")) | set(frame))
+        raise ValueError(
+            f"--payload {spec!r}: {head!r} is not a customPayload key of this template; "
+            f"declared keys: {', '.join(declared) or '(none)'}"
+        )
+    for depth, part in enumerate(parts[1:], start=1):
+        props = node.get("properties")
+        if isinstance(props, dict) and isinstance(props.get(part), dict):
+            node = props[part]
+        elif isinstance(props, dict) and props and node.get("additionalProperties") is not True:
+            raise ValueError(
+                f"--payload {spec!r}: {'.'.join(parts[:depth])} has no {part!r}; "
+                f"declared: {', '.join(sorted(props))}"
+            )
+        else:
+            node = {}
+    return node
+
+
+def _coerce_payload_value(raw: str, node: dict, spec: str):
+
+    declared = node.get("type")
+    types = [declared] if isinstance(declared, str) else list(declared or [])
+    if types and not set(types) & {"string", "boolean", "number", "integer"}:
+        raise ValueError(
+            f"--payload {spec!r}: this key holds {'/'.join(types)}, not a single value; "
+            f"set one of its fields instead (KEY.FIELD=VALUE)."
+        )
+    value: object = raw
+    if "boolean" in types:
+        word = raw.strip().lower()
+        if word in _TRUE_WORDS:
+            value = True
+        elif word in _FALSE_WORDS:
+            value = False
+        elif "string" not in types:
+            raise ValueError(f"--payload {spec!r}: expected true or false")
+    if value is raw and ("number" in types or "integer" in types):
+        try:
+            number = float(raw)
+        except ValueError:
+            if "string" not in types:
+                raise ValueError(f"--payload {spec!r}: expected a number") from None
+        else:
+            if "integer" in types and "number" not in types:
+                if not number.is_integer():
+                    raise ValueError(f"--payload {spec!r}: expected a whole number")
+                value = int(number)
+            else:
+                value = int(number) if number.is_integer() else number
+            lo, hi = node.get("minimum"), node.get("maximum")
+            if (lo is not None and value < lo) or (hi is not None and value > hi):
+                raise ValueError(f"--payload {spec!r}: must be within {lo}..{hi}")
+    enum = node.get("enum")
+    if isinstance(enum, list) and value not in enum:
+        raise ValueError(f"--payload {spec!r}: choose one of: {', '.join(str(v) for v in enum)}")
+    return value
+
+
+def _apply_scene_payload(
+    dsl: dict,
+    template_config: dict | None,
+    template_id: str | None,
+    payload_specs: list[str] | None,
+    motion: str | None,
+) -> None:
+
+
+
+
+
+
+
+    if not payload_specs and not motion:
+        return
+    if not template_id or template_config is None:
+        raise ValueError("--payload / --motion need --template-id: the allowed keys come from the template.")
+
+    writes = _parse_payload_specs(template_config, payload_specs)
+    if motion:
+        allowed = ("static", "kenburns-in", "kenburns-out", "pan-left", "pan-right", "float")
+        if motion not in allowed:
+            raise ValueError(f"--motion {motion!r}: choose one of: {', '.join(allowed)}")
+
+    for scene in dsl.get("scenes", []):
+        _write_payload(scene.setdefault("customPayload", {}), writes)
+        if motion:
+            hints = scene.get("animationHints") if isinstance(scene.get("animationHints"), dict) else {}
+            scene["animationHints"] = {**hints, "motion": motion}
+    for parts, _ in writes:
+        _lock_scene_path(dsl, "customPayload." + ".".join(parts))
+    if motion:
+        _lock_scene_path(dsl, "animationHints.motion")
+
+
+def _parse_payload_specs(template_config: dict, payload_specs: list[str] | None) -> PayloadWrites:
+
+    writes: PayloadWrites = []
+    for spec in payload_specs or []:
+        key, sep, raw = spec.partition("=")
+        parts = [p.strip() for p in key.split(".")]
+        if not sep or not all(parts):
+            raise ValueError(f"--payload {spec!r}: expected KEY=VALUE, e.g. grade=四年级 or carousel.fit=cover")
+        raw = raw.strip()
+        if not raw:
+            raise ValueError(f"--payload {spec!r}: empty value; leave the flag out to keep the template default")
+        node = _payload_node(template_config, parts, spec)
+        writes.append((parts, _coerce_payload_value(raw, node, spec)))
+    return writes
+
+
+def _write_payload(custom_payload: dict, writes: PayloadWrites) -> None:
+
+    for parts, value in writes:
+        node = custom_payload
+        for part in parts[:-1]:
+            if not isinstance(node.get(part), dict):
+                node[part] = {}
+            node = node[part]
+        node[parts[-1]] = value
+
+
 def build_dsl(
         topic: str,
         duration: int,
@@ -1549,6 +1821,9 @@ def build_dsl(
         item_count: int | None = None,
         source_document_url: str | None = None,
         variant: str | None = None,
+        sequence_preset: str | None = None,
+        sequence_fit: str | None = None,
+        payload_writes: PayloadWrites | None = None,
 ) -> dict:
 
 
@@ -1686,10 +1961,17 @@ def build_dsl(
             payload_defaults=contract["payload_defaults"],
             duration_strategy=contract["duration_strategy"],
             duration_model=contract["duration_model"],
+            sequence_schema=((template_config or {}).get("customPayloadSchema") or {}).get("sequence"),
+            sequence_preset=sequence_preset,
+            sequence_fit=sequence_fit,
+            payload_writes=payload_writes,
         )
         _enforce_supported_duration(carousel_dsl, template_config, template_id)
         return carousel_dsl
 
+    if sequence_preset not in (None, "none") or sequence_fit not in (None, "auto"):
+        raise ValueError(f"--sequence-preset / --sequence-fit only apply to image-sequence templates; {template_id!r} is not one")
+
 
 
 
@@ -2150,6 +2432,38 @@ Examples:
              "Written to every scene's customPayload.background.preset. When the user picked a background in "
              "the replicate card (e.g. `纯色（solid）`), pass that id. Requires --template-id.",
     )
+    parser.add_argument(
+        "--sequence-preset", default=None,
+        help="Image-sequence style preset (one of the template's customPayloadSchema.sequence.preset enum, "
+             "e.g. vlog / news / poster / cinematic / fast-cut), written to customPayload.sequence.preset; "
+             "`none` keeps the template defaults. When the user picked a style preset in the replicate card "
+             "(e.g. `快剪（fast-cut）`), pass that id. Only for templates declaring payloadDefaults.sequence.",
+    )
+    parser.add_argument(
+        "--sequence-fit", default=None,
+        help="How image-sequence media fill the frame (customPayloadSchema.sequence.fit enum: cover = fill and crop, "
+             "contain = show whole with a blurred backdrop), written to customPayload.sequence.fit; `auto` keeps "
+             "the template / preset default. When the user picked it in the replicate card, pass that id.",
+    )
+    parser.add_argument(
+        "--background-asset", default=None,
+        help="URL of the user's background image or video (.mp4/.mov/.webm → video). Added as an existing "
+             "asset and referenced from every scene's customPayload.background (assetRef for an image, "
+             "videoAssetRef for a video); the preset becomes image / video. Requires --template-id and a "
+             "template whose background enum offers that kind.",
+    )
+    parser.add_argument(
+        "--payload", action="append", default=None, metavar="KEY=VALUE",
+        help="Set a template customPayload field on every scene, e.g. --payload grade=四年级 "
+             "--payload carousel.fit=cover --payload templateData.revealMode=progressive. KEY is a dotted path "
+             "checked against the template's customPayloadSchema; VALUE is converted to its declared type "
+             "(true/false, numbers) and checked against its enum / range. Repeatable. Requires --template-id.",
+    )
+    parser.add_argument(
+        "--motion", default=None,
+        help="Camera motion for every scene (animationHints.motion): static / kenburns-in / kenburns-out / "
+             "pan-left / pan-right / float. Replaces the skeleton's alternating default.",
+    )
     parser.add_argument("--allow-digital-human", action="store_true", help="Allow digital-human assets")
     parser.add_argument("--allow-ai-video", action="store_true", help="Allow AI-generated video assets")
     parser.add_argument("--template-id", default=None, help="Template id. The template owns outputLanguage and may declare a defaultVoiceId.")
@@ -2353,6 +2667,16 @@ Examples:
             file=sys.stderr,
         )
 
+    try:
+
+
+        payload_writes = (
+            _parse_payload_specs(_load_template_config(args.template_id) or {}, args.payload)
+            if args.payload and args.template_id else []
+        )
+    except ValueError as exc:
+        parser.error(str(exc))
+
     try:
         dsl = build_dsl(
             topic=args.topic,
@@ -2378,6 +2702,9 @@ Examples:
             item_count=args.item_count,
             source_document_url=args.source_document_url,
             variant=args.variant,
+            sequence_preset=args.sequence_preset,
+            sequence_fit=args.sequence_fit,
+            payload_writes=payload_writes,
         )
     except ValueError as exc:
 
@@ -2386,13 +2713,16 @@ Examples:
         parser.error(str(exc))
 
     try:
+        look_config = _load_template_config(args.template_id) if args.template_id else None
         _apply_look(
             dsl,
-            _load_template_config(args.template_id) if args.template_id else None,
+            look_config,
             args.template_id,
             args.variant,
             args.background_preset,
+            args.background_asset,
         )
+        _apply_scene_payload(dsl, look_config, args.template_id, args.payload, args.motion)
     except ValueError as exc:
         parser.error(str(exc))
 

package/skills/gen-script/skill.json

@@ -54,7 +54,38 @@
       },
       "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."
+        "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` need the user's file: pass it as background_asset (which also sets the preset)."
+      },
+      "sequence_preset": {
+        "type": "string",
+        "description": "Image-sequence style preset, one of the template's customPayloadSchema.sequence.preset values (image-to-video: vlog / news / poster / cinematic / fast-cut). Written to customPayload.sequence.preset; the preset sets transitions, motion, text layout and pacing (fast-cut shortens every image to 1.5s, and the scene duration follows). **Must** pass when the user picked a style preset: the replicate card shows `风格预设: 快剪（fast-cut）` → pass `fast-cut`; `none` keeps the template defaults. Without it the choice is silently dropped. Only for templates declaring capabilities.payloadDefaults.sequence; unsupported values are rejected."
+      },
+      "sequence_fit": {
+        "type": "string",
+        "description": "How image-sequence media fill the frame, one of customPayloadSchema.sequence.fit (cover = fill the frame and crop, contain = show the whole picture over a blurred backdrop). Written to customPayload.sequence.fit and beats the preset's own fit. **Must** pass when the user picked it: `显示方式: 完整显示（contain）` → pass `contain`; `auto` keeps the template / preset default. Only for templates declaring capabilities.payloadDefaults.sequence."
+      },
+      "background_asset": {
+        "type": "string",
+        "description": "URL of the user's background image or video (the replicate card's 背景素材 / 背景图片 asset line → its URL). Added as an existing asset and referenced from every scene's customPayload.background (assetRef for an image, videoAssetRef for a video; .mp4/.mov/.webm/.m4v count as video); the background preset becomes image / video, so background_preset can be omitted. **Must** pass when the user gave a background file — without it a preset of image / video renders the template's plain default. Requires template_id; rejected when the template has no background of that kind."
+      },
+      "payload": {
+        "type": "array",
+        "items": {
+          "type": "string"
+        },
+        "description": "Template-specific card choices as `KEY=VALUE`, written to every scene's customPayload and locked so the dsl_json you save cannot overwrite them. KEY is a dotted path into the template's customPayloadSchema (e.g. `grade=四年级`, `watermarkText=WorkBuddy 实战课`, `preset=course`, `carousel.fit=cover`, `templateData.revealMode=progressive`, `cardStyle.championFx=false`); VALUE is the id inside the card line's parentheses, or the text verbatim for free-text fields. Booleans take true/false, numbers are range-checked, enums are checked — an undeclared key or value is rejected with the allowed list. **Must** pass every card line that the system prompt maps to a payload key; without it the choice is silently dropped. Requires template_id."
+      },
+      "motion": {
+        "type": "string",
+        "enum": [
+          "static",
+          "kenburns-in",
+          "kenburns-out",
+          "pan-left",
+          "pan-right",
+          "float"
+        ],
+        "description": "Camera motion for every scene (scenes[].animationHints.motion), replacing the skeleton's alternating push-in / pull-out. **Must** pass when the user picked one: `运镜效果: 缓慢推近（kenburns-in）` → `kenburns-in`."
       },
       "font_id": {
         "type": "string",
@@ -70,12 +101,18 @@
       },
       "template_source": {
         "type": "string",
-        "enum": ["user-explicit", "user-confirmed", "auto"],
+        "enum": [
+          "user-explicit",
+          "user-confirmed",
+          "auto"
+        ],
         "description": "How template_id was chosen; recorded at meta.templateSelection.source. **Always pass it with template_id.** `user-explicit`: the user named this template — its id or name, a pasted template detail-page prompt or link, or it was settled earlier in this conversation. `user-confirmed`: the user did not name one, you offered candidates and the user picked or approved this one in the chat. `auto`: you picked it yourself and the user has not confirmed — gen_script refuses, so instead of calling it, show the candidates and end the turn. Never mark a template user-confirmed that the user has not seen and approved."
       },
       "template_candidates": {
         "type": "array",
-        "items": { "type": "string" },
+        "items": {
+          "type": "string"
+        },
         "description": "The template ids you offered the user, recommended first; recorded at meta.templateSelection.candidates. Pass with template_source=user-confirmed — template_id must then be one of them (a template the user named outside the shortlist is user-explicit)."
       },
       "source_document_url": {
@@ -95,7 +132,7 @@
         "items": {
           "type": "string"
         },
-        "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 into customPayload.sequence.items when payloadDefaults.sequence is declared, otherwise 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."
+        "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 into customPayload.sequence.items when payloadDefaults.sequence is declared, otherwise 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. Image sequences (payloadDefaults.sequence) accept video URLs too (.mp4/.mov/.webm): gen_script probes each clip's real length, marks it type=video and plays it whole and muted; an unreadable video is rejected."
       },
       "scene_images": {
         "type": "array",
@@ -109,7 +146,7 @@
         "items": {
           "type": "string"
         },
-        "description": "On-screen caption lines for templates that declare a caption area (capabilities.payloadDefaults.caption). For image sequences (payloadDefaults.sequence), lines map in order to sequence.items[].caption, with at most one line per image. Otherwise each element is one line. Line-count limits and whether **emphasis** is parsed are declared by the template — read its llmHint, which gen_script prints in full on stderr. **Must** pass when the user explicitly provides bullet-point text / bottom copy. **Also must pass — written by you — when the user did NOT provide any copy but the template is typewriter-driven** (capabilities.durationStrategy=fit-caption): such templates have no narration, so these lines are both the video's content and the thing that decides its duration. Draft them from the material you researched (repo README, page screenshots, the topic). Leaving this empty for a fit-caption template is rejected: nothing auto-generates caption text, and an empty caption renders a titled carousel with no words at all."
+        "description": "On-screen caption lines for templates that declare a caption area (capabilities.payloadDefaults.caption). For image sequences (payloadDefaults.sequence), lines map in order to sequence.items[].caption, with at most one line per image. A replicate asset line's `(… desc: <text>)` suffix is the user's caption for that image: pass it here in the same order (use an empty string for images without one). Otherwise each element is one line. Line-count limits and whether **emphasis** is parsed are declared by the template — read its llmHint, which gen_script prints in full on stderr. **Must** pass when the user explicitly provides bullet-point text / bottom copy. **Also must pass — written by you — when the user did NOT provide any copy but the template is typewriter-driven** (capabilities.durationStrategy=fit-caption): such templates have no narration, so these lines are both the video's content and the thing that decides its duration. Draft them from the material you researched (repo README, page screenshots, the topic). Leaving this empty for a fit-caption template is rejected: nothing auto-generates caption text, and an empty caption renders a titled carousel with no words at all."
       },
       "stub_image_url": {
         "type": "string",
@@ -149,6 +186,11 @@
       "speed",
       "variant",
       "background_preset",
+      "sequence_preset",
+      "sequence_fit",
+      "background_asset",
+      "payload",
+      "motion",
       "font_id",
       "font_name",
       "list_fonts",

package/skills/template-registry/video_dsl/schema/video-dsl-v1alpha1.json

@@ -55,6 +55,11 @@
         },
         "audience": { "type": "string" },
         "description": { "type": "string" },
+        "lockedScenePaths": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "gen_script 用 CLI 参数（--payload / --background-asset / --background-preset / --motion）写进每个场景的值，按场景相对路径记录（如 customPayload.carousel.fit、animationHints.motion）。merge 模式合并模型提交的 DSL 后，ab-agent 按这张表把骨架里的值写回，模型写的同名对象盖不掉用户在参数卡里的选择。"
+        },
         "templateSelection": {
           "type": "object",
           "description": "模板是怎么定下来的（gen_script --template-source / --template-candidates 写入）。user-explicit = 用户点名；user-confirmed = agent 推荐、用户确认。未经确认的 auto 选择不会出现在这里：gen_script 直接拒绝生成。",