web-video-presentation

Web Video Presentation

把一篇文章或口播稿，一步步做成可錄製的「偽裝成影片的網頁」，可選合成
口播音訊。產出物 = Vite + React + TS 專案 + 按章節切分的音訊。

適用場景

• 「我有口播稿 / 一篇文章，幫我做成影片」 —— 口播驅動的內容
• 想做「動態 PPT」
• 16:9 橫向錄製，大字、留白、每頁都要有動效
• 教學 / 產品展示 / keynote 想要電影感
• B 站 / YouTube / 抖音影片內容

本 Skill 以方法論 + 協作流程為核心。腳手架模板提供 token 和原語，
但每個美學決策（配色、字型、動效氣質）都應該針對你的主題重新設計 ——
不要照搬。

---

工作流程總覽

Phase 1   內容編寫
   1.1  識別使用者輸入
   1.2  一次產出 script.md + outline.md
        （口播稿 + 開發計畫）
   ▼
[Checkpoint Plan]      ← 必須停。一次對齊 5 件事：
                         稿子 / outline / 主題 / 素材 / 開發模式
   ▼
Phase 2   網頁開發
   2.1  腳手架（按選定主題）
   2.2  第 1 章 = 主執行緒 + 完整版本（強制 anchor）
        ▼
        [硬節點] 使用者驗收第 1 章 ← 不可跳過
        ▼
   2.3  第 2~N 章（按選定模式：A 逐章 / B 順序 / C 並行）
   ▼
[Checkpoint Audio]     ← 必須停。是否合成音訊
   ▼
Phase 3   音訊合成（可選）
   ▼
Phase 4   錄製 + 後製

工作目錄約定（agent 在使用者當前目錄下建立 / 編輯）：

my-video/
├── article.md          # 使用者給原文時必有 —— 不刪！開發階段畫面資訊來源
├── script.md           # 必有：保持原文語言的平台化口播稿（決定節拍）
├── outline.md          # 必有：開發計畫（章節切分 + 每步內容 + 資訊池）
└── presentation/       # 腳手架產出的 Vite + React + TS 專案
    ├── src/chapters/<NN>-<id>/
    │   ├── <Chapter>.tsx     # 視覺實作
    │   ├── <Chapter>.css
    │   └── narrations.ts     # ★ step 數 + 口播文字的唯一真相來源
    ├── scripts/
    │   ├── extract-narrations.ts   # 掃所有 narrations.ts → audio-segments.json
    │   ├── synthesize-audio.sh     # provider-agnostic runner（循環 segments）
    │   └── tts-providers/          # 每 provider 一個 .sh（內建 2 個）
    │       ├── README.md           # 三函數契約 + 5 段現成程式碼片段（11labs / edge-tts / say / azure / gcloud）
    │       ├── minimax.sh          # 預設 provider，用 mmx-cli
    │       └── openai.sh           # 內建 OpenAI TTS（curl + OPENAI_API_KEY）
    ├── audio-segments.json         # extract 產出（合成前 review）
    └── public/audio/<id>/<N>.mp3   # 可選：合成的音訊

關鍵：narrations.ts 是 step 數和音訊合成的唯一真相來源。
章節 .tsx 裡的 if (step === N) 出現的最大 N + 1 必須等於
narrations.length。這保證 5 處地方（script / outline / 章節程式碼 /
chapters.ts / 音訊檔案）永遠不會漂移。

---

硬性自我檢查協議（貫穿整個 Skill）

下面三個產出，每一個完成後必須走自我檢查 → 修復 → 再回報 / 推進：

產出	自我檢查清單出處
script.md	SCRIPT-STYLE.md 三層自我檢查（形式 / 風骨 / 念出來）
outline.md	OUTLINE-FORMAT.md 自我檢查
單章實作完成	CHAPTER-CRAFT.md 完工自我檢查

執行方式（按能力降級，優先使用更隔離的方式）：

1. Agent Teams（最佳）：開一個獨立的 reviewer agent，給它「產出檔案
   路徑 + 對應清單 + 關鍵上下文」，讓它逐項核查並嚴格回報結論
   （哪幾條 pass / 哪幾條 fail + 證據 + 改寫建議）。
2. subAgent（次佳）：沒有 Teams 能力但能開 subagent 就用 subagent
   走同樣流程。
3. 自我檢查（備用）：當前 agent 都沒有上述能力，就自己嚴格逐項
   核查 —— 不允許目測一遍就放行。

鐵律：拿到結論後先按 fail 項把產出改完，再向使用者回報「做完了

• 自我檢查結論 + 改了什麼」。直接拿原始結論回報但不修復 = 違規。

---

各階段檔案讀取指南

不同階段讀不同的檔案。長對話裡 agent 容易遺忘原則，特別是
Phase 2.4 的「實作單章」會重複 N 次 —— 每次都要回頭看核心限制。

階段	必讀（每次都看）	一次性看完 / 按需查
Phase 1.1-1.2 內容編寫	references/SCRIPT-STYLE.md + references/OUTLINE-FORMAT.md + article.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 單一入口 —— Part 0 十條原則 / Part 1 開工 5 問 / Part 2 關係→動作決策樹 / Part 3 視覺工具箱 / Part 4 時長參考 / Part 5 反 AI 味反模式 / Part 6 程式碼硬規則（含 narrations.ts 強制限制）/ Part 7 完工自我檢查 / Part 8 反饋速查 + 目前主題的 themes/<id>/theme.json + 目前章節的 outline.md 段落 + article.md 本章對應段落 + 素材清單	references/EXAMPLES/（結構示意，不是抄襲模板）；references/THEMES.md 完整 token 契約
Phase 3 音訊合成	references/AUDIO.md（含 narrations.ts → segments.json → 任意 provider 流程，內建 minimax + openai）	templates/scripts/tts-providers/README.md（換 provider / 自帶 TTS 時）
Phase 4 錄製 + 後製	references/RECORDING.md（含 ?auto=1 自動錄製）	——
選 / 造 / 切主題	——	references/THEMES.md

寫章節時只讀一份 CHAPTER-CRAFT.md。十條原則 / 開工 self-prompting /
決策樹 / 反 AI 味反模式 / 完工自我檢查全部併入這一份單一入口。EXAMPLES/
不是必讀 —— 先按內容自由設計，卡住才翻（按 anchor 翻「形」，不要照搬）。

---

Phase 1 —— 內容編寫（一次產出）

1.1 識別使用者輸入

使用者給的東西	該做的
原始文章（書面語 / 公眾號 / 論文 / 部落格）	一次產出 script.md + outline.md（1.2），過 Checkpoint Plan
直接的口播稿 / 影片腳本	存成 script.md，一次產出 outline.md（1.2 簡化版），過 Checkpoint Plan
什麼都沒有，只說「幫我做個 X 主題的影片」	反問：先給一段素材或大綱。Skill 不替使用者構思內容

1.2 一次產出 script.md + outline.md

兩份產出物在一次思考中完成：

1. 生成 script.md：按 references/SCRIPT-STYLE.md
   的規則把 article 轉成保持原文語言的平台化口播稿。保留 article.md 不刪——它是
   outline 寫資訊池和章節實作畫面時的細節來源（雙源原則）。
2. 生成 outline.md：按 references/OUTLINE-FORMAT.md
   規則切章節 + 切 step + 每章首段抽資訊池。

outline 的邊界（關鍵）：

outline 必須寫	outline 不要寫
章節切分 / 每章 step 數 / 估時	具體動畫類型（blur clear / wipe / 彈簧）
每步螢幕內容（hero / 資料 / 標語 / 列表項）	CSS 實作手段（filter / SVG / clip-path）
章節級資訊池：從 article 抽的數字 / 引用 / 案例 / 標籤	時長數值（不寫 ~2.5s / 80~120ms）
步級關係名前綴（「反差對照」 / 「遞進列表」 / 「金句」 等可選 hint）	持續微動 / 錯峰量等微觀節奏

outline 不寫動畫的理由：寫死動畫 = chapter agent 退化為翻譯機；
留白讓 chapter agent 在每步開工時按 CHAPTER-CRAFT.md
的「內容驅動決策樹」自由設計，才有真正的影片感。詳見
CHAPTER-CRAFT.md Part 0 原則 7。

存檔後必須先走自我檢查再進 Checkpoint Plan：按上文「硬性自我檢查協議」分別
對 script.md / outline.md 執行（優先 Agent Teams → subAgent → 自我檢查），
按結論修復完成後再進入 Checkpoint Plan。

---

Checkpoint Plan —— 5 件事一次對齊（硬節點）

script.md + outline.md 寫完後必須停下來。使用者在這個節點同時確認
5 件事。

agent 此時要做的準備工作

1. 讀所有 themes/*/theme.json 拿 nameZh / descriptionZh / bestFor
   / mood —— 不要硬編碼清單
2. 根據 script.md 的內容類型 / 關鍵字 / 語氣，主動從主題裡挑 2~3
   套最匹配的推薦（匹配 bestFor 欄位）
3. 掃一遍 outline.md 末尾「素材清單」部分

總結模板（骨架，agent 按情況填充）

內容計畫寫完，產出檔案：
  📄 article.md     {若使用者給原文則保留}
  📄 script.md      {X} 字 / ~{T} 分鐘
  📄 outline.md     {N} 章 / {M} 步 + 每章資訊池 + 末尾素材清單

章節速覽：
  1. <id>     <章節標題>    <S> 步 ~<T>s
  2. ...

接下來一次對齊 5 件事：

  1. 稿子 (script.md) 要不要改？
     可以直接編輯檔案，或口頭告訴我修改方向。

  2. 開發計畫 (outline.md) 要不要改？重點看：
     - 章節切分 / step 數 / 估時是否合理（合理判斷：每章 30~60s）
     - 每步螢幕內容是否清晰
     - 每章首段「資訊池」是否有足夠的 article 細節供畫面掛載
     - 末尾素材清單是否完整

  3. 選哪個主題？我的推薦：
     ★ <推薦 1：nameZh (id)> — 因為 <bestFor 命中>；<descriptionZh 摘要>
     ★ <推薦 2 / 推薦 3>
     其它可選：<剩餘主題，nameZh + 一句話>
     也可以讓我幫你做新主題（詳見 references/THEMES.md）。

  4. 真實素材怎麼準備？粗略看本影片要的圖：<列粗略清單>
     a) 我從 <現有素材路徑> 幫你挑   b) 你自己提供   c) 全部 placeholder

  5. 開發模式選哪個？

     **第 1 章無論哪種模式都必須主執行緒做完 + 使用者驗收**（強制 anchor）。
     差異在第 2 章及之後：

     A) 預設 · 逐章確認（推薦）
        每章做完都暫停驗收 → 風險可控 / 節奏最穩
     B) 第 1 章後順序開發（不並行）
        第 2~N 章主執行緒順序做完後統一驗收 → 速度中 / 適合 agent 不支援並行
     C) 第 1 章後並行開發（subagent）
        第 2~N 章用 subagent 並行 → 最快 / 使用者控制並行數（一次幾章）
        ⚠️ 風格各章會有差異（這是預期，主題禁區備用）

收到回饋後：

• 稿子 / outline 要改：直接編輯檔案，編輯完通知一次（或口頭描述 agent 改）
• 主題必須明確才進入 Phase 2。使用者說「主題你幫我選」 → 取你推薦的第 1 個，
  告訴使用者你選了什麼、為什麼，給反悔機會
• 模式選定 → 進 Phase 2

---

Phase 2 —— 網頁開發

2.1 腳手架

bash <path-to-web-video-presentation>/scripts/scaffold.sh \
  ./presentation \
  --theme=<使用者選的主題 id>

bash <path-to-web-video-presentation>/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_CHAPTER
的 import 和陣列項移除。

2.2 第 1 章 —— 主執行緒 + 強制驗收

核心：第 1 章 = 完整版本一次到位（節奏 + 視覺 + 真實素材齊全）。
沒有「骨架版」概念 —— 第一章就要做出使用者能直接驗收的樣板。

為什麼第 1 章必須主執行緒：

• 它是 CHAPTER-CRAFT.md 這套指引在目前
  主題 + 目前題材下的第一次落地
• 如果指引有盲區 / 主題顏色 / 字型 token 不夠用，第 1 章一定會暴露 ——
  這時候有人類回饋就能修指引 / 調主題，早改成本最低
• 後續章節（無論順序 / 並行）都要參考第 1 章的程式碼模式，所以第 1 章 =
  當次專案的「風格錨點（不強求章節間一致，但單章自身得有完整說服力）」

做完第 1 章後必須停下來等使用者驗收：

第 1 章 <id> 做完了，dev server 在 localhost:5173 執行。

驗收重點：
  □ 視覺氣質對不對？符合 <theme nameZh> 的預期嗎？
  □ 節奏對不對？某些步太快 / 太慢 / 資訊太薄？
  □ 內容驅動動畫是否到位？還是有幾步是無腦入場動畫？
  □ 雙源原則：螢幕畫面有沒有「口播沒唸但 article 能掛」的細節？
  □ 反 AI 味檢查：紫粉漸層 / 圓角彩色邊框 / 假插圖 / emoji 是否有？

問題告訴我，我針對性改。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 章」）。最快，但風格各章會有差異 —— 這是預期，因為：

1. 每個 subagent 看不到別的 subagent 產出，無法機械對齊
2. 章節程式碼物理分離（每章一個資料夾 / 自己的 CSS 前綴），不會互相
   破壞
3. 主題 token 備用視覺統一（顏色 / 字型 / hero 數字 / 卡片 / 分隔線
   性格 / 裝飾），氣質不會跑偏
4. 風格不一致 = 人手寫影片的呼吸感（多 voice / 多視角）

並行 subagent 的 prompt 必須包含：

• 目前章節 outline 段落（含資訊池）
• references/CHAPTER-CRAFT.md 的路徑（單一必讀 —— 視覺演示要求 +
  逐步揭示 + 雙源原則 + 反 AI 味 + 程式碼紅線 + 完工自我檢查全部在這一份裡）
• 目前主題 theme.json 的 descriptionZh / mood / bestFor（參考氣質
  即可，動畫 / 時長 / 字型大小 / emoji 由 chapter agent 自由決定）
• 第 1 章程式碼作為「程式碼風格」參考（不是「視覺抄襲對象」）
• 硬規則：每章獨立 CSS 前綴（.cd- / .mg- / .pm- / ...）；
  不修改 chapters.ts；完工執行 npx tsc --noEmit

重要：無論選哪種模式，使用者隨時可以中途切換模式。第 2 章 OK
後使用者說「剩下的並行」 / 「剩下的逐章」 都行。

2.4 實作單章（每章必走）

詳細指引見 references/CHAPTER-CRAFT.md ——
單一必讀入口，涵蓋：視覺演示要求 / 逐步揭示 / 內容取捨 / 雙源原則
/ 影片演示基本審美 / 反 AI 味 / 程式碼紅線 / 完工自我檢查。

核心要點（CHAPTER-CRAFT.md 詳述）：

• 每章必須有 CSS / SVG / Canvas / JS 視覺演示，禁止純文字章節
• 逐步揭示：清單 / 列表必須 1 項 = 1 step，禁止一次全部展示
• 雙源原則：節奏跟口播稿（順序不能亂），細節回原始文章抽（資訊池 +
  本章 article 段落）
• 完工自我檢查逐項過，不達標回去改 —— 按上文「硬性自我檢查協議」執行
  （優先 Agent Teams → subAgent → 自我檢查），改完再向使用者回報本章交付

2.5 大改後 bump STORAGE_KEY

改動 chapters.ts（增加 / 刪除 / 重排章節，或某章 narrations.ts
長度變化）後，bump presentation/src/hooks/useStepper.ts 的
STORAGE_KEY（如 v4 → v5），避免持久化游標落到不存在的 step 上。

---

Checkpoint Audio —— 是否合成音訊（硬節點）

Phase 2 結束後必須停下來，問使用者：

網頁做完，{N} 章 {M} 步，dev server 在 localhost:5173 跑著。

要不要合成音訊做「自動播放錄製」？
  ✓ 合成 → 掃所有章節的 narrations.ts 出 audio-segments.json，
           調 TTS provider 合成每步一個 mp3 到 public/audio/。
           合成完後用 ?auto=1 模式可以一鏡到底錄製（音影片天然同步）。
           內建兩個 provider：
             • minimax (mmx-cli)    —— 預設，中文音色穩
             • openai  (OPENAI_API_KEY) —— curl-based，多數已有 key
           其它後端 (ElevenLabs / edge-tts 免費 / macOS say 離線 /
           Azure / Google) 見 scripts/tts-providers/README.md 的現成片段。
  ✗ 不合成 → 跳過 Phase 3，直接 Phase 4 用手動錄製 + 後製配音。

要合成 → Phase 3。不合成 → 直接 Phase 4。

---

Phase 3 —— 音訊合成（可選）

詳細流程見 references/AUDIO.md。簡化版：

cd presentation
npm run extract-narrations   # 掃所有 narrations.ts → audio-segments.json
# 讓使用者掃一眼 audio-segments.json 確認文字對
npm run synthesize-audio                       # 預設 minimax provider，增量
# 或用內建 openai (要 OPENAI_API_KEY):
PRESENTATION_TTS=openai npm run synthesize-audio
# 或自訂：寫一個 scripts/tts-providers/<name>.sh，見該目錄的 README.md

合成完告訴使用者：輸出位置 / 總段數 / 哪些段時長異常（太長 = 該 step 拆
分；太短 = 文案太薄）—— 給最後一次校準節奏的機會。然後進入 Phase 4。

---

Phase 4 —— 錄製 + 後製

詳見 references/RECORDING.md。兩種路徑：

場景	推薦路徑
Phase 3 已合成音訊	Auto 模式一鏡到底：瀏覽器開 localhost:5173/?auto=1 → 按 SPACE → 整片自動播完 → 停止錄製 → 裁頭尾即成片，無需後製對音軌
Phase 3 跳過	預設 Manual 模式手動點擊推進 → 後製任意剪輯工具配音

agent 在 Phase 3 / Checkpoint Audio 後主動告訴使用者適合的錄製路徑。

---

十條原則（一句話清單）

完整展開見 references/CHAPTER-CRAFT.md
Part 0 —— 寫章節時回那裡查，下面只是索引。

#	原則	一句話
1	16:9 固定舞台	內容 1920×1080 + transform scale，沒有響應式
2	全域 step 計數器	章節是 step 的純函數，無定時器
3	每步獨佔整螢幕	if (step === N) return <FullScene />
4	口播節拍 = step	一節拍 = 一 step = 一聚焦想法
5	隱藏的邊角控制項	進度條 / 翻頁器預設 opacity 0
6	舞台無 chrome	沒有 header / footer / 頁碼 / 品牌條
7	內容驅動動畫	先找內在動作，找不到才入場動畫備用；持續微動謹慎使用
8	多點逐個揭示	1 項 = 1 step，禁止同步 stagger 上 N 項
9	整片同一主題	章節間不翻表面色；顏色 / 字型走 token，其它尺度章節自由
10	雙源原則	script 定節拍，article 定畫面密度（落到資訊池）

---

常見使用者回饋速查

簡化表見 references/CHAPTER-CRAFT.md
Part 8「常見回饋速查」。關鍵：先定位是哪一層（節奏 / 視覺 / 內容
/ 程式碼），再改最小切片，不要重做整章。

---

相關資源

按「何時讀」標註，避免一次性全讀：

檔案	何時讀	內容
references/SCRIPT-STYLE.md	Phase 1.2 必讀	文章 → 口播稿規則、平台變體
references/OUTLINE-FORMAT.md	Phase 1.2 必讀	outline.md 欄位 spec、命名約定、章節切分、資訊池
references/CHAPTER-CRAFT.md	Phase 2.4 每章單一必讀入口	Part 0 十條原則 / Part 1 開工 5 問 / Part 2 關係→動作決策樹 / Part 3 視覺工具箱 / Part 4 時長 / Part 5 反 AI 味反模式 / Part 6 程式碼硬規則 / Part 7 完工自我檢查 / Part 8 回饋速查
references/EXAMPLES/	可選 —— 看結構	章節結構示意（hook / list-reveal / case-tech-review）；不是抄襲模板
references/THEMES.md	選 / 造 / 切主題時	完整 token 契約 + 內建主題清單 + 創作流程
references/AUDIO.md	Phase 3 才讀	provider-agnostic 音訊合成流程、內建 minimax 用法、換 provider 路徑、故障排除
templates/scripts/tts-providers/README.md	換 / 加 TTS provider 時	三函數契約 + 內建 2 個 (minimax / openai) + 5 種現成程式碼片段（ElevenLabs / edge-tts / macOS say / Azure / Google）
references/RECORDING.md	Phase 4 才讀	錄製工具 + 後製合成
themes/	Checkpoint Plan / Phase 1.2 時翻	內建主題（每個含 theme.json + tokens.css）
scripts/scaffold.sh	Phase 2.1 跑一次	一鍵專案腳手架