feat(guizang-product-video-skill): 默认确认动效与镜头推拉，新增逐句 Gemini 画外音（1.1.0）

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

@@ -44,6 +44,7 @@ npx skills add https://github.com/op7418/guizang-product-video-skill --skill gui
 | 暂时没有成熟的宣传视觉 | 用内置的 CodePilot 暖白／炭黑样式组织外层画面 |
 | 几句很技术的更新描述 | 写成完整的白话句子，让人知道改了什么、用起来有什么不同 |
 | 一支只有画面的片子 | 为本片用代码写配乐，给操作配独立音效，并在关键音效出现时压低音乐 |
+| 只有画面、没有旁白 | 需要时可以按镜头逐句生成中文旁白，改一句只重录那一句 |
 
 画面由代码渲染，能继续修改。标题、功能特写、完整工作区和细节镜头交替出现，既有大字文案，也留出看清操作的时间。
 
@@ -67,6 +68,8 @@ npx skills add https://github.com/op7418/guizang-product-video-skill --skill gui
 
 不需要写一份很长的 brief，把**介绍什么、给谁看、发在哪里**说清楚就够了。
 
+第一次制作时，它会先确认三件事：风格、动效（界面操作动效 + 镜头 zoom in/out）、要不要旁白。旁白走 EasyRouter 的 Gemini TTS，需要你自己的 key；不想加旁白直接说。
+
 **做一支版本更新片**
 
 > 介绍 v2.1 到 v2.4 的主要更新，优先讲多模型切换、文件预览和浏览器操作。发 B 站，横版 50 秒左右。沿用我们的产品设计，文案口语化一点，不要把提交记录逐条念出来。
@@ -91,7 +94,7 @@ npx skills add https://github.com/op7418/guizang-product-video-skill --skill gui
 2. **找真实内容。** 查版本与代码，核对功能状态，接通一个真实组件镜头。
 3. **把故事讲顺。** 写分镜和白话文案，渲染关键画面，检查排版与阅读时间。
 4. **让画面动起来。** 用可定位时间的主时间轴控制状态、入场、转场和细节。
-5. **把声音配好。** 原创配乐，查找合适音效，对齐操作节点，混音并处理音乐让位。
+5. **把声音配好。** 原创配乐，查找合适音效，需要时按句生成旁白，对齐操作节点，混音并处理音乐让位。
 6. **检查，再导出。** 核对画面、字体、图片、Logo、音画同步与最终文件。
 
 默认起点是 **45–60 秒、横版、中文**。你可以调整时长和画幅；竖版需要重新安排取景和文字，通常不会直接裁掉左右两边。
@@ -104,6 +107,8 @@ npx skills add https://github.com/op7418/guizang-product-video-skill --skill gui
 
 **音乐和音效分开混。** 点击、弹出、切换、完成提醒等动作有独立的音效事件。关键反馈出现时音乐会短暂降低，让叮咚、确认和转场真正听得见。
 
+**旁白按句生成。** 需要旁白时，用 EasyRouter 上的 Gemini TTS 按镜头逐句生成，再把每句对齐到镜头和卡点；哪一句不满意就重录哪一句。人声是锚，音乐会在这期间让位。不想要旁白就直说，只靠字幕、配乐和音效，片子也是完整的。
+
 ![配乐、动作音效与音乐让位](assets/readme/audio.jpg)
 
 ## 最后会拿到什么？

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

@@ -1,7 +1,7 @@
 ---
 name: guizang-product-video-skill
 category: 视频创作
-description: 制作代码驱动的软件版本更新宣传片（release notes video、changelog promo）。从真实更新提炼卖点，复用产品组件和设计语言，完成分镜、代码原创配乐、动作音效、渲染与验收。
+description: 制作代码驱动的软件版本更新宣传片（release notes video、changelog promo）。默认先确认风格、界面动效与镜头推拉、是否要 Gemini 画外音，再从真实更新提炼卖点，复用产品组件和设计语言，完成分镜、代码原创配乐、动作音效、逐句旁白、渲染与验收。
 upstream: op7418/guizang-product-video-skill
 upstreamPath: .
 upstreamSha: c45aab4599bc6e883a6f6ea9d82f49ecdde1c8d0
@@ -15,11 +15,11 @@ license: "AGPL-3.0; CodePilot fallback assets: BUSL-1.1 (see README.md)"
 
 ## 流程
 
-1. **确认范围与风格。** 已有工程沿用 brief 和用户决定，只处理本次修改。新片优先补齐产品/仓库、版本范围、发布平台、时长与画幅、语言和链接要求。风格尚未确定时问一次：“沿用代码库自己的设计风格（推荐），还是默认的暖白／炭黑风格？” `repo` 使用产品设计；`default` 使用默认样式包装；`hybrid` 保留产品识别并调整外层排版。用户已经指定时直接执行。普通场景可建议横版、45–60 秒、中文。
+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。
 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/audio-sourcing.md) 为当前影片代码原创配乐，先查找适合产品和动作的音效，缺项才用内置 WAV。按 [混音与验收](references/audio-and-qa.md) 对齐 `audio.cues`、压低关键音效期间的音乐并完成混音。
+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`、压低关键音效与人声期间的音乐并完成混音。
 6. **验证并交付。** 检查最终 MP4 的裁切、字体、图片、Logo、阅读时间、声音和用户指定的链接处理。修改后重新导出并复查相关镜头。交付 MP4、可复现工程和少量预览；区分自动检查、实际观看/试听及仍受限部分。遇到历史同类问题可查 [案例复盘](references/case-study.md)。
 
 ## 硬约束
@@ -28,6 +28,8 @@ license: "AGPL-3.0; CodePilot fallback assets: BUSL-1.1 (see README.md)"
 - **原组件。** 功能镜头优先接入实际业务组件、原样式及状态；抽象化用于取景、布局和外层动画。逐镜头核对导入图、来源与静帧。平台确实无法接入时记录阻碍和替代方式，遵从已有授权。
 - **清楚排版。** 宣传标题默认有意义的英文与中文各占一个 span、分别指定字体，中文无衬线；中文说明交代对象、动作和结果。原产品内部字体保持其设计；用户指定的语言/字体优先。
 - **完整声音。** 默认代码原创音乐与独立动作音效均入轨，关键反馈可闻、音画同步。用户要求静音或省略音效时，记录 `audioExceptionReason`；该字段保存用户依据。
+- **旁白服务于画面。** 用户要旁白时按镜头逐句生成，人声清楚、音乐在其间让位；每句的 `at` 默认落在所属镜头内、`duration` 用实测值，越界或超长时脚本给出告警、需要人确认是否有意为之；每句只讲一个有来源的信息点，不照抄标题。用户不要旁白时记录 `voiceoverExceptionReason`，不静默跳过。
+- **动效有依据。** 界面动效对应选中、展开、切换、完成等真实状态变化，镜头推拉服务“要让观众看哪里”；用户选全静态时不要为了“看起来在动”加无意义晃动，并记录 `motion.exceptionReason`。
 - **隔离工程。** 源码适配、展示依赖和构建配置放视频工程；原产品代码和依赖保持不动。读取产品已安装依赖，必要时在视频工程固定版本补装适配所需包。
 - **授权与真实验收。** 使用素材时保留来源和适用许可。默认样式仍受 [BSL 授权](assets/fallback/SOURCE.md) 约束。自动检查证明结构与文件一致性，视觉、语义和听感由实际审阅补充。
 
@@ -46,6 +48,7 @@ HyperFrames 工程使用 `--engine hyperframes`。新工程附 10 秒技术样
 - [起步工程](references/starter.md)：依赖接入、CSS、编译、静帧和导出耗时。
 - [配乐源码](assets/audio/codepilot-score-example.py)：48 秒、120 BPM、48 kHz 示例，复制进工程按本片改编。
 - [内置音效](assets/audio/SOURCE.md)：11 个 WAV；需改音色时运行 `scripts/make_sfx.py --output <new-sfx-dir>`。
+- `scripts/make_voiceover.py --plan plan.json --output <video-dir>`：按 `audio.voiceover.lines` 逐句生成旁白；key 只从 `EASYROUTER_API_KEY` 或工程 `.env` 读取，`--list-models` 可查实际 TTS 模型 id。
 - `scripts/mix_audio.py <plan.json>`：混音、音乐让位、独立音轨和证据报告。
 - `scripts/check_delivery.py <plan.json> [--video <final.mp4>] [--mix-report <audio-mix.json>]`：结构、文件、时间线与媒体验证。
 - `python3 -m unittest discover -s <skill-dir>/tests`：维护此 skill 时运行回归测试；日常制片无需读取测试源码。

skills/guizang-product-video-skill/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: "归藏 product video skill"
   short_description: "复用真实产品组件，用代码制作有配乐、有节奏、讲得清楚的软件更新宣传片"
-  default_prompt: "请使用 $guizang-product-video-skill，为这个产品最近几个版本制作一支宣传片，先确认用代码库风格还是默认风格。"
+  default_prompt: "请使用 $guizang-product-video-skill，为这个产品最近几个版本制作一支宣传片。先确认三件事：用代码库风格还是默认风格、要不要界面操作动效和镜头推拉、以及要不要画外音。"

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

@@ -6,15 +6,15 @@
       "zh": "产品宣传视频",
       "en": "Guizang Product Video"
     },
-    "version": "1.0.1",
-    "usageExample": "我们刚发布了 v2.3.0，更新内容在 CHANGELOG.md 里。帮我把这次更新做成一支 45 秒左右的横版宣传片：复用产品自己的界面组件和配色，配上原创音乐和动作音效，最后交付 MP4 和可复现的工程目录。",
+    "version": "1.1.0",
+    "usageExample": "我们刚发布了 v2.3.0，更新内容在 CHANGELOG.md 里。帮我把这次更新做成一支 45 秒左右的横版宣传片：复用产品自己的界面组件和配色，界面操作动效保留、镜头适当推拉，再加一段按镜头逐句生成的旁白，配上原创音乐和动作音效，最后交付 MP4 和可复现的工程目录。",
     "description": {
-      "zh": "制作代码驱动的软件版本更新宣传片（release notes video、changelog promo）。从真实更新提炼卖点，复用产品组件和设计语言，完成分镜、代码原创配乐、动作音效、渲染与验收。",
-      "en": "Produce code-driven software release promo videos (release notes videos, changelog promos). Distill selling points from real updates, reuse the product's own components and design language, then handle storyboarding, original code-generated soundtrack, motion sound effects, rendering and QA."
+      "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.0.1.zip"
+    "packageKey": "skills/guizang-product-video-skill/guizang-product-video-skill_1.1.0.zip"
   },
   "media": {
     "icon": {

skills/guizang-product-video-skill/references/audio-and-qa.md

@@ -72,6 +72,19 @@ python3 <skill-dir>/scripts/mix_audio.py plan.json
 5. 连续点击可用 click/click-alt 做轻微音色变化，输入声是有节奏的短簇，转场音只留给画面结构变化，叮咚保留给值得注意的状态。不要所有字出现都“叮”一下。
 6. 最后分别听音乐轨、音效轨、完整混音及最终 MP4；检查提示声的第一下是否被盖住、拖尾是否被切断、节奏是否拥挤。
 
+## 有旁白时人声是锚
+
+有旁白时先给人声留位置，再决定音乐和音效。旁白是观众听懂内容的依据，不要让它和配乐互相抢。
+
+- 音乐默认在语音期间压低约 6 dB：起音前 150ms 开始压、句尾后约 400ms 恢复，保持时间等于该句实测时长。别给所有句用一个固定 hold。
+- 音效仍要听得见。关键动作的反馈不能被人声吃掉；人声段里正好有关键音效时，先确认它还清楚，必要时错开动作或压短旁白。
+- 句与句之间不要忽大忽小；同一音色、同一增益，不额外做句内响度起伏。旁白整体音量在 `audio.voiceover.gain`（混音时生效）；单句的 `lines[].gain` 在拼装时就已经烘进音轨，混音不会再动它。
+- 旁白默认不跨镜头硬切，也不要和字幕抢读的时间；如果有意跨切点，需要结合画面、字幕和听感人工确认。
+
+有配音时最终混音的响度目标按 **-14 LUFS**（无配音时用 -16），TP 不高于 -1.5 dBTP、LRA 约 8 作起点，再按平台和听感调整。人声在场时整体响度天然更高，沿用无配音的 -16 会把句子压住。
+
+有旁白时 `mix_audio.py` 额外输出 `assets/voice-stem.wav` 供单独听人声轨，混音报告记录人声文件、每句时间与哈希，并把人声窗口计入让位记录。试听顺序：单独听人声轨 → 单独听音效轨 → 听 master → 听编码后的 MP4。
+
 ## 混音
 
 音乐应听得见但不疲劳；无配音短片可把最终混音约 -16 LUFS、true peak 不高于 -1 至 -1.5 dBTP 当起点，并依据平台要求和听感调整。不同平台/题材不强制同一数值。有配音时给人声留空间，根据听感做 ducking。
@@ -105,6 +118,7 @@ ffmpeg -i renders/final.mp4 -af loudnorm=I=-16:TP=-1.5:LRA=8:print_format=json -
 | 事实 | 功能状态有证据；示例不冒充客户成果或跑分 |
 | 组件 | 原业务组件及样式实际上镜；构建图、状态驱动、来源清单与静帧一致；没有以基础控件或 tokens 复刻冒充整项功能复用 |
 | 音频 | BGM 与关键动作 SFX 都可闻；完成/通知反馈清楚；动作对齐；不刺耳、不爆音、结尾完整 |
+| 旁白 | 人声清楚、与字幕和画面一致、不压过关键音效、结尾不被截断；句长与镜头匹配 |
 | 链接 | 按用户要求隐藏 URL/CTA，遮挡在缩放移动中不泄漏 |
 | 一致性 | 预览和 MP4 都检查，最终修改确实进入导出文件 |