口播脚本指导（jup-video-script-coach）

把专业术语多、难读难懂的宣传口播稿，加工成主播拿到就能看懂、会读、会演的 HTML 指导页：
上方注音 + 段落情感 + 词汇表 + 一键试读，全程不修改原文一个标点。

适用场景

• 自媒体/项目宣传类口播稿（知识科普、产品介绍、活动宣传）
• 中文为主、夹杂少量英文专业词（AI、API、SaaS 等）的脚本
• 主播反馈：词汇专业看不懂、发音不确定、不知道用什么情绪读

路径约定（先读）

• SKILL_DIR = 本 skill 的安装根目录，即 SKILL.md 所在目录。技能加载时 AI 会自动获得该目录（Base directory），无需硬编码。
• 所有资源均位于 skill 包内相对位置：
• 脚本：SKILL_DIR/scripts/
• 模板：SKILL_DIR/assets/template.html
• 参考文档：SKILL_DIR/references/
• 下文中所有命令示例均以 SKILL_DIR 为锚点；PY 表示本机可用的 Python 3 解释器。

环境准备（一次性）

脚本依赖 Python 3 + pypinyin。任一本机 Python 3 均可（Windows 通常为 python，macOS/Linux 通常为 python3；也可使用 WorkBuddy 托管的 Python）。推荐创建隔离 venv：

# 方式一（推荐）：创建隔离 venv（将 python3 换成你本机的 Python 3 解释器）
python3 -m venv .venv
.venv/bin/python -m pip install pypinyin        # Windows: .venv\Scripts\python -m pip install pypinyin

# 方式二：直接使用本机 Python 3
python3 -m pip install pypinyin                 # Windows: python -m pip install pypinyin

若环境里已有 pypinyin，可直接用系统 python 运行脚本。脚本自带 ImportError 提示。

> 工作流中的命令示例统一使用：
> bash > PY=python3 # 按本机环境替换为 python 或具体解释器路径 > SKILL_DIR=<本 skill 根目录> # 技能加载时自动获得（SKILL.md 所在目录） >

工作流（五步）

第 1 步：结构整理（分段分节，不改一字）

• 按语义短句切分段落：以句号/问号/感叹号/分号为自然边界，一句话过长的再按意群拆分。
• 铁律：段落 text 必须是原文原样的纯文本，一个字符都不许改（含标点、空格、大小写）。
• 段落间按内容递进关系排序，无需额外标题，编号由页面自动生成。

第 2 步：拼音注音（专业词 / 生僻字 / 成语）

1. 通读全文，挑出需要注音的词：
   - 专业词汇：术语、技术名词（大模型、算法、部署、商业化…）
   - 生僻字：日常少见的字（脍、炙、崭、澜…）
   - 成语/惯用语：脍炙人口、崭露头角、力挽狂澜…
   - 常用字不注音，避免满屏注音干扰阅读。
2. 运行注音脚本（确定性注音，保证带声调且多音字按上下文消歧）：

"$PY" "$SKILL_DIR/scripts/pinyin_annotate.py" -i 原稿.txt -w "大模型,脍炙人口,API,SaaS"

• 输出 JSON：chars（全文逐字拼音）、words（难词拼音）、heteronyms（多音字及其上下文读音）。
• 把 -w 参数换成你挑选的难词清单；脚本支持 --words-file（每行一个词）。
  3. 多音字复核：对照 heteronyms 逐条确认读音与语义一致（如「银行」行 háng、「行情」行 háng、「行走」xíng）。若个别不符，手动修正该词的 pinyin。
  4. 英文词处理：脚本对纯英文词返回 kind:"en"、拼音为空。由模型补上国际音标或读法提示（如 API → /ˌeɪ piː ˈaɪ/，读作"诶批哀"），填入 ruby 与词汇表。

第 3 步：逐段情感标注

• 情感列表（10 种常用）：开心 😊、悲伤 😢、吃惊 😲、喜乐 🎉、疑问 ❓、平静 😐、激动 🔥、温柔 💗、愤怒 😠、感动 🥹。
• 为每段分析情感基调，取最贴合的一种。
• 格式：段前标注 {情感名表情}，例如 {开心😊}。页面会渲染成徽章；朗读时播音员照着演即可。
• 情感判断要点：疑问句/设问 → 疑问；感叹号召 → 激动/喜乐；转折对比 → 吃惊；故事收尾升华 → 感动/温柔。

第 4 步：全文总结

• 写一段 100 字以内的总结，放在页面最上方（速览卡片）。
• 内容：这条视频讲什么、核心卖点/结论是什么、主播整体用什么基调播。
• 口语化、可读，避免罗列数字。

第 5 步：生成指导页面

1. 构造 script_data.json（schema 见下），保存到工作目录。
2. 运行渲染脚本（模板自动定位，无需传 -t；如自定义模板可加 -t 路径）：

"$PY" "$SKILL_DIR/scripts/build_page.py" -d script_data.json -o 口播指导.html

3. 产出单个自包含 HTML（CSS/JS 全内嵌，无外部依赖），用 preview_url 打开给用户预览。

script_data.json 规范

{
  "title": "视频标题（可留空）",
  "summary": "≤100字的全文总结",
  "emotions": [{"name": "开心", "emoji": "😊"}],
  "paragraphs": [
    {
      "emotion": "开心",
      "text": "段落纯文本，一字不改",
      "ruby": {"大模型": "dà mó xíng", "API": "/ˌeɪ piː ˈaɪ/ 读作诶批哀"}
    }
  ],
  "glossary": [
    {"word": "脍炙人口", "pinyin": "kuài zhì rén kǒu", "kind": "成语", "note": "比喻人人赞美、传诵"}
  ]
}

字段说明：
- emotions 可省略，页面使用内置 10 种情感图例。
- paragraphs[].ruby 可省略；键=需要注音的词（原文字样），值=拼音/音标。词必须与 text 完全一致才能命中。
- glossary[].kind：专业词 / 生僻字 / 成语 / 英文词 / 多音字。
- glossary[].note：一句话释义或读法说明，帮助主播理解。

朗读功能说明

• 默认方案（零配置）：页面内置浏览器 Web Speech API 试读——逐段朗读、当前段高亮、语速 0.5–1.5x 可调、点击任意段落从该段开始。Chrome/Edge 自带中文语音（如"Microsoft 晓晓"）。
• 进阶方案（高质量离线音频）：需要更自然的 AI 配音（如微软晓晓离线 MP3）时，可配置 edge-tts。完整的一步步配置指导见 references/tts-setup.md。

铁律

1. 绝不修改原文文字——结构整理、注音、情感标注都只能"叠加"，不能"改动"。注音由页面渲染层以 ruby 方式叠加，正文始终是原文。
2. 拼音必须带声调符号（dà 而非 da）；多音字按上下文定音。
3. 情感标注格式固定为 {情感名表情}。
4. 总结必须 ≤100 字。
5. 英文词要么给音标，要么给中文谐音读法，不能让主播卡壳。

资源

• scripts/pinyin_annotate.py — 确定性注音（整句分词 + 多音字消歧 + 多音字复核清单）
• scripts/build_page.py — 把 script_data.json 渲染进模板，产出最终 HTML
• assets/template.html — 朗读页面模板（数据驱动，含 ruby 注音 / 情感徽章 / 词汇表 / Web Speech API 朗读）
• references/tts-setup.md —（可选）edge-tts 高质量配音配置指导