用途：把文案与用户提供的本人或已授权参考录音合成为配音，交付 voiceover.wav（计时主文件）、voiceover.mp3、voiceover.srt、voiceover.json。SRT 为原稿短段的采样帧时间，不是字级强制对齐，也不证明读音完全正确。
后端选择：默认 MiniMax speech-2.8-hd，使用用户自己的服务账号与已登记音色，可能消耗在线额度；auto 读取个人偏好，无配置时选 minimax。显式用 --provider local 走免费本地路线：Apple Silicon 选 mlx（Qwen3-TTS 0.6B Base 4bit），其他平台选 qwen（官方 PyTorch，优先 CUDA，否则 CPU）。本地推理不需要 API key，首次需下载模型并占用计算资源。nano 仅供用户显式选择的较轻 CPU 路线，不因本地失败自动降级，也不自动切换云服务。
用法：原文保存为 script.md，不擅自改写读法、数字或术语；只有明确 Markdown 标题不朗读，编号列表保留。产物默认放 voiceover-<主题>/。SKILL_DIR 为技能所在目录，实际定位安装目录，不硬编码 ~/.claude 路径。
python3 "$SKILL_DIR/scripts/setup.py" python3 "$SKILL_DIR/scripts/configure.py" --provider minimax --voice YOUR_VOICE_ID "$PY" "$SKILL_DIR/scripts/run.py" script.md --outdir voiceover-demo
首次运行读 SETUP.md；各后端使用独立环境。参考录音要干净、单人、无音乐的完整短段：MiniMax 要求 10–300 秒，通常先选 10–30 秒；本地 Qwen/Nano 通常选 3–30 秒。Qwen 建议提供精确匹配的 --reference-text reference.txt 启用完整 ICL。声音条目按完整句子/语义短段组织，默认宽度 40。
续跑与验证：同一命令可续跑，缓存含正文、声音内容哈希、模型/版本与生成参数；每次成功保存一个 WAV，失败段阻止拼接。run.py 自动做结构验证，也可运行 verify.py voiceover-demo/voiceover.json。检查实际声音，本地 ASR 可辅助找漏读/重读，但 ASR 正确不等于音色相似。本地模型单句随机问题可用 --segment-seed 2:3，只使该句缓存失效；--force 会重新请求所有段并可能产生费用。接 web-video-presentation 时交 voiceover.json 和同目录产物。未实测的实时、零误差、任意硬件可用等承诺不成立。