Vocab HTML Builder v2

核心能力

输入任意包含英文生词的文件 → 输出：

1. 交互式 HTML 学习页面（格式完全参照 business_english_study_guide.html 蓝本）
2. 神经网络音频文件夹（对话 MP3 + 单词 MP3，edge-tts 生成）
3. 电脑/手机均可使用：HTML + audio/ 文件夹放同一目录即可

支持输入格式：xlsx / csv / txt / pdf / docx / html

输出格式（蓝本参照）

生成的 HTML 与 business_english_study_guide.html 完全一致：

📚 [主题] · 单词学习指南
├── 顶部 sticky 导航（标题 + 词数统计）
├── TOC 分组标签 + 📝 复习组入口
├── 单组显示（CSS :target 机制）
├── 每张卡片含：
│   ├── 编号 + 单词 🔊 + 音标（英/美）+ 📝 复习按钮
│   ├── 📖 释义（中文 + 词性）
│   ├── 🌱 词根词缀
│   └── 💬 场景对话（3 轮 A/B/A）
│       ├── 每行：角色标签 + 英文 + 「中」按钮 + 🔊
│       └── 点击行 → 显示/隐藏中文翻译
└── 复习系统（localStorage 持久化）

完整工作流

阶段 0：读取输入 + 理解上下文（AI 执行）

这是生成高质量对话的关键一步。

结构化文件（xlsx/csv）：运行 extract_words.py 自动解析

非结构化文件（txt/pdf/docx/html）：AI 直接读取文件内容，然后：

1. 理解文档主题：识别文档涉及的领域、场景、关键概念
2. 提取英文生词：过滤常见词，只保留需要学习的词汇
3. 为每个生词生成中文释义（准确、简洁）
4. 创建 words_normalized.csv：word,chinese,phonetic,etymology

# 对于结构化文件，运行提取脚本
python scripts/extract_words.py  --output ./work

阶段 1：创建上下文感知对话场景（AI 执行）

这是最重要的差异化步骤——让对话参考原文件内容，而非生硬的模板。

AI 基于对文档内容的理解，创建 context_scenarios.json：

{
  "supply_chain": [
    ["Have you reviewed the latest supplier report?", "Yes, the lead time for {} needs attention.", "Let's schedule a call with them tomorrow."],
    ["What's the status of our {} order?", "It's still pending customs clearance.", "Keep me posted. This is a priority shipment."],
    ["How do we handle {} in our supply chain?", "We use a dual-sourcing strategy to mitigate risk.", "Good. Diversification is key in today's market."]
  ],
  "meeting_business": [
    ["Have you prepared the {} presentation?", "Almost done. I'm adding the Q3 projections.", "Great. The board expects a thorough analysis."],
    ["What's your take on the {} proposal?", "I think it has merit, but we need more data.", "Agreed. Let's request additional metrics."]
  ]
}

要点：

• 每套模板 3 句话（A, B, A 角色）
• 每个模板至少 2 处插入 {}（用于填入生词）
• 场景名用英文下划线（如 supply_chain, medical_terms）
• 对话自然、务实，反映真实工作场景
• 至少创建 3-5 套场景模板

阶段 2：生成对话 + 提取句子

python scripts/build_vocab.py words_normalized.csv 
  --output ./output 
  --per-section 30 
  --title "商务英语360 · 单词学习指南" 
  --custom-scenarios context_scenarios.json 
  --extract-sentences

输出：

• unique_sentences.json：所有去重对话句子（供翻译用）
• words_list.txt：单词 ID 映射（供音频生成用）

阶段 3：AI 批量翻译

AI 读取 unique_sentences.json，逐条翻译为中文，写入 cn_translations.py：

# -*- coding: utf-8 -*-
CN = {
    "Have you reviewed the latest supplier report?": "你审阅过最新的供应商报告了吗？",
    "Yes, the lead time for board needs attention.": "是的，board 的交货周期需要注意。",
    # ... 全部句子
}

翻译规范：

• 商务/专业语境用正式中文
• 保留数字、百分号、金额符号原文
• 中文引号用「」
• 生词在翻译中保留英文原词（让学习者对照学习）
• 100% 覆盖率，缺一句都不行

阶段 4：构建最终 HTML

python scripts/build_vocab.py words_normalized.csv 
  --output ./output 
  --per-section 30 
  --title "商务英语360 · 单词学习指南" 
  --custom-scenarios context_scenarios.json 
  --translations cn_translations.py

验证清单：

• HTML 中 toggleCn(this) 调用数 = 对话总行数 × 3
• 空 cn-tip 标签数 = 0
• data-audio="audio/d_XXXX.mp3" 属性全部存在
• data-audio-word="audio/words/w_XXXXX.mp3" 属性全部存在
• 文件无 fetch() 调用（纯离线）

阶段 5：生成神经网络音频

# 1. 安装依赖（首次）
pip install edge-tts

# 2. 生成对话音频（男声 GuyNeural / 女声 JennyNeural）
python scripts/gen_dialogue_audio.py output/xxx.html --audio-dir output/audio --concurrency 8

# 3. 生成单词音频（男声 GuyNeural，慢速学习）
python scripts/gen_word_audio.py --words-list output/words_list.txt --output-dir output/audio/words --concurrency 8

阶段 6：验证 + 呈现

# 验证音频完整性
echo "对话音频: $(ls output/audio/d_*.mp3 | wc -l) 文件"
echo "单词音频: $(ls output/audio/words/w_*.mp3 | wc -l) 文件"
echo "零字节: $(find output/audio -size 0 | wc -l) 个"
echo "总大小: $(du -sh output/audio | cut -f1)"

通过 present_files 呈现 HTML 给用户。

最终交付物

output/
├── 商务英语360_单词学习指南.html    # 主文件
└── audio/                           # 音频文件夹
    ├── d_0000.mp3 ... d_XXXX.mp3    # 对话音频
    └── words/
        └── w_XXXXX.mp3              # 单词音频

部署：将 HTML + audio/ 文件夹拷贝到同一目录（电脑或手机均可）。

手机端使用说明

备用方案：手机上安装 "An HttpServer"（安卓免费开源应用），通过 http://localhost:port/ 访问，绕过所有 file:// 限制。

脚本速查

自定义场景模板格式

context_scenarios.json 格式参考：

{
  "场景英文名": [
    ["A 说的话（用 {} 占位生词）", "B 说的话", "A 说的话"],
    ["第二套模板的 A 行", "B 行", "A 行"]
  ]
}

场景命名约定：用小写英文 + 下划线，反映文档主题（如 supply_chain, legal_terms, medical_phrases）。

模板撰写原则：

• 自然的工作对话，不是教科书式问答
• 每个模板至少嵌入 2 个 {} 占位符
• 3 句话形成一个完整的小故事/情境
• 避免「What does X mean?」这类幼稚问法——用真实的工作交流方式