@gitruck/cli 1.1.0 → 1.1.1

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

@@ -0,0 +1,98 @@
+# 语速档案（写稿折算的单一真值源 · 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 单独当口径依据。
+
+## 四、缺省值 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 费用，返工与否由用户拍板。

package/skills/gtrk-vlog-docu/SKILL.md

@@ -81,7 +81,7 @@ description: Vlog 纪实类一站式成片图纸——纪实 Vlog 是散文的
 - **禁幼稚拟声与过度儿化**：换成真实事实——数字与事实比拟声词有力。
 - **风格贴着素材走**：素材什么气质，稿子就什么气质，不加分不减分。
 
-**成片时长 = min(内容支撑, 素材支撑)**；旁白折算约 200–240 字/分钟。
+**成片时长 = min(内容支撑, 素材支撑)**；旁白折算用**挂钟语速**（按检查点①选定的音色取，取不到用缺省 ≈330 字/分钟）——口径与标定档案见 `skills/gtrk-travel-recap/references/speech-rate.md`，**MUST NOT 复制数值表**。
 
 ### 3.2 立神：找出那根线（★ 本类型的第一步，先于选材）