@remixmate/cli 0.12.6 → 0.12.8

package/dist/manifest.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
-  "version": "0.12.6",
-  "generatedAt": "2026-10-18T13:29:08.016Z",
+  "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.6",
+  "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

@@ -78,7 +78,7 @@ The intent is to avoid the failure mode where "the generic DSL looks compatible
 4. Combine that with the template's `slotMapping`, `requiredProps`, `optionalProps`, `propExtractors`, `assetRequirements`, `supportedAspectRatios`, `supportedDurations`, `constraints`, and `scenePatterns`.
 5. Generate the DSL in the template's native shape — not the generic DSL shape.
 6. Make sure the DSL explicitly contains every template-specific field, e.g. `templateData.words`, `customPayload.slideId`, `visuals.avatar.assetRef`.
-7. After generation, run the schema check and show the script summary to the user for confirmation.
+7. After generation, run `gen_script.py --validate -i <dsl.json>` and fix every error it reports, then show the script summary to the user for confirmation. It checks the template contract, not just the DSL shape: undeclared `customPayload` field names, values outside a declared `enum` (e.g. `layout: "bogus"`, `style.preset: "nwes"`), and every `assetRef` / `*AssetRef` (`logoAssetRef`, `avatarAssetRef` …) pointing at an asset that `assets[]` does not declare. These are the same checks render-video runs before spending credits; catching them here saves a confirmed script from being rejected later.
 
 ### Document-driven templates: pass the source URL, don't author the payload
 
@@ -123,7 +123,7 @@ Picking the layout is only half of it. Each layout reads its own field names out
 
 This has shipped broken videos: a 7-scene deck guessed generic names (`title`, `description`, `ctaText`) where the chosen layouts read different ones. Five of seven scenes rendered as empty cards and placeholder copy — after paying for TTS and the render. Which names each layout reads is the template's fact; the template's `llmHint` calls out the usual traps.
 
-So: **copy the field names out of `slideSchemas[slideId]`.** The DSL validator now rejects unknown field names before any asset is generated and tells you the declared ones, but that check only fires for templates that ship `slideSchemas` — reading the contract is still the primary move, not the fallback.
+So: **copy the field names out of `slideSchemas[slideId]`.** The DSL validator (`gen_script.py --validate`, and again in render-video) rejects unknown field names and out-of-enum values before any asset is generated and tells you the declared ones — per layout from `slideSchemas` for multi-layout templates, from `customPayloadSchema` for every other template. Reading the contract is still the primary move, not the fallback: the validator checks names and enums, not whether the content fits the layout.
 
 ### On-screen text: the rules live in the template, not here
 
@@ -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
 
@@ -283,6 +284,12 @@ Without this flag the user's images are **ignored entirely** and every scene get
 AI-generated picture. That failure is quiet: the video renders fine, it just isn't made of
 the material the user handed you.
 
+**One shared background.** A template that declares `capabilities.backgroundStrategy: "shared"`
+(e.g. an audiogram whose whole video is one "show poster") gets a skeleton with a single
+`img-background` asset that every scene references, instead of one image per scene. Keep it
+that way; switch to another image only where the template's `llmHint` says you may (such as a
+new chapter). `--scene-images` still maps the user's own images one per scene.
+
 ### 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
@@ -473,8 +480,13 @@ python3 <SkillDir>/scripts/gen_script.py \
 | `--scenes` | Scene count. | auto-planned |
 | `--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. 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 |
+| `--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` 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. | — |
@@ -482,7 +494,7 @@ python3 <SkillDir>/scripts/gen_script.py \
 | `--template-candidates` | Repeatable. Template ids offered to the user, recommended first → `meta.templateSelection.candidates`. With `user-confirmed`, `--template-id` must be one of them. | — |
 | `--allow-digital-human` | Whether to allow digital-human assets. | off |
 | `--allow-ai-video` | Whether to allow AI-generated video assets. | off |
-| `--validate` | Validate-only mode: only validate the input DSL. | — |
+| `--validate` | Validate-only mode: validate the input DSL against the DSL schema **and** the template contract (customPayload field names, enum values, asset references). Warnings are printed but do not fail. | — |
 | `--input` | Input DSL file path (required in validate mode). | — |
 | `-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`). | — |
@@ -491,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

@@ -302,6 +302,33 @@ def validate_dsl(dsl: dict) -> list:
     return errors_as_strings(validate_structural(dsl))
 
 
+def validate_authored_dsl(dsl: dict) -> tuple[list, list]:
+
+
+
+
+
+
+
+
+
+    from video_dsl.runtime.dsl_validator import (
+        validate_integrity,
+        validate_structural,
+        errors_as_strings,
+    )
+    found, seen = [], set()
+
+    for e in validate_structural(dsl) + validate_integrity(dsl):
+        key = (e.path, e.message)
+        if key not in seen:
+            seen.add(key)
+            found.append(e)
+    errors = [e for e in found if getattr(e, "severity", "error") == "error"]
+    warnings = [e for e in found if getattr(e, "severity", "error") != "error"]
+    return errors_as_strings(errors), errors_as_strings(warnings)
+
+
 def plan_scenes(
     topic: str,
     duration: int,
@@ -609,6 +636,8 @@ def _template_needs_image(template_config: dict | None) -> bool:
 
 
 
+
+
 
 
 
@@ -674,6 +703,7 @@ def _resolve_contract(template_config: dict | None) -> dict:
         "duration_model": caps.get("durationModel"),
         "payload_defaults": payload_defaults,
         "primary_visual_type": primary_visual_type,
+        "background_strategy": "shared" if caps.get("backgroundStrategy") == "shared" else "per-scene",
         "default_layout": caps.get("defaultLayout"),
         "authored_scenes": caps.get("authoredScenes") is True,
 
@@ -1059,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(
@@ -1091,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:
 
 
@@ -1104,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",
@@ -1184,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)
 
@@ -1442,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:
 
 
@@ -1461,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())
@@ -1475,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:
@@ -1482,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,
@@ -1518,6 +1820,10 @@ def build_dsl(
         scene_images: list[str] | None = None,
         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:
 
 
@@ -1655,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")
+
 
 
 
@@ -1708,16 +2021,33 @@ def build_dsl(
 
 
 
-    image_style_guide = resolve_style_guide(template_config) if _HAS_ENHANCER else {}
+
+
+
+    image_style_guide = (
+        resolve_style_guide(template_config, variant or "") if _HAS_ENHANCER else {}
+    )
     image_compose = _HAS_ENHANCER and is_compose_mode(image_style_guide)
     image_ratio = image_style_guide.get("ratio") or ratio
 
     tail_pad_sec = _nb.template_tail_pad_sec(template_config) if _HAS_BUDGET else None
+
+
+
+
+    shared_background = (
+        contract["background_strategy"] == "shared"
+        and primary_visual_type == "image"
+        and not provided_slots
+    )
+    shared_background_planned = False
     for idx, plan in enumerate(scene_plans):
         scene_id = f"scene-{idx + 1:02d}"
 
         if primary_visual_type == "video":
             visual_asset_id = f"video-{scene_id}"
+        elif shared_background:
+            visual_asset_id = "img-background"
         else:
             visual_asset_id = f"img-{scene_id}"
         narration_asset_id = f"narration-{scene_id}" if needs_narration else None
@@ -1733,7 +2063,11 @@ def build_dsl(
         scene_has_visual = has_visual and _slot_reads_visual(template_config, plan["purpose"])
 
 
-        if scene_has_visual and primary_visual_type == "image":
+        if scene_has_visual and shared_background and shared_background_planned:
+            pass
+        elif scene_has_visual and primary_visual_type == "image":
+            if shared_background:
+                shared_background_planned = True
             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:
@@ -1760,6 +2094,12 @@ def build_dsl(
             else:
                 if image_compose:
                     image_result = {"prompt": COMPOSE_SUBJECT_PLACEHOLDER}
+                elif shared_background:
+
+
+                    image_result = generate_image_prompt(
+                        "point", topic, style, narration_text="", style_guide=image_style_guide,
+                    )
                 else:
                     image_result = generate_image_prompt(
                         plan["purpose"], topic, style,
@@ -2082,7 +2422,8 @@ Examples:
         "--variant", default=None,
         help="Template visual variant id (a key of the template's `variants`, listed as variantIds by "
              "template-registry --list-templates). Written to meta.templateVariant, which overrides the "
-             "fuzzy --style match. When the user picked a style in the replicate card (shown as "
+             "fuzzy --style match, and the variant's imageStyleGuide drives the skeleton's image "
+             "prompts. When the user picked a style in the replicate card (shown as "
              "`名字（id）`, e.g. `紫色科技（tech-purple）`), pass that id. Requires --template-id.",
     )
     parser.add_argument(
@@ -2091,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.")
@@ -2189,7 +2562,9 @@ Examples:
             sys.exit(1)
         with open(args.input, "r", encoding="utf-8") as f:
             dsl = json.load(f)
-        errors = validate_dsl(dsl)
+        errors, warnings = validate_authored_dsl(dsl)
+        for w in warnings:
+            print(f"⚠️  {w}", file=sys.stderr)
         if errors:
             print("❌ DSL validation failed:", file=sys.stderr)
             for err in errors:
@@ -2292,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,
@@ -2316,6 +2701,10 @@ Examples:
             scene_images=args.scene_images,
             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:
 
@@ -2324,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/gen-script/version.json

@@ -2,6 +2,6 @@
   "skillName": "gen-script",
   "repoName": "agent-skill-media-maker",
   "skillId": "474",
-  "version": "V21",
+  "version": "V22",
   "skillDescription": "Video-script generation skill. Turns a user-supplied topic into a structured Video DSL (JSON) that describes the full video — scene structure, asset requirements, and narrative flow.\n\nUse this skill as soon as the user mentions any of these intents:\n- Write a video script, generate a video script, plan a video, write storyboards\n- Create a short video, plan video content, generate a Video DSL\n- Turn a topic into a video structure / video content plan\n\nEven when the user does not say \"generate the DSL\", use this skill whenever they want to turn a topic into a structured video plan.\n\n⚠️ Stop-and-confirm gate: after this skill returns a DSL, show the full script and wait for the user's explicit confirmation. Never call `prepare_video_assets` in the same turn."
 }

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

@@ -779,6 +779,12 @@ def _probe_video_duration(url: str):
     return probe_video_duration(url)
 
 
+def _probe_video_meta(url: str) -> dict:
+
+    from _video_probe import probe_video_meta
+    return probe_video_meta(url)
+
+
 def build_render_plan(dsl: dict, binding: dict) -> dict:
 
     fps = dsl.get("global", {}).get("fps", 30)
@@ -868,11 +874,35 @@ def build_render_plan(dsl: dict, binding: dict) -> dict:
 
 
 
+
+
+
+
+
+
+
+    meta_by_url: dict = {}
     for aid, asset in assets_by_id.items():
-        if asset["type"] == "video" and asset["source"] == "existing" and not asset.get("duration") and asset.get("url"):
-            probed = _probe_video_duration(asset["url"])
-            if probed:
-                asset["duration"] = probed
+        url = asset.get("url")
+        if asset["type"] != "video" or asset["source"] != "existing" or not url:
+            continue
+        need_size = not (asset.get("width") and asset.get("height"))
+        need_duration = not asset.get("duration")
+        if not (need_size or need_duration):
+            continue
+        meta = meta_by_url.get(url)
+        if meta is None and need_size:
+            meta = meta_by_url[url] = _probe_video_meta(url)
+        meta = meta or {}
+        if need_size and meta.get("width") and meta.get("height"):
+            asset["width"], asset["height"] = meta["width"], meta["height"]
+        if need_duration:
+            if meta.get("duration_ms"):
+                asset["duration"] = meta["duration_ms"] / 1000.0
+            else:
+                probed = _probe_video_duration(url)
+                if probed:
+                    asset["duration"] = probed
 
     timeline = []
     current_frame = 0

package/skills/template-registry/version.json

@@ -2,6 +2,6 @@
   "skillName": "template-registry",
   "repoName": "agent-skill-media-maker",
   "skillId": "475",
-  "version": "V28",
+  "version": "V29",
   "skillDescription": "Video-template registry skill. Stores every video-template definition and lists the available templates (templateId / name / aspect ratio / style tags).\n\nUse this skill as soon as the user mentions any of these intents:\n- View available templates / list every template\n\nNote: DSL→TemplateBinding is no longer a separate exposed step — once prepare_video_assets receives a template_id it builds the binding internally."
 }

package/skills/template-registry/video_dsl/runtime/dsl_validator.py

@@ -1014,6 +1014,10 @@ def _walk_payload(
 
 
 
+
+
+
+
     errors = _check_payload_object(
         data,
         schema,
@@ -1086,6 +1090,10 @@ def _check_payload_object(
                 "the slide renders its built-in placeholder instead of your content.",
             ))
 
+    for key, sub in merged_props.items():
+        if key in data and isinstance(sub, dict):
+            errors += _enum_errors(data[key], sub, path=f"{path}.{key}", scene=scene, key=key)
+
 
 
     for key, sub in props.items():
@@ -1104,6 +1112,41 @@ def _check_payload_object(
     return errors
 
 
+def _enum_errors(
+    value: object, schema: dict, *, path: str, scene: str, key: str
+) -> list[ValidationError]:
+
+
+
+
+
+    enum = schema.get("enum")
+    if isinstance(enum, list) and enum:
+        if value is None or isinstance(value, (dict, list)) or value in enum:
+            return []
+        hint = ""
+        if isinstance(value, str):
+            hit = difflib.get_close_matches(
+                value, [e for e in enum if isinstance(e, str)], n=1, cutoff=0.6
+            )
+            if hit:
+                hint = f" Did you mean '{hit[0]}'?"
+        allowed = ", ".join(repr(e) for e in enum)
+        return [ValidationError(
+            path,
+            f"scene '{scene}': '{key}' is {value!r}, which is not one of [{allowed}] — the "
+            "template ignores an unknown value and falls back to its default, so the look "
+            "you asked for silently never appears." + hint,
+        )]
+    items = schema.get("items")
+    if schema.get("type") == "array" and isinstance(items, dict) and isinstance(value, list):
+        errors: list[ValidationError] = []
+        for i, item in enumerate(value):
+            errors += _enum_errors(item, items, path=f"{path}[{i}]", scene=scene, key=f"{key}[{i}]")
+        return errors
+    return []
+
+
 def _is_blank(value: object) -> bool:
 
 

package/skills/template-registry/video_dsl/runtime/payload_contract.py

@@ -59,13 +59,22 @@ def required_payload_errors(template: dict, props: dict) -> list[str]:
 
 def asset_references(value, path: str = "", *, bound_props: bool = False):
 
+
+
+
+
+
     if isinstance(value, list):
         for index, item in enumerate(value):
             yield from asset_references(item, f"{path}[{index}]", bound_props=bound_props)
     elif isinstance(value, dict):
         for key, child in value.items():
             child_path = f"{path}.{key}" if path else key
-            if key == "assetRef" or (bound_props and key.endswith("AssetId")):
+            if (
+                key == "assetRef"
+                or key.endswith("AssetRef")
+                or (bound_props and key.endswith("AssetId"))
+            ):
                 if isinstance(child, str) and child.strip():
                     yield child_path, child
             else:

package/skills/template-registry/video_dsl/runtime/prompt_enhancer.py

@@ -462,7 +462,9 @@ def compose_dsl_image_prompts(dsl: dict, template: Optional[dict]) -> list[str]:
 
 
     meta = dsl.get("meta") or {}
-    variant_id = str(meta.get("variantId") or "")
+
+
+    variant_id = str(meta.get("templateVariant") or meta.get("variantId") or "")
     if not is_compose_mode(resolve_style_guide(template, variant_id)):
         return []
 

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 直接拒绝生成。",