叙说式数据课程 是做什么的？
构建一个类似参考示例（“我们按年龄与谁共度时光”）的课程：一段在实时图表上进行的叙说视频，以及一个“探索”选项卡，学习者可在其中与数据互动。一个课程 = 一个文件夹，包含 index.html、lesson.json、data.json、video.json（故事板）、旁白音频以及可选的背景音乐。
先阅读： references/design-rules.md（已批准的视觉、动态和强调规则；请严格遵循）和 references/user-guidance.md（如何与用户协作）。
以下路径均相对于此技能的文件夹（${CLAUDE_SKILL_DIR}）。
你将要与之协作的人
假定用户不具备技术背景。请用平实的语言，一步一指引，并明确告知他们何时需要点击什么（如下载文件、登录 ElevenLabs、批准脚本等）。永远不要要求他们编辑代码或 JSON。请使用 references/user-guidance.md 中的分步说明。
工作流程（包含检查点和自我检查）
在每一步结束时执行自检。若结果为“失败”，不得进入下一步。
1. 获取数据
- 接受链接、文件或 PDF。如果链接被屏蔽（网站常阻止自动下载），引导用户通过浏览器下载文件并分享给您。
- 对其进行分析：
python3 scripts/profile_data.py <文件或URL>
2. 数据是否适用？（始终告知用户）
阅读分析器的结论和 references/chart-chooser.md，然后用平实的语言告知用户：
- 适用： “这可以作为 ___ 数据使用，因为 ___。” 说明它能回答什么学习问题。
- 部分适用： 说明哪些部分可用，缺少什么，以及权衡之处。
- 不适用： 清晰说明原因，并描述什么样的数据才适用。不要强行使用。
✋ 检查点 1：图表类型和故事角度
提出图表类型、主要学习问题以及 4-6 个故事节拍（讲解员将指出的要点），每个节拍都与您将要计算的一个数字相关联。等待用户批准。
3. 数据塑形
- 启动课程文件夹：
python3 scripts/new_lesson.py --chart <类型> --out <文件夹> - 在课程文件夹中编写一个简短、可重复运行的脚本，用于将源数据转换为符合图表格式的
data.json（references/data-formats.md）以及生成facts.json：其中包含讲解员将要说的每个数字，这些数字均根据源数据计算得出，并注明其表述方式。 - 自检：
python3 scripts/check_lesson.py <文件夹>；同时手动抽查 2-3 个值，与源数据核对（打开原始文件并找到它们）。报告您检查的内容。
4. 编写故事
- 根据 references/storyboard.md 和 design-rules §1 中的故事弧线（开场钩子→如何阅读图表→故事节拍→总结→反思→“轮到你了”）编写
video.json（场景、节拍、提示）。 - 按照 ElevenLabs 风格（references/narration.md）编写旁白脚本，保存为
narration/script.txt。每条陈述必须与facts.json匹配；避免夸大其词（design-rules §8）。 - 填写
lesson.json：标题、引语、关键标签、分组描述、注释、来源。
✋ 检查点 2：批准脚本
以纯文本形式展示脚本。当用户提出要求时提供相关选项；未获用户批准不得应用任何更改。
5. 预览（在录制之前）
- 静默预览：
python3 scripts/estimate_timing.py <文件夹>/video.json --out <文件夹>/narration/narration.words.json接着运行python3 scripts/time_storyboard.py <文件夹>/video.json <文件夹>/narration/narration.words.json - 运行服务并打开：
python3 scripts/devserver.py 8123（从课程文件夹的上一级目录运行），然后访问http://localhost:8123/<课程>/ - 自检（浏览器）： 按照 references/self-checks.md 操作：在每个节拍处截图，确保无内容重叠，无控制台错误，每个命名的内容都能在其对应的词汇处高亮显示。
6. 旁白和音乐（需用户的 ElevenLabs 账户）
- 引导用户登录（user-guidance.md → ElevenLabs）。设置：语音 Quentin – Narrator and Educator，Eleven v4，稳定性 ≈ 80%，英语；整个脚本一次录制完成。保存为
narration/narration.mp3。 - 没有 ElevenLabs？提供免费的占位符：
python3 scripts/placeholder_voice.py <文件夹>（Mac）。 - 同步词汇：
python3 scripts/align_narration.py <文件夹>/narration/narration.mp3 --out <文件夹>/narration/narration.words.json，然后再次运行time_storyboard.py。目标：≥ 99% 的词汇匹配。 - 音乐（可选，ElevenLabs Music，器乐，平静风格，约2分钟）：使用
prep_music.py准备；如果视频时长超过音轨，使用find_loop.py+extend_music.py扩展（绝不允许音乐在讲解员说话时结束或循环）。 - 自检：
check_lesson.py（音频长度、事实核对）+ 在浏览器中完整播放一遍。
✋ 检查点 3：一起回顾
引导用户浏览完成的课程：告诉他们需要关注什么，以及如何尝试“探索”功能。根据他们的要求进行修改，并在每次修改后重新运行自检。
7. 发布（可选）
引导用户部署到 GitHub Pages 或任何静态托管平台（user-guidance.md → 发布）。课程文件夹是独立的。
自检规则（始终遵守）
- 在步骤 3、4、5、6 之后以及每次修订之后，运行
scripts/check_lesson.py。 - 在每次视觉更改后，在浏览器中进行验证：在旁白播放的时刻截图，并与故事板进行对比。报告您检查的内容。
- 根据源数据重新计算每个旁白中提到的数字；切勿凭记忆输入任何数字。
- 如果某步失败，请先修复并重新检查，然后再告知用户已完成。
参考文件
| 文件 | 用途 |
|---|---|
| references/design-rules.md | 外观、动态、强调、旁白、同步、音乐、数据诚实性 |
| references/chart-chooser.md | 针对不同问题选择何种图表；适用标准 |
| references/data-formats.md | 四种 data.json 格式 |
| references/storyboard.md | video.json：每种图表类型的场景、节拍、提示、facts.json |
| references/narration.md | 脚本风格、ElevenLabs 设置、计时、音乐 |
| references/self-checks.md | 每个步骤需要验证的内容 |
| references/user-guidance.md | 为用户提供的平实语言分步指南 |
| references/chart-interface.md | 添加新的图表类型 |