敘事型資料課程 是做什麼的？
建構一個類似參考範例（「我們與誰共度時光，按年齡分層」）的課程：一個在動態圖表上執行的敘事影片，以及一個讓學習者能動手探索資料的「探索」分頁。一個課程就是一個資料夾，內含 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 <檔案或網址>。
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%、語言為 English；整份腳本一次錄完。儲存為
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 → Publishing）。課程資料夾是自成一格的。
自我檢查規則（務必遵守）
- 在第 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 | 新增圖表類型 |