視覺敘事網站交付 是做什麼的？
核心原則
先問清 → 出計劃 → 獨立審核 → 自核實 → 實測校正 → 分批實施 → 每批可部署。 任何「不卡頓」「觀感好」這類無法腳本判定的驗收語都是禁區：每條驗收標準必須能被無頭瀏覽器斷言。
本 skill 的 6 個組成部分：
- 本文件：七階段流程 + 提問清單 + 審核模板 + 彙報格式
references/verify-recipes.md：13 種執行時量測技術 + 座標/管線陷阱references/pitfalls.md：22 條實測坑（現象→根因→修復→通用規則）references/animation-components.md：第三方 canvas 元件的整合套路（快取鍵 / cleanup / 掛載條件 / 停幀驗收）references/content-sourcing.md：數字必須有出處或明確標教學示意（科普/醫學/數據類必讀）assets/：long-stage.tsx+long-stage.css（長舞台三層結構）、tokens.css（雙主題）、verify-skeleton.mjs.md（驗收腳本骨架）
觸發即讀的對應關係：要接第三方動畫元件 → 讀 animation-components；頁面有具體數字/科學結論 → 讀 content-sourcing；其餘按階段順序讀。
階段 1：先問，不許猜
需求存在任何未經證實的假設時，禁止寫程式碼。把待定決策畫成樹，每輪只問前置條件已確定的；每個問題必須附推薦答案 + 理由，讓用戶能直接說 yes；能自己查證的（讀檔案、跑命令、查文件）不要問用戶。
必問清單（按依賴順序，可按專案裁剪）：
- 主題具體是什麼（領域/子領域/呈現角度）
- 給誰看（決定術語密度與容錯度）——「評分人/評審視角」是隱性需求，必須主動挖：問「誰來判斷它做得好不好」比問「寫多深」有效
- 打開頁面第一眼要讓人看懂什麼（一句話定調；給「數字衝擊型/提問互動型/反差懸念型」候選）
- 資料來源：真實可溯源 / 教學示意 / 混合
- 視覺基調：深色沉浸 / 淺色專業 / 高對比
- 交付型態：單頁 landing / 多章節長滾動 / 多頁
- 要不要 3D（收益 vs 驗收成本）
- 互動增強：長舞台 / 滑鼠跟隨 / 第三方動畫元件
- 專案目錄位置
- 用戶提供的參考材料如何落地（原始碼整合 vs 只當視覺參考）
- 線上地址 / 部署方式
用戶中途修訂決策是正常的（例：淺色 → 雙主題）。決策表要保留「原決策作廢」記錄，不要靜默覆蓋。
階段 2：出計劃，等審核
計劃檔案寫到 docs/plan-<主題>.md 並入庫。必須包含：
- 現狀分析：改現有專案時每句話帶
file:line；新建專案列檔案清單 - 決策表 D1–Dn：每條寫「為什麼這麼選」，不寫「我打算這麼做」
- 分批：每批獨立可部署、可回滾
- 驗收標準必須腳本能判定：「不卡頓」→「rAF 幀間隔中位數 ≤33ms」；「觀感好」→「相鄰卡片 blur(3px) opacity .55」
- 明確「不做什麼」：寫清排除項，防止實施期膨脹
階段 3：等明確確認
「嗯」「好」「行」視為含糊，再確認一次；「看著辦」不算確認。
階段 4：獨立審核
派全新上下文的子代理審核計劃。它不能只看計劃，必須同時給它真實程式碼與驗收腳本。
你正在審核一份尚未開始實施的計劃。你的任務是找出問題，不是批准。
## 必讀
- 計劃文件：<路徑>
- 真實程式碼：<專案根>，重點 <檔案>
- 驗收工具：<腳本路徑>
## 按優先級檢查
1. 事實準確性（最高價值）：每一處 file:line 是否正確？每一條關於現有行為的論斷是否成立？錯了用引用真實程式碼行反駁。
2. 完整性：聲稱實現 N 個決策，逐個檢查是否都有任務落實。
3. 內部矛盾：A 節承諾的，B 節是否禁止了？
4. 具體技術風險：列出 3-5 個本任務最可能出錯的點。
5. 遺漏：計劃沒寫、實施者必須自己發明的東西有哪些？
6. 驗收可檢驗性：每條標準能否被客觀判斷？哪些是模糊話？
7. 批次順序：有沒有批次依賴後面的批次？有沒有東西不屬於任何批次？
## 輸出
編號列表，每條：嚴重程度（BLOCKING/MAJOR/MINOR）、位置、錯在哪（帶證據）、怎麼修。
最後給結論：能否進入實施？
不要修改任何檔案。不要為了禮貌而批准——什麼都沒找到的審核是失敗的審核。
階段 5：審核意見必須自己核實
子代理會犯錯。 逐條去程式碼裡驗證，確認成立才改。預設「預期有一條是它自己錯的」。
已觀察到的兩次真實結果：
- 一次審核 16 條意見全部成立（7 MAJOR + 9 MINOR，其中 3 條是「驗收機制本身失效」——斷言恆真或永不失敗）
- 另一次它把 A 元件的 idle 判定安到 B 元件頭上，靠讀原始碼行號識破
階段 6：實測校正
審核代理靠讀程式碼推斷，讀不出執行時尺寸/幀率/合成行為。用無頭瀏覽器量，所有寫進文件的數字必須是實測值。
見 references/verify-recipes.md。
階段 7：分批實施
每批結束：跑完整驗收 → git tag → 提交。commit 訊息寫「改了什麼、為什麼、實測數據」。
彙報固定三段：
- 做了什麼：檔案清單 + 實測數據（不是「已完成」，而是
pinTop=68.0、travel 偏差 0.0px） - 還差什麼
- 發現了什麼：計劃錯還是程式碼錯，錯在哪一行
驗收體系的最小構成（本專案實測 45 斷言 / 7 單測）
| 層 | 工具 | 管什麼 |
|---|---|---|
| 類型 | tsc --noEmit | 類型完整性。vitest 全綠 ≠ 能構建，esbuild 剝類型 |
| 單元 | vitest run | 數據誠實性（出處欄位非空、兩類必須共存）、純函式 |
| 執行時 | scripts/verify.mjs（puppeteer-core + 系統 Chrome） | 佈局溢出、對比度、幀率、動畫狀態、降級分支 |
| 交付 | npm run build | 真實產物能構建 |
斷言必須能失敗。 寫完每條斷言後反向改一次程式碼確認它 FAIL，否則你不知道它是恆真還是真在測。
跨視口的斷言必須走 setViewportSettled。 page.setViewport 只保證視口尺寸已提交，不保證 reflow 完成；緊接著讀 scrollWidth 會拿到縮窄前的舊值，表現為偶發 FAIL（見 references/pitfalls.md 第 21 條）。這類偶發問題只有重複跑才暴露——單次全綠不能當驗收證據。
常見誤區
| 誤區 | 實際 |
|---|---|
| 「單元測試通過了就能交付」 | esbuild 剝類型，tsc 報錯時 vitest 仍全綠 |
| 「截圖 diff 能測所有視覺變化」 | headless 截圖管線可能不捕獲 DOM 重繪，只捕獲 canvas 紋理 |
| 「輪詢等待 500ms 夠了」 | scroll-behavior:smooth + scrub:1 都是非同步的，必須顯式 instant + 顯式輪詢到條件成立 |
| 「響應式就是改 viewport 測一遍」 | pin/觸摸/CDP 狀態會跨用例污染，必須新開 page 或新開瀏覽器程序 |
| 「reduced-motion 就是關動畫」 | 關動畫但資訊必須一條不少，要斷言文字量不減 |
與其它 skill 的關係
- 視覺方向/反 AI 味：
frontend-design、design-taste-frontend - 計劃與審核紀律：
writing-plans、plan-sds-review - 缺陷定位：
systematic-debugging - 完成後驗證：
verification-before-completion
本 skill 只補它們沒有的部分：執行時數據的採集口徑、可視化專有的坑、長滾動敘事的結構。