@remixmate/cli 0.9.40 → 0.9.41

package/dist/manifest.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
-  "version": "0.9.40",
-  "generatedAt": "2026-09-22T08:04:46.896Z",
+  "version": "0.9.41",
+  "generatedAt": "2026-10-08T23:39:24.336Z",
   "skills": [
     {
       "id": "doc-parse",
@@ -464,7 +464,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 directly into customPayload.carousel.items as existing assets — NO AI image generation is triggered. **Must** pass when the user explicitly provides image/video URLs for such a template. Each element is a full URL string."
+            "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."
           },
           "scene_images": {
             "type": "array",
@@ -478,7 +478,7 @@
             "items": {
               "type": "string"
             },
-            "description": "On-screen caption lines for templates that declare a caption area (capabilities.payloadDefaults.caption). 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. 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",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remixmate/cli",
-  "version": "0.9.40",
+  "version": "0.9.41",
   "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",
@@ -37,6 +37,8 @@
     "check:render": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/render-template-check.py",
     "clean": "node scripts/clean.mjs",
     "test:countdown": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-countdown-strategy.py",
+    "test:prepare-contracts": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-prepare-contracts.py",
+    "test:image-sequence": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-image-sequence.py",
     "test:ranking-count": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-ranking-count.py"
   },
   "keywords": [

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

@@ -22,6 +22,8 @@ import math
 import os
 import sys
 import uuid
+from copy import deepcopy
+from urllib.parse import urlsplit
 
 SCHEMA_PATH = os.environ.get(
     "VIDEO_DSL_SCHEMA_PATH",
@@ -480,7 +482,7 @@ def _template_needs_image(template_config: dict | None) -> bool:
 #   - countdown         dict|None    countdown 策略的解析结果（见 countdown_spec 模块；
 #                                    非 countdown 模板为 None）
 #   - payload_style     str          capabilities.payloadStyle ∈ {visual-overlay, slide, carousel-caption}
-#   - duration_strategy str          capabilities.durationStrategy ∈ {explicit, fit-caption}
+#   - duration_strategy str          capabilities.durationStrategy ∈ {explicit, fit-caption, fit-images}
 #   - payload_defaults  dict         capabilities.payloadDefaults（carousel-caption 的轮播/字幕默认值）
 #   - duration_model    dict|None    capabilities.durationModel（fit-caption 估时用的节奏数值，
 #                                    由模板声明；缺省则不估时，见 _estimate_fit_caption_duration）
@@ -524,7 +526,7 @@ def _resolve_contract(template_config: dict | None) -> dict:
         payload_style = "slide" if primary_visual_type == "none" else "visual-overlay"
 
     duration_strategy = caps.get("durationStrategy")
-    if duration_strategy not in ("explicit", "fit-caption"):
+    if duration_strategy not in ("explicit", "fit-caption", "fit-images"):
         duration_strategy = "explicit"
 
     fixed_scenes = caps.get("fixedScenes")
@@ -786,6 +788,29 @@ def _estimate_fit_caption_duration(
     return max(headline_intro, caption_sec, carousel_sec) + duration_model.get("tailPaddingSec", 0)
 
 
+def _estimate_fit_images_duration(sequence: dict, model: dict | None, fps: int = 30) -> float:
+    """Apply template-declared image timing, in frames just like the renderer.
+
+    Hold tiers and transition margins belong to durationModel.sequence; never
+    infer them from a template id or silently use the caller's target duration.
+    """
+    timing = (model or {}).get("sequence", {})
+    tiers = timing.get("holdSecByCount", [])
+    count = len(sequence["items"])
+    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"))
+    margin = timing.get("minHoldMarginFrames")
+    if transition_ms is None or margin is None:
+        raise ValueError("fit-images requires sequence transitionMs and durationModel.sequence.minHoldMarginFrames")
+    # Python round uses ties-to-even; JS Math.round uses floor(x + 0.5).
+    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 _build_carousel_caption_dsl(
     *,
     template_id: str,
@@ -814,7 +839,12 @@ def _build_carousel_caption_dsl(
     needsNarration），不再读 input-schema.json，也没有 if template_id==X 分支。
     轮播素材由调用方在 carousel_items 里直接给 URL（existing 资产），不触发 AI 生图。
     """
-    defaults = payload_defaults or {}
+    defaults = deepcopy(payload_defaults or {})
+    sequence_mode = isinstance(defaults.get("sequence"), dict)
+    if sequence_mode and not carousel_items:
+        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")
 
     # ── Build assets from carousel_items ──────────────────────────────────
     assets = []
@@ -822,7 +852,9 @@ def _build_carousel_caption_dsl(
     for idx, url in enumerate(carousel_items):
         asset_id = f"carousel-img-{idx + 1:02d}"
         # Determine if URL is a video (basic heuristic on extension)
-        is_video = any(url.lower().endswith(ext) for ext in (".mp4", ".mov", ".webm", ".avi"))
+        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")
         assets.append({
             "assetId": asset_id,
             "type": "video" if is_video else "image",
@@ -889,6 +921,18 @@ def _build_carousel_caption_dsl(
         if defaults.get(key):
             custom_payload[key] = defaults[key]
 
+    # The carousel-caption capability also covers full-frame image sequences.
+    # Its declared sequence defaults select that payload shape; do not send
+    # carousel entrance/exit or a typewriter caption block to such components.
+    if sequence_mode:
+        sequence_config = defaults["sequence"]
+        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)
+        ]
+        custom_payload = {"sequence": sequence_config}
+
     # ── Narration skeleton ────────────────────────────────────────────────
     narration_text = _localize_label(output_language, "narration_opening",
                                      label="", topic=topic, duration=duration)
@@ -898,6 +942,10 @@ def _build_carousel_caption_dsl(
     # 这是打字机/画面驱动模板的核心——没有旁白来"撑"时长，
     # 必须由 caption 自己定，否则文字打完后画面会静止到 targetDuration。
     effective_duration = duration
+    if duration_strategy == "fit-images":
+        if not sequence_mode:
+            raise ValueError("fit-images requires capabilities.payloadDefaults.sequence")
+        effective_duration = _estimate_fit_images_duration(custom_payload["sequence"], duration_model)
     if duration_strategy == "fit-caption":
         est = _estimate_fit_caption_duration(custom_payload, duration_model, template_id)
         if est > 0:
@@ -1631,7 +1679,8 @@ Examples:
              "--carousel-items url1 --carousel-items url2. "
              "For templates declaring capabilities.payloadStyle=carousel-caption, "
              "these URLs are placed directly into "
-             "customPayload.carousel.items as existing assets, bypassing AI image generation entirely.",
+             "customPayload.sequence.items when payloadDefaults.sequence is declared, otherwise "
+             "customPayload.carousel.items, as existing assets without AI image generation.",
     )
     parser.add_argument(
         "--scene-images",
@@ -1654,7 +1703,8 @@ Examples:
         help="On-screen caption line. Can be repeated: "
              "--caption-lines 'line1' --caption-lines 'line2'. "
              "For templates declaring capabilities.payloadStyle=carousel-caption, "
-             "these are placed into customPayload.caption.lines. "
+             "these are placed into customPayload.caption.lines, or sequence.items[].caption "
+             "in image order when payloadDefaults.sequence is declared. "
              "Line count limits and whether **emphasis** is parsed are declared per "
              "template — see the chosen template's llmHint.",
     )

package/skills/gen-script/skill.json

@@ -61,7 +61,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 directly into customPayload.carousel.items as existing assets — NO AI image generation is triggered. **Must** pass when the user explicitly provides image/video URLs for such a template. Each element is a full URL string."
+        "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."
       },
       "scene_images": {
         "type": "array",
@@ -75,7 +75,7 @@
         "items": {
           "type": "string"
         },
-        "description": "On-screen caption lines for templates that declare a caption area (capabilities.payloadDefaults.caption). 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. 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",

package/skills/gen-script/version.json

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

@@ -2363,6 +2363,14 @@ Examples:
             LogPrint(f"❌ {exc}", file=sys.stderr)
             sys.exit(2)
 
+    from video_dsl.runtime.payload_contract import plan_asset_errors
+    reference_errors = plan_asset_errors(render_plan)
+    if reference_errors:
+        LogPrint("❌ RenderPlan asset references are invalid:", file=sys.stderr)
+        for error in reference_errors[:10]:
+            LogPrint(f"   - {error}", file=sys.stderr)
+        sys.exit(2)
+
     if not args.skip_asset_resolve:
         # Stub mode: short-circuit gen-image / gen-video before counting pending.
         # CLI flag takes precedence; env vars act as fallback with a visible warning

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

@@ -17,6 +17,8 @@ from pathlib import Path
 sys.path.insert(0, str(Path(__file__).resolve().parents[2] / "template-registry" / "scripts"))
 
 from countdown_spec import resolve_countdown_spec  # noqa: E402
+sys.path.insert(0, str(Path(__file__).resolve().parents[2] / "template-registry"))
+from video_dsl.runtime.payload_contract import required_payload_errors  # noqa: E402
 
 
 def _payload_prop(props: dict, key: str):
@@ -84,6 +86,7 @@ def validate_required_props(template: dict, rows: list[dict]) -> None:
         schema = template.get("customPayloadSchema") or {}
         missing = [error for key in sorted(required)
                    for error in _required_value_errors(_payload_prop(props, key), schema.get(key, {}), key)]
+        missing += required_payload_errors(template, props)
         if missing:
             failures.append(f"scene {row.get('sceneId', '?')}: {', '.join(missing)}")
 

package/skills/render-video/version.json

@@ -2,6 +2,6 @@
   "skillName": "render-video",
   "repoName": "agent-skill-media-maker",
   "skillId": "473",
-  "version": "V23",
+  "version": "V24",
   "skillDescription": "Final-render skill: loads a persisted RenderPlan by `job_id` and drives the Remotion engine to produce the final video.\n\nUse this skill as soon as the user mentions any of these intents (after assets are already prepared):\n- Render the video, composite the video, export the video\n- Turn the prepared assets into the final clip\n- Render with Remotion\n\nPrerequisite: assets must already be generated via `prepare_video_assets`. This skill never resolves or regenerates assets — pass it a `job_id` from a previous `prepare_video_assets` call.\n\n⚠️ Stop-and-confirm gate: never call this skill until the user has explicitly confirmed the assets prepared by `prepare_video_assets`. If those assets were prepared in the current turn and the user has not replied since, stop and ask instead of rendering."
 }

package/skills/template-registry/version.json

@@ -2,6 +2,6 @@
   "skillName": "template-registry",
   "repoName": "agent-skill-media-maker",
   "skillId": "475",
-  "version": "V15",
+  "version": "V16",
   "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

@@ -300,29 +300,17 @@ def _check_asset_enums(dsl: dict) -> list[ValidationError]:
 def _check_scene_asset_refs(dsl: dict) -> list[ValidationError]:
     """render-video 历史:scene 引用的 assetRef 必须在 assets[] 声明过。
 
-    检查范围:
-      - scene.audio.narration.assetRef
-      - scene.visuals.background.assetRef
+    包括 customPayload / templateData 中的嵌套 assetRef 与 global 引用。
     """
     errors: list[ValidationError] = []
     declared = {
         a.get("assetId") for a in (dsl.get("assets") or []) if a.get("assetId")
     }
-    for idx, scene in enumerate(dsl.get("scenes", []) or []):
-        sid = scene.get("id", f"scenes[{idx}]")
-        nar = (scene.get("audio") or {}).get("narration") or {}
-        nar_ref = nar.get("assetRef")
-        if nar_ref and nar_ref not in declared:
-            errors.append(ValidationError(
-                f"scenes[{idx}].audio.narration.assetRef",
-                f"scene '{sid}': narration.assetRef '{nar_ref}' not found in assets[]",
-            ))
-        bg_ref = ((scene.get("visuals") or {}).get("background") or {}).get("assetRef")
-        if bg_ref and bg_ref not in declared:
-            errors.append(ValidationError(
-                f"scenes[{idx}].visuals.background.assetRef",
-                f"scene '{sid}': visuals.background.assetRef '{bg_ref}' not found in assets[]",
-            ))
+    from .payload_contract import asset_references
+    for key in ("scenes", "global"):
+        for path, ref in asset_references(dsl.get(key), key):
+            if ref not in declared:
+                errors.append(ValidationError(path, "assetRef not found in assets[]"))
     return errors
 
 
@@ -742,14 +730,19 @@ def _check_custom_payload_fields(dsl: dict) -> list[ValidationError]:
     tpl = _get_template_cfg(_pick_template_id(dsl))
     if not tpl:
         return []
+    from .payload_contract import required_payload_errors
+    errors: list[ValidationError] = []
+    for idx, scene in enumerate(dsl.get("scenes", []) or []):
+        custom = scene.get("customPayload") or {"templateData": scene.get("templateData")}
+        errors += [ValidationError(f"scenes[{idx}].customPayload", message)
+                   for message in required_payload_errors(tpl, custom)]
     if isinstance(tpl.get("slideSchemas"), dict):
-        return []  # 多版式模板走 _check_slide_payload_fields
+        return errors  # 多版式字段走 _check_slide_payload_fields
     cps = tpl.get("customPayloadSchema")
     if not isinstance(cps, dict) or not cps:
-        return []
+        return errors
 
     root = {"type": "object", "properties": cps}
-    errors: list[ValidationError] = []
     for idx, scene in enumerate(dsl.get("scenes", []) or []):
         custom = scene.get("customPayload")
         if not isinstance(custom, dict) or not custom:
@@ -1054,4 +1047,3 @@ def validate_dsl(dsl: dict) -> list[ValidationError]:
     errors += _check_slide_cross_field(dsl)
     return errors
 
-

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

@@ -0,0 +1,82 @@
+"""Template-declared content requirements and recursive asset references.
+
+Shared by DSL preparation and saved RenderPlan validation. Requirements use a
+small JSON Schema subset; values never appear in diagnostic messages.
+"""
+
+
+def payload_values(props: dict) -> dict:
+    """Flatten templateData wrappers, with non-null outer props taking precedence."""
+    layers, seen = [], set()
+    while isinstance(props, dict) and id(props) not in seen and len(layers) < 10:
+        layers.append(props)
+        seen.add(id(props))
+        props = props.get("templateData")
+    result = {}
+    for layer in reversed(layers):
+        result.update({k: v for k, v in layer.items() if k != "templateData" and v is not None})
+    return result
+
+
+def requirement_errors(value, schema: dict, path: str = "customPayload") -> list[str]:
+    """Enforce type/const/enum/required/properties/items/minItems/anyOf."""
+    errors = []
+    kind = schema.get("type")
+    matches = {"object": isinstance(value, dict), "array": isinstance(value, list),
+               "string": isinstance(value, str)}
+    if kind in matches and not matches[kind]:
+        return [f"{path} (expected {kind})"]
+    if "const" in schema and value != schema["const"]:
+        return [f"{path} (unexpected value)"]
+    if "enum" in schema and value not in schema["enum"]:
+        return [f"{path} (unexpected value)"]
+    if isinstance(value, dict):
+        for key in schema.get("required", []):
+            if value.get(key) is None or value.get(key) == "":
+                errors.append(f"{path}.{key} (required)")
+        for key, child in schema.get("properties", {}).items():
+            if key in value:
+                errors += requirement_errors(value[key], child, f"{path}.{key}")
+    if isinstance(value, list):
+        if len(value) < schema.get("minItems", 0):
+            errors.append(f"{path} (too few items)")
+        if "items" in schema:
+            for index, item in enumerate(value):
+                errors += requirement_errors(item, schema["items"], f"{path}[{index}]")
+    if "anyOf" in schema:
+        branches = [requirement_errors(value, branch, path) for branch in schema["anyOf"]]
+        if not branches or all(branches):
+            alternatives = " OR ".join("; ".join(branch) for branch in branches)
+            errors.append(f"{path} must satisfy one content alternative: {alternatives}")
+    return errors
+
+
+def required_payload_errors(template: dict, props: dict) -> list[str]:
+    caps = template.get("capabilities")
+    schema = caps.get("payloadRequirements") if isinstance(caps, dict) else None
+    return requirement_errors(payload_values(props), schema) if isinstance(schema, dict) else []
+
+
+def asset_references(value, path: str = "", *, bound_props: bool = False):
+    """Walk nested assetRef fields; bound props also use *AssetId names."""
+    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 isinstance(child, str) and child.strip():
+                    yield child_path, child
+            else:
+                yield from asset_references(child, child_path, bound_props=bound_props)
+
+
+def plan_asset_errors(plan: dict) -> list[str]:
+    declared = {asset.get("assetId") for asset in plan.get("resolvedAssets", []) if isinstance(asset, dict)}
+    errors = []
+    for index, row in enumerate(plan.get("timeline", [])):
+        for path, ref in asset_references(row.get("props", {}), f"timeline[{index}].props", bound_props=True):
+            if ref not in declared:
+                errors.append(f"{path} references an asset missing from resolvedAssets[]")
+    return errors