讲解视频剪辑岗·数字员工（文稿变讲解视频）
> 这是一个"交活型"岗位技能，不是建议型。
> 你给一份文稿，它直接交成片 mp4：竖屏图文卡 + 逐句配音人声 + 对齐的字幕 + 封面大标题。
> 对标的是 VibeKnow「文档变视频」那类在线平台，但全程在你本机跑——不出网、不上传、不依赖第三方账号。
> 未发布的选题稿不能外流，这是硬要求，本技能按这个前提设计。
0. 这一岗位交付什么（完整交付清单）
一次调用交付以下 5 项，缺一项即视为未交付完成：
| # | 交付物 | 位置 |
|---|---|---|
| 1 | 成片 mp4（1080×1920 竖屏，H.264 + AAC，≤20MB 自动重压） | <out>/成片_讲解版.mp4 |
| 2 | 逐句配音人声（44.1kHz 单声道 wav，按卡片顺序拼接） | <out>/voice.wav |
| 3 | 对齐的字幕（每句真实音频时长，非估算） | <out>/voice.srt |
| 4 | 竖屏图文卡（1080×1920 PNG，含封面卡与页码） | <out>/cards/card_XX.png |
| 5 | 交付自检报告（卡片数 / 字幕条数 / 时长 / 体积） | <out>/_report.json |
交付后本技能会主动确认：打印实际卡片数、配音体积、字幕条数、成片体积与时长，并给出"校验通过"或"在第几步失败"的明确结论。
1. 用法（一条命令）
python scripts/build_explain_video.py \
--doc "文稿.md" \
--out "D:/分享/001_某期" \
--brand "品牌角标" --title "封面大标题" --domain policy
只想知道会切出哪些卡、不渲染：
python scripts/build_explain_video.py --doc "文稿.md" --out "任意目录" --dry-run
2. 参数
| 参数 | 默认值 | 说明 |
|---|---|---|
--doc |
必填 | 文稿（.md / .txt）。口播风效果最好；蒸馏笔记/论文体会被清洗成短句 |
--out |
必填 | 输出目录，不存在会自建 |
--title |
文稿文件名 | 封面卡大标题 |
--brand |
空 | 卡片右下角品牌角标 |
--voice |
zh-CN-YunxiNeural |
edge-tts 音色；老人受众推荐 zh-CN-YunxiNeural + --rate -10% |
--rate |
+0% |
语速。银发内容建议 -10%，老人听得清 |
--domain |
policy |
配色氛围：policy（知识/民生，冷蓝明快）/ elder（老人家庭，暖黄） |
--ffmpeg |
自动探测 | 找不到 ffmpeg 时用此参数指定绝对路径 |
--no-sub |
关 | 不烧字幕（卡片本身已带文字，字幕是叠加强调） |
--dry-run |
关 | 只清洗 + 打印分镜，不渲染 |
3. 环境依赖（都是公开可装的，无内部路径依赖）
| 依赖 | 安装 |
|---|---|
| Python 3.9+ | 系统自带或 python.org |
| Pillow | pip install pillow |
| edge-tts | pip install edge-tts（配音用微软 Edge 在线合成，需联网） |
| ffmpeg | winget install ffmpeg / brew install ffmpeg / apt install ffmpeg，或 --ffmpeg 指定 |
中文字体自动探测（Windows 微软雅黑/黑体 → macOS 苹方 → Linux Noto CJK），找不到中文字体会直接报错停在第 2 步，不会出空白卡。
4. 每步都校验，不许静默失败
| 步 | 校验 | 不通过怎么办 |
|---|---|---|
| ① 清洗 | 清洗后句子数 > 0 | 报"清洗后没有可用句子"，指明是输入问题 |
| ② 出卡 | 卡片数 ≥ 2 | 报实际卡片数，停 |
| ③ 配音 | voice.wav > 100KB | 报实际体积，停（拒绝"零句也照样出片"） |
| ④ 合成 | 成片 > 300KB | 报实际体积，停 |
| ⑤ 体积 | > 20MB 自动分级重压 | 先提 CRF 保 1080×1920，不动分辨率 |
任一步受限，本技能必须明说受限在哪一步（错误信息形如 [FAIL] voice: 第 3 句配音合成失败（网络或音色不可用）…），不静默降级、不假装成功。唯一例外：字幕滤镜在个别环境下失败时，会明确打印降级提示后出无字幕版（画面本身已带文字）。
5. 铁律
- 不录原句：文稿必须是自有话重述的内容。本技能只做形式转换，不替你改内容实质。
- 内部标注不进画面：
池号、「（池号锚点版）」「自有话重写」这类蒸馏笔记专用元信息会被清洗器挡掉，绝不会印到卡片上或念出口播。 - 文稿不出本机：全程本地渲染，无一次上传。
- 不碰第三方素材：卡片底图为纯色渐变程序化渲染，不含任何需授权的图片、字体或音乐。
6. 已知边界（提前说清，不含糊）
- 蒸馏笔记体（条目式、带内部锚点）清洗后偏书面，先改写成口播稿再喂进来，成片自然很多。
- 卡片是图文卡 + 逐句配音的讲解片形态，不是影视级动态画面。要动态画面需另走视频生成模型，本技能不覆盖。
- 配音依赖 edge-tts 联网；断网环境请用
--no-sub之外的路径：先把 wav 准备好再自行替换。
7. 与在线平台的分工
| 本技能 | 在线平台（如 VibeKnow） | |
|---|---|---|
| 数据 | 全程本机，不上传 | 文稿要上传到对方服务器 |
| 成本 | 零（本地渲染，不花平台积分） | 通常按次收费 |
| 可控性 | 版式/节奏/配色可改脚本调 | 只能用平台给的模板 |
| 上限 | 图文卡讲解片 | 有更强的视频生成模型 |
结论：要快、要稳、稿子不能外流 → 用本技能；要影视级动态画面 → 再考虑在线平台补一条并行版本。
支付宝付费改造契约（PAYSKILL）
本技能为付费技能（PAYSKILL），单次 9.90 元/次，计费单元「按次」，产品 ID wengao-jiangjie-shipin。
调用遵循支付宝 AI 按量付费（A2M）契约，由平台调度层执行 probe → pay → complete → ack：
- probe（探测）：平台调用前先探测是否已持有本技能的有效付费凭证，已付费直接放行。
- 402 Payment-Needed：未付费时，
scripts/payment_gate.py输出 HTTP 状态402与Payment-Needed标记，平台据此唤起支付宝付费页。 - complete（扣费确认）：用户在支付宝完成付费，平台下发
Payment-Proof。 - ack（验签放行）：平台携带
Payment-Proof重试调用，闸门验签通过后放行主流程。
订阅持久化与幂等：付费状态缓存在本地 .pay_cache/state.json，同一 Payment-Proof 在 24 小时幂等窗口内仅生效一次，避免重复扣费。
用户调用 → 平台 probe →
未付费：下发 402 Payment-Needed → 支付宝 pay → complete → 下发 Payment-Proof
已付费/携带 Proof：脚本 ack 验签 → 放行主流程
> 本契约由 SkillHUB 平台调度层解析，脚本本地仅处理 402 / 验签 / 持久化 三环节；付费本体交给支付宝。
