@remixmate/cli 0.9.37 → 0.9.39

package/dist/manifest.json

@@ -1,8 +1,81 @@
 {
   "schemaVersion": 1,
-  "version": "0.9.37",
-  "generatedAt": "2026-09-21T03:49:51.210Z",
+  "version": "0.9.39",
+  "generatedAt": "2026-09-21T14:35:49.704Z",
   "skills": [
+    {
+      "id": "doc-parse",
+      "toolName": "doc_parse",
+      "tier": "tool",
+      "category": "consuming",
+      "title": "Document Extraction",
+      "summary": "Extract a document (.pptx) into structured data: per-page title and body text, the speaker notes, and — when asked for the layout layer — the exact shapes, coordinates, colors and animation beats of every slide. Runs server-side (ab-render /extract); nothing is installed locally and no model is involved, so the result is deterministic. Two layers via `fields`: `content` is lightweight text (title / text / rawNotes) and is what you want for narration or for summarizing a deck; `layout` additionally returns the slide payload that the ppt-to-video template renders one-to-one from the original file — it embeds every icon as a data URI and is large, so it is written to a file rather than printed.",
+      "triggers": [
+        "Turn this PPT / slide deck into a video",
+        "Extract text or speaker notes from a .pptx",
+        "Use a PowerPoint file as source material",
+        "Get customPayload.slide for ppt-to-video"
+      ],
+      "entry": {
+        "type": "python",
+        "scriptPath": "scripts/extract_via_render.py"
+      },
+      "runtime": "python",
+      "envVars": [
+        "RENDER_API_URL",
+        "PRIV_TOKEN",
+        "CONVERSATION_ID"
+      ],
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "url": {
+            "type": "string",
+            "description": "Direct document URL (http/https). A page link or a share link will not work — pass the file URL itself (e.g. what the asset library returns)."
+          },
+          "kind": {
+            "type": "string",
+            "enum": [
+              "pptx"
+            ],
+            "description": "Document kind. Only pptx today; a binary .ppt must be re-saved as .pptx first."
+          },
+          "fields": {
+            "type": "string",
+            "description": "Comma-separated layers: `content` (title/text/rawNotes — small) and/or `layout` (slide shapes + beats — large, embeds icons). Default `content,layout`. Ask for content only when you just need the words."
+          },
+          "slide": {
+            "type": "number",
+            "description": "Only extract this 1-based page. Omit for the whole deck."
+          },
+          "out": {
+            "type": "string",
+            "description": "Where to write the full JSON result (default ./<name>.extract.json). stdout gets a per-page summary instead."
+          },
+          "json_output": {
+            "type": "boolean",
+            "description": "Pipeline mode — emit the full JSON on stdout. Avoid with the layout layer: it is hundreds of KB of base64 per page."
+          }
+        },
+        "required": [
+          "url"
+        ]
+      },
+      "ui": {
+        "primary": [
+          "url",
+          "fields"
+        ],
+        "advanced": [
+          "slide",
+          "kind"
+        ],
+        "hidden": [
+          "out",
+          "json_output"
+        ]
+      }
+    },
     {
       "id": "export-jianying",
       "toolName": "export_jianying",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remixmate/cli",
-  "version": "0.9.37",
+  "version": "0.9.39",
   "description": "AI media generation skills for Claude Code / Codex — 12 skills covering image, video, voice, digital human, web screenshot, web recording, script, template registry, rendering, Jianying export, and video deconstruction.",
   "type": "module",
   "main": "dist/index.js",

package/skills/doc-parse/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: doc-parse
+description: |
+  Document extraction skill — turn a `.pptx` into structured data through the ab-render `/extract` endpoint.
+
+  Two layers, picked with `--fields`:
+  - **content** — per-page `title`, `text[]`, and `rawNotes` (the speaker notes). Small, no base64. This is the narration source material.
+  - **layout** — the full `slide` payload the `ppt-to-video` template renders from: every shape, coordinate, color, clip path and the animation `beats`, plus the `mode` verdict. Large (icons are embedded as data URIs).
+
+  Deterministic: the endpoint parses OOXML, it does **not** call a model. Notes come back verbatim — rewriting them into narration is your job, not the endpoint's.
+
+  Use this skill immediately whenever the user asks for any of:
+  - Turn this PPT / slide deck into a video
+  - Read / extract / summarize a .pptx, pull the text or the speaker notes out of a deck
+  - Use a PowerPoint file as source material for a script
+  - Anything that needs `customPayload.slide` for the `ppt-to-video` template
+
+  Never hand-write `slide` nodes for `ppt-to-video`. A page has dozens of shapes with exact EMU coordinates; transcribing them by eye is guaranteed to drift from the original, and the template's own hint says so.
+triggers:
+  - Turn this PPT / slide deck into a video
+  - Extract text or speaker notes from a .pptx
+  - Use a PowerPoint file as source material
+  - Get customPayload.slide for ppt-to-video
+---
+
+# Document Extraction Skill (`doc_parse`)
+
+Entry script **`scripts/extract_via_render.py`**, pure Python (stdlib only — no Office libraries, no local install).
+
+> Path convention: read the system-injected `Base directory for this skill: <path>` as `<SkillDir>`. Never hardcode an absolute path.
+
+## How it works
+
+```
+POST $RENDER_API_URL/extract        → { taskId }
+POST $RENDER_API_URL/extractStatus  → { status, result? }   (polled for you)
+```
+
+The heavy lifting (download, unzip, OOXML parsing, geometry) happens server-side. The script submits, polls, then **writes the full JSON to a file and prints a per-page summary**.
+
+That default matters: one page of `layout` with embedded icons can be hundreds of KB. Printing it would fill your context with base64 and bury the three facts you actually need — the page's mode, its beat count, and whether it has speaker notes.
+
+## Environment
+
+| Var | Meaning | Default |
+| --- | --- | --- |
+| `RENDER_API_URL` | ab-render base URL (falls back to `REMOTION_RENDER_API_URL`) | `https://api-render.remixmate.ai` |
+| `PRIV_TOKEN` | ab-api private token — **required**, the endpoint refuses anonymous calls | — |
+| `CONVERSATION_ID` | Conversation id, for provenance | — |
+
+## Usage
+
+Whole deck, both layers (what `ppt-to-video` needs):
+
+```bash
+python3 <SkillDir>/scripts/extract_via_render.py --url "https://oss.example.com/deck.pptx"
+```
+
+Text and notes only — summarizing a deck, or writing narration without touching the visuals:
+
+```bash
+python3 <SkillDir>/scripts/extract_via_render.py --url "https://…/deck.pptx" --fields content
+```
+
+One page:
+
+```bash
+python3 <SkillDir>/scripts/extract_via_render.py --url "https://…/deck.pptx" --slide 3
+```
+
+## Output
+
+```jsonc
+{
+  "source": { "url": "…", "name": "deck.pptx", "slideCount": 12, "canvas": [1920, 1080], "fields": ["content","layout"] },
+  "slides": [
+    {
+      "slideIndex": 1,
+      // content 层
+      "title": "产品介绍",
+      "text": ["三大优势", "…"],
+      "rawNotes": "备注页原文，逐字返回，未经改写",
+      // layout 层
+      "mode": "sequenced",
+      "modeReason": "4×1 格点，4 块 + 2 组页面家具",
+      "nodes": [ /* … */ ],
+      "beats": [ { "reveal": ["n12","n13"] } ],
+      "ambientIds": ["n2"],
+      "recommendedSec": 5.3,
+      "background": { "color": "#FFFFFF" },
+      "flags": ["unsupported_geom:rightArrow×3"]
+    }
+  ]
+}
+```
+
+## Using the result
+
+**For the picture** — feed `slides[i]` straight into the template's `customPayload.slide`. Do not edit the coordinates, and do not raise `mode`: the verdict comes from the extractor, which can see reconstruction problems you cannot (`modeReason` says why). You may lower it. Raising it requires `trustMeMode: true` and means you have personally checked that page.
+
+**For the words** — `rawNotes` and `text` are two different kinds of raw material, and they need different treatment:
+
+| Source | What it is | What to do | Can you check yourself? |
+| --- | --- | --- | --- |
+| `rawNotes` | already a script, written to be spoken | re-cut into one sentence per beat, make it spoken-register, drop stage directions (“as you can see here”, “(next slide)”) and non-script items (citations, TODOs) | **yes** — the original is right there |
+| `text` | bullet points, sometimes just keywords | expand into sentences | **no** — there is nothing to check against |
+
+Two rules:
+
+1. **Do not introduce facts that are not on the slide.** This is the user's own deck; inventing content puts words in their mouth.
+2. **Talk about it, don't read it out.** The body text is already on screen. Narrating it verbatim gives the viewer the same sentence three times — on the slide, in the subtitle, and in the voice-over.
+
+When a page had no notes and you wrote the narration from `text`, say so and ask the user to look it over. Do not ship it silently.
+
+## Failure modes
+
+Errors come back as plain sentences; pass them to the user as-is rather than retrying:
+
+- a binary `.ppt` (PowerPoint 97-2003) — it must be re-saved as `.pptx`, the formats are unrelated
+- not a zip at all, or a zip without `ppt/slides/`
+- the deck exceeds the per-call page limit — extract page by page with `--slide`, or split the file
+- the file is too large, or unpacks to too much
+
+`flags` on a page is **not** an error: it records what the extractor refused to reconstruct. Surface it — a silently missing element on screen is worse than a mentioned one.

package/skills/doc-parse/scripts/extract_via_render.py

@@ -0,0 +1,218 @@
+#!/usr/bin/env python3
+"""
+文档抽取脚本 — 通过 ab-render HTTP 接口实现，本地不需要任何 Office/解析依赖。
+
+调用链：
+  POST $RENDER_API_URL/extract        → { taskId }
+  POST $RENDER_API_URL/extractStatus  → { status, progress, result?, error? }
+
+两层产物（--fields）：
+  content   title / text[] / rawNotes —— 正文与备注页，轻量，不含任何 base64
+  layout    slide{nodes,beats,mode,…} —— 坐标形状，带内嵌图标，**体积很大**
+
+默认**不把完整结果打到 stdout**：一页 PPT 的 layout 带上内嵌图标可能几百 KB，
+直接进对话正文会撑爆上下文，还会让用户在聊天记录里滚过一屏 base64。默认写文件 +
+打一份人能读的摘要；确实要管道传全量时用 --json-output（或只要 content 层）。
+
+必要环境变量（由 ab-agent 自动注入）：
+  RENDER_API_URL   ab-render 服务地址（默认 https://api-render.remixmate.ai）
+  PRIV_TOKEN       ab-api 私有 token
+
+可选环境变量：
+  CONVERSATION_ID  对话 ID，用于留痕与产物归属
+"""
+
+import argparse
+import json
+import os
+import sys
+import time
+import urllib.error
+import urllib.request
+
+# ─── 环境变量 ─────────────────────────────────────────────────────────────────
+
+RENDER_API_URL = (
+    os.environ.get("RENDER_API_URL")
+    or os.environ.get("REMOTION_RENDER_API_URL")
+    or "https://api-render.remixmate.ai"
+).rstrip("/")
+PRIV_TOKEN = os.environ.get("PRIV_TOKEN", "")
+CONVERSATION_ID = os.environ.get("CONVERSATION_ID", "")
+
+# ─── HTTP 工具 ────────────────────────────────────────────────────────────────
+
+
+def api_post(path: str, body: dict, timeout: int = 30) -> dict:
+    """向 ab-render 发送 POST 请求，返回解析后的 JSON。"""
+    url = f"{RENDER_API_URL}{path}"
+    data = json.dumps(body).encode()
+
+    headers: dict[str, str] = {
+        "Content-Type": "application/json",
+        "X-Priv-Token": PRIV_TOKEN,
+    }
+    if CONVERSATION_ID:
+        headers["x-conversation-id"] = CONVERSATION_ID
+
+    req = urllib.request.Request(url, data=data, headers=headers, method="POST")
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            return json.loads(resp.read())
+    except urllib.error.HTTPError as e:
+        body_text = e.read().decode(errors="replace")
+        raise RuntimeError(f"HTTP {e.code}: {body_text}") from e
+
+
+def log(msg: str, silent: bool = False) -> None:
+    if not silent:
+        print(msg, flush=True)
+
+
+# ─── 摘要 ─────────────────────────────────────────────────────────────────────
+
+
+def summarize(result: dict, out_path: str | None) -> str:
+    """
+    人能读的一页纸。**这是这个 skill 存在的一半价值** —— 端点给的是全量结构，
+    决定"喂多少进上下文"是入口层的责任（设计文档 §4.4）。
+
+    每页一行：页码、档位、拍数、标题、讲稿来源。档位与拍数决定后面怎么写旁白，
+    讲稿来源决定走严格改写还是扩写，这两件是下一步真正要用的信息。
+    """
+    src = result.get("source", {})
+    lines = [
+        f"共 {src.get('slideCount', '?')} 页，本次抽到 {len(result.get('slides', []))} 页"
+        f"（fields={'+'.join(src.get('fields', []))}）",
+        "",
+    ]
+
+    for s in result.get("slides", []):
+        idx = s.get("slideIndex", "?")
+        bits = [f"第 {idx} 页"]
+
+        if s.get("mode"):
+            beats = len(s.get("beats") or [])
+            bits.append(f"{s['mode']}/{beats} 拍")
+        if s.get("title"):
+            bits.append(f"「{s['title']}」")
+
+        notes = (s.get("rawNotes") or "").strip()
+        if notes:
+            head = notes.replace("\n", " ")[:40]
+            bits.append(f"备注 {len(notes)} 字：{head}…")
+        elif "rawNotes" in s:
+            bits.append("无备注（旁白需按正文扩写）")
+
+        lines.append("  " + " · ".join(bits))
+
+        if s.get("modeReason"):
+            lines.append(f"      判定：{s['modeReason']}")
+        flags = s.get("flags") or []
+        if flags:
+            # flag 是显式的降级记录，不是日志 —— 画面上少一块，这里不说就没人知道为什么。
+            lines.append(f"      ⚠ 降级：{'; '.join(flags[:3])}")
+
+    if out_path:
+        lines += ["", f"完整结果已写入：{out_path}"]
+    return "\n".join(lines)
+
+
+# ─── 主逻辑 ───────────────────────────────────────────────────────────────────
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="Document extraction — calls the ab-render /extract endpoint"
+    )
+    parser.add_argument("--url", required=True, help="Direct document URL (.pptx)")
+    parser.add_argument("--kind", default="pptx", choices=["pptx"], help="Document kind (default pptx)")
+    parser.add_argument("--slide", type=int, help="Only extract this 1-based page")
+    parser.add_argument(
+        "--fields", default="content,layout",
+        help="Comma-separated: content / layout (default both)",
+    )
+    parser.add_argument(
+        "--out", help="Write the full JSON result here (default: ./<name>.extract.json)",
+    )
+    parser.add_argument(
+        "--json-output", action="store_true",
+        help="Pipeline mode: emit the full JSON on stdout (careful: layout is large)",
+    )
+    args = parser.parse_args()
+
+    if not PRIV_TOKEN:
+        print(
+            "❌ PRIV_TOKEN env var is not configured — /extract requires auth.",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    fields = [f.strip() for f in args.fields.split(",") if f.strip()]
+
+    # ── 1. Submit ────────────────────────────────────────────────────────────
+    log(f"[doc-parse] Submitting extraction: {args.url[:80]}", args.json_output)
+
+    body: dict = {"documentUrl": args.url, "kind": args.kind, "fields": fields}
+    if args.slide is not None:
+        body["slide"] = args.slide
+
+    resp = api_post("/extract", body)
+    if resp.get("code") != 0:
+        print(f"❌ submission failed: {resp.get('msg', 'unknown error')}", file=sys.stderr)
+        sys.exit(1)
+
+    task_id: str = resp["data"]["taskId"]
+    log(f"[doc-parse] task accepted, taskId={task_id}", args.json_output)
+
+    # ── 2. Poll ──────────────────────────────────────────────────────────────
+    max_wait_sec = 600
+    poll_interval = 2
+    elapsed = 0
+
+    while elapsed < max_wait_sec:
+        time.sleep(poll_interval)
+        elapsed += poll_interval
+
+        try:
+            status_resp = api_post("/extractStatus", {"taskId": task_id})
+        except Exception as e:  # noqa: BLE001
+            log(f"[doc-parse] polling error (will retry): {e}", args.json_output)
+            continue
+
+        if status_resp.get("code") != 0:
+            log(f"[doc-parse] polling error code (will retry): {status_resp.get('msg')}", args.json_output)
+            continue
+
+        task = status_resp["data"]
+        status = task.get("status", "unknown")
+
+        if status == "succeeded":
+            result = task.get("result") or {}
+
+            if args.json_output:
+                print(json.dumps(result, ensure_ascii=False))
+                return
+
+            # 默认落盘 + 摘要：layout 层直接打进 stdout 会撑爆上下文（见文件头）。
+            out_path = args.out or f"./{(result.get('source') or {}).get('name', 'document')}.extract.json"
+            with open(out_path, "w", encoding="utf-8") as f:
+                json.dump(result, f, ensure_ascii=False, indent=2)
+
+            print("\n✅ 抽取完成\n")
+            print(summarize(result, out_path))
+            return
+
+        if status == "failed":
+            # 端点的错误已经是人话（格式不对/超页数/超体积），原样透出，不要再包一层。
+            print(f"❌ extraction failed: {task.get('error', 'unknown error')}", file=sys.stderr)
+            sys.exit(1)
+
+        log(f"[doc-parse] status={status} elapsed={elapsed}s", args.json_output)
+
+    print(f"❌ extraction timed out (over {max_wait_sec}s)", file=sys.stderr)
+    sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

package/skills/doc-parse/skill.json

@@ -0,0 +1,54 @@
+{
+  "name": "doc-parse",
+  "toolName": "doc_parse",
+  "tier": "tool",
+  "category": "consuming",
+  "title": "Document Extraction",
+  "description": "Extract a document (.pptx) into structured data: per-page title and body text, the speaker notes, and — when asked for the layout layer — the exact shapes, coordinates, colors and animation beats of every slide. Runs server-side (ab-render /extract); nothing is installed locally and no model is involved, so the result is deterministic. Two layers via `fields`: `content` is lightweight text (title / text / rawNotes) and is what you want for narration or for summarizing a deck; `layout` additionally returns the slide payload that the ppt-to-video template renders one-to-one from the original file — it embeds every icon as a data URI and is large, so it is written to a file rather than printed.",
+  "auth": "required",
+  "envVars": [
+    "RENDER_API_URL",
+    "PRIV_TOKEN",
+    "CONVERSATION_ID"
+  ],
+  "entry": {
+    "type": "python",
+    "scriptPath": "scripts/extract_via_render.py"
+  },
+  "parameters": {
+    "type": "object",
+    "properties": {
+      "url": {
+        "type": "string",
+        "description": "Direct document URL (http/https). A page link or a share link will not work — pass the file URL itself (e.g. what the asset library returns)."
+      },
+      "kind": {
+        "type": "string",
+        "enum": ["pptx"],
+        "description": "Document kind. Only pptx today; a binary .ppt must be re-saved as .pptx first."
+      },
+      "fields": {
+        "type": "string",
+        "description": "Comma-separated layers: `content` (title/text/rawNotes — small) and/or `layout` (slide shapes + beats — large, embeds icons). Default `content,layout`. Ask for content only when you just need the words."
+      },
+      "slide": {
+        "type": "number",
+        "description": "Only extract this 1-based page. Omit for the whole deck."
+      },
+      "out": {
+        "type": "string",
+        "description": "Where to write the full JSON result (default ./<name>.extract.json). stdout gets a per-page summary instead."
+      },
+      "json_output": {
+        "type": "boolean",
+        "description": "Pipeline mode — emit the full JSON on stdout. Avoid with the layout layer: it is hundreds of KB of base64 per page."
+      }
+    },
+    "required": ["url"]
+  },
+  "ui": {
+    "primary": ["url", "fields"],
+    "advanced": ["slide", "kind"],
+    "hidden": ["out", "json_output"]
+  }
+}

package/skills/gen-script/SKILL.md

@@ -441,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.).

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
 
 # 字幕显示时需要去掉的末尾标点（中英文句末 + 逗号等）
@@ -157,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 []