@remixmate/cli 0.9.36 → 0.9.38

package/dist/handlers/gen-voice.js

@@ -88,13 +88,26 @@ export async function genVoice(input, ctxIn) {
     if (speed < voice.speedMin || speed > voice.speedMax) {
         throw new SkillError(`❌ speed must be in the range ${voice.speedMin}~${voice.speedMax}`);
     }
+    // Language hint for mixed-script narration. Like `local`, this is deliberately
+    // absent from skill.json's `parameters`: the service already applies a sane
+    // default for every caller, so handing the model a 40-value enum only invites
+    // it to guess. Reachable from the DSL (global/scene `narration.languageBoost`,
+    // forwarded by render_video) and by typing the flag yourself. Omitted =
+    // the service default.
+    const languageBoost = input.language_boost?.trim() || undefined;
     const ctx = await resolveHttpContext(ctxIn.skillName, {
         apiBaseUrl,
         privateToken: input.priv_token,
         preflightToken: ctxIn.auth?.token,
     });
     emitProgress({ phase: 'gen-voice:request', voiceId, speed });
-    const data = await mmPost(ctx, '/tool/tts', { provider: voice.provider, text, voiceSetting: { voiceId, speed }, outputFormat: 'url' }, { timeoutMs: 120_000 });
+    const data = await mmPost(ctx, '/tool/tts', {
+        provider: voice.provider,
+        text,
+        voiceSetting: { voiceId, speed },
+        outputFormat: 'url',
+        ...(languageBoost ? { languageBoost } : {}),
+    }, { timeoutMs: 120_000 });
     const audioUrl = data.audio;
     if (!audioUrl) {
         throw new SkillError(`❌ API response did not contain an audio URL: ${JSON.stringify(data)}`);

package/dist/manifest.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
-  "version": "0.9.36",
-  "generatedAt": "2026-09-20T05:40:23.517Z",
+  "version": "0.9.38",
+  "generatedAt": "2026-09-21T11:34:27.703Z",
   "skills": [
     {
       "id": "export-jianying",
@@ -350,18 +350,6 @@
             "type": "string",
             "description": "Video topic (required)"
           },
-          "platform": {
-            "type": "string",
-            "enum": [
-              "douyin",
-              "xiaohongshu",
-              "bilibili",
-              "wechat",
-              "youtube",
-              "generic"
-            ],
-            "description": "Target platform"
-          },
           "duration": {
             "type": "number",
             "description": "Target duration in seconds"
@@ -442,7 +430,6 @@
         ],
         "advanced": [],
         "hidden": [
-          "platform",
           "duration",
           "style",
           "ratio",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remixmate/cli",
-  "version": "0.9.36",
+  "version": "0.9.38",
   "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",
@@ -26,6 +26,7 @@
     "test:props-contract": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-props-contract.py",
     "test:card-array-keys": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-card-array-keys.py",
     "test:narration-speed": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-narration-speed.py",
+    "test:narration-tts": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-narration-tts.py",
     "test:render-resume": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-render-resume.py",
     "test:render-plan": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-render-plan-snapshot.py",
     "test:render-plan:update": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-render-plan-snapshot.py --update",

package/skills/gen-script/SKILL.md

@@ -171,7 +171,7 @@ The agent should show the following in clear Markdown:
 
 ### Video info
 - Topic: 3 AI study hacks
-- Platform: douyin | Aspect ratio: 9:16 | Estimated duration: 45s
+- Aspect ratio: 9:16 | Estimated duration: 45s
 
 ### Scene structure
 | # | Purpose | Duration | Narration |
@@ -374,7 +374,7 @@ Env vars `STUB_IMAGE_URL` / `STUB_VIDEO_URL` also work — their priority is low
 ## Steps
 
 1. **Script path**: read the system-injected `Base directory for this skill: <path>` as `<SkillDir>`. Every command below uses `<SkillDir>/scripts/gen_script.py`; never hard-code paths.
-2. **Understand the request**: extract topic, target platform, duration, style, audience, etc.
+2. **Understand the request**: extract topic, duration, style, audience, etc.
 3. **If the user specifies a template, read it first**: load the matching `template.json` via `template-registry` and confirm its template-specific fields and asset requirements. Do not skip this step.
 4. **Generate the DSL**: pick the right command or DSL shape for the target template (see the per-template commands below).
 5. **Schema validation**: make sure the output DSL conforms to v1alpha1.
@@ -385,7 +385,6 @@ Env vars `STUB_IMAGE_URL` / `STUB_VIDEO_URL` also work — their priority is low
 ```bash
 python3 <SkillDir>/scripts/gen_script.py \
   --topic "3 AI hacks that double your study efficiency" \
-  --platform douyin \
   --duration 30 \
   --style "tech" \
   --ratio "9:16"
@@ -416,7 +415,6 @@ python3 <SkillDir>/scripts/gen_script.py \
 | Flag | Description | Default |
 |------|-------------|---------|
 | `--topic` | Video topic (required unless `--validate`). | — |
-| `--platform` | Target platform: `douyin` / `xiaohongshu` / `bilibili` / `wechat` / `youtube` / `generic`. | `generic` |
 | `--headline` | On-screen main title (4–12 chars / ~3 words). Written to `meta.headline` + `textLayers[role=headline]`. **Pass it whenever the user gave a title** — otherwise headline falls back to the long-form topic and overflows the top text layer. | falls back to `--topic` |
 | `--subheadline` | On-screen subtitle / slogan. Written to `meta.subheadline` + `textLayers[role=subheadline]`. Multi-line via `\n`; how many lines survive and whether `**emphasis**` renders is declared per template — see its `llmHint`. Not the same thing as CC subtitles (`global.subtitle`). | `""` |
 | `--duration` | Target duration (seconds). Templates whose `durationStrategy` is `fit-caption` / `fit-narration` recompute the real duration and ignore this value. | `30` |
@@ -443,11 +441,22 @@ Apply the following principles when producing the DSL:
 1. **Narrative-first**: opening hook → point expansion → CTA close.
 2. **Assets are declared, not executed**: every asset starts as `AssetRef` with `status: planned`; no generation API call from this skill.
 3. **Narration drives duration**: each scene's duration should match its narration reading time (≈ 3–4 zh chars/sec, or ~2 words/sec for English).
-4. **Segment narration at subtitle granularity**: separate segments inside `audio.narration.text` with `\n`; each segment is 10–16 Chinese characters (or an equivalent number of English words). TTS returns per-line timestamps split on `\n`; the renderer uses them directly as subtitle cut points. Segments longer than 18 characters wrap awkwardly on screen; segments shorter than 6 flicker. Example:
+4. **One complete thought per line — do NOT pre-split at subtitle width.** Separate lines inside `audio.narration.text` with `\n`, and put **one full clause or sentence** on each line (roughly 15–30 Chinese characters, or an equivalent number of English words). A `\n` is a hard cut in the *audio*: TTS treats each line as its own segment and returns a timestamp for it, so lines should fall where a human would actually pause for breath.
+
+   **Do not cut mid-phrase to make lines "subtitle-sized".** The renderer splits each line into on-screen subtitles itself, and it does that better than you can from the text alone: it measures the real glyph widths for the actual font size and frame (`HNSW` is not as wide as four Chinese characters), knows how many characters fit on one line of *this* template and aspect ratio, and picks cut points by punctuation strength (sentence end → colon → comma → enumeration comma → space). It also guarantees no wrapping. Pre-splitting takes all of that away and just makes the captions choppy.
+
+   Measured on a shipped video (2026-09-21): narration written as 6–8 character lines produced 57 subtitle screens in 121.5s — a median of 2.10s each, 33% of them under 1.5s, with `AI Agent` alone on a screen. The renderer's own splitter never even fired.
+
+   Write:
    ```
-   "text": "Alibaba's open-source AI video-editing project\nalready has 4.3k stars on GitHub"
+   "text": "最近刷爆科技圈的 AI Agent 到底厉害在哪\n真正的分水岭不是文案更精准，而是自主执行能力"
    ```
-   instead of one continuous paragraph.
+   not:
+   ```
+   "text": "最近刷爆科技圈的\nAI Agent\n到底厉害在哪\n不是文案更精准\n也不是对话更流畅"
+   ```
+
+   **Use full-width punctuation in Chinese narration** (`，。：；？！`), not half-width (`,.:;?!`). Half-width punctuation in Chinese text renders with no trailing space — `第一步,目标感知:只给最终目标` reads cramped on screen.
 5. **Moderate scene count**: 30-second videos work well with 4–6 scenes, 60-second videos with 6–10.
 6. **Leave room for templates**: pick generic layouts; do not assume a specific template implementation.
 7. **Image model allowlist**: every `type: image` + `source: gen-image` `AssetRef`'s `payload.model` **must** be one of the values in the table below. **Never** use display names, short forms, or made-up ids (e.g. `seedream`, `seedream-5`, etc.).
@@ -474,7 +483,6 @@ prefix and version — not a short alias:
 
 - **Schema validation failed**: check the DSL JSON shape and required fields against the schema.
 - **Scene duration mismatch**: adjust the narration length or the scene duration.
-- **Invalid platform**: look at the supported-platform list.
 - **`carousel-caption template ... needs visual or text content`**: you passed neither `--carousel-items` nor `--caption-lines`. Pass the user's media URLs (and caption lines where the template requires them).
 - **`template ... is typewriter-driven ... but --caption-lines is empty`**: a `fit-caption` template got no caption. Write the copy yourself if the user did not supply it, then pass one `--caption-lines` per line.
 - **`duration Ns is below/above template ... supportedDurations`**: the assembled DSL falls outside the range the template declares it was designed for. Below the minimum usually means the content is too thin (add caption lines / narration / scenes); above the maximum means trimming content or lowering `--duration`. This is enforced at generation time on purpose — a degenerate video still costs full render credits.

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

@@ -3,8 +3,8 @@
 Video script generator — turns a topic into Video DSL v1alpha1 JSON.
 
 Default behavior:
-  Produces a structured Video DSL JSON to stdout based on the topic, platform,
-  duration, and other constraints.
+  Produces a structured Video DSL JSON to stdout based on the topic, duration,
+  and other constraints.
 
 Usage:
   python gen_script.py --topic "3 AI hacks that double study efficiency" --duration 30 --ratio "9:16"
@@ -56,7 +56,6 @@ try:
 except ImportError:
     _HAS_REGISTRY_LOADER = False
 
-VALID_PLATFORMS = ["douyin", "xiaohongshu", "bilibili", "wechat", "youtube", "generic"]
 VALID_RATIOS = ["16:9", "9:16", "1:1", "4:3", "3:4", "21:9"]
 VALID_PURPOSES = ["opening", "point", "example", "explanation", "highlight", "cta", "ending"]
 
@@ -761,7 +760,6 @@ def _build_carousel_caption_dsl(
     carousel_items: list[str],
     caption_lines: list[str],
     duration: int,
-    platform: str,
     style: str,
     ratio: str,
     resolution: str,
@@ -910,7 +908,6 @@ def _build_carousel_caption_dsl(
             "topic": topic,
             "headline": effective_headline,
             "subheadline": effective_subheadline,
-            "platform": platform,
             "targetDuration": effective_duration,
             "language": LANGUAGE_TO_META.get(output_language, "zh-CN"),
             "outputLanguage": output_language,
@@ -987,7 +984,6 @@ def _build_custom_payload(template_config: dict | None) -> dict:
 
 def build_dsl(
         topic: str,
-        platform: str,
         duration: int,
         style: str,
         ratio: str,
@@ -1124,7 +1120,6 @@ def build_dsl(
             carousel_items=carousel_items or [],
             caption_lines=caption_lines or [],
             duration=duration,
-            platform=platform,
             style=style,
             ratio=ratio,
             resolution=resolution,
@@ -1419,7 +1414,6 @@ def build_dsl(
             "topic": topic,
             "headline": effective_headline,
             "subheadline": effective_subheadline,
-            "platform": platform,
             "targetDuration": duration,
             "language": LANGUAGE_TO_META[output_language],
             "outputLanguage": output_language,
@@ -1461,12 +1455,6 @@ Examples:
         """,
     )
     parser.add_argument("--topic", help="Video topic (required for generation mode)")
-    parser.add_argument(
-        "--platform",
-        default="generic",
-        choices=VALID_PLATFORMS,
-        help="Target platform (default: generic)",
-    )
     parser.add_argument("--duration", type=int, default=30, help="Target duration in seconds (default: 30)")
     parser.add_argument("--style", default="", help="Style tag")
     parser.add_argument("--ratio", default=None, choices=VALID_RATIOS, help="Aspect ratio. When omitted: if --template-id is set, use the template's supportedAspectRatios[0]; otherwise default 16:9.")
@@ -1625,7 +1613,6 @@ Examples:
 
     print(f"📝 generating video script...", file=sys.stderr)
     print(f"   topic: {args.topic}", file=sys.stderr)
-    print(f"   platform: {args.platform}", file=sys.stderr)
     print(f"   duration: {args.duration}s", file=sys.stderr)
     print(f"   ratio: {args.ratio}", file=sys.stderr)
     if args.speed is not None:
@@ -1664,7 +1651,6 @@ Examples:
 
     dsl = build_dsl(
         topic=args.topic,
-        platform=args.platform,
         duration=args.duration,
         style=args.style,
         ratio=args.ratio,

package/skills/gen-script/skill.json

@@ -20,18 +20,6 @@
         "type": "string",
         "description": "Video topic (required)"
       },
-      "platform": {
-        "type": "string",
-        "enum": [
-          "douyin",
-          "xiaohongshu",
-          "bilibili",
-          "wechat",
-          "youtube",
-          "generic"
-        ],
-        "description": "Target platform"
-      },
       "duration": {
         "type": "number",
         "description": "Target duration in seconds"
@@ -112,7 +100,6 @@
     ],
     "advanced": [],
     "hidden": [
-      "platform",
       "duration",
       "style",
       "ratio",

package/skills/gen-voice/SKILL.md

@@ -84,6 +84,7 @@ remixmate gen-voice --text "<text-to-synthesize>" --json-output
 | `--text` | Text to synthesize (required, except with `--list-voices`) | — |
 | `--voice-id` | Voice id (use `--list-voices` to discover) | `Chinese (Mandarin)_Male_Announcer` |
 | `--speed` | Speech rate, 0.5–2.0 | `1.0` |
+| `--language-boost` | CLI-only. Language hint for MiniMax (`auto` / `Chinese` / `English` / …). Mixed-script narration ("只有四个字：Agent Loop") mispronounces the Latin terms without one, so the service already applies its own default — pass this only to pin a specific language. Usually set from the DSL (`global.narration.languageBoost`, scene-level overrides) rather than by hand. Not exposed to the agent — see the handler comment. | service default |
 | `--list-voices` | List available voices and exit | — |
 | `--local` | CLI-only. With `--list-voices`: print the 2-entry hardcoded fallback list instead of querying the service (offline dev). Not exposed to the agent — see the handler comment. | off |
 | `--json-output` | Emit JSON (url, audio_length_ms, subtitles) | off |

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

@@ -175,6 +175,23 @@ def _narration_speed(narration: dict) -> Optional[float]:
     return float(raw) if raw > 0 else None
 
 
+def _narration_language_boost(narration: dict) -> Optional[str]:
+    """Read a narration block's language hint, or None when unset.
+
+    Same tolerance as _narration_speed: a malformed value must not take down an
+    otherwise fine render. The service applies its own default when we send
+    nothing, so "unset" is always a safe outcome — this flag exists to pin a
+    language when auto-detection is not good enough (e.g. an English-only
+    template whose narration still carries a Chinese brand name).
+    """
+    if not isinstance(narration, dict):
+        return None
+    raw = narration.get("languageBoost")
+    if not isinstance(raw, str) or not raw.strip():
+        return None
+    return raw.strip()
+
+
 def extract_narration_lines(narration: dict) -> Optional[tuple[list[str], int, list[Optional[float]]]]:
     """If narration uses the structured {intro, items, outro} form, return
     (lines, intro_line_count, at_sec_list). `at_sec_list` is parallel to
@@ -650,6 +667,7 @@ def build_render_plan(dsl: dict, binding: dict) -> dict:
     dsl_assets_by_id = {a["assetId"]: a for a in dsl.get("assets", [])}
     global_narration = (dsl.get("global") or {}).get("narration") or {}
     global_speed = _narration_speed(global_narration)
+    global_language_boost = _narration_language_boost(global_narration)
     for scene in dsl.get("scenes", []):
         narration = (scene.get("audio") or {}).get("narration") or {}
         ref = narration.get("assetRef")
@@ -666,6 +684,13 @@ def build_render_plan(dsl: dict, binding: dict) -> dict:
             speed = global_speed
         if speed is not None:
             payload["speed"] = speed
+        # 语种提示走与语速完全相同的路线（场景覆盖全局，都不写就交给服务端默认）：
+        # resolve_asset_audio 只看得见 asset，看不见 scene。
+        language_boost = _narration_language_boost(narration)
+        if language_boost is None:
+            language_boost = global_language_boost
+        if language_boost is not None:
+            payload["languageBoost"] = language_boost
         extracted = extract_narration_lines(narration)
         if extracted:
             lines, intro_lines, _ = extracted
@@ -905,6 +930,10 @@ def resolve_asset_audio(asset: dict, private_token: str, timeout: int) -> dict:
     speed = _narration_speed(payload)
     if speed is not None:
         cmd.extend(["--speed", str(speed)])
+    # 同 speed：不带就**不传**这个 flag，默认值归服务端一处持有。
+    language_boost = _narration_language_boost(payload)
+    if language_boost is not None:
+        cmd.extend(["--language-boost", language_boost])
     if private_token:
         cmd.extend(["--priv-token", private_token])
 

package/skills/template-registry/SKILL.md

@@ -193,6 +193,7 @@ Rules:
 - Do not write `templateData.highlightMap`; `render_video.py` builds it automatically from the per-line timestamps that TTS returns.
 - If the author explicitly provides a `highlightMap`, the system keeps it as-is.
 - The legacy flat `narration.text` form still works but the author then has to keep `highlightMap` in sync with the subtitle segmentation (error-prone, not recommended).
+- `narration.languageBoost` (optional, also accepted at `global.narration`) pins the TTS language hint (`auto` / `Chinese` / `English` / …). Leave it unset unless auto-detection gets it wrong — the service applies its own default, and a scene-level value overrides the global one, exactly like `speed`.
 
 ## Image sources (picture-book-en and every other template)
 

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

@@ -25,7 +25,6 @@ import re
 from typing import Iterable, Optional
 
 VALID_VERSIONS = {"v1alpha1"}
-VALID_PLATFORMS = {"douyin", "xiaohongshu", "bilibili", "wechat", "youtube", "generic"}
 VALID_RATIOS = {"16:9", "9:16", "1:1", "4:3", "3:4", "21:9"}
 VALID_RESOLUTIONS = {"480p", "720p", "1080p", "4k"}
 VALID_PURPOSES = {"opening", "intro", "point", "example", "explanation", "transition", "highlight", "cta", "ending"}
@@ -175,19 +174,6 @@ def _check_meta_presence(dsl: dict) -> list[ValidationError]:
     return errors
 
 
-def _check_meta_enums(dsl: dict) -> list[ValidationError]:
-    """完整版额外:meta.platform 必须是已知枚举。"""
-    errors: list[ValidationError] = []
-    meta = dsl.get("meta")
-    if isinstance(meta, dict):
-        platform = meta.get("platform", "generic")
-        if platform not in VALID_PLATFORMS:
-            errors.append(ValidationError(
-                "meta.platform", f"must be one of {sorted(VALID_PLATFORMS)}",
-            ))
-    return errors
-
-
 def _check_global_presence(dsl: dict) -> list[ValidationError]:
     """gen-script 历史:global 必须存在(只检查存在性)。"""
     if not isinstance(dsl.get("global"), dict):
@@ -358,6 +344,51 @@ def _check_assetbindings_deprecation(dsl: dict) -> list[ValidationError]:
     return errors
 
 
+def _check_narration_items_text_coexist(dsl: dict) -> list[ValidationError]:
+    """分行旁白与整段 ``narration.text`` 并存 → warning(text 会被整个忽略)。
+
+    渲染侧是 **items 优先、text 完全忽略**:``extract_narration_lines`` 一旦拿到
+    items,TTS 文本就是 ``"\\n".join(items)``,字幕也改走 ``split_subtitle_from_lines``,
+    ``narration.text`` 既不喂 TTS 也不切字幕。
+
+    为什么值得报:gen_script 的骨架**总是**写一条 ``narration.text``,agent 之后为
+    逐行高亮补 items 时不会删它,于是两者并存几乎是这类模板的默认结局。留着的那
+    一份是死数据 —— 它曾经在旁白编辑面板里被当成"可以单独改、单独重新生成"的一
+    行摆出来(实测一个场景因此显示三行,其中一行是另外两行拼起来的),改它不影响
+    成片,生成它照样扣积分。
+
+    只报 warning 不拒绝:两者并存不会让画面出错,它只是让人误以为 text 还有用。
+    """
+    errors: list[ValidationError] = []
+    for idx, scene in enumerate(dsl.get("scenes", []) or []):
+        sid = scene.get("id", f"scenes[{idx}]")
+        narration = (scene.get("audio") or {}).get("narration") or {}
+        if not isinstance(narration, dict):
+            continue
+        items = narration.get("items")
+        has_items = isinstance(items, list) and any(
+            (isinstance(x, str) and x.strip()) or isinstance(x, dict) for x in items
+        )
+        has_intro_outro = any(
+            isinstance(narration.get(k), str) and narration[k].strip()
+            for k in ("intro", "outro")
+        )
+        text = narration.get("text")
+        if not (has_items or has_intro_outro):
+            continue
+        if not (isinstance(text, str) and text.strip()):
+            continue
+        errors.append(ValidationError(
+            f"scenes[{idx}].audio.narration.text",
+            f"scene '{sid}': this scene uses per-line narration (intro/items/outro), so "
+            "narration.text is ignored end to end — it is neither sent to TTS nor split "
+            "into subtitles. Leaving it here makes it look like editable copy that no "
+            "longer affects the video. Drop the text field and keep the lines.",
+            severity="warning",
+        ))
+    return errors
+
+
 def _check_narration_items_count(dsl: dict) -> list[ValidationError]:
     """render-video / 完整版:结构化 narration items 数与 templateData 的对应数组等长。
 
@@ -978,6 +1009,7 @@ def validate_integrity(dsl: dict) -> list[ValidationError]:
     errors += _check_asset_duplicates(dsl)
     errors += _check_scene_asset_refs(dsl)
     errors += _check_narration_items_count(dsl)
+    errors += _check_narration_items_text_coexist(dsl)
     # 新增(非历史规则):多版式模板必须逐场景选定 slideId。放进 integrity 集合是因为
     # render-video 与 prepare_video_assets 都走这条 —— 而"没选版式"正是要在烧掉渲染
     # 积分之前拦住的东西。单版式模板不受影响,见 _check_slide_id_chosen。
@@ -1001,7 +1033,6 @@ def validate_dsl(dsl: dict) -> list[ValidationError]:
     errors: list[ValidationError] = []
     errors += _check_version(dsl)
     errors += _check_meta_presence(dsl)
-    errors += _check_meta_enums(dsl)
     errors += _check_global_presence(dsl)
     errors += _check_global_enums(dsl)
     errors += _check_scenes_min(dsl)
@@ -1014,6 +1045,7 @@ def validate_dsl(dsl: dict) -> list[ValidationError]:
     errors += _check_scene_asset_refs(dsl)
     errors += _check_assetbindings_deprecation(dsl)
     errors += _check_narration_items_count(dsl)
+    errors += _check_narration_items_text_coexist(dsl)
     errors += _check_narration_language_strict(dsl)
     errors += _check_slide_id_chosen(dsl)
     errors += _check_slide_payload_fields(dsl)

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

@@ -20,10 +20,35 @@ from typing import Optional
 CHARS_PER_SECOND = 5.0
 
 _PRIMARY_BREAK = re.compile(r"(?<=[。！？；\n])")
-_SECONDARY_BREAK = re.compile(r"(?<=[，,、：:])")
+# 次级断点**不含顿号 `、`**。顿号是并列项之间的分隔，在它上面下刀就是把一串并列
+# 拦腰切开（`调研、策划、` ／ `开发、分析，…`）。这一层只数字符、分不出标点的语义
+# 强度，所以干脆不碰它 —— 真需要再切时交给渲染端，那边是分级的（句末 > 冒号 >
+# 逗号 > 顿号 > 空格），只有前面几级都切不动才会降到顿号。
+_SECONDARY_BREAK = re.compile(r"(?<=[，,：:])")
 _PRIMARY_TAIL = re.compile(r"[。！？；\n]\s*$")
 
-MAX_SEGMENT_CHARS = 16
+# ─── 这两个上限管的是「喂给 TTS 的行」，不再是「一屏字幕」 ────────────────
+#
+# 曾经是 16 / 6，那是渲染端还不会分屏时的产物：谁都不会再切，所以必须在这里
+# 就把旁白预切成一屏放得下的大小。现在渲染端（core 的 `chunkSubtitleSegments`）
+# 会按**实际字号与实际可用宽度**算容量、按**标点语义强度分级**切分，这件事它
+# 做得比这里好得多：
+#   · 这里只能数字符数，数不出 `HNSW` 比 4 个中文字窄一半；
+#   · 这里的 `_SECONDARY_BREAK` 是平的，冒号和顿号同权，会把并列项拦腰切开；
+#   · 这里一个全局 16 要同时服务 16:9（一行放 44 字）和 9:16（一行放 22 字）。
+#
+# 于是 16 的唯一效果变成了**抢在渲染端之前把句子剁碎**。2026-09-21 线上成片实测：
+# 121.5s 里 57 屏、中位 2.10s 一屏、33% 短于 1.5s，「AI Agent」独占一屏 —— 全都是
+# 这个 16 的产物，渲染端的分屏阈值（20）一次都没被触发。
+#
+# 现在这里只负责一件事：**在真实语音停顿处断行**，让 Minimax 按停顿返回时间戳。
+# 句末（`_PRIMARY_BREAK`）永远断；逗号那一级只在句子长到一行 TTS 太长时才用。
+# 30 是「一个中文长句」的量级 —— 越过它说明这句本来就该有个呼吸点。
+#
+# ⚠️ 别再把它当字幕宽度调：想改一屏显示多少字，改 core 的
+# `DEFAULT_SPLIT_MAX_UNITS` / `LINE_FILL_LIMIT`，那边才看得见字号和画幅。
+MAX_SEGMENT_CHARS = 30
+# 合并下限保持 6：TTS 行太短会让合成的语气断掉（和字幕闪烁是两回事）。
 MIN_SEGMENT_CHARS = 6
 
 # 字幕显示时需要去掉的末尾标点（中英文句末 + 逗号等）
@@ -50,21 +75,70 @@ def resolve_dimensions(ratio: str, resolution: str) -> tuple[int, int]:
     return dims.get(resolution, dims.get("1080p", (1920, 1080)))
 
 
+def _is_latin_word_char(ch: str) -> bool:
+    return ch.isascii() and ch.isalnum()
+
+
+def _breakable(prev_token: str, next_token: str) -> bool:
+    """两个 token 之间断开是否安全 —— 拉丁↔拉丁即同一词组内部，不安全。
+
+    拆与并共用这一个判据：断的时候躲开的边界，并的时候就得把空格补回去。
+    """
+    if not prev_token or not next_token:
+        return True
+    return not (_is_latin_word_char(prev_token[-1]) and _is_latin_word_char(next_token[0]))
+
+
+def _concat_segments(left: str, right: str) -> str:
+    """拼接两个字幕段，必要时补回被切分吃掉的那个空格。
+
+    ``_split_at_spaces`` 在空格处断开，空格本身不属于任何一段；直接 ``+`` 拼回去
+    会把 ``capabilities and`` + ``more`` 粘成 ``capabilities andmore`` —— 这串同样会
+    原样进 TTS，读出来就是一个不存在的词。中文两侧不补空格（中文本来就不分词）。
+    """
+    if _breakable(left, right):
+        return left + right
+    return left + " " + right
+
+
 def _split_at_spaces(text: str, max_len: int) -> list[str]:
-    """Split long text at space boundaries to protect English words."""
+    """Split long text at space boundaries, keeping multi-word Latin terms whole.
+
+    These boundaries are not only subtitle cuts: ``segment_narration`` joins the
+    result with ``\\n`` and that is what goes to TTS, where each line is a hard
+    segment boundary. Cutting between two Latin words therefore breaks the term
+    apart in the *audio* — Minimax loses both the liaison and the context that
+    told it this was English at all.
+
+    实测(2026-09-20): ``最近刷爆科技圈的 AI Agent，`` 是 18 字、超过 16 的上限，而这
+    段里仅有的两个空格都在 "AI Agent" 中间,于是旧实现只能从词组中间下刀,切成
+    ``最近刷爆科技圈的 AI`` + ``Agent，`` —— 合成出来 "AI" 收在上一段末尾、"Agent"
+    孤零零起一段,那个词就读不准了。同句末尾的 "Agent Loop。" 因为没超上限反而完好,
+    用户听到的正是"中间那个 Agent 不对"。
+
+    所以断点优先选**中文↔拉丁**边界(回退到词组之前),找不到再退回"就近断开"。
+    纯英文旁白里根本不存在中文↔拉丁边界,每个断点都会走回退分支,行为与旧实现逐字
+    相同 —— picture-book-en 这类全英文模板不受影响。
+    """
     if len(text) <= max_len:
         return [text]
+
     parts: list[str] = []
-    current = ""
+    buf: list[str] = []  # 当前段已收的 token
     for word in text.split(" "):
-        candidate = f"{current} {word}" if current else word
-        if len(candidate) > max_len and current:
-            parts.append(current)
-            current = word
-        else:
-            current = candidate
-    if current:
-        parts.append(current)
+        if buf and len(" ".join(buf + [word])) > max_len:
+            # 从最靠后的边界往回找第一个安全断点;整段都没有就按旧行为就近断开。
+            cut = len(buf)
+            for i in range(len(buf), 0, -1):
+                following = word if i == len(buf) else buf[i]
+                if _breakable(buf[i - 1], following):
+                    cut = i
+                    break
+            parts.append(" ".join(buf[:cut]))
+            buf = buf[cut:]
+        buf.append(word)
+    if buf:
+        parts.append(" ".join(buf))
     return parts
 
 
@@ -83,17 +157,17 @@ def _merge_short(segments: list[str], min_len: int) -> list[str]:
         prev_is_sentence_end = bool(_PRIMARY_TAIL.search(merged[-1]))
         if len(merged[-1]) < min_len:
             # Previous fragment is short — always merge forward into it
-            merged[-1] += seg
+            merged[-1] = _concat_segments(merged[-1], seg)
         elif len(seg) < min_len and not prev_is_sentence_end:
             # Current fragment is short and prev is NOT a sentence end — merge backward
-            merged[-1] += seg
+            merged[-1] = _concat_segments(merged[-1], seg)
         else:
             # Either both are long enough, or seg is short but prev ends a sentence
             merged.append(seg)
     # Handle trailing short segment (avoid merging across sentence boundary)
     if len(merged) > 1 and len(merged[-1]) < min_len:
         if not _PRIMARY_TAIL.search(merged[-2]):
-            merged[-2] += merged.pop()
+            merged[-2] = _concat_segments(merged[-2], merged.pop())
     return merged
 
 
@@ -108,10 +182,15 @@ def _strip_trailing_punct(text: str) -> str:
 
 
 def segment_narration(text: str) -> list[str]:
-    """Split narration text into subtitle-display-sized segments (text only).
+    """Split narration into **TTS lines**, cutting at speech pauses.
 
     Use before TTS: ``"\\n".join(segment_narration(text))`` sends to Minimax
-    so it returns per-segment timestamps.
+    so it returns per-line timestamps.
+
+    ⚠️ 这里切的**不是字幕屏**。字幕分屏归渲染端（core 的
+    ``chunkSubtitleSegments``），它知道字号、画幅和标点的语义强度；这里只知道
+    字符数。这一层切得越细，留给渲染端的余地越小 —— 见 ``MAX_SEGMENT_CHARS``
+    的注释。
     """
     if not text:
         return []

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

@@ -44,11 +44,6 @@
       "properties": {
         "title": { "type": "string" },
         "topic": { "type": "string" },
-        "platform": {
-          "type": "string",
-          "enum": ["douyin", "xiaohongshu", "bilibili", "wechat", "youtube", "generic"],
-          "default": "generic"
-        },
         "targetDuration": {
           "type": "number",
           "description": "目标总时长（秒）"
@@ -95,7 +90,8 @@
           "properties": {
             "voiceId": { "type": "string", "description": "Minimax 音色 ID" },
             "voiceName": { "type": "string" },
-            "speed": { "type": "number", "default": 1.0 }
+            "speed": { "type": "number", "default": 1.0 },
+            "languageBoost": { "type": "string", "description": "TTS 语种提示（auto / Chinese / English …）。中英混排的旁白不给提示时，英文词容易被按中文音系读出来；留空由服务端取默认值。" }
           }
         },
         "bgm": {
@@ -250,7 +246,8 @@
                   "description": "每行一个卡片的叙述句。长度必须等于 templateData 里对应数组（concepts/pillars/eras/items）的长度"
                 },
                 "outro": { "type": "string", "description": "可选：收尾句（此期间无卡片高亮）" },
-                "assetRef": { "type": "string", "description": "旁白音频 assetId" }
+                "assetRef": { "type": "string", "description": "旁白音频 assetId" },
+                "languageBoost": { "type": "string", "description": "TTS 语种提示（auto / Chinese / English …）。中英混排的旁白不给提示时，英文词容易被按中文音系读出来；覆盖 global.narration 的同名字段；留空则跟随全局/服务端默认。" }
               }
             },
             "bgm": {