@remixmate/cli 0.9.25 → 0.9.27

package/README.md

@@ -6,7 +6,7 @@ English | [简体中文](./README.zh-CN.md)
 
 AI media generation skills for Claude Code / Codex.
 
-11 skills covering the full short-video production pipeline: image / video / voice / digital-human asset generation, web page capture, script planning, template binding, Remotion rendering, Jianying (CapCut) draft export, and video deconstruction.
+13 skills covering the full short-video production pipeline: image / video / voice / digital-human asset generation, web page capture and text extraction, script planning, template binding, Remotion rendering, Jianying (CapCut) draft export, and video deconstruction.
 
 ## Install
 
@@ -159,11 +159,11 @@ cp .env.example .env
 source .env
 ```
 
-Python skills (8 of 12) require `python3 >= 3.10`. `web-screenshot` / `web-record` require Playwright (auto-installs chromium on first run). `ffmpeg` is only needed for `video-parser`'s optional local tool (`deconstruct_video.py`); the default `video-parser` entry runs server-side via ab-render and needs no local ffmpeg.
+Python skills (9 of 13) require `python3 >= 3.10`. `web-screenshot` / `web-record` / `web-read` require Playwright (auto-installs chromium on first run). `ffmpeg` is only needed for `video-parser`'s optional local tool (`deconstruct_video.py`); the default `video-parser` entry runs server-side via ab-render and needs no local ffmpeg.
 
 ## Skills
 
-This project contains 11 AI media generation skills covering the full pipeline from asset generation, script orchestration, template binding, and video rendering to Jianying export.
+This project contains 13 AI media generation skills covering the full pipeline from asset generation, script orchestration, template binding, and video rendering to Jianying export.
 
 ### Skill layers
 
@@ -186,6 +186,7 @@ This project contains 11 AI media generation skills covering the full pipeline f
 │  video-parser      Video deconstruction (audio / ASR / kf)  │
 │  web-screenshot    Web page screenshot (png / jpg)          │
 │  web-record        Web page recording / storyboard video    │
+│  web-read          Web page text extraction (markdown/json) │
 └─────────────────────────────────────────────────────────────┘
 ```
 
@@ -207,7 +208,8 @@ This project contains 11 AI media generation skills covering the full pipeline f
 │   ├── export-jianying/        # orchestration: export Jianying draft ZIP
 │   ├── video-parser/           # tool: video deconstruction & analysis
 │   ├── web-screenshot/         # tool: headless-browser screenshot (also hosts record.py)
-│   └── web-record/             # tool: headless-browser recording (entry -> web-screenshot/scripts/record.py)
+│   ├── web-record/             # tool: headless-browser recording (entry -> web-screenshot/scripts/record.py)
+│   └── web-read/               # tool: headless-browser text extraction (entry -> web-screenshot/scripts/read_page.py)
 └── README.md
 ```
 
@@ -227,6 +229,7 @@ This project contains 11 AI media generation skills covering the full pipeline f
 | video-parser | tool | Video → audio + ASR + keyframes + scene segmentation | python `scripts/parse_via_render.py` |
 | web-screenshot | tool | Web page screenshot (png / jpg) | python `scripts/screenshot.py` |
 | web-record | tool | Web page recording / scroll-through / storyboard video (webm -> mp4 -> VOD) | python `../web-screenshot/scripts/record.py` |
+| web-read | tool | Web page → main text (markdown / plain text / structured JSON) | python `../web-screenshot/scripts/read_page.py` |
 
 ### Core workflows
 
@@ -268,6 +271,10 @@ npm run regress:update
 # Run only the render-plan snapshot layer:
 npm run test:render-plan
 
+# Narration speed wiring (gen_script → render plan → gen-voice --speed).
+# Fully offline: no registry, no TTS call.
+npm run test:narration-speed
+
 # L3 — selective, real Remotion render of chosen template(s). NOT full-library
 # by design (rendering is slow + needs asset generation). Catches crashes /
 # black frames the static layers can't. Needs PRIV_TOKEN for narration TTS;

package/README.zh-CN.md

@@ -6,7 +6,7 @@
 
 面向 Claude Code / Codex 的 AI 媒体生成技能集。
 
-包含 11 个技能，覆盖完整的短视频生产链路：图片 / 视频 / 语音 / 数字人素材生成、网页捕获、脚本编排、模板绑定、Remotion 渲染、剪映（CapCut）草稿导出，以及视频解构。
+包含 13 个技能，覆盖完整的短视频生产链路：图片 / 视频 / 语音 / 数字人素材生成、网页捕获与正文抽取、脚本编排、模板绑定、Remotion 渲染、剪映（CapCut）草稿导出，以及视频解构。
 
 ## 安装
 
@@ -113,11 +113,11 @@ cp .env.example .env
 source .env
 ```
 
-Python 技能（12 个中的 8 个）需要 `python3 >= 3.10`。`web-screenshot` / `web-record` 需要 Playwright（首次运行自动安装 chromium）。`ffmpeg` 仅 `video-parser` 的可选本地工具（`deconstruct_video.py`）需要；`video-parser` 默认入口走 ab-render 服务端解构，无需本地 ffmpeg。
+Python 技能（13 个中的 9 个）需要 `python3 >= 3.10`。`web-screenshot` / `web-record` / `web-read` 需要 Playwright（首次运行自动安装 chromium）。`ffmpeg` 仅 `video-parser` 的可选本地工具（`deconstruct_video.py`）需要；`video-parser` 默认入口走 ab-render 服务端解构，无需本地 ffmpeg。
 
 ## 技能
 
-本项目包含 12 个 AI 媒体生成技能，覆盖从素材生成、脚本编排、模板绑定、视频渲染到剪映导出的完整视频内容生产链路。
+本项目包含 13 个 AI 媒体生成技能，覆盖从素材生成、脚本编排、模板绑定、视频渲染到剪映导出的完整视频内容生产链路。
 
 ### 技能分层
 
@@ -140,6 +140,7 @@ Python 技能（12 个中的 8 个）需要 `python3 >= 3.10`。`web-screenshot`
 │  video-parser      视频解构（音频提取 / ASR / 关键帧）       │
 │  web-screenshot    网页截图（png / jpg）                     │
 │  web-record        网页录屏 / 滚动录屏 / 分镜视频            │
+│  web-read          网页正文抽取（markdown / 纯文本 / JSON）  │
 └─────────────────────────────────────────────────────────────┘
 ```
 
@@ -161,7 +162,8 @@ Python 技能（12 个中的 8 个）需要 `python3 >= 3.10`。`web-screenshot`
 │   ├── export-jianying/        # 编排: 导出剪映草稿 ZIP
 │   ├── video-parser/           # 工具: 视频解构与分析
 │   ├── web-screenshot/         # 工具: 无头浏览器截图（record.py 也放在这里）
-│   └── web-record/             # 工具: 无头浏览器录屏（入口指向 web-screenshot/scripts/record.py）
+│   ├── web-record/             # 工具: 无头浏览器录屏（入口指向 web-screenshot/scripts/record.py）
+│   └── web-read/               # 工具: 无头浏览器正文抽取（入口指向 web-screenshot/scripts/read_page.py）
 └── README.md
 ```
 
@@ -181,6 +183,7 @@ Python 技能（12 个中的 8 个）需要 `python3 >= 3.10`。`web-screenshot`
 | video-parser | 工具 | 视频 → 音频 + ASR + 关键帧 + 场景分段 | python `scripts/parse_via_render.py` |
 | web-screenshot | 工具 | 网页截图（png / jpg） | python `scripts/screenshot.py` |
 | web-record | 工具 | 网页录屏 / 滚动录屏 / 分镜视频（webm → mp4 → VOD） | python `../web-screenshot/scripts/record.py` |
+| web-read | 工具 | 网页正文抽取（markdown / 纯文本 / 结构化 JSON） | python `../web-screenshot/scripts/read_page.py` |
 
 ### 核心链路
 
@@ -218,6 +221,7 @@ remixmate export-jianying --help
 remixmate video-parser --help
 remixmate web-screenshot --help
 remixmate web-record --help
+remixmate web-read --help
 remixmate template-registry --help
 
 # http 技能（gen-image、gen-video、gen-voice、gen-digital-human）没有

package/dist/handlers/gen-voice.d.ts

@@ -4,9 +4,19 @@
  * Operations:
  *   --list-voices true                 → GET available voice IDs from /voice/page (live)
  *   --list-voices true --local true    → print the built-in language-tagged
- *                                        fallback catalog (offline, no API call)
+ *                                        fallback catalog (offline, no API call).
+ *                                        **CLI-only escape hatch for offline dev.**
  *   default                            → synthesize text into an MP3 URL
  *
+ * `local` is deliberately absent from `skills/gen-voice/skill.json`'s
+ * `parameters`, which is what ab-agent turns into the model-facing tool schema.
+ * A model asked to check a voice id would reach for `local: true`, get a
+ * two-entry hardcoded list back, and conclude that a perfectly valid voice does
+ * not exist — which is exactly what happened on the hosted web agent
+ * ("本地回退列表中没有该音色"). The remote catalog is the only authority on
+ * which voices exist; the local list is a developer convenience for working
+ * without a token, and it is only reachable by typing the flag yourself.
+ *
  * The previous Python script also offered `--download` to write the MP3 to
  * disk. That's intentionally dropped here: the agent flow never used it (the
  * audio URL is persisted in cloud) and removing local file I/O keeps the

package/dist/handlers/gen-voice.js

@@ -4,9 +4,19 @@
  * Operations:
  *   --list-voices true                 → GET available voice IDs from /voice/page (live)
  *   --list-voices true --local true    → print the built-in language-tagged
- *                                        fallback catalog (offline, no API call)
+ *                                        fallback catalog (offline, no API call).
+ *                                        **CLI-only escape hatch for offline dev.**
  *   default                            → synthesize text into an MP3 URL
  *
+ * `local` is deliberately absent from `skills/gen-voice/skill.json`'s
+ * `parameters`, which is what ab-agent turns into the model-facing tool schema.
+ * A model asked to check a voice id would reach for `local: true`, get a
+ * two-entry hardcoded list back, and conclude that a perfectly valid voice does
+ * not exist — which is exactly what happened on the hosted web agent
+ * ("本地回退列表中没有该音色"). The remote catalog is the only authority on
+ * which voices exist; the local list is a developer convenience for working
+ * without a token, and it is only reachable by typing the flag yourself.
+ *
  * The previous Python script also offered `--download` to write the MP3 to
  * disk. That's intentionally dropped here: the agent flow never used it (the
  * audio URL is persisted in cloud) and removing local file I/O keeps the
@@ -21,6 +31,10 @@ import { isTrue, toNumber } from './shared.js';
  * Mirrors the language-keyed defaults that gen_script.py uses, kept in sync
  * by hand because the two callers live on different runtimes.
  *
+ * This is **not** a list of available voices — it is the two ids the resolver
+ * falls back to when nothing else is specified, and one of them is still a
+ * placeholder. Never treat it as evidence about what the service offers.
+ *
  * Promote to a JSON config once this grows beyond a handful of entries.
  */
 const LOCAL_VOICE_CATALOG = [
@@ -44,6 +58,8 @@ async function listVoicesRemote(ctx) {
     process.stdout.write(`💡 Use --voice-id <id> to select a voice for synthesis\n`);
 }
 function listVoicesLocal() {
+    process.stderr.write('⚠️  --local prints a hardcoded 2-entry fallback list, NOT the available voices. ' +
+        'Drop --local to query the live catalog.\n');
     for (const v of LOCAL_VOICE_CATALOG) {
         process.stdout.write(`${v.id}\t${v.language}\t${v.name}\n`);
     }

package/dist/manifest.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
-  "version": "0.9.25",
-  "generatedAt": "2026-09-08T15:32:17.519Z",
+  "version": "0.9.27",
+  "generatedAt": "2026-09-13T09:11:30.410Z",
   "skills": [
     {
       "id": "export-jianying",
@@ -382,6 +382,10 @@
             "type": "string",
             "description": "Narration voice id. Default depends on the bound template's outputLanguage; query gen_voice with list_voices=true to see available ids."
           },
+          "speed": {
+            "type": "number",
+            "description": "Narration speech rate, 0.5-2.0 (default 1.0). Stored at global.narration.speed and applied when prepare_video_assets synthesizes the voice-over. **Must** pass when the user picked a speech rate — a template's 语速 / speed parameter arrives as a multiplier like 1.1, and without this flag it is silently dropped and the narration comes back at 1.0. Above ~1.3 subtitle alignment drifts and the delivery sounds mechanical; suggest shortening the script instead of raising it further."
+          },
           "template_id": {
             "type": "string",
             "description": "Template id (e.g. html-slide). The template owns outputLanguage and may also declare a defaultVoiceId; both flow into the produced DSL."
@@ -444,6 +448,7 @@
           "ratio",
           "scenes",
           "voice_id",
+          "speed",
           "template_id",
           "headline",
           "subheadline",
@@ -631,7 +636,7 @@
           },
           "voice_id": {
             "type": "string",
-            "description": "Voice id. Default 'Chinese (Mandarin)_Male_Announcer'. When unsure, call with list_voices=true first to see what's available — do not invent ids."
+            "description": "Voice id. Default 'Chinese (Mandarin)_Male_Announcer'. When unsure, call with list_voices=true first to see what's available — do not invent ids, and do not declare a voice unavailable unless it is missing from that list."
           },
           "speed": {
             "type": "number",
@@ -639,11 +644,7 @@
           },
           "list_voices": {
             "type": "boolean",
-            "description": "List available voices and exit"
-          },
-          "local": {
-            "type": "boolean",
-            "description": "Used together with list_voices=true: print the voice-resolver fallback catalog with language tags (no remote /voice/page call). Output is one '<id>\\t<lang>\\t<name>' line per voice."
+            "description": "List the available voices and exit. This queries the live voice service and is the authoritative catalog — one call is enough, and its absence from this list is the only evidence that a voice id is invalid."
           },
           "json_output": {
             "type": "boolean",
@@ -662,8 +663,7 @@
         ],
         "hidden": [
           "json_output",
-          "list_voices",
-          "local"
+          "list_voices"
         ]
       }
     },
@@ -960,6 +960,162 @@
         ]
       }
     },
+    {
+      "id": "web-read",
+      "toolName": "web_read",
+      "tier": "tool",
+      "category": "consuming",
+      "title": "Web Page Reader",
+      "summary": "Open any URL in a headless browser (Playwright Python) and return the page's MAIN TEXT — title, headings, paragraphs, lists, code blocks and tables — as Markdown, plain text, or structured JSON. Boilerplate (nav / sidebar / comments / ads / footer) is stripped by a Readability-style pass, and JS-rendered pages work because a real browser runs the page. This is the tool to use whenever you need to KNOW WHAT A PAGE SAYS: summarizing an article, pulling source material for a script, reading a README or docs page, checking what a link contains. It returns text, not pictures — for a screenshot (png/jpg) use web_screenshot, for a recording (mp4/webm) use web_record. Output is capped by max_chars (default 20000) and truncated on a block boundary; pass an `output` path to keep the full text on disk.",
+      "triggers": [
+        "Read this link / what does this page say / summarize this article",
+        "Fetch page content, extract article text, get the text of a URL",
+        "Use a web page as source material for a script or video",
+        "Read a README / docs page / changelog / blog post",
+        "Pull code samples or tables out of a page"
+      ],
+      "entry": {
+        "type": "python",
+        "scriptPath": "../web-screenshot/scripts/read_page.py"
+      },
+      "runtime": "python",
+      "envVars": [
+        "WEB_CAPTURE_BROWSER",
+        "WEB_CAPTURE_ALLOW_PRIVATE_HOSTS",
+        "PLAYWRIGHT_BROWSERS_PATH"
+      ],
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "url": {
+            "type": "string",
+            "description": "Target page URL (http/https). Private / loopback / link-local addresses are refused unless WEB_CAPTURE_ALLOW_PRIVATE_HOSTS=1."
+          },
+          "format": {
+            "type": "string",
+            "enum": [
+              "markdown",
+              "text",
+              "json"
+            ],
+            "description": "markdown (default: keeps headings, lists, code fences, tables) | text (plain) | json (structured blocks + metadata, not truncated)"
+          },
+          "max_chars": {
+            "type": "number",
+            "description": "Cap on the printed text, cut at a block boundary with an explicit [truncated] notice (default 20000, 0 = unlimited). Raise it when you need the whole document; a very long page will otherwise fill your context."
+          },
+          "selector": {
+            "type": "string",
+            "description": "Read only inside this CSS selector. Leave empty to auto-detect the article container — only reach for this when the auto-detected container was wrong."
+          },
+          "include_links": {
+            "type": "boolean",
+            "description": "Keep hyperlinks as [text](url) instead of plain text. Useful when you need to follow links from the page."
+          },
+          "include_images": {
+            "type": "boolean",
+            "description": "Keep images as ![alt](src). Useful for harvesting illustration URLs out of an article."
+          },
+          "output": {
+            "type": "string",
+            "description": "Also write the FULL (untruncated) text to this local path. stdout still respects max_chars — use this when a long page must be kept for later steps."
+          },
+          "settle_ms": {
+            "type": "number",
+            "description": "Extra wait before extracting, in ms. Raise for pages that render content late."
+          },
+          "wait_for_selector": {
+            "type": "string",
+            "description": "Wait for this CSS selector before extracting (the reliable fix for JS-rendered content)"
+          },
+          "wait_for_timeout": {
+            "type": "number",
+            "description": "Fixed wait before extracting, in ms"
+          },
+          "device": {
+            "type": "string",
+            "description": "Device emulation name, e.g. 'iPhone 15 Pro' — some sites serve a leaner page to mobile"
+          },
+          "viewport": {
+            "type": "string",
+            "description": "Viewport as 'width,height', e.g. '1280,800'"
+          },
+          "color_scheme": {
+            "type": "string",
+            "enum": [
+              "light",
+              "dark",
+              "no-preference"
+            ],
+            "description": "Emulate prefers-color-scheme"
+          },
+          "user_agent": {
+            "type": "string",
+            "description": "Override the User-Agent (try this when a site blocks headless browsers)"
+          },
+          "timeout": {
+            "type": "number",
+            "description": "Global Playwright action timeout in ms"
+          },
+          "ignore_https_errors": {
+            "type": "boolean",
+            "description": "Ignore HTTPS certificate errors"
+          },
+          "storage_state": {
+            "type": "string",
+            "description": "Path to a Playwright storageState JSON file (logged-in session)"
+          },
+          "cookies": {
+            "type": "string",
+            "description": "Playwright cookies as a JSON string or a path to a JSON file (top level is an array)"
+          },
+          "browser": {
+            "type": "string",
+            "enum": [
+              "chromium",
+              "firefox",
+              "webkit"
+            ],
+            "description": "Browser engine (default chromium)"
+          },
+          "quiet": {
+            "type": "boolean",
+            "description": "Suppress the extraction diagnostics on stderr"
+          }
+        },
+        "required": [
+          "url"
+        ]
+      },
+      "ui": {
+        "primary": [
+          "url",
+          "format",
+          "max_chars"
+        ],
+        "advanced": [
+          "selector",
+          "include_links",
+          "include_images",
+          "wait_for_selector",
+          "settle_ms",
+          "device",
+          "viewport",
+          "color_scheme",
+          "timeout"
+        ],
+        "hidden": [
+          "output",
+          "quiet",
+          "user_agent",
+          "ignore_https_errors",
+          "storage_state",
+          "cookies",
+          "browser",
+          "wait_for_timeout"
+        ]
+      }
+    },
     {
       "id": "web-record",
       "toolName": "web_record",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remixmate/cli",
-  "version": "0.9.25",
+  "version": "0.9.27",
   "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",
@@ -21,8 +21,10 @@
     "smoke": "node scripts/smoke.mjs",
     "test:cli": "npm run build && node --test test/*.test.mjs",
     "test:validators": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-validators.py",
+    "test:web-read": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-web-read.py",
     "test:template-pipeline": "PYTHONDONTWRITEBYTECODE=1 node dist/cli.js exec -- python3 scripts/test-template-pipeline.py",
     "test:props-contract": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-props-contract.py",
+    "test:narration-speed": "PYTHONDONTWRITEBYTECODE=1 python3 scripts/test-narration-speed.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",
     "test:contracts": "PYTHONDONTWRITEBYTECODE=1 python3 skills/template-registry/scripts/check_contracts.py",

package/skills/gen-script/SKILL.md

@@ -401,6 +401,7 @@ python3 <SkillDir>/scripts/gen_script.py \
 | `--ratio` | Aspect ratio. | `16:9` |
 | `--scenes` | Scene count. | auto-planned |
 | `--voice-id` | Narration voice id. | resolved from template + language fallback |
+| `--speed` | Narration speech rate (0.5–2.0), written to `global.narration.speed` and applied when `prepare_video_assets` calls gen-voice. Pass it whenever the user picked a speed (the replicate form's 语速 field sends one). Above ~1.3 subtitle alignment drifts and the delivery turns mechanical — shorten the script instead. | `1.0` |
 | `--allow-digital-human` | Whether to allow digital-human assets. | off |
 | `--allow-ai-video` | Whether to allow AI-generated video assets. | off |
 | `--validate` | Validate-only mode: only validate the input DSL. | — |

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

@@ -80,6 +80,24 @@ FALLBACK_VOICE = {
     "en": "english-male-friendly-01",
 }
 
+# ── Narration speed ───────────────────────────────────────────────────────────
+# Written to global.narration.speed; render_video copies it down into the
+# gen-voice asset payload (same route as narration text) and passes it to
+# `gen-voice --speed`. The envelope mirrors gen-voice's own 0.5–2.0 contract;
+# the real per-voice limits (capabilities speedMin/speedMax) are only known at
+# synthesis time, which is several confirmation steps and a few paid image
+# generations later — so an obviously-out-of-range value fails here instead.
+DEFAULT_NARRATION_SPEED = 1.0
+SPEED_MIN = 0.5
+SPEED_MAX = 2.0
+
+
+def _resolve_narration_speed(speed):
+    """CLI speed → the value written to global.narration.speed. Total function."""
+    if speed is None:
+        return DEFAULT_NARRATION_SPEED
+    return float(speed)
+
 
 def _resolve_template_language_meta(template_config):
     """Tolerant reader for outputLanguage / defaultVoiceId on a template dict.
@@ -750,6 +768,7 @@ def _build_carousel_caption_dsl(
     resolution: str,
     output_language: str,
     resolved_voice_id: str,
+    narration_speed: float,
     font_id: str | None,
     font_name: str | None,
     narration_enabled: bool,
@@ -907,7 +926,7 @@ def _build_carousel_caption_dsl(
             # 无配音模板：关闭 CC 字幕（字幕段是 narration→TTS 的派生物），
             # 并省略 global.narration，避免下游误判存在旁白。
             "subtitle": {"enabled": narration_enabled, "style": "bottom"},
-            **({"narration": {"voiceId": resolved_voice_id, "speed": 1.0}} if narration_enabled else {}),
+            **({"narration": {"voiceId": resolved_voice_id, "speed": narration_speed}} if narration_enabled else {}),
             **({"font": {"fontId": font_id, **({"fontName": font_name} if font_name else {})}} if font_id else {}),
             "bgm": {"enabled": True, "volume": 0.12},
         },
@@ -961,6 +980,7 @@ def build_dsl(
         scene_count: int | None,
         allow_digital_human: bool,
         allow_ai_video: bool,
+        speed: float | None = None,
         template_id: str | None = None,
         stub_image_url: str = "",
         stub_video_url: str = "",
@@ -992,6 +1012,10 @@ def build_dsl(
     图给第 i 个场景，没被占到的场景照常走 gen-image 补图。这条规则不是随便定的——
     见 docs/asset-annotation-design.md §6：另外两种立场（模型自由挑选 / 严格一一对应）
     都会让"只传两张图"要么失去可预期性，要么直接跑不通。
+
+    speed 是旁白语速倍率，落在 global.narration.speed（不给 = 1.0）。它**不写进
+    gen-voice 资产的 payload**——与旁白文本同一条规矩：唯一来源在 DSL 上，
+    render_video 在调 TTS 前按 assetRef 回查注入，免得两处存一个值各自漂移。
     """
     # Load template config（registry 单一数据源）→ 归一化 contract
     template_config = _load_template_config(template_id) if template_id else None
@@ -1010,6 +1034,7 @@ def build_dsl(
     # values fall back to "zh" so old templates keep their current behavior.
     output_language, template_default_voice_id = _resolve_template_language_meta(template_config)
     resolved_voice_id = _resolve_voice_id(voice_id, template_default_voice_id, output_language)
+    narration_speed = _resolve_narration_speed(speed)
     if resolved_voice_id != voice_id:
         print(
             f"ℹ️  voice resolution: cli={voice_id!r} → resolved={resolved_voice_id!r} "
@@ -1087,6 +1112,7 @@ def build_dsl(
             resolution=resolution,
             output_language=output_language,
             resolved_voice_id=resolved_voice_id,
+            narration_speed=narration_speed,
             font_id=font_id,
             font_name=font_name,
             narration_enabled=needs_narration,
@@ -1377,7 +1403,7 @@ def build_dsl(
             # 无配音模板：关闭 CC 字幕（字幕段是 narration→TTS 的派生物），并省略
             # global.narration，避免下游误判存在旁白。
             "subtitle": {"enabled": needs_narration, "style": "bottom"},
-            **({"narration": {"voiceId": resolved_voice_id, "speed": 1.0}} if needs_narration else {}),
+            **({"narration": {"voiceId": resolved_voice_id, "speed": narration_speed}} if needs_narration else {}),
             **({"font": {"fontId": font_id, **({"fontName": font_name} if font_name else {})}} if font_id else {}),
             "bgm": {"enabled": True, "volume": 0.12},
         },
@@ -1416,7 +1442,18 @@ Examples:
     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.")
     parser.add_argument("--resolution", default="1080p", help="Resolution (default: 1080p)")
     parser.add_argument("--scenes", type=int, default=None, help="Scene count (default: auto-planned)")
-    parser.add_argument("--voice-id", default=None, help="Narration voice id. When omitted, the resolver picks template.defaultVoiceId, then the language-keyed fallback (zh→Chinese (Mandarin)_Male_Announcer, en→TBD English voice). gen_voice --list-voices --local prints the language-tagged catalog.")
+    parser.add_argument("--voice-id", default=None, help="Narration voice id. When omitted, the resolver picks template.defaultVoiceId, then the language-keyed fallback (zh→Chinese (Mandarin)_Male_Announcer, en→TBD English voice). gen_voice --list-voices prints the live catalog.")
+    parser.add_argument(
+        "--speed",
+        type=float,
+        default=None,
+        help=(
+            f"Narration speech rate ({SPEED_MIN}-{SPEED_MAX}, default {DEFAULT_NARRATION_SPEED}). "
+            "Stored at global.narration.speed and applied by render_video when it calls gen-voice. "
+            "Above ~1.3 subtitle alignment starts to drift and the delivery turns mechanical — "
+            "shorten the script instead."
+        ),
+    )
     parser.add_argument(
         "--font-id",
         default=None,
@@ -1521,6 +1558,15 @@ Examples:
         parser.print_help()
         sys.exit(1)
 
+    if args.speed is not None and not (SPEED_MIN <= args.speed <= SPEED_MAX):
+        print(
+            f"❌ --speed must be in the range {SPEED_MIN}~{SPEED_MAX} (got {args.speed}).\n"
+            "   Speech rate is a multiplier, not a percentage: 1.0 is the voice's own pace, "
+            "1.1 is slightly brisker.",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
     # ── 模板感知的 ratio 自动推导 ────────────────────────────────────────────
     # 用户没显式传 --ratio 时：
     #   1. 若指定了 --template-id，取模板 supportedAspectRatios[0]（避免横竖屏不匹配）
@@ -1552,6 +1598,8 @@ Examples:
     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:
+        print(f"   narration speed: {args.speed}x", file=sys.stderr)
 
     # CLI flag takes precedence; env vars act as fallback with a visible warning
     # so silent cross-session leakage is always observable.
@@ -1592,6 +1640,7 @@ Examples:
         ratio=args.ratio,
         resolution=args.resolution,
         voice_id=args.voice_id,
+        speed=args.speed,
         font_id=args.font_id,
         font_name=args.font_name,
         scene_count=args.scenes,

package/skills/gen-script/skill.json

@@ -52,6 +52,10 @@
         "type": "string",
         "description": "Narration voice id. Default depends on the bound template's outputLanguage; query gen_voice with list_voices=true to see available ids."
       },
+      "speed": {
+        "type": "number",
+        "description": "Narration speech rate, 0.5-2.0 (default 1.0). Stored at global.narration.speed and applied when prepare_video_assets synthesizes the voice-over. **Must** pass when the user picked a speech rate — a template's 语速 / speed parameter arrives as a multiplier like 1.1, and without this flag it is silently dropped and the narration comes back at 1.0. Above ~1.3 subtitle alignment drifts and the delivery sounds mechanical; suggest shortening the script instead of raising it further."
+      },
       "template_id": {
         "type": "string",
         "description": "Template id (e.g. html-slide). The template owns outputLanguage and may also declare a defaultVoiceId; both flow into the produced DSL."
@@ -114,6 +118,7 @@
       "ratio",
       "scenes",
       "voice_id",
+      "speed",
       "template_id",
       "headline",
       "subheadline",

package/skills/gen-script/version.json

@@ -2,6 +2,6 @@
   "skillName": "gen-script",
   "repoName": "agent-skill-media-maker",
   "skillId": "474",
-  "version": "V11",
+  "version": "V12",
   "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/gen-voice/SKILL.md

@@ -46,13 +46,15 @@ There is no skill-local env file — the executing process inherits the system e
 remixmate gen-voice --list-voices
 ```
 
-To inspect the local language-tagged fallback catalog used by the voice resolver (no remote API call), add `--local`:
+The list above is the **authoritative** catalog — a voice id is invalid only if it is missing from it.
+
+For offline development (no token / no network) there is a `--local` escape hatch. It prints the resolver's two hardcoded fallback ids, **not** the available voices, so never use it to decide whether a voice exists:
 
 ```bash
 remixmate gen-voice --list-voices --local
 ```
 
-The local catalog prints one voice per line as `<voice-id>\t<lang>\t<display-name>`.
+It prints one line per entry as `<voice-id>\t<lang>\t<display-name>`.
 
 ### Default synthesis (URL output)
 
@@ -83,7 +85,7 @@ remixmate gen-voice --text "<text-to-synthesize>" --json-output
 | `--voice-id` | Voice id (use `--list-voices` to discover) | `Chinese (Mandarin)_Male_Announcer` |
 | `--speed` | Speech rate, 0.5–2.0 | `1.0` |
 | `--list-voices` | List available voices and exit | — |
-| `--local` | Used with `--list-voices`: print the local fallback catalog (offline) | off |
+| `--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 |
 | `--priv-token` | Override token | env var |