fix(guizang-product-video-skill): 按旁白答案条件上报 EASYROUTER_API_KEY

skills/guizang-product-video-skill/SKILL.md

@@ -15,11 +15,11 @@ license: "AGPL-3.0; CodePilot fallback assets: BUSL-1.1 (see README.md)"
 
 ## 流程
 
-1. **确认范围与三个选择。** 已有工程沿用 brief 和用户决定，只处理本次修改。新片先补齐产品/仓库、版本范围、发布平台、时长与画幅、语言和链接要求，再用一次 `ask_user_question` 问清三件会改变工作量的事：**风格**（`repo` 沿用产品设计／`default` 默认暖白炭黑／`hybrid` 保留产品识别并调整外层排版）、**动效**（界面操作动效 + 镜头 zoom in/out／只做界面动效／只做镜头推拉／全静态）、**旁白**（要 Gemini 画外音／只要字幕与音效／稍后再定）。用户已经指定、或已有工程里记过答案时不要重复问；旧工程缺 `motion` 或 `voiceoverRequired` 时补问一次写进 plan 再继续（脚本对缺失只告警，对自相矛盾才报错）。答案写进 `plan.json` 的 `motion.uiEffects`、`motion.cameraMove` 和 `voiceoverRequired`；用户否决的一项用 `motion.exceptionReason` 或 `voiceoverExceptionReason` 留下依据。普通场景可建议横版、45–60 秒、中文。
-2. **初始化后检查环境。** 风格确定后，按下方工具入口初始化独立视频目录，再运行环境检查。仅对报告的缺项加载 [依赖安装](references/onboarding.md) 并补装，随后复查；`ready:true` 继续制作。已有工程直接检查，无需再次初始化。Python 本身缺失时先按依赖安装文档补齐 Python。检查每次执行，安装文档按缺项加载；browser 每次重查环境并实际启动浏览器，`cached:true` 仅表示环境指纹匹配上次成功记录；HyperFrames 指纹匹配时可跳过 doctor。
+1. **确认范围与三个选择。** 已有工程沿用 brief 和用户决定，只处理本次修改。新片先补齐产品/仓库、版本范围、发布平台、时长与画幅、语言和链接要求，再用一次 `ask_user_question` 问清三件会改变工作量的事：**风格**（`repo` 沿用产品设计／`default` 默认暖白炭黑／`hybrid` 保留产品识别并调整外层排版）、**动效**（界面操作动效 + 镜头 zoom in/out／只做界面动效／只做镜头推拉／全静态）、**旁白**（要 Gemini 画外音／只要字幕与音效／稍后再定）。用户已经指定、或已有工程里记过答案时不要重复问；旧工程缺 `motion` 或 `voiceoverRequired` 时补问一次写进 plan 再继续（脚本对缺失只告警，对自相矛盾才报错）。答案写进 `plan.json` 的 `motion.uiEffects`、`motion.cameraMove` 和 `voiceoverRequired`；用户否决的一项用 `motion.exceptionReason` 或 `voiceoverExceptionReason` 留下依据。旁白选定为「要」时**当场**解析 `EASYROUTER_API_KEY`（环境变量或视频工程 `.env`）：缺就立刻向用户索取，不要等画面做完——申请 key 要用户花时间，而它挡的是混音不是渲染，拖到最后才发现等于让用户白等整轮制作。普通场景可建议横版、45–60 秒、中文。
+2. **初始化后检查环境。** 风格确定后，按下方工具入口初始化独立视频目录，再运行环境检查。把第 1 步的旁白答案传给检查脚本（`--voiceover yes|no|undecided`）：只有 `yes` 时 `EASYROUTER_API_KEY` 会作为 `prereqs` 报出来，`undecided` 只给告警。**不要改用 `plan.json` 的 `voiceoverRequired`**——此刻 plan 还是起步工程的技术样片，那个字段是过期的，读它会静默压掉提示。仅对报告的缺项加载 [依赖安装](references/onboarding.md) 并补装（`prereqs` 是用户提供的凭据，你装不了，只能索取），随后 `--force` 复查；`ready:true` 继续制作。已有工程直接检查，无需再次初始化。Python 本身缺失时先按依赖安装文档补齐 Python。检查每次执行，安装文档按缺项加载；browser 每次重查环境并实际启动浏览器，`cached:true` 仅表示环境指纹匹配上次成功记录；HyperFrames 指纹匹配时可跳过 doctor。
 3. **调查更新并接通组件。** 按 [仓库与风格审计](references/repo-and-style.md) 确定日期/版本、发布状态和 3–5 组核心变化。找到对应业务组件、完整样式和所需状态，先接通一个功能镜头。React 项目的依赖解析、CSS/Tailwind 接入见 [起步工程](references/starter.md)，其他挂载路径见 [组件接入](references/component-pipeline.md)。
 4. **编排画面与文案。** 按 [分镜与文案](references/story-and-copy.md) 写解释、标题、动作及阅读时间，交替安排字卡、组件特写、工作区和细节。用真实渲染路径输出 3–6 张关键静帧自检；用户要求先看方向时等反馈，否则继续。默认样式可先看 [标题预览](assets/fallback/title-preview.png) 与 [组件预览](assets/fallback/preview.png)。
-5. **完成动效与声音。** 用主时间轴控制组件状态和镜头，支持前后 seek；界面动效与镜头推拉按 [分镜与文案](references/story-and-copy.md) 的镜头语言执行，动效对应真实状态变化，缩放后重新核对变换后的边界。按 [配乐与音效来源](references/audio-sourcing.md) 为当前影片代码原创配乐，先查找适合产品和动作的音效，缺项才用内置 WAV；用户要旁白时用 `scripts/make_voiceover.py` 按镜头逐句生成并量出实际时长。按 [混音与验收](references/audio-and-qa.md) 对齐 `audio.cues` 与 `audio.voiceover`、压低关键音效与人声期间的音乐并完成混音。
+5. **完成动效与声音。** 用主时间轴控制组件状态和镜头，支持前后 seek；界面动效与镜头推拉按 [分镜与文案](references/story-and-copy.md) 的镜头语言执行，动效对应真实状态变化，缩放后重新核对变换后的边界。按 [配乐与音效来源](references/audio-sourcing.md) 为当前影片代码原创配乐，先查找适合产品和动作的音效，缺项才用内置 WAV；用户要旁白时**先用候选音色各试一句、量出这部片子自己的语速**，再按它决定每句长度，然后用 `scripts/make_voiceover.py` 按镜头逐句生成并量出实际时长（旁白语速靠选音色和写短句子来调，见 [配乐与音效来源](references/audio-sourcing.md)）。按 [混音与验收](references/audio-and-qa.md) 对齐 `audio.cues` 与 `audio.voiceover`、压低关键音效与人声期间的音乐并完成混音。
 6. **验证并交付。** 检查最终 MP4 的裁切、字体、图片、Logo、阅读时间、声音和用户指定的链接处理。修改后重新导出并复查相关镜头。交付 MP4、可复现工程和少量预览；区分自动检查、实际观看/试听及仍受限部分。遇到历史同类问题可查 [案例复盘](references/case-study.md)。
 
 ## 硬约束
@@ -28,7 +28,7 @@ license: "AGPL-3.0; CodePilot fallback assets: BUSL-1.1 (see README.md)"
 - **原组件。** 功能镜头优先接入实际业务组件、原样式及状态；抽象化用于取景、布局和外层动画。逐镜头核对导入图、来源与静帧。平台确实无法接入时记录阻碍和替代方式，遵从已有授权。
 - **清楚排版。** 宣传标题默认有意义的英文与中文各占一个 span、分别指定字体，中文无衬线；中文说明交代对象、动作和结果。原产品内部字体保持其设计；用户指定的语言/字体优先。
 - **完整声音。** 默认代码原创音乐与独立动作音效均入轨，关键反馈可闻、音画同步。用户要求静音或省略音效时，记录 `audioExceptionReason`；该字段保存用户依据。
-- **旁白服务于画面。** 用户要旁白时按镜头逐句生成，人声清楚、音乐在其间让位；每句的 `at` 默认落在所属镜头内、`duration` 用实测值，越界或超长时脚本给出告警、需要人确认是否有意为之；每句只讲一个有来源的信息点，不照抄标题。用户不要旁白时记录 `voiceoverExceptionReason`，不静默跳过。
+- **旁白服务于画面。** 用户要旁白时按镜头逐句生成，人声清楚、音乐在其间让位；每句的 `at` 默认落在所属镜头内、`duration` 用实测值，越界或超长时脚本给出告警、需要人确认是否有意为之；每句只讲一个有来源的信息点，不照抄标题；语速用该音色的自然语速，要调整就换音色或删词。用户不要旁白时记录 `voiceoverExceptionReason`，不静默跳过。
 - **动效有依据。** 界面动效对应选中、展开、切换、完成等真实状态变化，镜头推拉服务“要让观众看哪里”；用户选全静态时不要为了“看起来在动”加无意义晃动，并记录 `motion.exceptionReason`。
 - **隔离工程。** 源码适配、展示依赖和构建配置放视频工程；原产品代码和依赖保持不动。读取产品已安装依赖，必要时在视频工程固定版本补装适配所需包。
 - **授权与真实验收。** 使用素材时保留来源和适用许可。默认样式仍受 [BSL 授权](assets/fallback/SOURCE.md) 约束。自动检查证明结构与文件一致性，视觉、语义和听感由实际审阅补充。
@@ -39,8 +39,8 @@ license: "AGPL-3.0; CodePilot fallback assets: BUSL-1.1 (see README.md)"
 
 ```sh
 python3 <skill-dir>/scripts/init_project.py --output <video-dir> --style repo --repo <repo-dir>
-python3 <skill-dir>/scripts/check_environment.py --project <video-dir> --engine browser
-# 缺项 → 按 references/onboarding.md 补装 → 使用 --force 复查。
+python3 <skill-dir>/scripts/check_environment.py --project <video-dir> --engine browser --voiceover <yes|no|undecided>
+# 缺项 / prereqs → 按 references/onboarding.md 处理 → 使用 --force 复查。
 ```
 
 HyperFrames 工程使用 `--engine hyperframes`。新工程附 10 秒技术样片，用于验证链路；正式制作按实际产品替换内容。

skills/guizang-product-video-skill/marketplace.json

@@ -6,15 +6,15 @@
       "zh": "产品宣传视频",
       "en": "Guizang Product Video"
     },
-    "version": "1.1.0",
+    "version": "1.1.1",
     "usageExample": "我们刚发布了 v2.3.0，更新内容在 CHANGELOG.md 里。帮我把这次更新做成一支 45 秒左右的横版宣传片：复用产品自己的界面组件和配色，界面操作动效保留、镜头适当推拉，再加一段按镜头逐句生成的旁白，配上原创音乐和动作音效，最后交付 MP4 和可复现的工程目录。",
     "description": {
       "zh": "制作代码驱动的软件版本更新宣传片（release notes video、changelog promo）。默认先确认风格、界面操作动效与镜头推拉、是否要 Gemini 画外音，再从真实更新提炼卖点，复用产品组件和设计语言，完成分镜、代码原创配乐、动作音效、逐句旁白、渲染与验收。",
       "en": "Produce code-driven software release promo videos (release notes videos, changelog promos). It first confirms style, UI motion and camera zoom, and whether you want a Gemini voiceover, then distills selling points from real updates, reuses the product components and design language, and handles storyboarding, an original code-generated soundtrack, motion sound effects, per-line narration, rendering and QA."
     }
   },
   "storage": {
-    "packageKey": "skills/guizang-product-video-skill/guizang-product-video-skill_1.1.0.zip"
+    "packageKey": "skills/guizang-product-video-skill/guizang-product-video-skill_1.1.1.zip"
   },
   "media": {
     "icon": {

skills/guizang-product-video-skill/references/audio-sourcing.md

@@ -91,10 +91,25 @@ python3 <skill-dir>/scripts/make_voiceover.py --plan plan.json --output <video-d
 旁白的写法：
 
 - 是写给人听的句子，不是标题的复述。一句放一到两个信息点，写完念一遍再改。
-- 句长跟着镜头时长走：中文约每秒 6–9 字是预警线，读不完就删词或加长镜头，不要靠加速。
+- 句长跟着镜头时长走，但**这是两个不同的约束，不要混用**：
+  - **屏幕上给人读的字**（标题、说明、页脚）约每秒 6–9 字是预警线——这是阅读速度。
+  - **旁白**按这部片子自己的实测语速排，通常在 **4–6 字/秒**（见下「旁白用音色自己的自然语速」）。低于阅读预警线是正常的——听人说话比读字慢；照 6–9 字/秒 排旁白会**系统性超时**。
 - `at` 默认落在所属镜头内，句尾留一点余量；如果为了叙事有意跨镜头或超出镜头时长，脚本只给出告警，需要结合画面、字幕和听感人工确认。
 - 只讲有来源的事实，旁白里的数字和效果主张同样要能追溯到变更记录。
-- 音色按产品和受众选（Gemini 预置音色，如 Aoede、Kore、Puck、Charon），一部片子只用一个音色。
+- 音色按产品和受众选（Gemini 预置音色，如 Aoede、Kore、Puck、Charon、Fenrir、Orus、Alnilam、Sulafat、Leda、Autonoe 等），一部片子只用一个音色。**助手通常听不了声音，不要替用户拍板音色和语速**：用同一句话、同一设置、逐条对齐电平（`loudnorm`）拼成一个试听文件发给用户点选，再按选中的音色重跑。
+
+### 旁白用音色自己的自然语速
+
+慢一点、快一点都是这样得到的：**换一个自然语速不同的音色**，或者**把句子写短**。不要去改语速——加语速指令、`speed` 参数、变速后处理这些都会让听感变成被快进，观众听得出（Gemini 后端的 `speed` 参数还会直接静默失效）。
+
+所以顺序是：写稿 → 量这一版的实际语速 → 按实测值重排，而不是先按某个数字编预算。
+
+- 量法：先用候选音色各生成一句（`make_voiceover.py --voice <Name> --force`），读 `evidence/voiceover.json` 里 `lines[].duration`，算 `字数 ÷ 秒数`。
+- **用这部片子自己的稿子量。** 音色的自然语速随句子变化很大（实测同一个音色在不同句子上差 20% 以上），拿一句话的结果去编整片预算，会有近一半句子越界。
+- 量出来通常在 **4–6 字/秒**：要更慢就换音色，要更快就换音色，都还嫌长就删词。
+- 脚本对越界和重叠只报错、不自动修。报错就删词，或把 `at` 提前到镜头内第一个拍点。
+
+助手通常听不了声音，能自动核对的只有时长是否越界、是否重叠、人声是否真的进了 master（比较人声轨与 master 在有人声/无人声窗口的 RMS 电平差）。**音色和语速快慢让用户听样片定**：同一句话、同一设置、逐条对齐电平拼成一个试听文件发过去。
 
 用户不要旁白时，在 plan 里记 `voiceoverRequired: false` 和 `voiceoverExceptionReason`（写用户的依据），不要一声不响地跳过。
 

skills/guizang-product-video-skill/references/onboarding.md

@@ -1,6 +1,6 @@
 # 依赖安装（仅有缺项时读取）
 
-先确认风格并初始化视频目录，再运行 `check_environment.py --project <video-dir>`。Python 不存在时先补 Python。检查脚本只用标准库，缺依赖也可运行并列出需要安装的项目。
+先确认风格并初始化视频目录，再运行 `check_environment.py --project <video-dir> --voiceover <第 1 步的旁白答案>`。Python 不存在时先补 Python。检查脚本只用标准库，缺依赖也可运行并列出需要安装的项目。
 
 ## 安装范围与验证
 
@@ -88,12 +88,19 @@ npx hyperframes browser ensure
 
 ## 旁白（可选）
 
-画外音不引入新的系统依赖，仍是 Python 与 FFmpeg，只多一个 EasyRouter key（在 https://ezr.sh/ 申请）。key 放环境变量 `EASYROUTER_API_KEY` 或视频工程的 `.env`，不要提交。缺 key 时不要把旁白写成已完成，说明情况并等用户提供；申请 key 不是必装步骤，用户不要旁白时整段可跳过。
+画外音不引入新的系统依赖，仍是 Python 与 FFmpeg，只多一个 EasyRouter key（在 https://ezr.sh/ 申请）。key 放环境变量 `EASYROUTER_API_KEY` 或视频工程的 `.env`，不要提交。
+
+**用户在需求确认阶段选了要旁白时，就在那一刻索取 key。** 检查脚本只在传了 `--voiceover yes` 时才把它报成 `prereqs`——它是用户提供的凭据，装不了，只能索取；而它挡的是混音不是渲染，拖到最后才发现会让用户白等整轮制作。缺 key 时不要把旁白写成已完成，说明情况并等用户提供；用户不要旁白时整段可跳过，脚本也不提这件事。
+
+两个实测过的环境问题，先按它们排查，不要误判成 key 或配额问题：
+
+- **macOS 上优先用 Homebrew 的 python3 跑旁白脚本。** 系统自带的 `/usr/bin/python3`（3.9 + LibreSSL）访问网关会报 `EOF occurred in violation of protocol`；`/opt/homebrew/bin/python3`（OpenSSL 3）正常。
+- **`/audio/speech` 偶发首次请求被对端断开**，报 `Remote end closed connection without response`。重试即可；批量生成时带一次重试。
 
 ## 复查
 
 ```sh
-python3 <skill-dir>/scripts/check_environment.py --project <video-dir> --engine browser --force
+python3 <skill-dir>/scripts/check_environment.py --project <video-dir> --engine browser --voiceover <yes|no|undecided> --force
 ```
 
 HyperFrames 改为 `--engine hyperframes`。成功后继续原分镜工作；只有缺项才重新读取对应段落。平台安装语法来自上述官方来源，实机覆盖以验证记录为准。

skills/guizang-product-video-skill/references/starter.md

@@ -9,7 +9,7 @@
 ```sh
 python3 <skill-dir>/scripts/init_project.py --output <video-dir> --style repo --repo <repo-dir>
 cd <video-dir>
-python3 <skill-dir>/scripts/check_environment.py --project . --engine browser
+python3 <skill-dir>/scripts/check_environment.py --project . --engine browser --voiceover <yes|no|undecided>
 # ready:true 跳过安装；缺项时按 references/onboarding.md 补齐后复查。
 npm run build
 npm run render -- --still 4 --output evidence/frame-04.png