@gitruck/cli 1.2.7 → 1.2.9

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@gitruck/cli",
-	"version": "1.2.7",
+	"version": "1.2.9",
 	"description": "同合云成片流水线 CLI —— agent 驱动云端任务、产物拉回本地、三方工程文件（客户端/剪映/PR）互通。",
 	"license": "MIT",
 	"author": "Gitruck (同合云)",
@@ -50,7 +50,7 @@
 		"build": "bun build ./src/index.ts --target=node --minify --outfile dist/index.js",
 		"typecheck": "tsc --noEmit",
 		"prepublishOnly": "npm run typecheck && npm test && bun run build",
-		"test": "esbuild src/lib/compliance-notice.ts src/lib/config.ts src/lib/crash-report.ts src/lib/enum-catalog.ts src/lib/first-run-tutorial.ts src/lib/desktop-client-hint.ts src/lib/command-path.ts src/lib/user-path.ts src/lib/runtime-channel.ts src/lib/self-install.ts src/lib/chunk-upload.ts src/lib/upload-cache.ts src/lib/upload-submit.ts src/lib/render.ts src/lib/cloud.ts src/lib/materialize.ts src/lib/jianying.ts src/lib/clip-brief.ts src/lib/media.ts src/lib/projection.ts src/lib/reproject.ts src/lib/splitdoc.ts src/lib/gtrk-writeback.ts src/lib/gtrk-patch.ts src/lib/frame-domain.ts src/lib/clock-adapter.ts src/lib/gtrk-invariants.ts src/lib/column-config.ts src/lib/third-party-catalog.ts src/lib/mg-adopt.ts src/lib/mg-registry.ts src/lib/matrix.ts src/lib/matrix-material.ts src/lib/matrix-fetch.ts src/lib/matrix-lay.ts src/lib/arrange-metering.ts src/lib/arrange-wire.ts src/lib/arrange-apply.ts src/lib/arrange-client.ts src/lib/arrange-gate.ts src/lib/arrange-decision-pin.ts src/lib/arrange-qc.ts src/lib/arrange-qc-bind.ts src/lib/rate-limit-wait.ts src/lib/embed-client.ts src/lib/describe.ts src/lib/highlight-rubric.ts src/lib/local-index.ts src/lib/index-decode.ts src/lib/local-search.ts src/lib/qc.ts src/lib/alignment-qc.ts src/lib/bgm-history.ts src/lib/image-move.ts src/lib/cloud-render-guard.ts src/lib/outdir-guard.ts src/lib/landing-wait.ts src/lib/material-integrity.ts src/lib/solid-png.ts src/lib/mask-raster.ts src/lib/mg-lint.ts src/lib/mg-visual-job.ts src/lib/mg-track-identity.ts src/lib/particle-identity.ts src/lib/text-ir/compile.ts src/lib/text-ir/validate.ts src/lib/text-ir/compile-local.ts src/lib/text-templates.ts src/lib/text-ir-client.ts src/lib/mg-lay.ts src/lib/mg-render.ts src/lib/particle-qtrle.ts src/lib/tool-descriptors.ts src/lib/tool-runner.ts src/lib/tool-pricing.ts src/lib/transcript.ts src/lib/runtime-assets.ts src/lib/subtitle-lay.ts src/lib/caption-align.ts src/lib/subtitle-line-split-client.ts src/lib/audio-align.ts src/lib/audio-tighten.ts src/lib/ai-drama-lay.ts src/lib/pip-lay.ts --bundle --platform=node --format=esm --external:bun:sqlite --outdir=.test-build --out-extension:.js=.mjs && esbuild src/lib/text-ir/compile.ts --bundle --platform=node --format=esm --outfile=.test-build/text-ir-compile.mjs && esbuild src/commands/split.ts --bundle --platform=node --format=esm --outdir=.test-build --out-extension:.js=.mjs && esbuild src/commands/patch.ts --bundle --platform=node --format=esm --external:commander --outfile=.test-build/patch-cmd.mjs && esbuild src/commands/matrix.ts --bundle --platform=node --format=esm --external:bun:sqlite --outfile=.test-build/matrix-cmd.mjs && esbuild src/commands/mg.ts --bundle --platform=node --format=esm --outfile=.test-build/mg-cmd.mjs && esbuild src/commands/mg-text.ts --bundle --platform=node --format=esm --outfile=.test-build/mg-text-cmd.mjs && esbuild src/commands/tool.ts --bundle --platform=node --format=esm --outfile=.test-build/tool-cmd.mjs && esbuild src/commands/transcript.ts --bundle --platform=node --format=esm --outfile=.test-build/transcript-cmd.mjs && esbuild src/commands/project.ts --bundle --platform=node --format=esm --outfile=.test-build/project-cmd.mjs && esbuild src/commands/audio.ts --bundle --platform=node --format=esm --outfile=.test-build/audio-cmd.mjs && esbuild src/commands/subtitle.ts --bundle --platform=node --format=esm --outfile=.test-build/subtitle-cmd.mjs && esbuild src/commands/ai-drama.ts --bundle --platform=node --format=esm --outfile=.test-build/ai-drama-cmd.mjs && esbuild src/commands/feedback.ts --bundle --platform=node --format=esm --outfile=.test-build/feedback-cmd.mjs && esbuild src/commands/music-visualizer.ts --bundle --platform=node --format=esm --external:commander --outfile=.test-build/music-visualizer-cmd.mjs && esbuild src/commands/long2short.ts --bundle --platform=node --format=esm --external:commander --outfile=.test-build/long2short-cmd.mjs && esbuild src/commands/oralcut.ts --bundle --platform=node --format=esm --external:commander --outfile=.test-build/oralcut-cmd.mjs && esbuild src/commands/oralcut-result.ts --bundle --platform=node --format=esm --external:commander --outfile=.test-build/oralcut-result-cmd.mjs && esbuild src/commands/skills.ts --bundle --platform=node --format=esm --outfile=.test-build/skills-cmd.mjs && esbuild src/commands/qc.ts --bundle --platform=node --format=esm --external:commander --external:bun:sqlite --outfile=.test-build/qc-cmd.mjs && esbuild src/lib/convert/ir_to_jsx.ts src/lib/convert/ir_to_am.ts src/lib/convert/ir_to_nv.ts src/lib/convert/am_parse.ts src/lib/convert/nv_parse.ts src/lib/convert/parse.ts src/lib/convert/download.ts src/lib/convert/bake_ops.ts --bundle --platform=node --format=esm --outdir=.test-build/convert --out-extension:.js=.mjs && esbuild src/lib/mad/selector.ts src/lib/mad/techniques.ts src/lib/mad/beat.ts src/lib/mad/scan.ts src/lib/mad/data.ts src/lib/mad/pool.ts src/lib/mad/cloud-beat.ts src/lib/mad/mad.ts --bundle --platform=node --format=esm --outdir=.test-build/mad --out-extension:.js=.mjs && node --import ./test/helpers/test-home.mjs --test \"test/*.test.mjs\"",
+		"test": "esbuild src/lib/compliance-notice.ts src/lib/config.ts src/lib/crash-report.ts src/lib/log.ts src/lib/read-json.ts src/lib/enum-catalog.ts src/lib/first-run-tutorial.ts src/lib/desktop-client-hint.ts src/lib/command-path.ts src/lib/user-path.ts src/lib/runtime-channel.ts src/lib/self-install.ts src/lib/chunk-upload.ts src/lib/upload-cache.ts src/lib/upload-submit.ts src/lib/render.ts src/lib/cloud.ts src/lib/materialize.ts src/lib/jianying.ts src/lib/clip-brief.ts src/lib/media.ts src/lib/projection.ts src/lib/reproject.ts src/lib/splitdoc.ts src/lib/gtrk-writeback.ts src/lib/gtrk-patch.ts src/lib/frame-domain.ts src/lib/clock-adapter.ts src/lib/gtrk-invariants.ts src/lib/column-config.ts src/lib/third-party-catalog.ts src/lib/mg-adopt.ts src/lib/mg-registry.ts src/lib/matrix.ts src/lib/matrix-material.ts src/lib/matrix-fetch.ts src/lib/matrix-lay.ts src/lib/arrange-metering.ts src/lib/arrange-wire.ts src/lib/arrange-apply.ts src/lib/arrange-client.ts src/lib/arrange-gate.ts src/lib/arrange-decision-pin.ts src/lib/arrange-qc.ts src/lib/arrange-qc-bind.ts src/lib/rate-limit-wait.ts src/lib/embed-client.ts src/lib/describe.ts src/lib/highlight-rubric.ts src/lib/local-index.ts src/lib/index-decode.ts src/lib/local-search.ts src/lib/qc.ts src/lib/alignment-qc.ts src/lib/bgm-history.ts src/lib/image-move.ts src/lib/cloud-render-guard.ts src/lib/outdir-guard.ts src/lib/landing-wait.ts src/lib/material-integrity.ts src/lib/solid-png.ts src/lib/mask-raster.ts src/lib/mg-lint.ts src/lib/mg-visual-job.ts src/lib/mg-track-identity.ts src/lib/particle-identity.ts src/lib/text-ir/compile.ts src/lib/text-ir/validate.ts src/lib/text-ir/compile-local.ts src/lib/text-templates.ts src/lib/text-ir-client.ts src/lib/mg-lay.ts src/lib/mg-render.ts src/lib/particle-qtrle.ts src/lib/tool-descriptors.ts src/lib/tool-runner.ts src/lib/tool-pricing.ts src/lib/transcript.ts src/lib/runtime-assets.ts src/lib/subtitle-lay.ts src/lib/caption-align.ts src/lib/subtitle-line-split-client.ts src/lib/audio-align.ts src/lib/audio-tighten.ts src/lib/ai-drama-lay.ts src/lib/pip-lay.ts --bundle --platform=node --format=esm --external:bun:sqlite --outdir=.test-build --out-extension:.js=.mjs && esbuild src/lib/text-ir/compile.ts --bundle --platform=node --format=esm --outfile=.test-build/text-ir-compile.mjs && esbuild src/commands/split.ts --bundle --platform=node --format=esm --outdir=.test-build --out-extension:.js=.mjs && esbuild src/commands/patch.ts --bundle --platform=node --format=esm --external:commander --outfile=.test-build/patch-cmd.mjs && esbuild src/commands/matrix.ts --bundle --platform=node --format=esm --external:bun:sqlite --outfile=.test-build/matrix-cmd.mjs && esbuild src/commands/mg.ts --bundle --platform=node --format=esm --outfile=.test-build/mg-cmd.mjs && esbuild src/commands/mg-text.ts --bundle --platform=node --format=esm --outfile=.test-build/mg-text-cmd.mjs && esbuild src/commands/tool.ts --bundle --platform=node --format=esm --outfile=.test-build/tool-cmd.mjs && esbuild src/commands/transcript.ts --bundle --platform=node --format=esm --outfile=.test-build/transcript-cmd.mjs && esbuild src/commands/project.ts --bundle --platform=node --format=esm --outfile=.test-build/project-cmd.mjs && esbuild src/commands/audio.ts --bundle --platform=node --format=esm --outfile=.test-build/audio-cmd.mjs && esbuild src/commands/subtitle.ts --bundle --platform=node --format=esm --outfile=.test-build/subtitle-cmd.mjs && esbuild src/commands/ai-drama.ts --bundle --platform=node --format=esm --outfile=.test-build/ai-drama-cmd.mjs && esbuild src/commands/feedback.ts --bundle --platform=node --format=esm --outfile=.test-build/feedback-cmd.mjs && esbuild src/commands/music-visualizer.ts --bundle --platform=node --format=esm --external:commander --outfile=.test-build/music-visualizer-cmd.mjs && esbuild src/commands/long2short.ts --bundle --platform=node --format=esm --external:commander --outfile=.test-build/long2short-cmd.mjs && esbuild src/commands/oralcut.ts --bundle --platform=node --format=esm --external:commander --outfile=.test-build/oralcut-cmd.mjs && esbuild src/commands/oralcut-result.ts --bundle --platform=node --format=esm --external:commander --outfile=.test-build/oralcut-result-cmd.mjs && esbuild src/commands/skills.ts --bundle --platform=node --format=esm --outfile=.test-build/skills-cmd.mjs && esbuild src/commands/qc.ts --bundle --platform=node --format=esm --external:commander --external:bun:sqlite --outfile=.test-build/qc-cmd.mjs && esbuild src/lib/convert/ir_to_jsx.ts src/lib/convert/ir_to_am.ts src/lib/convert/ir_to_nv.ts src/lib/convert/am_parse.ts src/lib/convert/nv_parse.ts src/lib/convert/parse.ts src/lib/convert/download.ts src/lib/convert/bake_ops.ts --bundle --platform=node --format=esm --outdir=.test-build/convert --out-extension:.js=.mjs && esbuild src/lib/mad/selector.ts src/lib/mad/techniques.ts src/lib/mad/beat.ts src/lib/mad/scan.ts src/lib/mad/data.ts src/lib/mad/pool.ts src/lib/mad/cloud-beat.ts src/lib/mad/mad.ts --bundle --platform=node --format=esm --outdir=.test-build/mad --out-extension:.js=.mjs && node --import ./test/helpers/test-home.mjs --test \"test/*.test.mjs\"",
 		"test:linux": "node scripts/test-linux.mjs",
 		"openspec:gate": "node openspec/gate.mjs",
 		"mg-registry:snapshot": "node scripts/mg-registry-snapshot.mjs",

package/skills/gtrk-mg/SKILL.md

@@ -47,7 +47,8 @@ description: MG 动态图颗粒铺轨器——成片 SOP 第 ⑤ 步（**最后
   4. **用文字模板**：同合云自家的文字特效模板库（`gtrk mg fetch --source text`，见下节「文字模板工作流」）。改字走 `gtrk mg compile`、改效果走 `gtrk mg edit --say`。
      ⚠️ **它的适用面由派单的 `visual_job` 决定，不由「省不省事」决定**（见下「按 visual_job 路由」）。
   另可查推荐目录（公约 §三‴）：`gtrk skills recommend --scene mg-explainer` 列第三方 MG 生产 skill，装完 `gtrk skills add <owner/repo> --produces MG` 登记即被本节解析到——本 skill 正文不点名任何仓、不点名任何块。
-- **有匹配时中性块与文字模板缺省都不用**：只当栏目 skill 明显不擅长某类（如数据图表 / 界面拟物 / 纯文字入场）时可**提议**「这一槽用中性块」或「这一槽用文字模板」，用户点头才用。
+  推荐目录另有一方**排版技法族**（`gtrk skills recommend --scene technique`）：技法不是生产者、不登记为 MG 车道（`routing:none`），某槽位的内容形态命中某技法（如引用文献页 / 截图局部强调）时由你按槽位取用——内容与节奏按口播定、栏目色未定时用技法自带的中性底；本 skill 正文同样不点名仓。
+- **有匹配时中性块与文字模板缺省都不用**：只当栏目 skill 明显不擅长某类（如数据图表 / 界面拟物 / 纯文字入场）时可**提议**「这一槽用中性块」或「这一槽用文字模板」，用户点头才用。技法族同理——槽位内容形态命中某技法时可**提议**「这一槽用技法」（`gtrk skills recommend --scene technique`），栏目色板与字体照栏目注入，用户点头才用。
 
 ## ★ 按 `visual_job` 路由（不是按省事路由）
 
@@ -187,6 +188,9 @@ gtrk mg lint "<产物目录>/mg/<composition_id>.html" --dispatch "<产物目录
 
 - 纯本地静态校验颗粒 HTML 的**铁律机器可判定子集**：`<template>` 包裹、`data-composition-id` + 1920×1080、`gsap.timeline({ paused: true })`、`window.__timelines` 注册、无 `Math.random` / `Date.now`（可逐帧 seek 的确定性）、自包含无相对外链、`background` 声明与 `opaque` 自洽…；给 `--dispatch` 会额外校验 `composition_id` 命中派单。
 - **`1-cid-expect`（致命）——复制改名必查**：颗粒内部的 `data-composition-id` 必须等于期望 id（`--dispatch` 命中时 = 该条派单的 `composition_id`，否则 = 文件名）。**你从别的颗粒复制模板时最容易漏改内部 id**：那样铺出来的 clip 指向 A、文件注册的却是 `__timelines["B"]`，渲染必错，且两颗粒抢同一个 `[data-composition-id]` 样式作用域。改名的临时副本（`./tmp.html`）不比对，不会误伤。
+- **铁律④⑤「体积上限」两项**（正本条款 = `contracts/gsap-emit-v1.md` 铁律 4⑤；上限**同源自客户端颗粒运行时**，不是 CLI 的取舍）：
+  - `4-html-size`（**致命，命中即短路、其余项不跑**）：颗粒 HTML 超过 **2,000,000 字符**——客户端 bootstrap 直接拒载、每次 seek 的快照同限，这颗在客户端**永远加载不出来**（此前 lint / 铺轨 / 云渲全绿放行，2026-09-18 真实案例：整张 4.4 MB PNG base64 内嵌进 CSS 背景）。文案会点名**最大的一段 data: URI**（类型 / 字符数 / 解码字节数 / 落点）。**处置**：回步骤 2，让生产 skill 把那张图**按它在颗粒里的实际显示尺寸裁剪缩放**后再内嵌（不透明图改 JPEG / WebP，只有需要 alpha 才留 PNG）；仍超就把大图放图片素材轨、颗粒只留透明叠加层。**别拿云渲成功当反证**——云端没有这条上限，客户端有。
+  - `4-html-size-heavy`（非致命）：500,000～2,000,000 字符——客户端每次 seek 都把颗粒根节点的 outerHTML 整份快照回传，体积直接决定预览帧率。能缩就缩；**不拦铺轨**。
 - **铁律④「实心底与透明度」两项恒非致命**（正本条款 = `contracts/gsap-emit-v1.md` 铁律 4，含 2026-07-26 真机证据锚；**本处只说看到该码怎么办，元素位置以契约为准**）：
   - `4-bg-on-root`：这颗把**实心底写在了根元素的 `style` 上**。**根元素的绘制属性会在子合成挂载时被丢弃**——那层底在成片里**一个像素都不落地**：前景照常渲出、底没了、底轨透出来，观感是「浮空面板」；而**本地播放器与客户端预览都看不出**（预览会按登记的 `opaque` 位自己给根盒打底，对这个问题结构性失明）。**报了要回步骤 2 让生产 skill 把实心底下沉为子层**——改法是机械的（把那条 `background` 声明整体搬到根下第一个全幅子层，根上改写 `background:transparent`）。⚠️ 它**不影响退出码、不拦铺轨**（避免存量颗粒一夜之间铺不进去），但**不是可以放着不管的噪音**：不改就是出片丢底。
   - `4-bg-explicit`：根与根下首个全幅子层**都**没有 `background` 声明 → lint 只能按「透明叠加」处理。契约要求**透明与否显式**：满屏颗粒在全幅子层写实心底，透明叠加颗粒在根写 `background:transparent`。**别靠「不写」表达透明**——作者与机器都分不清「想透明」和「忘了想」。
@@ -211,7 +215,7 @@ gtrk mg lint "<产物目录>/mg/<composition_id>.html" --dispatch "<产物目录
   - `c-filter-indeterminate`：补间的 `filter` 值不是字符串字面量（变量 / 模板串 / 函数返回），lint **对该处没作判定**——既不是「判过且通过」，也不是命中。**人眼确认它到底会不会驱动 blur / drop-shadow**；会就按 `c-filter-animated` 的改法处理。**不拦铺轨**。
   - **`box-shadow` 整族不在射程内**（含 `box-shadow: 0 0 0 Npx` 这类零卷积脉冲写法，也含带模糊半径的写法）——看到 `box-shadow` 没被报**不是漏报**，是既定射程边界。
   - ⚠️ **没报 ≠ 这颗便宜**：这三项是**形态提示**，真判据永远是**真渲染出片计时**。收益也别外推——现网既有栏目语料（21 颗）去掉滤镜只省 **0~3.1%**（2026-07-30 真机实测，仅对该语料成立），这组规则的价值在**滤镜重的新语料进管线前先把门立好**。
-- **id 前缀读法**（三个命名空间，别按前缀反推错阻断行为）：**数字前缀 `1-`~`8-`** = 契约铁律项，致命性**按项声明**（`4-*` / `5-*` / `7-*` / `8-*` 就都不致命）；**`x-`** = 哨兵项，**恒不拦**；**`c-`** = 成本项，致命性按项声明，**当前三项均不拦**。
+- **id 前缀读法**（三个命名空间，别按前缀反推错阻断行为）：**数字前缀 `1-`~`8-`** = 契约铁律项，致命性**按项声明**（`4-html-size` **致命**且命中即短路；其余 `4-*` / `5-*` / `7-*` / `8-*` 非致命）；**`x-`** = 哨兵项，**恒不拦**；**`c-`** = 成本项，致命性按项声明，**当前三项均不拦**。
 - **不过（非 0 退出、逐条报因）→ 把报错原样丢回栏目 MG 生产 skill 修，重产重 lint，别硬铺**。铺一颗不合规颗粒会污染工程。
 - 只想批量干校验不写回：`gtrk mg --project <dir> --lint-only`（有 beat 没过就 `ok:false` + **非 0 退出**，工程一个字节都不动）。
 

package/skills/gtrk-tools/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gtrk-tools
-description: gtrk 单点工具与媒体转换能力的调用向导，覆盖 `gtrk tool` 家族。当用户想“让图动起来 / 抠像去背景 / 图片或视频去黑边 / 图片或视频比例转换 / 视频防抖 / 添加蒸汽波滤镜 / 清理有权处理的图片或视频中的水印、字幕或叠加元素 / 视频超分变清晰 / 视频补帧变流畅 / 分离人声和伴奏 / 提取伴奏 / 按说话人分轨 / 音频变调变速 / 钢琴扒谱转 MIDI 或修复钢琴录音 / 给音频或视频降噪 / 去掉音频静音停顿 / 长图转方图 / 图片变 LivePhoto 微动 / 视频机械分镜或智能分镜切镜头 / 提取运镜高光片段 / 给视频加字幕或翻译字幕或烧录字幕 / 一键剪 MAD / 用某个 gtrk 单点工具 / gtrk 工具族里有什么”时使用本 Skill。凡涉及这些能力，优先驱动 CLI，不让用户自己去终端敲，也不手搓 ffmpeg。
+description: gtrk 单点工具与媒体转换能力的调用向导，覆盖 `gtrk tool` 家族。当用户想“让图动起来 / 抠像去背景 / 图片或视频去黑边 / 图片或视频比例转换 / 视频防抖 / 添加蒸汽波滤镜 / 清理有权处理的图片或视频中的水印、字幕或叠加元素 / 视频超分变清晰 / 视频补帧变流畅 / 分离人声和伴奏 / 提取伴奏 / 按说话人分轨 / 音频变调变速 / 钢琴扒谱转 MIDI 或修复钢琴录音 / 给音频或视频降噪 / 去掉音频静音停顿 / 长图转方图 / 图片变 LivePhoto 微动 / 视频机械分镜或智能分镜切镜头 / 提取运镜高光片段 / 给视频加字幕或翻译字幕或烧录字幕 / 把视频翻译配音成另一种语言或译制 / 一键剪 MAD / 用某个 gtrk 单点工具 / gtrk 工具族里有什么”时使用本 Skill。凡涉及这些能力，优先驱动 CLI，不让用户自己去终端敲，也不手搓 ffmpeg。
 ---
 
 # gtrk 工具族（gtrk-tools）
@@ -52,10 +52,20 @@ description: gtrk 单点工具与媒体转换能力的调用向导，覆盖 `gtr
 | `image_classic_template` | 「做封面 / 智能拼图 / 标题配图出封面图」 | **多张图片**（可传多个路径，文件顺序即拼装顺序）；**`--main-title <标题>` 必填**；可选 `--sub-title`、`--template-mode`、`--aspect`、`--quality`、`--output-pic-count`（服务端钳制 ≤20）、`--output-text-count`（≤20）、`--title-layout` | 封面/拼图成品（text/pic/render 三组、各组可空可多张） | 运行前实时查询 | 已上线 |
 | `image_vertical_stitch` | 「拼长图 / 多图竖拼 / 截图接成一张长图」 | **多张图片**（可传多个路径，顺序=自上而下拼接顺序） | 一张垂直拼接长图 | 运行前实时查询 | 已上线 |
 | `audio_tts_clone` | 「配音 / 文字转语音 / TTS / 用 xx 音色念这段 / 把这段稿子合成音频」 | **无文件**：`--text <短文本>` 或 `--text-file <txt>` 二选一（≤5000 字，服务端为真相）+ **`--speaker <音色代号>` 必填**（可用音色见官网文档，传错时报错会列出全部可用项）；可选 `--text-lang`/`--output-format wav\|mp3`/`--speed`/`--split-method`/`--batch-size`/`--fragment-interval <秒>`（句间停顿，**仅自训音色**，云引擎音色传了会报错；speed/切分法缺省跟随该音色调好的参数）/`--subtitle-format <fmt>`（**可选出字幕**，如 `srt`；缺省不出字幕、不额外计费，取值以服务端为准，传了不认的格式服务端会拒并列出可用项）。**计量单位与单价以 `gtrk tool list` 实时显示为准 —— MUST NOT 在本文写死**（此处写死过一次「200 字/分钟」，服务端实为 240，且计量口径已改为千字符）** | 配音音频（wav/mp3）；传了 `--subtitle-format` 时另产字幕 `tts-<音色代号>.srt`（服务端字幕降级时只落音频、不留空字幕文件） | 运行前实时查询 | 已上线 |
+| `video_translate_dub` | 「视频翻译配音 / 译制 / 把这条视频换成英文配音 / 用我的声音说英文 / 给视频出个外语配音版」 | 单条视频或音频（**≤120 分钟**，整片上传）；**`--language <源语种>`、`--translate-language <目标语种>`、`--speaker <clone 或音色代号>` 三项必填**（语种传标准地区码如 `zh-CN` / `en-US`；可用语种与音色以服务端为准，传错时报错会列出可用项）；`clone` = 用原片说话人的声音，可加 `--ref <音频或视频>` 指定克隆参考、`--ref-lang` 标参考语种（非 `clone` 时 `--ref` 会被忽略并提示）；可选 `--no-keep-bgm`（不保留原伴奏）、`--fit-policy`（时长拟合策略）、`--speed-band <最小,最大>`（语速倍率区间）、`--subtitle-mode`（字幕形态，音频输入不能烧录）、`--subtitle-type`（烧录样式）、`--project-formats <逗号分隔>`（缺省只出客户端工程 `.gtrk`；要剪映草稿写 `gtrk,jianying`，要 PR / Final Cut 工程写如 `gtrk,xml`）、`--jianying-draft-dir <目录>`（剪映草稿目录，缺省读 `gtrk init` 配置或自动探测）；各参数取值以服务端为准 | 配音成片 `<输入名>-dub.mp4`（音频输入为 `-dub.mp3`）+ 纯配音轨 `dub.wav` + 伴奏轨 `bgm.wav`（有则）+ 延长后的底片 `base.mp4`（有则）+ 字幕 `<输入名>.srt` / `<输入名>_bilingual.srt`（有则）+ 逐句对齐记录 `transcript.json` + 工程文件按格式分目录（如 `gtrk/project.gtrk`、`jianying/`；音频输入没有）+ `result-output.json`（配音对齐报告） | 运行前实时查询 | 已上线 |
 | `mad` | 「一键剪 MAD / 素材文件夹自动出卡点成片 / 自动选技法 / 给这堆素材出个 AE 工程 / 我想要某某效果的卡点片」 | 一个素材文件夹（3~10 条视频）+ 可选 `--bgm 歌.mp3` + 可选 `--technique 技法名`；`--search <词>` 只查技法目录不要输入 | AE 母合成工程 `.jsx`（仅支持 AE） | 仅 `--bgm` 触发实时查价 | 已上线 |
 
 > 清单随 CLI 版本增补。**动手前先跑 `gtrk tool list --json` 拿最新清单**，别凭记忆——新工具、状态变化都在那里。
 
+### video_translate_dub（视频译制配音）要提前讲给用户的
+
+- **克隆声音须本人同意**：`--speaker clone`（或 `--ref` 给的是别人的录音）会克隆说话人的声音。克隆别人的声音 MUST 先取得那个人的同意，发起任务即视为已取得；不确定就先问用户，别替他默认。
+- **只换音轨，画面保持原样**：不做口型同步，镜头也不动。缺省拟合策略下，个别译句过长时画面可能短暂定格来让出时间；用户要成片与原片严格等长，传 `--fit-policy strict`（超出部分截尾）。
+- **时长与耗时**：单条最长 120 分钟，超了 CLI 在上传前直接拒并提示分段；长片耗时十几分钟起，CLI 最多等 4 小时。中途断开别直接重跑（会重新计费），凭产物目录里 `task.json` 的任务号取回。
+- **工程文件怎么打开**：CLI 提交时自动带上原片与产物目录的本机路径，各格式工程里的素材都指向本机的原片与产物目录里的 `dub.wav` / `bgm.wav` / `base.mp4`，打开即用。要剪映草稿加 `--project-formats gtrk,jianying`：草稿自动放进剪映草稿目录，打开剪映就在列表里；CLI 提示「没找到剪映草稿目录」或「草稿缺 draft_meta_info.json」时，让用户给出剪映草稿目录再用 `--jianying-draft-dir` 重跑，或先用客户端工程。CapCut 草稿留在产物目录 `capcut/`，需要时手动放进 CapCut 草稿目录。
+- **附带产物偶尔缺项不算失败**：字幕、逐句对齐记录、工程文件某一项没生成时，成片与配音轨照出、`ok=true`，终端打一行「部分附带产物未生成」，原因在 `result-output.json` 的 `errors`。照实告诉用户少了哪样。
+- 常用形态：`gtrk tool video_translate_dub ./talk.mp4 --language zh-CN --translate-language en-US --speaker clone --json`；用自己另录的干净人声做参考加 `--ref ./me.m4a`；要剪映草稿加 `--project-formats gtrk,jianying`，要 PR 工程加 `--project-formats gtrk,xml`。
+
 ### mad（一键剪 MAD）的特殊之处
 
 `mad` 是族内首个 **local 型「纯本地工具、可选云端加料」**成员，与 cloud 型工具不同：

package/skills/gtrk-travel-recap/SKILL.md

@@ -126,7 +126,7 @@ description: 旅拍解说一站式成片图纸——输入一个旅拍素材文
 **成片时长 = min(内容所支撑, 素材所支撑)**：
 - 内容支撑：有多少真东西说多少话，素材再多也不注水；
 - 素材支撑：按「30% 图片×8 秒 + 70% 视频素材时长」估算上限，稿子在写稿阶段就按上限收敛（不要等铺轨时开天窗）；把这个秒数换算成字数用下一条的折算口径（**公式本身不动**）；
-- **折算口径 = 挂钟语速**（wall-clock：稿件字数 ÷ 合成音频总时长，**含**句间停顿），**按检查点①选定的那条音色取值**；取不到该音色的语速就用**缺省 ≈330 字/分钟**，并明说这是缺省估值、**不是该音色的实测值**。3 分钟成片 ≈ **1000 字**。
+- **折算口径 = 挂钟语速**（wall-clock：稿件字数 ÷ 合成音频总时长，**含**句间停顿），**按检查点①选定的那条音色取值：读 catalog 该音色的 `speech_rate_cpm`（字/分钟），并把 `speech_rate_basis` 一并报给用户（`measured` = 实测 / `derived` = 由声学参数推算）**；catalog 没给该字段（非中文音色）或拉不到 catalog 时才用**缺省 ≈330 字/分钟**，并明说这是缺省估值、**不是该音色的实测值**。3 分钟成片 ≈ **1000 字**。
   缺省 330 的出处（★ 2026-09-02 立，`fix-speech-rate-calibration`）：全库 49 条 zh-CN 音色挂钟中位 308.7、`narrator` 349.3（**单点实测，未覆盖全库**）、260902 真机三条片 316–342 —— 逐条档案与标定方法见 `references/speech-rate.md`，**MUST NOT 把那张表贴回本图纸**（单一真值源，垂类只许引用）。
 - ⚠️ **MUST NOT 拿计费折算常量（240 字/分钟）推稿子字数**：那是**计费**用的保守下界（volc 单点实测 260 再下调留余量），与写稿侧的保守方向**正好相反**——计费侧低估语速只是「分钟数变大、不少收」，写稿侧低估语速却会让稿子写短、成片缩水（按 240 写 3 分钟 = 720 字，用 349 的挂钟语速实播只有 2.06 分钟，**缩水 31%**）。计费那一栏见 §九，两个数 MUST NOT 互相冒充。
 
@@ -197,7 +197,7 @@ gtrk matrix describe --plan <工程>/split/broll-plan.json --highlight-rubric @<
 1. **解说稿 + 标题**：正文全文贴给用户（不是给路径），标题候选列出；
 2. **画幅**（★ 打样事故教训——横屏素材铺进默认竖屏画布=信箱黑边）：问目标平台——横屏 B 站/西瓜=1920x1080，竖屏抖音=1080x1920。**素材几何与画幅不一致时明确提示**（横素材→竖画布会裁切或留边）；
 3. **TTS 音色**：拉 catalog（`GET {apiBase}/task/tts/voices`，免鉴权）按内容调性挑 2-4 个候选，**每个附试听链接**（catalog 的 audition_url 字段，api.ai-mcn.tv:9000 静态直链）——用户在对话框里直接点开听。internal 标注的音色注明「仅内部成员」。也可按用户描述语义挑（「要个温柔女声」）。
-   **每个候选还 SHALL 附上该音色的挂钟语速与据此推的稿件字数区间**（查 `references/speech-rate.md`；档案里没有就明说「用缺省 330 估」）——挑音色的同时也是在挑稿子长度，别让用户回头才发现稿子长了三成。这条是**加项**，MUST NOT 削弱既有的「无试听链接 = 未完成推荐」义务；
+   **每个候选还 SHALL 附上该音色的挂钟语速与据此推的稿件字数区间**（取同一份 catalog 载荷里的 `speech_rate_cpm` + `speech_rate_basis`，零额外往返；该字段缺席就明说「用缺省 330 估」；标定方法与历史档案见 `references/speech-rate.md`，不再从那里查数）——挑音色的同时也是在挑稿子长度，别让用户回头才发现稿子长了三成。这条是**加项**，MUST NOT 削弱既有的「无试听链接 = 未完成推荐」义务；
 4. **BGM 处置（双来源）**：
    - 用户有本地音乐 → 询问是否 `gtrk tool audio_separation` 伴奏分离后取伴奏（缺省建议分离——TTS 配音不与歌曲人声打架）；
    - 用户未提供 → **搜同和素材矩阵**：`gtrk matrix material "<按稿件情绪+地理文化写的检索词>" --scope audio --top-k 5 --diversity --json`

package/skills/gtrk-travel-recap/references/speech-rate.md

@@ -1,119 +1,139 @@
-# 语速档案（写稿折算的单一真值源 · fix-speech-rate-calibration 2026-09-02 立）
-
-> 本文件服务于 `SKILL.md` §三 的「成片时长 = min(内容支撑, 素材支撑)」——把秒数换算成字数的那一步。
-> **图纸正文只留一句指针 + 缺省值，数值表只住在这里**（垂类图纸继承通用框架层时**引用不复制**）。
->
-> 表放哪：三方案取舍如下，自裁 **(B) 过渡 + (C) 终局**。
->
-> | 方案 | 优点 | 缺点 | 判 |
-> |---|---|---|---|
-> | (A) 49 条表直接贴进 `SKILL.md` | 零新增依赖，agent 读图纸即得 | ① 淹没图纸主线（图纸是编排指南不是数据表）；② 随注册表漂移，音色增删要手改；③ 图纸随 npm 发版分发，必然过期 | **弃** |
-> | (B) 本文件（`references/speech-rate.md`） | 不淹图纸；仓内已有先例（`gtrk-cover` / `gtrk-splitter` / `gtrk-style-maker` 都有 `references/`）；能同时装标定方法与档案 | 仍是静态快照会漂；且这条口径不止旅拍要用，挂在某一个垂类下有被复制扩散的风险 | **取（过渡态）** |
-> | (C) infra 出字段 + CLI 从 catalog 直接读 | **唯一不漂**：注册表是真值源，新增音色自动带上；检查点①本来就要拉 catalog，读同一份载荷零额外往返 | 要 infra 联动件；改 `PUBLIC_FIELDS` 会让所有 ETag 失效一次；上线前 CLI 无数据 | **取（终局）** |
-> | (D) 新增 `gtrk` 子命令去查语速 | 对 agent 友好 | 净新增命令面：今天 CLI 里没有任何代码拉 `/task/tts/voices`（图纸是教 agent 直接 GET 的），为一个写稿阶段只用一次的读操作立子命令，收益不抵维护面 | **弃** |
->
-> (C) 落地后，本文件降级为**纯方法学文档**：只留 §二 标定方法与 §三 历史档案，删掉数值、改指 catalog 字段。
-
-## 一、两个数不是一回事
-
-| | 公式 | 低估语速的后果 | 保守方向 |
-|---|---|---|---|
-| **计费折算**（`_SPEECH_CHARS_PER_MINUTE = 240`） | 计费分钟 = 字数 ÷ 语速 | 分钟数变大 ⇒ **多收** | 低估是**安全**的（不少收） |
-| **写稿折算**（挂钟语速，本文件） | 成片时长 = 字数 ÷ 语速 | 时长被高估 ⇒ **稿子写短** | 低估是**有害**的（成片缩水） |
-
-240 的来历：volc 引擎**单点实测 100 汉字 ≈ 23.06 秒（约 260 字/分钟），再人为下调留余量**取 240；
-2026-08-20 起它**已退出计费链路**，保留只为时长预估。把这份「宁可低估」的偏置搬到写稿侧，
-就是本档案要治的那个缺陷 —— 按 240 写 3 分钟稿 = 720 字，用 `narrator` 349.3 的挂钟语速实播只有
-**2.06 分钟，缩水 31%**。
-
-两条口径的换算关系：**挂钟语速 = 有效语速 × (1 − 停顿占比)**。
-注册表 `acoustic.rate` 记的是**有效语速**（扣掉停顿的净说话速度），写稿要的是**挂钟**（含停顿）。
-
-## 二、标定方法（一条记录 MUST 齐备五项，缺一不得作口径依据）
-
-| # | 必填项 | 说明 |
-|---|---|---|
-| ① | **音色与引擎** | `voice_id` + `engine`（自训 gpt_sovits / 云引擎 volc / …） |
-| ② | **影响语速的合成参数** | `speed`、`fragment_interval`、`split_method` 等。`narrator` 的 `fragment_interval=0.28` 会实打实抬高句间停顿占比，不记就没法复现 |
-| ③ | **稿件** | 字数口径（Unicode 码点、含不含标点与英文数字，与服务端 `_MAX_TEXT_LEN` 同口径）+ 稿件出处或哈希 + 字数 |
-| ④ | **测量方法** | 音频总时长怎么取（`ffprobe` duration）、首尾静音算不算 |
-| ⑤ | **结果两个数 + 样本数 + 日期** | **挂钟语速**（写稿用）与**有效语速 / 停顿占比**（注册表口径），样本条数，标定日期 |
-
-两条禁令：
-
-- **MUST NOT 再写「（TTS 实测）」这类无主体、无出处的括注**。任何写进图纸的语速数字，
-  要么能指到一条满足上表的档案，要么明确标注为「派生值 / 缺省值」。
-  （这条的由来：`SKILL.md` 的「200-240 字/分钟（TTS 实测，语速快的音色偏 270）」是
-  **一次性写入、无出处**——`git log -S` 只命中 skill 首发那一个 commit，归档 change 里 grep 零命中。）
-- **单点标定 MUST NOT 外推到其它引擎的音色**。240 那次是 volc 单点标定，与自训 gpt_sovits 的
-  `narrator` 没有任何关系。
-
-## 三、已标定档案
-
-> ⚠️ **实测与派生逐条标注区分**，MUST NOT 混着读。本节今天只有一条真机实测，
-> **MUST NOT 宣称「已按新口径标定过全库」**。
-
-### 3.1 `narrator`（**单点实测 · 未覆盖全库**）
-
-| 项 | 值 |
-|---|---|
-| ① 音色 / 引擎 | `narrator`（`ext_code=narrator`）/ 自训 gpt_sovits |
-| ② 合成参数 | `speed=1.0`、`fragment_interval=0.28` |
-| ③ 稿件 | 见来源件 `fix-speech-rate-calibration`（注册表标定样本，字数口径未逐条留痕 —— **这一格是弱项，后续回校须补齐**） |
-| ④ 测量 | 注册表 `acoustic` 口径（有效语速 + 停顿占比） |
-| ⑤ 结果 | 有效语速 `rate = 379.7`、停顿占比 `pause = 0.08` ⇒ **挂钟 ≈ 349.3 字/分**；日期 2026-09-02（复算） |
-
-### 3.2 全库 49 条 zh-CN 音色（**派生值，非逐条实测**）
-
-`voice_registry.json` 55 条中 49 条带 `acoustic.rate`，据 `挂钟 = rate × (1 − pause)` 派生：
-
-| 口径 | min | 中位 | max |
-|---|---|---|---|
-| 有效语速（`rate`，注册表原值） | 309.77 | 361.13 | 427.47 |
-| **挂钟语速**（扣停顿后，写稿用） | 222.02 | **308.66** | — |
-
-**落进 200–240 区间的：0 条。低于旧图纸所称上限 270 的：0 条。** 旧口径不是「偏保守」，是全库无一命中。
-
-### 3.3 260902 真机三条旅拍片（**复盘记录，未逐条复算**）
-
-实测 **316–342 字/分**（挂钟口径），与 3.1 派生的 349.3 同量级、互为旁证。
-本条**不满足** §二 的五项（缺 ②③④ 的逐条留痕），故只作旁证、MUST NOT 单独当口径依据。
-
-### 3.4 `volc_zh_male_cixingjieshuonan_uranus_bigtts`（**五项齐备 · 双样本实测**）
-
-| 项 | 值 |
-|---|---|
-| ① 音色 / 引擎 | 磁性解说男声 2.0 `volc_zh_male_cixingjieshuonan_uranus_bigtts` / 火山引擎 `volcengine`（云引擎，非自训） |
-| ② 合成参数 | `speed` 未传（= 默认 1.0）；`fragment_interval` **不适用**——云引擎音色不受理该参数；`split_method` 走服务端默认 |
-| ③ 稿件 | 两稿，Unicode 码点口径（含标点与英文数字）。① 凯奇坎 823 码点 `sha256:fd4e4f0efaabdfa1…` ② 黄石 904 码点 `sha256:9ce70f69b9d00f20…` |
-| ④ 测量 | `ffprobe -show_entries format=duration` 取 wav 总时长，**首尾静音计入**（挂钟口径的定义即如此） |
-| ⑤ 结果 | 稿① 823 / 230.40s = **214.3**；稿② 904 / 248.33s = **218.4**；合并 1727 / 478.73s = **216.4 字/分**。样本 2 条，日期 2026-09-03 |
-
-**这条记录的价值不在它自己，在它顺手验了 §3.2 那张派生表。**
-注册表给这条音色 `rate=321.77 / pause=0.31`，按 `挂钟 = rate × (1 − pause)` 派生得 **222.0**；
-两次实测 214.3 / 218.4，偏 **−3.5% / −1.6%**。
-§3.2 的 49 条派生值此前**从未被任何实测检验过**（3.1 是注册表自身口径的复算，不是独立测量），
-本条是第一次拿真机音频去撞那条公式，**没撞坏**。派生表因此从「未经检验的推算」升格为「有一个实测锚点的推算」——
-仍 MUST NOT 宣称全库已标定，但对**云引擎 volc 这一档**，派生值可以当估值用，误差量级 <5%。
-
-⚠️ 另记一条选音色时该知道的事实：这条音色的 `pause=0.31` 是**全库最高**，挂钟 222.0 正是 §3.2 那张表的
-`min` 值本人。同一份稿子交给它，比交给缺省 330 长 **48%**，比交给 `narrator`（349.3）长 **57%**。
-写稿时 MUST 按它自己的挂钟值反推字数，照缺省 330 写会让成片直接长出三成。
-
-## 四、缺省值 330 是怎么来的，用在哪儿
-
-- **取值**：落在全库挂钟中位 **308.7** 与 `narrator` **349.3** 之间，覆盖真机 **316–342** 区间的中部；
-- **性质**：**缺省估值，不是任何一条音色的实测值**。用它折算时 SHALL 在交付说明里明示这一点；
-- **适用边界**：只适用**中文**、**正常语速档**、**未加 `--speed`** 的合成。
-  换引擎、换语种、动了 `--speed` / `fragment_interval` 的，一律回 §二 重新标定，MUST NOT 沿用；
-- **怎么退役**：终局 (C) 上线（catalog 投影出 `acoustic` 或派生只读字段）后，
-  取值路径改为「读 catalog 字段」，330 只在字段缺失时兜底。
-
-## 五、回校怎么攒样本（`SKILL.md` §五 ④′）
-
-TTS 合成完成后，稿件字数与音频实际时长都已在手（`project init --tts-task` 本就要读它）：
-
-1. 算 **实测挂钟语速 = 稿件字数 ÷ 音频实际时长**；
-2. 与写稿所用估值比对，**偏差 >15% 在交付汇报里点名**（报「估 X / 实测 Y / 偏 Z%」）；
-3. 按 §二 五项格式**追加一条**进 §三 —— 每跑一条片就攒一条样本，「孤证」这个病从结构上被治掉；
-4. **MUST NOT 自动改稿、MUST NOT 自动重跑 TTS**：改稿要从配音步重跑、重付 TTS 费用，返工与否由用户拍板。
+# 语速档案（方法学与历史档案 · fix-speech-rate-calibration 2026-09-02 立，2026-09-16 降级）
+
+> ★ **(C) 已落地（2026-09-11 上线，infra `link-voice-catalog-speech-rate`）**：写稿折算的**取值**改读 catalog（`GET {apiBase}/task/tts/voices` 每条音色的 `speech_rate_cpm` + `speech_rate_basis`），**本文件不再是数值真值源**，只保留 §一 口径划界、§二 标定方法、§三 历史档案（含日期快照，勿当现值）、§四 缺省值来历、§五 回校攒样本。§3.2 那张 49 条派生表是 2026-09-02 的快照，此后音色增删与重标不再回写此处。
+> 本文件服务于 `SKILL.md` §三 的「成片时长 = min(内容支撑, 素材支撑)」——把秒数换算成字数的那一步。
+> **图纸正文只留一句指针 + 缺省值，方法与历史只住在这里**（垂类图纸继承通用框架层时**引用不复制**）。
+>
+> 表放哪：三方案取舍如下，自裁 **(B) 过渡 + (C) 终局**。
+>
+> | 方案 | 优点 | 缺点 | 判 |
+> |---|---|---|---|
+> | (A) 49 条表直接贴进 `SKILL.md` | 零新增依赖，agent 读图纸即得 | ① 淹没图纸主线（图纸是编排指南不是数据表）；② 随注册表漂移，音色增删要手改；③ 图纸随 npm 发版分发，必然过期 | **弃** |
+> | (B) 本文件（`references/speech-rate.md`） | 不淹图纸；仓内已有先例（`gtrk-cover` / `gtrk-splitter` / `gtrk-style-maker` 都有 `references/`）；能同时装标定方法与档案 | 仍是静态快照会漂；且这条口径不止旅拍要用，挂在某一个垂类下有被复制扩散的风险 | **取（过渡态）** |
+> | (C) infra 出字段 + CLI 从 catalog 直接读 | **唯一不漂**：注册表是真值源，新增音色自动带上；检查点①本来就要拉 catalog，读同一份载荷零额外往返 | 要 infra 联动件；改 `PUBLIC_FIELDS` 会让所有 ETag 失效一次；上线前 CLI 无数据 | **取（终局）** |
+> | (D) 新增 `gtrk` 子命令去查语速 | 对 agent 友好 | 净新增命令面：今天 CLI 里没有任何代码拉 `/task/tts/voices`（图纸是教 agent 直接 GET 的），为一个写稿阶段只用一次的读操作立子命令，收益不抵维护面 | **弃** |
+>
+> (C) 落地后，本文件降级为**纯方法学文档**：只留 §二 标定方法与 §三 历史档案，取值改指 catalog 字段。——**已于 2026-09-16 执行**（见文首 ★）。
+
+## 一、两个数不是一回事
+
+| | 公式 | 低估语速的后果 | 保守方向 |
+|---|---|---|---|
+| **计费折算**（`_SPEECH_CHARS_PER_MINUTE = 240`） | 计费分钟 = 字数 ÷ 语速 | 分钟数变大 ⇒ **多收** | 低估是**安全**的（不少收） |
+| **写稿折算**（挂钟语速，本文件） | 成片时长 = 字数 ÷ 语速 | 时长被高估 ⇒ **稿子写短** | 低估是**有害**的（成片缩水） |
+
+240 的来历：volc 引擎**单点实测 100 汉字 ≈ 23.06 秒（约 260 字/分钟），再人为下调留余量**取 240；
+2026-08-20 起它**已退出计费链路**，保留只为时长预估。把这份「宁可低估」的偏置搬到写稿侧，
+就是本档案要治的那个缺陷 —— 按 240 写 3 分钟稿 = 720 字，用 `narrator` 349.3 的挂钟语速实播只有
+**2.06 分钟，缩水 31%**。
+
+两条口径的换算关系：**挂钟语速 = 有效语速 × (1 − 停顿占比)**。
+注册表 `acoustic.rate` 记的是**有效语速**（扣掉停顿的净说话速度），写稿要的是**挂钟**（含停顿）。
+
+## 二、标定方法（一条记录 MUST 齐备五项，缺一不得作口径依据）
+
+| # | 必填项 | 说明 |
+|---|---|---|
+| ① | **音色与引擎** | `voice_id` + `engine`（自训 gpt_sovits / 云引擎 volc / …） |
+| ② | **影响语速的合成参数** | `speed`、`fragment_interval`、`split_method` 等。`narrator` 的 `fragment_interval=0.28` 会实打实抬高句间停顿占比，不记就没法复现 |
+| ③ | **稿件** | 字数口径（Unicode 码点、含不含标点与英文数字，与服务端 `_MAX_TEXT_LEN` 同口径）+ 稿件出处或哈希 + 字数 |
+| ④ | **测量方法** | 音频总时长怎么取（`ffprobe` duration）、首尾静音算不算 |
+| ⑤ | **结果两个数 + 样本数 + 日期** | **挂钟语速**（写稿用）与**有效语速 / 停顿占比**（注册表口径），样本条数，标定日期 |
+
+两条禁令：
+
+- **MUST NOT 再写「（TTS 实测）」这类无主体、无出处的括注**。任何写进图纸的语速数字，
+  要么能指到一条满足上表的档案，要么明确标注为「派生值 / 缺省值」。
+  （这条的由来：`SKILL.md` 的「200-240 字/分钟（TTS 实测，语速快的音色偏 270）」是
+  **一次性写入、无出处**——`git log -S` 只命中 skill 首发那一个 commit，归档 change 里 grep 零命中。）
+- **单点标定 MUST NOT 外推到其它引擎的音色**。240 那次是 volc 单点标定，与自训 gpt_sovits 的
+  `narrator` 没有任何关系。
+
+## 三、已标定档案
+
+> ⚠️ **实测与派生逐条标注区分**，MUST NOT 混着读。本节的独立真机实测只有 §3.4（云引擎 volc 一条音色）与 §3.5（自训 `narrator`），
+> §3.1 是注册表口径复算、§3.2 是派生表，**MUST NOT 宣称「已按新口径标定过全库」**。
+
+### 3.1 `narrator`（**单点实测 · 未覆盖全库**）
+
+| 项 | 值 |
+|---|---|
+| ① 音色 / 引擎 | `narrator`（`ext_code=narrator`）/ 自训 gpt_sovits |
+| ② 合成参数 | `speed=1.0`、`fragment_interval=0.28` |
+| ③ 稿件 | 见来源件 `fix-speech-rate-calibration`（注册表标定样本，字数口径未逐条留痕 —— **这一格是弱项**，2026-09-16 已由 §3.5 用五项齐备的独立样本补上） |
+| ④ 测量 | 注册表 `acoustic` 口径（有效语速 + 停顿占比） |
+| ⑤ 结果 | 有效语速 `rate = 379.7`、停顿占比 `pause = 0.08` ⇒ **挂钟 ≈ 349.3 字/分**；日期 2026-09-02（复算） |
+
+### 3.2 全库 49 条 zh-CN 音色（**派生值，非逐条实测**）
+
+`voice_registry.json` 55 条中 49 条带 `acoustic.rate`，据 `挂钟 = rate × (1 − pause)` 派生：
+
+| 口径 | min | 中位 | max |
+|---|---|---|---|
+| 有效语速（`rate`，注册表原值） | 309.77 | 361.13 | 427.47 |
+| **挂钟语速**（扣停顿后，写稿用） | 222.02 | **308.66** | — |
+
+**落进 200–240 区间的：0 条。低于旧图纸所称上限 270 的：0 条。** 旧口径不是「偏保守」，是全库无一命中。
+
+### 3.3 260902 真机三条旅拍片（**复盘记录，未逐条复算**）
+
+实测 **316–342 字/分**（挂钟口径），与 3.1 派生的 349.3 同量级、互为旁证。
+本条**不满足** §二 的五项（缺 ②③④ 的逐条留痕），故只作旁证、MUST NOT 单独当口径依据。
+
+### 3.4 `volc_zh_male_cixingjieshuonan_uranus_bigtts`（**五项齐备 · 双样本实测**）
+
+| 项 | 值 |
+|---|---|
+| ① 音色 / 引擎 | 磁性解说男声 2.0 `volc_zh_male_cixingjieshuonan_uranus_bigtts` / 火山引擎 `volcengine`（云引擎，非自训） |
+| ② 合成参数 | `speed` 未传（= 默认 1.0）；`fragment_interval` **不适用**——云引擎音色不受理该参数；`split_method` 走服务端默认 |
+| ③ 稿件 | 两稿，Unicode 码点口径（含标点与英文数字）。① 凯奇坎 823 码点 `sha256:fd4e4f0efaabdfa1…` ② 黄石 904 码点 `sha256:9ce70f69b9d00f20…` |
+| ④ 测量 | `ffprobe -show_entries format=duration` 取 wav 总时长，**首尾静音计入**（挂钟口径的定义即如此） |
+| ⑤ 结果 | 稿① 823 / 230.40s = **214.3**；稿② 904 / 248.33s = **218.4**；合并 1727 / 478.73s = **216.4 字/分**。样本 2 条，日期 2026-09-03 |
+
+**这条记录的价值不在它自己，在它顺手验了 §3.2 那张派生表。**
+注册表给这条音色 `rate=321.77 / pause=0.31`，按 `挂钟 = rate × (1 − pause)` 派生得 **222.0**；
+两次实测 214.3 / 218.4，偏 **−3.5% / −1.6%**。
+§3.2 的 49 条派生值此前**从未被任何实测检验过**（3.1 是注册表自身口径的复算，不是独立测量），
+本条是第一次拿真机音频去撞那条公式，**没撞坏**。派生表因此从「未经检验的推算」升格为「有一个实测锚点的推算」——
+仍 MUST NOT 宣称全库已标定，但对**云引擎 volc 这一档**，派生值可以当估值用，误差量级 <5%。
+
+⚠️ 另记一条选音色时该知道的事实：这条音色的 `pause=0.31` 是**全库最高**，挂钟 222.0 正是 §3.2 那张表的
+`min` 值本人。同一份稿子交给它，比交给缺省 330 长 **48%**，比交给 `narrator`（349.3）长 **57%**。
+写稿时 MUST 按它自己的挂钟值反推字数，照缺省 330 写会让成片直接长出三成。
+
+### 3.5 `narrator`（**五项齐备 · 双样本实测 · 自训引擎首个独立锚点**）
+
+| 项 | 值 |
+|---|---|
+| ① 音色 / 引擎 | `narrator` / 自训 gpt_sovits（生产环境 2026-09-16，CLI 1.1.7 `gtrk tool audio_tts_clone --speaker narrator`） |
+| ② 合成参数 | `speed` 未传（= 1.0）；`fragment_interval` 样本 a 未传（跟随音色预设 **0.28**）、样本 b 显式 `--fragment-interval 0.2`；`split_method` 走服务端默认 |
+| ③ 稿件 | 同一稿两跑，Unicode 码点口径（含标点）**261** 码点，黄石公园解说短稿 `sha256:a1d8eda9b2e44c40…`（正文与产物在工作区根 `_evidence/tts_pause_2026-09-16/`） |
+| ④ 测量 | wav 总时长 = 采样数 ÷ 采样率，**首尾静音计入**；停顿占比按 infra `add-tts-fragment-interval-param` 5.1 法（0.1 s 窗 RMS < 2% 峰值、连续 ≥0.2 s 计一段） |
+| ⑤ 结果 | 样本 a：261 / 44.60 s = **351.1 字/分**，停顿占比 7.0% ⇒ 有效 ≈ 377.5；样本 b：261 / 43.80 s = **357.5 字/分**，停顿占比 4.3% ⇒ 有效 ≈ 373.6。样本 2 条（同稿两参数），日期 2026-09-16；任务 114462641666715654 / 114462754220863494 |
+
+**这条记录的价值同 §3.4：拿真机音频去撞注册表口径，这次撞的是自训那一档。**
+catalog 给 `narrator` 的派生挂钟是 349.3（`rate=379.7 × (1 − 0.08)`），样本 a 实测 351.1，偏 **+0.5%**；
+有效语速 377.5 对注册表 379.7，偏 **−0.6%**。§3.2 那张派生表此前只有 volc 一个实测锚点（§3.4），
+现在自训引擎也有了一个，两档都落在 5% 内。仍 MUST NOT 外推到其它自训音色（各自 `pause` 不同）；
+也要记住本稿只有 45 s，短稿的停顿占比对首尾静音更敏感，长稿回校（§五）攒到第三条再谈收敛。
+
+⚠️ 顺手得到的一个事实：`fragment_interval` 从预设 0.28 压到 0.2，挂钟语速只快 **1.8%**（44.6 → 43.8 s）。
+写稿折算时这档参数可以忽略；它改的是听感（静音总量 −38%），拿它去「调时长」没有意义。
+
+## 四、缺省值 330 是怎么来的，用在哪儿
+
+- **取值**：落在全库挂钟中位 **308.7** 与 `narrator` **349.3** 之间，覆盖真机 **316–342** 区间的中部；
+- **性质**：**缺省估值，不是任何一条音色的实测值**。用它折算时 SHALL 在交付说明里明示这一点；
+- **适用边界**：只适用**中文**、**正常语速档**、**未加 `--speed`** 的合成。
+  换引擎、换语种、动了 `--speed` / `fragment_interval` 的，一律回 §二 重新标定，MUST NOT 沿用；
+- **怎么退役**：终局 (C) 上线（catalog 投影出 `acoustic` 或派生只读字段）后，
+  取值路径改为「读 catalog 字段」，330 只在字段缺失时兜底。
+
+## 五、回校怎么攒样本（`SKILL.md` §五 ④′）
+
+TTS 合成完成后，稿件字数与音频实际时长都已在手（`project init --tts-task` 本就要读它）：
+
+1. 算 **实测挂钟语速 = 稿件字数 ÷ 音频实际时长**；
+2. 与写稿所用估值比对，**偏差 >15% 在交付汇报里点名**（报「估 X / 实测 Y / 偏 Z%」）；
+3. 按 §二 五项格式**追加一条**进 §三 —— 每跑一条片就攒一条样本，「孤证」这个病从结构上被治掉；
+4. **MUST NOT 自动改稿、MUST NOT 自动重跑 TTS**：改稿要从配音步重跑、重付 TTS 费用，返工与否由用户拍板。