Web Slides 是做什麼的？
把一堆素材 / 提纲 / 要点，一步步做成可现场放映的「电影感 HTML 幻灯片」。 產出物 = Vite + React + TS 項目，點擊 / 方向鍵推進，每一步獨佔整屏，按 P 開獨立的演講者視窗看口播稿（即時預覽 + 計時器，兩窗聯動；投屏只共享主 slide 視窗即可對觀眾隱藏），按 N 是排練用的備註浮層。
與 [web-video-presentation] 的區別：那個 Skill 做的是「偽裝成影片的網
頁」——有口播稿、合成音訊、錄屏成片。本 Skill 只做現場放映的 slides：
沒有口播稿、沒有音訊、沒有錄屏；每一步的文字變成演講備註（presenter
notes），給演講者提詞用，不會出現在畫面上。其餘的視覺方法論、主題系統、
逐步揭示原則完全保留。
適用場景
- 「我有一些素材 / 提綱，幫我做成 slides / 演示文稿」
- 技術分享 / keynote / 產品演示 / pitch deck / 教學課件
- 面試項目復盤（project retro） —— 現場對著 slides 講，按 P 開演講者視窗看提詞
- 想要 16:9 橫屏、大字、留白、每屏都有動效的「動態 PPT 但不像 PPT」
- 把一篇文章 / 一份筆記變成可交互的逐步講解
本 Skill 以方法論 + 協作流程為核心。腳手架模板提供 token 和原語， 但每個美學決策（配色、字型、動效氣質）都應該針對你的主題重新設計 —— 不要照搬。
兩種密度 profile：影片式 / 演示 deck 式
同一套引擎能跑兩種節奏，Phase 1 就先定一個（寫進 outline.md 頂部，
Checkpoint Plan 與用戶確認）：
| 🎬 影片式（預設 / 稀疏） | 🎤 演示 deck 式（有限頁 / 高密度） | |
|---|---|---|
| 場景 | 錄屏講解、不停講、節拍多 | 現場 / 投屏演講、頁數有限、圍著一頁講（面試復盤常用） |
| 一張幻燈片 | = 一個 step（整屏接管） | = 一個 chapter（一頁穩定的密集畫面） |
| step 語義 | 切到下一個想法（換場景） | 同一張 slide 上逐步 build（元素留屏漸顯，不換場景） |
| 一屏資訊 | 1 hero + 1~3 元素 + 大留白 | 圖 / 表 / 示意 + 幾條要點 + 資料可同屏 |
| 規模 | 很多章 × 少步 | 較少章（≈ 目標頁數）× 每章 2~5 build |
| 主題 | 任意 | 優先結構 / 編輯型（newsroom / monochrome-print / blueprint / swiss-ikb / vintage-editorial） |
兩種都不改引擎（chapter/step、16:9 舞台、token、MaskReveal 全通用），
差異只在章節怎麼寫。deck 式放開「一屏一想法 / 大留白 / 全 hero」，但
「避免 AI 味」+ token + 真實層級 + 必須有視覺演示 + 雙源這套照舊 ——
那才是「不難看」的根。每章具體寫法見
CHAPTER-CRAFT.md「兩種密度 profile」。
不確定 → 🎬 影片式。
工作流總覽
Phase 1 內容規劃
1.1 識別用戶輸入
1.2 產出 outline.md
（章節切分 + 每步螢幕內容 + 可選每步備註 + 資訊池）
▼
[Checkpoint Plan] ← 必須停。一次對齊 4 件事：
outline / 主題 / 素材 / 開發模式
▼
Phase 2 網頁開發
2.1 腳手架（按選定主題）
2.2 第 1 章 = 主執行緒 + 完整版本（強制 anchor）
▼
[硬節點] 用戶驗收第 1 章 ← 不可跳過
▼
2.3 第 2~N 章（按選定模式：A 逐章 / B 順序 / C 並行）
▼
[Checkpoint Done] ← slides 做完，dev server 跑著
▼
Phase 3 放映 / 匯出
沒有「音訊合成」和「錄屏」階段 —— 這是 slides，不是影片。
工作目錄約定（agent 在用戶當前目錄下建立 / 編輯）：
my-slides/
├── material.md # 用戶給原始素材時保留 —— 不刪！開發階段畫面資訊源
├── outline.md # 必有：開發計劃（章節切分 + 每步內容 + 資訊池 + 可選備註）
└── presentation/ # 腳手架產出的 Vite + React + TS 專案
└── src/chapters/<NN>-<id>/
├── <Chapter>.tsx # 視覺實作
├── <Chapter>.css
└── notes.ts # ★ step 數 + 演講備註的唯一真相源
關鍵：
notes.ts是 step 數的唯一真相源。章節.tsx裡的if (step === N)出現的最大 N + 1 必須等於notes.length。這保證 章節程式碼、進度條、stepper 永遠不會漂。備註內容（陣列裡的字串）只餵 演講者視窗（按 P）和備註浮層（按 N），永遠不出現在 slide 畫面上，可留空""。
硬性自檢協議（貫穿整個 Skill）
下面兩個產出，每一個完成後必須走自檢 → 修復 → 再回報 / 推進：
| 產出 | 自檢清單出處 |
|---|---|
outline.md | OUTLINE-FORMAT.md 自檢 |
| 單章實作完成 | CHAPTER-CRAFT.md 完工自檢 |
執行方式（按能力降級，優先使用更隔離的方式）：
- Agent Teams（最優）：開一個獨立的 reviewer agent，給它「產出檔案 路徑 + 對應清單 + 關鍵上下文」，讓它逐項核查並嚴格回報結論 （哪幾條 pass / 哪幾條 fail + 證據 + 改寫建議）。
- subAgent（次優）：沒有 Teams 能力但能開 subagent 就用 subagent 走同樣流程。
- 自檢（兜底）：當前 agent 都沒有上述能力，就自己嚴格逐項 核查 —— 不允許目測一遍就放行。
鐵律：拿到結論後先按 fail 項把產出改完，再向用戶回報「做完了
- 自檢結論 + 改了什麼」。直接拿原始結論回報但不修復 = 違規。
各階段檔案讀取指南
不同階段讀不同的檔案。長會話裡 agent 容易遺忘原則，特別是 Phase 2.4 的「實作單章」會重複 N 次 —— 每次都要回看核心約束。
| 階段 | 必讀（每次都看） | 一次性看完 / 按需查 |
|---|---|---|
| Phase 1.1-1.2 內容規劃 | references/OUTLINE-FORMAT.md + material.md（用戶原始素材，如有） | —— |
| Checkpoint Plan 選主題 | —— | themes/*/theme.json（動態讀全部，列清單 + bestFor 推薦 + descriptionZh）；references/THEMES.md（用戶想了解主題系統時） |
| Phase 2.1 腳手架 | —— | SKILL.md 本節看一次 |
| Phase 2.4 實作單章（×N 次，被 2.2 / 2.3 呼叫） | references/CHAPTER-CRAFT.md 單一入口 —— 視覺演示要求 / 逐步揭示 / 內容取捨 / 雙源（outline+material）/ 放映審美 / 避免 AI 味 / 程式碼層最小約束（含 notes.ts 強制約束）/ 時長參考 / 完工自檢 + 目前主題的 themes/<id>/theme.json + 目前章節的 outline.md 段落 + material.md 本章對應段落 + 素材清單 | references/EXAMPLES/（結構示意，不是抄襲模板）；references/THEMES.md 完整 token 契約 |
| Phase 3 放映 / 匯出 | references/PRESENTING.md（全螢幕放映、鍵盤導航、按 N 看備註、匯出 PDF / 截圖） | —— |
| 選 / 造 / 切主題 | —— | references/THEMES.md |
寫章節時只讀一份
CHAPTER-CRAFT.md。十條原則 / 開工 self-prompting / 決策樹 / 反 AI 味反模式 / 完工自檢全部併入這一份單一入口。EXAMPLES/不是必讀 —— 先按內容自由設計，卡殼才翻（按 anchor 翻「形」，不要照搬）。
Phase 1 —— 內容規劃
1.1 識別用戶輸入
| 用戶給的東西 | 該做的 |
|---|---|
| 原始素材（文章 / 筆記 / 一堆要點 / 資料） | 產出 outline.md（1.2），保留原素材為 material.md，過 Checkpoint Plan |
| 已經寫好的提綱 / 大綱 | 整理成 outline.md 格式（1.2），過 Checkpoint Plan |
| 啥都沒有，只說「幫我做個 X 主題的 slides」 | 反問：先給一段素材或要點。Skill 不替用戶構思內容 |
1.2 產出 outline.md
按 references/OUTLINE-FORMAT.md 規則：切章節
→ 切 step → 每章首段抽資訊池 → 每步寫螢幕內容（+ 可選演講備註 hint）。
先定密度 profile（🎬 影片式 / 🎤 deck 式，見上方「兩種密度 profile」）—— 它直接決定章節怎麼切：deck 式時章節數 ≈ 目標頁數，每章 2~5 個 build。
保留 material.md 不刪——它是 outline 寫資訊池、章節實現畫面時的細節源
（雙源原則）。
outline 的邊界（關鍵）：
| outline 必須寫 | outline 不要寫 |
|---|---|
| 章節切分 / 每章 step 數 / 估時 | 具體動畫類型（blur clear / wipe / 彈簧） |
| 每步螢幕內容（hero / 資料 / 標語 / 列表項） | CSS 實現手段（filter / SVG / clip-path） |
| 章節級資訊池：從素材抽的數字 / 引用 / 案例 / 標籤 | 時長 / 微觀節奏數值 |
| 每步演講備註 hint（可選：你打算在這一步講什麼） | 持續微動 / 錯峰量等微觀節奏 |
| 步級關係名前綴（「反差對照」/「遞進列表」/「金句」等可選 hint） | —— |
outline 不寫動畫的理由：寫死動畫 = chapter agent 退化為翻譯機； 留白讓 chapter agent 在每步開工時按
CHAPTER-CRAFT.md的「內容驅動決策樹」自由設計，才有真正的視覺感。
落盤後必須先走自檢再進 Checkpoint Plan：按上文「硬性自檢協議」對
outline.md 執行（優先 Agent Teams → subAgent → 自檢），按結論修復後再進。
Checkpoint Plan —— 4 件事一次對齊（硬節點）
outline.md 寫完後必須停下來。用戶在這一個節點同時確認 4 件事。
agent 此時要做的預備工作
- 讀所有
themes/*/theme.json拿nameZh/descriptionZh/bestFor/mood—— 不要硬編碼清單 - 根據 outline 的內容類型 / 關鍵詞 / 語氣，主動從主題裡挑 2~3 套
最匹配的推薦（匹配
bestFor欄位） - 掃一遍
outline.md末尾「素材清單」部分
總結模板（骨架，agent 按情況填充）
內容計劃寫完，產出檔案：
📄 material.md {若用戶給原素材則保留}
📄 outline.md {N} 章 / {M} 步 + 每章資訊池 + 末尾素材清單
章節速覽：
1. <id> <章節標題> <S> 步 ~<T>s
2. ...
接下來一次對齊 4 件事：
1. 開發計劃 (outline.md) 要不要改？重點看：
- 密度 profile 對不對（🎬 影片式：多步稀疏 / 🎤 deck 式：有限頁高密度）
- 章節切分 / step 數是否合理（每章 ~5~12 步是常見區間）
- 每步螢幕內容是否清晰
- 每章首段「資訊池」是否有足夠的素材細節供畫面掛
- 末尾素材清單是否完整
2. 選哪個主題？我的推薦：
★ <推薦 1：nameZh (id)> — 因為 <bestFor 命中>；<descriptionZh 摘要>
★ <推薦 2 / 推薦 3>
其它可選：<剩餘主題，nameZh + 一句話>
也可以讓我幫你做新主題（詳見 references/THEMES.md）。
3. 真素材怎麼準備？粗看本 slides 要的圖：<列粗略清單>
a) 我從 <現有素材路徑> 幫你挑 b) 你自己提供 c) 全部 placeholder
4. 開發模式選哪個？
**第 1 章無論哪種模式都必須主執行緒做完 + 用戶驗收**（強制 anchor）。
差異在第 2 章及之後：
A) 預設 · 逐章確認（推薦）
每章做完都暫停驗收 → 風險可控 / 節奏最穩
B) 第 1 章後順序開發（不並行）
第 2~N 章主執行緒順序做完後統一驗收 → 速度中 / 適合 agent 不支援並行
C) 第 1 章後並行開發（subagent）
第 2~N 章用 subagent 並行 → 最快 / 用戶控並行數（一次幾章）
⚠️ 風格各章會有差異（這是預期，主題禁區兜底）
收到回饋後：
- outline 要改：直接編輯檔案，編輯完 ping 一次（或口頭描述 agent 改）
- 主題必須明確才進入 Phase 2。用戶說「主題你幫我選」→ 取你推薦的第 1 個， 告訴用戶你選了什麼、為什麼，給反悔機會
- 模式選定 → 進 Phase 2
Phase 2 —— 網頁開發
2.1 腳手架
bash <path-to-web-slides>/scripts/scaffold.sh \
./presentation \
--theme=<用戶選的主題 id>
bash <path-to-web-slides>/scripts/scaffold.sh --list-themes
自訂主題 → 先按
references/THEMES.md「創作新主題」流程做一個themes/<my-theme>/，再--theme=<my-theme>。
腳手架帶一個 01-example demo。在寫第一章真實內容前刪掉：
rm -rf presentation/src/chapters/01-example
並把 presentation/src/registry/chapters.ts 裡 example 章節
的 import 和陣列項移除。
2.2 第 1 章 —— 主執行緒 + 強制驗收
核心：第 1 章 = 完整版本一次到位（節奏 + 視覺 + 真素材齊全）。 沒有「骨架版」概念 —— 第一章就要做出用戶能直接驗收的樣板。
為什麼第 1 章必須主執行緒：
- 它是
CHAPTER-CRAFT.md這套指引在當前 主題 + 當前題材下的第一次落地 - 如果指引有盲區 / 主題顏色 / 字體 token 不夠用，第 1 章一定會暴露 —— 這時候有人類回饋就能修指引 / 調主題，早改成本最低
- 後續章節（無論順序 / 並行）都要參考第 1 章的程式碼模式，所以第 1 章 = 當次專案的「風格錨點」
做完第 1 章後必須停下來等用戶驗收：
第 1 章 <id> 做完了，dev server 在 localhost:5174 執行。
驗收重點：
□ 視覺氣質對不對？符合 <theme nameZh> 的預期嗎？
□ 節奏對不對？某些步太快 / 太慢 / 資訊太薄？
□ 內容驅動動畫是否到位？還是有幾步是無腦入場動畫？
□ 雙源原則：螢幕畫面有沒有「備註沒提但素材能掛」的細節？
□ 反 AI 味檢查：紫粉漸變 / 圓角彩色邊框 / 假插畫 / emoji 是否有？
□ 按 N 看演講備註，對著講順不順？
問題告訴我，我針對性改。OK 了告訴我「繼續」，我按選定模式做第 2 章及之後。
2.3 第 2~N 章 —— 按選定模式
所有模式下的共同規則：每章獨立按 CHAPTER-CRAFT.md
開發。風格不強求章節間完全一致 —— 主題顏色 / 字體 token 兜底視覺
統一，動畫 / 節奏 / 視覺演示由章節自由發揮是設計預期。
模式 A · 預設 · 逐章確認
第 2 章做完 → 暫停驗收 → OK → 第 3 章 → 暫停 → ... → 第 N 章。每章 獨立驗收，問題隨時改，風險最低，節奏最穩。用戶不明確選模式時 預設走這個。
模式 B · 第 1 章後順序開發
第 2 章 → 第 3 章 → ... → 第 N 章 主執行緒順序做完，最後統一驗收。 速度中等，適合 agent 不支援並行任務的環境。
模式 C · 第 1 章後並行開發（subagent）
用 subagent 把第 2~N 章並行做完，最大並行數由用戶控制（「一次 4 章」 /「一次 2 章」）。最快，但風格各章會有差異 —— 這是預期，因為：
- 每個 subagent 看不到別的 subagent 產出，無法機械對齊
- 章節程式碼物理分離（每章一個資料夾 / 自己的 CSS 前綴），不會互相破壞
- 主題 token 兜底視覺統一（顏色 / 字體 / hero 數字 / 卡片 / 分割線 性格 / 裝飾），氣質不會跑偏
- 風格不一致 = 人手寫的呼吸感（多 voice / 多視角）
並行 subagent 的 prompt 必須包含：
- 目前章節 outline 段落（含資訊池）
references/CHAPTER-CRAFT.md的路徑（單一必讀）- 目前主題
theme.json的descriptionZh/mood/bestFor - 第 1 章程式碼作為「程式碼風格」參考（不是「視覺抄襲物件」）
- 硬規則：每章獨立 CSS 前綴（
.cd-/.mg-/.pm-/ ...）； 不修改chapters.ts；每章帶notes.ts（長度 = step 數）； 完工跑npx tsc --noEmit
重要：無論選哪種模式，用戶隨時可以中途切換模式。
2.4 實作單章（每章必走）
詳細指引見 references/CHAPTER-CRAFT.md ——
單一必讀入口，涵蓋：視覺演示要求 / 逐步揭示 / 內容取捨 / 雙源原則
/ 視覺演示基本審美 / 反 AI 味 / 程式碼紅線 / 完工自檢。
核心要點（CHAPTER-CRAFT.md 詳述）：
- 每章必須有 CSS / SVG / Canvas / JS 視覺演示，禁純文字章節
- 逐步揭示：清單 / 列表必須 1 項 = 1 step，禁一次全展示
- 雙源原則：節奏跟 outline（順序不能亂），細節回原始素材抽（資訊池 + 本章 material 段落）
- 每章帶
notes.ts：長度 = step 數（唯一真相源），內容是演講備註 （可留空""），不會出現在畫面上 - 完工自檢逐項過，不達標回去改 —— 按「硬性自檢協議」執行，改完 再向用戶回報本章交付
2.5 大改後 bump STORAGE_KEY
改動 chapters.ts（增加 / 刪除 / 重排章節，或某章 notes.ts 長度變化）
後，bump presentation/src/hooks/useStepper.ts 的 STORAGE_KEY
（如 web-slides-cursor-v1 → v2），避免持久化游標落到不存在的 step 上。
Phase 3 —— 放映 / 匯出
詳細流程見 references/PRESENTING.md。要點：
- 現場放映：
npm run dev→ 瀏覽器全螢幕（F11）→ 點擊 / 方向鍵推進。 - 鍵盤導航：
← →/ 空格 推進；Home/End跳首尾；數字鍵1-9跳章；按P開演講者視窗（獨立視窗：口播稿 + 即時預覽 + 計時器，兩窗聯動）； 按N開 / 關備註浮層（疊在當前視窗上，僅排練用 —— ⚠️ 會被一起投屏）。 - 投屏看不到口播稿的正確姿勢：按
P開演講者視窗 → 會議軟體裡選 「共用某個視窗 / 標籤頁」並選中主 slide 視窗（不要「共用整個螢幕」）→ 演講者視窗只有你自己看得到，翻頁兩窗聯動，單屏也成立。 - 離線分發 / 投屏穩一點：
npm run build→npm run preview，或部署dist/。 - 匯出（可選）：逐步截圖成 PNG，或瀏覽器逐步「列印為 PDF」。
Phase 2 結束後主動告訴用戶：slides 做完了，dev server 跑在 localhost:5174，可以現場放映 / 投屏；按 P 開演講者視窗看口播稿（投屏時 只共用主 slide 視窗，觀眾看不到），按 N 是排練用的備註浮層（會被投屏）。
十條原則（一句話清單）
完整展開見 references/CHAPTER-CRAFT.md
的對應章節 —— 寫章節時回那裡查，下面只是索引。
| # | 原則 | 一句話 |
|---|---|---|
| 1 | 16:9 固定舞台 | 內容 1920×1080 + transform scale，沒有響應式 |
| 2 | 全域 step 計數器 | 章節是 step 的純函數，無定時器 |
| 3 | 每步獨佔整屏 | if (step === N) return <FullScene /> |
| 4 | 邏輯節拍 = step | 一節拍 = 一 step = 一個聚焦想法 |
| 5 | 隱藏的邊角控制項 | 進度條預設 opacity 0；備註預設隱藏（按 N 開） |
| 6 | 舞台無 chrome | 沒有 header / footer / 頁碼 / 品牌條 |
| 7 | 內容驅動動畫 | 先找內在動作，找不到才入場動畫兜底；持續微動慎用 |
| 8 | 多點逐個揭示 | 1 項 = 1 step，禁同步 stagger 上 N 項 |
| 9 | 整片同一主題 | 章節間不翻表面色；顏色 / 字體走 token，其它尺度章節自由 |
| 10 | 雙源原則 | outline 定節拍，素材定畫面密度（落到資訊池） |
🎤 deck 式下原則 3「每步獨佔整屏」/ 8「1 項 = 1 step」放寬為： 一頁 = 一 chapter，step = 同頁逐步 build（元素留屏漸顯）；其餘原則不變。 見上方「兩種密度 profile」。
常見用戶回饋速查
收到回饋先定位是哪一層（節奏 / 視覺 / 內容 / 程式碼），再改最小切片， 不要重做整章：
- 節奏：太快 / 太慢 / 資訊太薄 → 拆 / 合併 step（同步改
notes.ts長度 + 章節if (step===N)） - 視覺：氣質不對 / 有 AI 味 → 回 CHAPTER-CRAFT.md「避免 AI 味」+「放映基本審美」
- 內容：畫面太空 / 細節不夠 → 回資訊池 + 本章
material段落（雙源原則） - 程式碼：報錯 / token 不生效 → 回 CHAPTER-CRAFT.md「程式碼層最小約束」
相關資源
按「何時讀」標註，避免一次性全讀：
| 檔案 | 何時讀 | 內容 |
|---|---|---|
references/OUTLINE-FORMAT.md | Phase 1.2 必讀 | outline.md 欄位 spec、命名約定、章節切分、資訊池、每步備註 |
references/CHAPTER-CRAFT.md | Phase 2.4 每章單一必讀入口 | 視覺演示要求 / 逐步揭示 / 內容取捨 / 雙源（outline+material）/ 放映審美 / 避免 AI 味 / 程式碼層最小約束（含 notes.ts）/ 時長參考 / 完工自檢 |
references/EXAMPLES/ | 可選 —— 看結構 | 章節結構示意（hook / list-reveal / case-tech-review）；不是抄襲模板 |
references/THEMES.md | 選 / 造 / 切主題時 | 完整 token 契約 + 內置主題清單 + 創作流程 |
references/PRESENTING.md | Phase 3 才讀 | 全螢幕放映、鍵盤導航、按 N 看備註、匯出 PDF / 截圖 |
themes/ | Checkpoint Plan / Phase 1.2 時翻 | 內置主題（每個含 theme.json + tokens.css） |
scripts/scaffold.sh | Phase 2.1 跑一次 | 一鍵專案腳手架 |
本 Skill 由
web-video-presentation（作者 ConardLi）改造而來 —— 去掉口播 / 音訊 / 錄屏，保留全部視覺方法論 與主題系統，專做現場放映的 HTML slides。