Manual Explainer
從使用手冊建立一個自包含的 HTML「課程應用程式」：
頁面以圖片形式顯示，每個步驟以中文、韓文或英文解說——可隨時切換（瀏覽器
文字轉語音，附句子高亮顯示），學習者可以隨時按下 ✋ 打斷提問。
這會在中句暫停旁白，打開一個知道學習者當前位置的提問面板，
根據手冊內容回答問題並附上 [p.N] 頁面連結，然後
▶ 繼續講解 會從被打斷的句子恢復解說。
應用程式的品質幾乎完全取決於步驟 2（理解）和 步驟 3（課程設計）。腳本僅處理機械性工作。
工作流程
1. 提取
SK=<此技能的目錄>
python $SK/scripts/extract_manual.py "/mnt/user-data/uploads/<檔案>" /home/claude/mx
支援 pdf、pptx、ppt、docx、doc（所有檔案都會先轉換為 PDF，以便頁碼與圖片相符）。輸出在 /home/claude/mx 目錄下：content.md（包含 [[pN]] 標記、pptx 備忘稿、docx 標題大綱的完整文字）、content.json、pages/pN.jpg。列印的報告會列出 image_heavy_pages 以及遮罩了多少機密資訊。
對於包含一張大型圖片和旁邊文字方塊備忘稿的 PPTX 投影片，提取器會以原始解析度使用該圖片本身作為頁面圖片（在 warnings 中報告），因此投影片顯示得更大且更清晰。
如果沒有附加檔案，請要求提供。如果檔案是掃描的 PDF 且沒有文字（total_chars 接近 0），請以視覺方式閱讀頁面圖片，並根據所見內容自行撰寫 knowledge。
2. 在設計任何內容之前，先完整理解手冊
從頭到尾閱讀 content.md（如果很長，請使用 view 分塊閱讀）。然後
view 每個 image_heavy 頁面的圖片，以及任何文字中提到圖形、畫面、面板、接線圖、表格或按鈕配置的頁面——這些視覺元素通常是手冊的核心，而文字提取會遺漏它們。
建立一個運作模型，並將筆記記錄在 /home/claude/mx/notes.md：
- 產品/流程是什麼、讀者是誰、他們讀完後必須能夠做什麼
- 實際結構：設定 → 正常操作 → 設定 → 維護 → 疑難排解，或手冊實際使用的任何結構
- 每個程序的順序、前置條件和預期結果
- 每個警告 / 注意 / 危險通知（這些必須一字不差地保留在課程中，意義相同）
- 規格和數字（壓力、電壓、時序、限制）以及所在的頁面
- 學習者必須知道的術語（→ 詞彙表）
- 矛盾、遺漏或不清楚的地方——在最後向使用者提及這些，而非自行猜測
3. 設計課程 → /home/claude/mx/lesson.json
閱讀 references/lesson_schema.md 以了解確切格式和旁白規則。
設計原則：
- 教學，而非照本宣科。 按學習者首先需要的內容排序，而非必然按頁面順序。典型大小：3–10 個章節，每個章節 2–8 個步驟，每個步驟一個概念。
- 每個步驟顯示最相關的頁面圖片（
image），並列出page_refs中的所有輔助頁面。 - 旁白解釋原因和可能出錯的地方，指出頁面圖片上可見的內容，並以適合口語朗讀的方式撰寫。
- 將每個安全警告移至其適用步驟的
warning中。 - 每個章節有 1–3 個針對實務上重要事項（程序順序、限制、警告）的測驗問題——而非冷知識。
knowledge=content.md中經過清理的完整文字，保留其[[pN]]標記（刪除頁首/頁尾和重複的樣板文字；保留表格）。在影像密集頁面的標記下，為您看到的重要圖片添加簡短描述，以便導師也能回答相關問題。- 涵蓋範圍檢查： 每個頁面都應出現在某個步驟的
image或page_refs中，封面、目錄、空白頁和法律頁面除外。建置報告會列印uncovered_pages；請修補包含實際內容的遺漏處。 - 語言（預設：中文 / 한국어 / English）： 以全部三種語言建立每個課程——
"languages": ["zh","ko","en"]——以便學習者隨時在應用程式標題中切換。將language（預設語言）設定為使用者與您交談時使用的語言。僅在使用者要求時才建立較少的語言。 所有可見文字（標題、旁白、項目符號、警告、測驗、詞彙表）都必須是{"zh":…,"ko":…,"en":…}物件；如果缺少任何一種語言，建置將會拒絕執行。每種語言都應以其母語書寫，適合口語表達，而非其他兩種語言的逐字翻譯，並且在所有語言中都應保持同樣嚴格的警告。knowledge保留手冊的原始語言——導師會閱讀它並以所選語言回答。 在每種語言中，第一次出現手冊的原始螢幕標籤（按鈕名稱、警報代碼）時，請保留原樣。 - 對於較長的手冊，請先以預設語言撰寫課程，檢查涵蓋範圍，然後逐個欄位添加其他兩種語言。
4. 建置
python $SK/scripts/build_app.py /home/claude/mx/lesson.json /home/claude/mx /mnt/user-data/outputs/<名稱>-講解.html
建置會驗證課程（若出現「課程錯誤」，請修正並重新執行），再次遮罩機密資訊，將頁面圖片嵌入到約 14.5 MiB 的預算內（已發布頁面必須保持在 16 MB 以下），並列印報告。圖片為 WebP 格式，相同的頁面僅儲存一次。步驟圖片始終嵌入並保持最清晰（最高 1800px，絕不放大）；僅在 page_refs 中列出的頁面以較小尺寸嵌入，任何無法容納的頁面將僅以純文字引用形式顯示。對於非常長的手冊（數百頁），請將步驟圖片限制為不同的、必要的頁面。
頁面圖片（螢幕截圖、投影片文字）中出現的憑證無法被文字掃描捕獲：請在建置前在 pages/pN.jpg 中將其塗黑。
請勿為單一手冊手動編輯範本的邏輯；請修改 lesson.json。
5. 交付
- 存在 Artifact 工具的地方（claude.ai）： 使用
capabilities: {"sample": {}}和 📘 favicon 發布 HTML。sample允許應用程式內導師詢問 Claude。請勿宣告其他功能。 - 其他地方（Claude Code、Cowork、無 Artifact 工具）： 呈現 HTML 檔案。 作為純文字檔案開啟時，提問面板會回退到手冊中搜尋，並顯示最相關的原始段落及其頁碼。
然後，以使用者的語言簡短回覆：用一兩行列出章節清單、如何使用（▶ 播放、✋ 隨時打斷、鍵盤：Space / ← → / Q）、第一個問題會請求允許使用他們的 Claude 用量，以及您在手冊中發現的任何遺漏或矛盾之處。
6. 疊代
如需變更（「第3章講細一點」、「語速太快」、「加一章故障排除」），請編輯 lesson.json、重新建置，並重新發布到同一個 artifact（傳遞其 url）。
安全性（公司文件）
手冊可能包含帳戶名稱、預設密碼、帶有憑證的 IP、授權金鑰或客戶資料。
- 兩個腳本都會自動遮罩密碼、Token、金鑰、私鑰和帶有憑證的連線字串。切勿將這些值複製到旁白、項目符號或您的回覆中；僅報告有 N 個項目被遮罩及其類型。
- 如果手冊的預設憑證是程序的一部分（例如「使用初始密碼以管理員身分登入」），請描述該步驟並指向頁面（「初始密碼見手冊第12頁，或向管理員獲取」），而非陳述該值。
- 請勿將手冊上傳到任何外部服務；所有操作均在本地和已發布的頁面中執行。
應用程式的功能（用於回答使用者關於它的問題）
- 標題：標題、語言切換器（中文 / 한국어 / EN——切換時保留當前步驟，並且可在課程中或提問面板內運作）、🔊 語音面板、速度 0.8–1.5×；進度條。
- 語音：應用程式會對瀏覽器的語音進行排名，並自動選擇最自然的語音（Edge「Natural/Online」神經語音 > Apple Enhanced/Premium > Google 語音 > 其他）。🔊 面板會列出它們（★ = 自然），提供預覽，並記住每種語言的選擇。當只有機械語音可用時，它會說明並建議使用 Edge / Google 語音 / 下載增強語音。無法預先錄製音訊：已發布的頁面無法呼叫 TTS 服務，且音訊會超過大小限制。
- 內容抽屜（手機上為 ☰）：章節、步驟（已訪問的標記）、測驗、詞彙表。
- 步驟卡片：頁面圖片、標題、要點、警告、帶有當前句子高亮顯示的旁白、頁面標籤。
- 🖼 大投影片模式（預設開啟）：內容移入 ☰ 抽屜，投影片填滿螢幕高度，旁邊有窄文字欄（在窄螢幕上堆疊）。可切換並記住每位檢視者的偏好。
- 頁面檢視器（點選投影片、頁面標籤或 [p.N] 連結）：捏合/滑鼠滾輪縮放最高 6 倍、拖曳平移、雙擊縮放、− ⤢ + 按鈕、‹ › 翻閱所有嵌入頁面；鍵盤 + − 0 ← → Esc。在直立手機上，它會建議將手機橫放。
- 自動播放會跨步驟繼續，並在每個章節測驗處停止。
- ✋ 提問面板：顯示當前位置的上下文行、建議標籤（再講一遍 / 更簡單 / 舉例 / 為什麼重要 / 常見錯誤）、串流答案（附可點擊的
[p.N]）、停止按鈕、▶ 繼續講解會從被打斷的句子恢復。 - 位置、語音和速度會記住每位檢視者的偏好。
- 語音取決於檢視者的瀏覽器/作業系統；如果沒有匹配的語音，應用程式仍會透過朗讀時間和高亮顯示來推進。