@remixmate/cli 0.9.5 → 0.9.7

package/skills/export-jianying/SKILL.md

@@ -37,7 +37,7 @@ There is no dedicated env file; the **process environment** variables of the cal
 | Env var | Description | Default |
 |---------|-------------|---------|
 | `PRIV_TOKEN` | Tianyan token; overridable with `--priv-token`. | (none) |
-| `MM_API_BASE_URL` | API root URL. | `http://localhost:3001/api` |
+| `MM_API_BASE_URL` | API root URL. | `https://api-agent.remixmate.com/api` |
 | `AGENT_NAME` | Optional, sent as the `x-invoke-agent` request header. | (none) |
 
 ## Steps

package/skills/export-jianying/scripts/gen_jianying_draft.py

@@ -13,7 +13,7 @@
   python gen_jianying_draft.py --title "测试" --scenes scenes.json --download -o draft.zip
 
 环境变量:
-  MM_API_BASE_URL                - 后端 API 地址（默认: http://localhost:3001/api）
+  MM_API_BASE_URL                - 后端 API 地址（默认: https://api-agent.remixmate.com/api）
   PRIV_TOKEN                     - PrivToken（优先读取；未配置时提示手动输入）
 """
 
@@ -30,7 +30,7 @@ import urllib.request
 import uuid
 import zipfile
 
-API_BASE_URL = os.environ.get("MM_API_BASE_URL", "http://localhost:3001/api")
+API_BASE_URL = os.environ.get("MM_API_BASE_URL", "https://api-agent.remixmate.com/api")
 PRIVATE_TOKEN = ""  # 在 main() 中通过 resolve_token() 初始化
 SKILL_NAME = "export-jianying"
 AGENT_NAME = os.environ.get("AGENT_NAME", "")

package/skills/gen-digital-human/SKILL.md

@@ -44,7 +44,7 @@ No skill-local env file — the executing process inherits the system environmen
 | Env var | Description | Default |
 |---------|-------------|---------|
 | `PRIV_TOKEN` | Tianyan token; `--priv-token` overrides | none |
-| `MM_API_BASE_URL` | API root; `--api-base-url` overrides | `http://localhost:2999/api` |
+| `MM_API_BASE_URL` | API root; `--api-base-url` overrides | `https://api.remixmate.com/api` |
 | `AGENT_NAME` | Optional `x-invoke-agent` header | none |
 
 ## Operations

package/skills/gen-image/SKILL.md

@@ -46,7 +46,7 @@ No skill-local env file — the executing process inherits the system environmen
 |---------|-------------|---------|
 | `PRIV_TOKEN` | Tianyan token; `--priv-token` overrides | none |
 | `MM_IMAGE_MODEL` | Default model id | `doubao/doubao-seedream-4-5-251128` |
-| `MM_API_BASE_URL` | API root; `--api-base-url` overrides | `http://localhost:2999/api` |
+| `MM_API_BASE_URL` | API root; `--api-base-url` overrides | `https://api.remixmate.com/api` |
 | `AGENT_NAME` | Optional `x-invoke-agent` header | none |
 
 ## Operations

package/skills/gen-script/SKILL.md

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

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

@@ -842,6 +842,25 @@ def build_dsl(
             f"ℹ️  contract: payloadStyle=carousel-caption for template {template_id}",
             file=sys.stderr,
         )
+        # 兜底校验：carousel-caption 模板的画面由 carousel_items（图片/视频 URL）驱动，
+        # 文字由 caption_lines 驱动。两者皆空时会生成一个空轮播 + 空字幕的退化场景——
+        # 渲染出来就是「黑屏 + fit-caption 退化成最短 2s」。这是调用方（agent）忘了
+        # 把用户提供的图片塞进 --carousel-items 的典型表现，必须显式报错而不是静默产出。
+        if not (carousel_items or []) and not (caption_lines or []):
+            print(
+                "❌ carousel-caption template "
+                f"'{template_id}' needs visual or text content, but received neither "
+                "--carousel-items nor --caption-lines.\n"
+                "   This template renders a carousel of user-supplied media; with no items "
+                "it produces a black, minimum-length (2s) clip.\n"
+                "   Fix: pass the user's image/video URLs via --carousel-items "
+                "(repeat the flag per item), e.g.\n"
+                "     gen_script.py --topic <topic> --template-id "
+                f"{template_id} --carousel-items <url1> --carousel-items <url2> ...\n"
+                "   Optionally add --caption-lines '<text>' for on-screen typewriter captions.",
+                file=sys.stderr,
+            )
+            sys.exit(1)
         return _build_carousel_caption_dsl(
             template_id=template_id,
             topic=topic,

package/skills/gen-video/SKILL.md

@@ -60,7 +60,7 @@ No skill-local env file — the executing process inherits the system environmen
 |---------|-------------|---------|
 | `PRIV_TOKEN` | Tianyan token; `--priv-token` overrides | none |
 | `MM_VIDEO_MODEL` | Default model id | `doubao-seedance-1-5-pro-251215` |
-| `MM_API_BASE_URL` | API root; `--api-base-url` overrides | `http://localhost:2999/api` |
+| `MM_API_BASE_URL` | API root; `--api-base-url` overrides | `https://api.remixmate.com/api` |
 | `AGENT_NAME` | Optional `x-invoke-agent` header | none |
 
 ## Operations

package/skills/gen-voice/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: gen-voice
 description: |
-  Text-to-speech (TTS) skill: synthesize narration audio from text via ab-api's `/tool/minimaxT2aV2` endpoint (Minimax TTS).
+  Text-to-speech (TTS) skill: synthesize narration audio from text via ab-api's unified `/tool/tts` endpoint with `provider: "minimax"` (Minimax TTS).
 
   Use this skill immediately whenever the user asks for any of:
   - AI voice-over, TTS, text-to-speech, generate narration audio
@@ -17,7 +17,7 @@ triggers:
 
 # Text-to-Speech (TTS) Skill
 
-Wraps ab-api's `POST /tool/minimaxT2aV2` (the same endpoint the web studio uses), authenticated with the **Tianyan privateToken**, backed by the **Minimax TTS** model.
+Wraps ab-api's unified `POST /tool/tts` with `provider: "minimax"` (the same endpoint the web studio uses), authenticated with the **Tianyan privateToken**, backed by the **Minimax TTS** model.
 
 ## Auth & environment
 
@@ -29,7 +29,7 @@ There is no skill-local env file — the executing process inherits the system e
 | Env var | Description | Default |
 |---------|-------------|---------|
 | `PRIV_TOKEN` | Tianyan token; `--priv-token` overrides | none |
-| `MM_API_BASE_URL` | API root; `--api-base-url` overrides | `http://localhost:2999/api` |
+| `MM_API_BASE_URL` | API root; `--api-base-url` overrides | `https://api.remixmate.com/api` |
 | `AGENT_NAME` | Optional `x-invoke-agent` header | none |
 
 ## Operations

package/skills/gen-voice/version.json

@@ -3,5 +3,5 @@
   "repoName": "agent-skill-media-maker",
   "skillId": "338",
   "version": "V7",
-  "skillDescription": "语音合成（TTS）技能，将文字转为语音音频（调用 ab-api /tool/minimaxT2aV2，基于 Minimax TTS）。\n\n当用户提到以下任何需求时，立即使用本 skill：\n- AI 配音、语音合成、文字转语音、TTS、文本转音频、生成语音\n- 使用 minimax 语音合成\n- 用户想要将一段文字朗读出来、生成音频\n\n即使用户没有明确说「使用 AI」，只要他们想要将文字转为语音，也要使用本 skill。"
+  "skillDescription": "语音合成（TTS）技能，将文字转为语音音频（调用 ab-api 统一 /tool/tts，provider=minimax，基于 Minimax TTS）。\n\n当用户提到以下任何需求时，立即使用本 skill：\n- AI 配音、语音合成、文字转语音、TTS、文本转音频、生成语音\n- 使用 minimax 语音合成\n- 用户想要将一段文字朗读出来、生成音频\n\n即使用户没有明确说「使用 AI」，只要他们想要将文字转为语音，也要使用本 skill。"
 }

package/skills/prepare-video-assets/SKILL.md

@@ -54,8 +54,8 @@ The asset resolver invokes the following skills based on `AssetRef` declarations
 | Env var | Description | Default |
 |---------|-------------|---------|
 | `PRIV_TOKEN` | Tianyan token (needed for asset generation + DB persist). | (none) |
-| `MM_API_BASE_URL` | Asset-generation API root (ab-agent proxy). | `http://localhost:3001/api` |
-| `MM_BACKEND_API_URL` | Backend API root (RenderPlan persistence). | `http://localhost:2999/api` |
+| `MM_API_BASE_URL` | Asset-generation API root (ab-agent proxy). | `https://api-agent.remixmate.com/api` |
+| `MM_BACKEND_API_URL` | Backend API root (RenderPlan persistence). | `https://api.remixmate.com/api` |
 | `ASSET_CACHE_DIR` | Asset cache directory. | `./.asset-cache/` |
 
 ## Canonical usage (inline DSL JSON, no temp files)

package/skills/render-video/SKILL.md

@@ -49,8 +49,8 @@ Rendering supports two modes:
 | Env var | Description | Default |
 |---------|-------------|---------|
 | `PRIV_TOKEN` | Tianyan token (needed to load the RenderPlan from the DB and to upload). | (none) |
-| `MM_BACKEND_API_URL` | Backend API root URL (RenderPlan / VOD lookups). | `http://localhost:2999/api` |
-| `REMOTION_RENDER_API_URL` | Remote renderer base URL (ab-render). | `http://localhost:3000` |
+| `MM_BACKEND_API_URL` | Backend API root URL (RenderPlan / VOD lookups). | `https://api.remixmate.com/api` |
+| `REMOTION_RENDER_API_URL` | Remote renderer base URL (ab-render). | `https://api-render.remixmate.com` |
 | `REMOTION_RENDER_MODE` | Default render mode (`remote` / `local`); CLI `--renderer` overrides it. | `remote` |
 | `REMOTION_OUTPUT_DIR` | Render output directory. | `./output/` |
 | `REMOTION_CONCURRENCY` | Local Remotion render concurrency. | `2` |
@@ -194,8 +194,8 @@ If the remote service is unreachable or auth fails, the script exits with a deta
 The Remotion render project lives at the monorepo root under `<monorepo-root>/remotion-renderer/` and is deployed as a **standalone HTTP service**. The client script in this skill only sends POST requests and does not participate in server-side code sync.
 
 - Server code + deployment docs: `<monorepo-root>/remotion-renderer/README.md`.
-- Local debugging: in the renderer directory run `npm install && npm run server:dev`; the client defaults to `http://localhost:3000`.
-- Production: set `REMOTION_RENDER_API_URL` to the production base URL.
+- Production (default): the client uses `https://api-render.remixmate.com` when `REMOTION_RENDER_API_URL` is unset — no config needed.
+- Local debugging: in the renderer directory run `npm install && npm run server:dev`, then point the client at it with `REMOTION_RENDER_API_URL=http://localhost:3000`.
 
 ## Error handling
 

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

@@ -59,7 +59,10 @@ def _query_duration_from_api(url: str) -> Optional[float]:
     if not media_id:
         return None
 
-    api_base = os.environ.get("MM_API_BASE_URL", os.environ.get("MM_BACKEND_API_URL", "")).rstrip("/")
+    api_base = os.environ.get(
+        "MM_API_BASE_URL",
+        os.environ.get("MM_BACKEND_API_URL", "https://api.remixmate.com/api"),
+    ).rstrip("/")
     if not api_base:
         return None
 

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

@@ -40,7 +40,7 @@ def poll_vod_playback_url(
       - 看到阿里云 OSS 直链时记为 fallback，继续等 CDN
       - 超时仍未拿到 CDN 时退回到 OSS 原始地址
     """
-    api_base = os.environ.get("MM_BACKEND_API_URL", "http://localhost:2999/api").rstrip("/")
+    api_base = os.environ.get("MM_BACKEND_API_URL", "https://api.remixmate.com/api").rstrip("/")
     url = f"{api_base}/file/get"
     headers = {
         "Content-Type": "application/json",

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

@@ -18,8 +18,8 @@
 
 Base URL 优先级：
   1. 调用方显式传入 base_url
-  2. 环境变量 REMOTION_RENDER_API_URL
-  3. 默认 http://localhost:3000（与 server/config.ts 的 PORT 默认值一致，方便本地调试）
+  2. 环境变量 REMOTION_RENDER_API_URL（指向本地/staging 时在此覆盖）
+  3. 默认 https://api-render.remixmate.com（生产，零配置可用）
 
 本模块只负责 HTTP 层；调用方（render_video.py）负责把结果写回 render_plan。
 """
@@ -35,7 +35,7 @@ import urllib.parse
 import urllib.request
 from typing import Callable, Optional
 
-DEFAULT_API_BASE_URL = "http://localhost:3000"
+DEFAULT_API_BASE_URL = "https://api-render.remixmate.com"
 API_BASE_URL = (os.environ.get("REMOTION_RENDER_API_URL") or DEFAULT_API_BASE_URL).strip()
 SKILL_NAME = "render-video"
 AGENT_NAME = os.environ.get("AGENT_NAME", "")

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

@@ -1646,6 +1646,11 @@ def render_with_remote_api(
             "upload": True,
             "uploadTitle": effective_title,
         }
+        # 私有模板封面：传 coverCompositionId 让 /renderDraft 渲模板自带 cover 组件
+        # （ab-render 注册了 DraftCover），与内置 /render 的 MainCover 对等；
+        # 不传则 ab-render 退回截首帧 / 不渲。
+        if cover_composition_id:
+            payload["coverCompositionId"] = cover_composition_id
         render_path = "/renderDraft"
         status_path = "/renderDraftStatus"
     else:
@@ -1666,7 +1671,7 @@ def render_with_remote_api(
         LogPrint(f"   Private template (OSS dynamic bundle): {template_id}", file=sys.stderr)
     else:
         LogPrint(f"   Composition: {composition_id}", file=sys.stderr)
-    if cover_composition_id and not source_oss_key:
+    if cover_composition_id:
         LogPrint(f"   Cover: {cover_composition_id}", file=sys.stderr)
     LogPrint(f"   size: {config.get('width')}x{config.get('height')}", file=sys.stderr)
     LogPrint(f"   total frames: {total_frames}", file=sys.stderr)

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

@@ -13,7 +13,7 @@
   python3 upload_video.py --file output/video.mp4 --json-output
 
 环境变量:
-  MM_API_BASE_URL - API 根地址（默认 MM_API_BASE_URL 环境变量或 http://localhost:3001/api）
+  MM_API_BASE_URL - API 根地址（默认 MM_API_BASE_URL 环境变量或 https://api-agent.remixmate.com/api）
 
 注意:
   - `uploadMediaFile` 接口视频大小限制 ≤ 50MB，音频 ≤ 15MB
@@ -31,7 +31,7 @@ import urllib.parse
 import urllib.request
 import uuid
 
-# DEFAULT_API_BASE_URL = "http://localhost:3001/api"
+DEFAULT_API_BASE_URL = "https://api-agent.remixmate.com/api"
 
 
 def _guess_content_type(file_path: str) -> str:
@@ -164,7 +164,7 @@ def main():
     parser.add_argument(
         "--api-base-url",
         default=None,
-        help="API root URL (defaults to MM_API_BASE_URL env var or http://localhost:3001/api)",
+        help="API root URL (defaults to MM_API_BASE_URL env var or https://api-agent.remixmate.com/api)",
     )
     parser.add_argument("--timeout", type=int, default=600, help="Upload timeout in seconds (default 600)")
     parser.add_argument("--json-output", action="store_true", help="Emit the full response as JSON on stdout")

package/skills/template-registry/README.md

@@ -9,7 +9,7 @@ CLI 暴露面是「列出可用模板」(`--list-templates`)。把 Video DSL 场
 | 来源 | 触发条件 | 适用场景 |
 |---|---|---|
 | 显式 `VIDEO_TEMPLATE_REGISTRY_URL`（ab-api 接口） | 环境变量非空 + `PRIV_TOKEN` 有效 | 指定后端 |
-| 派生默认 URL `<MM_API_BASE_URL>/remotionTemplate/registry` | `VIDEO_TEMPLATE_REGISTRY_URL` 未设置 | 默认（含独立安装 codex / `npm i -g`，默认 `http://localhost:2999/api`） |
+| 派生默认 URL `<MM_API_BASE_URL>/remotionTemplate/registry` | `VIDEO_TEMPLATE_REGISTRY_URL` 未设置 | 默认（含独立安装 codex / `npm i -g`，默认 `https://api.remixmate.com/api`） |
 
 只从 ab-api 取数，是为了避免「本地文件 / monorepo 源码 / 数据库」多源并存导致的不一致——私有 / 多租户模板只存在于 ab-api，本地源永远不全。默认 URL **内置在 remixmate-cli 自身**（按 CLI 后端约定 `MM_API_BASE_URL` 推导），不再依赖 ab-agent 等宿主在 spawn 时注入，独立运行即可找到 registry。指向你自己的 ab-api 只需设 `MM_API_BASE_URL`（或直接设 `VIDEO_TEMPLATE_REGISTRY_URL`）并配置 `PRIV_TOKEN`。
 

package/skills/template-registry/SKILL.md

@@ -63,12 +63,12 @@ The skill itself only reads the registry; whether a token is needed depends on t
 | Env var | Description | Default |
 |---------|-------------|---------|
 | `VIDEO_TEMPLATE_REGISTRY_URL` | ab-api endpoint returning the registry (the single source of truth). | derived from `MM_API_BASE_URL` |
-| `MM_API_BASE_URL` | ab-api base URL the CLI talks to. When `VIDEO_TEMPLATE_REGISTRY_URL` is unset, the registry endpoint is derived as `<base>/remotionTemplate/registry`. | `http://localhost:2999/api` |
+| `MM_API_BASE_URL` | ab-api base URL the CLI talks to. When `VIDEO_TEMPLATE_REGISTRY_URL` is unset, the registry endpoint is derived as `<base>/remotionTemplate/registry`. | `https://api.remixmate.com/api` |
 | `PRIV_TOKEN` | Sent as `X-Priv-Token` when hitting the registry endpoint. Falls back to `~/.config/remixmate/credentials.json`. | unset |
 | `VIDEO_TEMPLATE_REGISTRY_HTTP_METHOD` | `POST` (default) or `GET`. POST shape matches ab-api `{code,msg,data}`. | `POST` |
 
 Resolution (single source — see `scripts/registry_loader.py` for the canonical implementation):
-the registry is loaded **only** from the ab-api HTTP endpoint — explicit `VIDEO_TEMPLATE_REGISTRY_URL`, otherwise `<MM_API_BASE_URL>/remotionTemplate/registry` (default `http://localhost:2999/api/...`). There is no local-file / monorepo / PREFER_LOCAL fallback: those multi-source paths were removed to avoid registry skew (private/multi-tenant templates only exist on ab-api). On a transient HTTP failure the loader degrades to the on-disk cache of the same URL; with no cache it fails loud. A standalone install (Codex / `npm i -g`) just needs `MM_API_BASE_URL` (or `VIDEO_TEMPLATE_REGISTRY_URL`) pointed at your ab-api plus a valid `PRIV_TOKEN`.
+the registry is loaded **only** from the ab-api HTTP endpoint — explicit `VIDEO_TEMPLATE_REGISTRY_URL`, otherwise `<MM_API_BASE_URL>/remotionTemplate/registry` (default `https://api.remixmate.com/api/...`). There is no local-file / monorepo / PREFER_LOCAL fallback: those multi-source paths were removed to avoid registry skew (private/multi-tenant templates only exist on ab-api). On a transient HTTP failure the loader degrades to the on-disk cache of the same URL; with no cache it fails loud. A standalone install (Codex / `npm i -g`) just needs `MM_API_BASE_URL` (or `VIDEO_TEMPLATE_REGISTRY_URL`) pointed at your ab-api plus a valid `PRIV_TOKEN`.
 
 ## Steps
 
@@ -149,7 +149,7 @@ print(json.dumps(binding, ensure_ascii=False, indent=2))
 | Comes from a scene-level custom field whose name matches a prop directly | put it in `customPayload.<propName>` | `customPayload.slideId`, `customPayload.background`, `customPayload.bullets` |
 | Structured data internal to the template (arrays, sub-objects, etc.) | use `customPayload.templateData.*` | `templateData.concepts`, `templateData.items` (shared by feature-grid / timeline / column-compare) |
 
-**Common pitfall**: writing the same field in both `propExtractors` and `customPayload` — when they collide, `propExtractors` wins. Keep each field in exactly one place.
+**Common pitfall**: writing the same field in both `propExtractors` and `customPayload` — when they collide, `propExtractors` wins. Keep each field in exactly one place. `build_binding` now **detects this**: any prop name that is both declared in `propExtractors` and hit by `customPayload` pass-through (top-level, or `templateData` when the extractor reads from elsewhere) is recorded on the binding row as `dualChannelProps` and printed as a stderr warning; `test-template-pipeline.py` surfaces it as a non-fatal authoring warning. A field placed in its extractor's own declared source (e.g. extractor `from:"templateData.slideId"` + value in `templateData.slideId`) is **not** flagged — that is the legitimate source, not a double-write.
 
 > Historical issue: an early html-slide `point` slot declared `slideId` as `propExtractors.slideId={from:"templateData.slideId"}` and also marked it as `requiredProps`. But every existing DSL wrote `slideId` at `customPayload.slideId` (top-level, not inside templateData), so the propExtractor returned nothing and rendering fell back to the generic layout. The convention now is unified: **slideId flows through customPayload top-level pass-through**, propExtractors no longer declares it. New templates must follow the same convention.
 

package/skills/template-registry/scripts/check_contracts.py

@@ -152,31 +152,14 @@ def main() -> int:
             file=sys.stderr,
         )
 
-    # P1.1 nudge (warning only): compositionId should be prefixed with
-    # `<templateId>/` so the 300-400 names we'll have at 100+ templates can't
-    # collide in the flat global namespace. The actual migration touches
-    # remotion-renderer/manifest.ts and every template.json, so we ship the
-    # warning first to surface the gap without breaking builds.
-    unprefixed: list[tuple[str, str]] = []
-    for ref in refs:
-        cid = ref["compositionId"]
-        tid = ref["templateId"]
-        expected_prefix = f"{tid}/"
-        # Allow either `<tid>/Cover` or `<tid>.Cover` (TS member access form).
-        if not (cid.startswith(expected_prefix) or cid.startswith(f"{tid}.")):
-            unprefixed.append((tid, cid))
-    if unprefixed:
-        print(
-            "WARN (P1.1): the following compositionIds are not prefixed with their "
-            "templateId — at 100+ templates this flat namespace will collide. "
-            "Migration plan: rename `<cid>` to `<templateId>/<cid>` in both "
-            "template.json and remotion-renderer/manifest.ts.",
-            file=sys.stderr,
-        )
-        for tid, cid in unprefixed[:10]:
-            print(f"  - {tid}: '{cid}' → suggested '{tid}/{cid}'", file=sys.stderr)
-        if len(unprefixed) > 10:
-            print(f"  ... ({len(unprefixed)} total)", file=sys.stderr)
+    # 命名空间唯一性说明：compositionId 是否全库唯一，由 template-library 的
+    # generateManifest 在生成 manifest.ts 时保障（跨模板撞名直接抛
+    # DuplicateCompositionIdError、CI 失败）。manifest.ts 因此按构造即唯一，
+    # 本脚本读取的已是去重结果，无需再校验唯一性。
+    #
+    # （已移除早期 P1.1 的 `<templateId>/` 前缀 warning：权威 schema 的
+    # compositionId pattern 为 PascalCase `^[A-Z][A-Za-z0-9]*$`，本就禁止 `/`，
+    # 前缀建议与 schema 矛盾且非必需——唯一性已由上游硬保障。）
 
     if errors:
         print("FAIL: contract check found inconsistencies:", file=sys.stderr)

package/skills/template-registry/scripts/match_template.py

@@ -14,6 +14,7 @@ sibling 的 `list_templates.py` 实现（它复用 registry_loader 的统一加
 """
 
 from registry_loader import load_registry_data
+import sys
 
 
 def load_registry() -> list:
@@ -105,6 +106,30 @@ def build_binding(template: dict, dsl: dict) -> dict:
         # 字幕」兜底样式，所有场景看起来都是同一个布局。
         custom = scene.get("customPayload") or {}
         template_data = custom.get("templateData") or scene.get("templateData") or {}
+
+        # 脆弱点 3：双通道冲突检测。同一字段名既声明在 slot 的 propExtractors，
+        # 又被 customPayload 的全字段透传命中时，来源二义：propExtractors 永远赢
+        # （下面 `k not in props` 透传），但如果 extractor 返回 None、值又恰好在
+        # payload 里，作者会误以为"是 payload 生效"，反之亦然。html-slide 的
+        # slideId 事故正是此类——extractor 读 `templateData.slideId`，DSL 却把值
+        # 写在 `customPayload.slideId` 顶层。
+        #
+        # 仅标记**真正的位置冲突**，避开误报：当 extractor 的 `from` 恰好指向
+        # `templateData.<同名>` 时，templateData 里出现该字段是它的**法定来源**，
+        # 不算"写错位置"，跳过。其余命中（顶层透传、或 templateData 透传但 extractor
+        # 从别处取值）才算冲突。只记录 + warning，不改透传行为；CI 的
+        # test-template-pipeline.py 据此浮出去重提示。
+        extractors = slot_def.get("propExtractors", {}) or {}
+        top_keys = {k for k in custom.keys() if k != "templateData"}
+        dual_channel = []
+        for k in extractors:
+            collides_top = k in top_keys
+            extractor_from = (extractors.get(k) or {}).get("from", "")
+            collides_td = k in template_data and extractor_from != f"templateData.{k}"
+            if collides_top or collides_td:
+                dual_channel.append(k)
+        dual_channel = sorted(dual_channel)
+
         # 先注入 templateData.* 再注入顶层 customPayload.*，让顶层覆盖同名值
         for k, v in template_data.items():
             if k not in props:
@@ -120,7 +145,15 @@ def build_binding(template: dict, dsl: dict) -> dict:
         entrance = anim.get("entrance", "fade")
         transition_type = entrance if entrance != "none" else "cut"
 
-        bindings.append({
+        # requiredProps 完整性：slotMapping 声明的 requiredProps 必须都已进 props。
+        # 这里只**记录**缺失（不抛错，保持渲染行为不变）；CI 的
+        # test-template-pipeline.py 据此断言「requiredProps 齐全」并 fail loud，
+        # 避免历史上「声明了 requiredProps 却静默缺失 → React 端回退通用布局」的事故
+        # （见 template-json-design.md 脆弱点 2）。是否升级为渲染前硬失败属后续决策。
+        required_props = slot_def.get("requiredProps") or []
+        missing_required = [p for p in required_props if p not in props]
+
+        binding_row = {
             "sceneId": scene_id,
             "slotId": slot_id,
             "compositionId": comp_id,
@@ -128,7 +161,18 @@ def build_binding(template: dict, dsl: dict) -> dict:
             "props": props,
             "transitionIn": {"type": transition_type, "durationFrames": 15},
             "transitionOut": {"type": "fade", "durationFrames": 15},
-        })
+        }
+        if missing_required:
+            binding_row["missingRequiredProps"] = missing_required
+        if dual_channel:
+            binding_row["dualChannelProps"] = dual_channel
+            print(
+                f"⚠️  双通道字段：scene={scene_id!r} slot={slot_id!r} 的 "
+                f"{dual_channel} 同时声明在 propExtractors 与 customPayload，"
+                f"propExtractors 优先。建议二选一，避免写错位置时静默取错值。",
+                file=sys.stderr,
+            )
+        bindings.append(binding_row)
 
     # P1.2: 不再做 screen-walkthrough 专属的截断 / 兜底。模板的 propExtractors
     # 已声明 titleText ← textLayers[role=headline]、projectName ← textLayers[role=subheadline]，
@@ -139,16 +183,16 @@ def build_binding(template: dict, dsl: dict) -> dict:
     motion = template.get("defaultMotionPreset", "smooth")
     colors = template.get("defaultColorScheme", [])
 
-    # --- variant selection ---
+    # --- variant selection（确定性）---
     # 优先级：
-    #   1) DSL 显式声明 — meta.templateVariant / renderHints.templateVariant
-    #   2) DSL meta.style / renderHints.brandColors 与 variant.styleTags 的子串/包含匹配
-    # 显式声明优先是因为：
-    #   - 风格名（如 "紫色科技"）在不同 variant 的 styleTags 里可能多义；
-    #   - meta.style 经常是一整串短语而非单 tag，旧的"逐 tag 拼成空格 → 子串匹配"
-    #     会被 split 后的整段短语漏过（例如 "紫色科技" 不是 "紫色 科技 purple ..."
-    #     的子串）。显式 templateVariant 让作者可以一锤定音。
+    #   1) DSL 显式声明 — meta.templateVariant / meta.variant / renderHints.templateVariant
+    #   2) meta.style 与 variant.styleTags 的**分级**匹配（精确 > 整段包含 > token 子串）
+    # 旧实现按 dict 遍历顺序「命中第一个」，多义时结果不稳定；现改为：
+    #   - 按 variant id 排序遍历（消除顺序依赖）；
+    #   - 取匹配等级最高（tier 数最小）的 variant；
+    #   - 同一最高等级有多个候选 → 记歧义、取排序首个，并把理由写进 variantReason。
     variant_id = None
+    variant_reason = None
     meta = dsl.get("meta", {}) or {}
     render_hints = dsl.get("renderHints", {}) or {}
     explicit_variant = (
@@ -160,31 +204,57 @@ def build_binding(template: dict, dsl: dict) -> dict:
 
     if explicit_variant and explicit_variant in variants:
         variant_id = explicit_variant
-    else:
-        # Fallback: 把 meta.style 拆成更细的 token（按逗号 / 空白 / 中英标点 / 单字）
-        # 再到 variant.styleTags 里找任一包含或被包含关系。这样 "紫色科技" 既能命中
-        # ["紫色","科技"] 这种细粒度 tag，也能命中 ["紫色科技"] 这种整段 tag。
+        variant_reason = "explicit"
+    elif variants:
         raw_style = (meta.get("style") or "").strip().lower()
         if raw_style:
-            # 整段 + 逗号/分号/空白拆分 + 单中文字符级 token，统一去重
-            style_tokens = {raw_style}
-            for sep in [",", "，", ";", "；", " ", "/", "·"]:
-                raw_style = raw_style.replace(sep, ",")
-            for tok in raw_style.split(","):
+            # token 化：整段 + 分隔符拆分 + 单中文字符级
+            s = raw_style
+            for sep in [",", "，", ";", "；", " ", "/", "·", "、"]:
+                s = s.replace(sep, ",")
+            tokens = set()
+            for tok in s.split(","):
                 tok = tok.strip()
                 if not tok:
                     continue
-                style_tokens.add(tok)
-                # 中文按字拆，命中如 "紫"/"色"/"科"/"技" 这种单字 tag 的场景
+                tokens.add(tok)
                 for ch in tok:
                     if "\u4e00" <= ch <= "\u9fff":
-                        style_tokens.add(ch)
-            for vid, variant in variants.items():
-                vtags = [str(t).strip().lower() for t in variant.get("styleTags", [])]
-                # 任一 tag 与任一 style token 互为子串即视为匹配
-                if any(any(tok in tag or tag in tok for tag in vtags) for tok in style_tokens if tok):
-                    variant_id = vid
-                    break
+                        tokens.add(ch)
+
+            # 为每个 variant 算最佳匹配等级（1 最强）
+            #   tier 1: 某 style token 与某 tag 完全相等
+            #   tier 2: 整段 raw_style 与某 tag 互为子串（整体短语级）
+            #   tier 3: 某 token 与某 tag 互为子串（细粒度，最宽松）
+            by_tier: dict = {}
+            for vid in sorted(variants.keys()):
+                vtags = [str(t).strip().lower() for t in (variants[vid].get("styleTags") or []) if str(t).strip()]
+                tier = None
+                if any(tok == tag for tok in tokens for tag in vtags):
+                    tier = 1
+                elif any((raw_style in tag) or (tag in raw_style) for tag in vtags):
+                    tier = 2
+                elif any((tok in tag) or (tag in tok) for tok in tokens for tag in vtags):
+                    tier = 3
+                if tier is not None:
+                    by_tier.setdefault(tier, []).append(vid)
+
+            if by_tier:
+                best_tier = min(by_tier.keys())
+                winners = by_tier[best_tier]  # 已按 vid 排序
+                variant_id = winners[0]
+                if len(winners) > 1:
+                    variant_reason = (
+                        f"style-match tier{best_tier} (ambiguous among {winners}; "
+                        f"picked '{variant_id}' by id order — 建议作者改用显式 meta.templateVariant)"
+                    )
+                    print(
+                        f"⚠️  variant 选择歧义：style={meta.get('style')!r} 在 tier{best_tier} "
+                        f"命中多个变体 {winners}，确定性取 '{variant_id}'。建议显式声明 meta.templateVariant。",
+                        file=sys.stderr,
+                    )
+                else:
+                    variant_reason = f"style-match tier{best_tier}"
 
     if variant_id and variant_id in variants:
         variant = variants[variant_id]
@@ -211,6 +281,8 @@ def build_binding(template: dict, dsl: dict) -> dict:
     }
     if variant_id:
         result["variantId"] = variant_id
+        if variant_reason:
+            result["variantReason"] = variant_reason
     return result
 
 

package/skills/template-registry/scripts/registry_loader.py

@@ -15,7 +15,7 @@
     1. 显式 VIDEO_TEMPLATE_REGISTRY_URL（若设置则直接用）
     2. 否则按 CLI 后端约定推导：
          <MM_API_BASE_URL>/remotionTemplate/registry
-       MM_API_BASE_URL 默认 http://localhost:2999/api（与 src/http.ts 一致），
+       MM_API_BASE_URL 默认 https://api.remixmate.com/api（与 src/http.ts 一致），
        兼容 ab-agent 注入的 MM_BACKEND_API_URL。默认值内置在 CLI 自身，独立安装
        （codex / npm i -g）开箱即用，无需宿主在 spawn 时注入。
 
@@ -71,7 +71,7 @@ _CACHE_DIR = os.environ.get(
 
 
 # CLI 默认后端 base，与 remixmate-cli/src/http.ts 的 DEFAULT_API_BASE_URL 保持一致。
-_DEFAULT_API_BASE_URL = "http://localhost:2999/api"
+_DEFAULT_API_BASE_URL = "https://api.remixmate.com/api"
 
 
 def _default_registry_url() -> str:
@@ -83,7 +83,7 @@ def _default_registry_url() -> str:
     base 解析顺序与 CLI / ab-agent 对齐：
       MM_API_BASE_URL（CLI ``src/http.ts`` 约定）
         → MM_BACKEND_API_URL（ab-agent 约定，向后兼容）
-        → http://localhost:2999/api（本地 dev 兜底）
+        → https://api.remixmate.com/api（生产默认，零配置）
     路径段固定为 ``/remotionTemplate/registry``（POST，返回 ``{code,msg,data}``）。
     """
     base = (

package/skills/template-registry/scripts/render_job_client.py

@@ -6,7 +6,7 @@ render_job_client.py — ab-api renderJob 接口 Python 客户端
 gen_jianying_draft.py 使用。
 
 认证方式: X-Priv-Token header（与其他 skill 脚本一致）
-接口地址: 由环境变量 MM_BACKEND_API_URL 控制（默认 http://localhost:2999/api）
+接口地址: 由环境变量 MM_BACKEND_API_URL 控制（默认 https://api.remixmate.com/api）
 """
 
 import json
@@ -17,7 +17,7 @@ import urllib.request
 
 
 def _api_base() -> str:
-    return os.environ.get("MM_BACKEND_API_URL", "http://localhost:2999/api").rstrip("/")
+    return os.environ.get("MM_BACKEND_API_URL", "https://api.remixmate.com/api").rstrip("/")
 
 
 def _make_headers(priv_token: str) -> dict: