Visual Flow Verify

Visual Flow Verify (vfv) · 以 Figma node 為節點的可重播視覺驗證

工程師看畫面「對了」，設計師看畫面「不對」，而流程走到第 7 步的那個狀態， 沒有人能第二次重現出來—— **vfv 把流程的每一步綁在一個 Figma node 上：任何一步都能直達重播、像素確定、 diff 熱區＋疊圖滑桿給人看、HTTP API 給 AI agent 跑迴圈。**

[English](#english) ｜ [60 秒上手](#60-秒上手) ｜ [為什麼不用其他工具](#為什麼不用其他工具) ｜ [三層漏斗](#三層漏斗ai-操作人裁決) ｜ [綁自己的 app](#綁自己的-app) ｜ [API](#api給-ai-agent-的入口) ｜ [已知地板](#已知比對地板)

---

它長什麼樣


每一步四張圖並排：**實作截圖**、**設計基準**（Figma 匯出或本機 PNG）、**diff 熱區**（紅＝差異）、 **疊圖**（拉桿調透明度）。超過閾值的步驟標紅；L2 資料對帳表、L3 AI 裁決、確定性連跑結果都掛在該步下面。 報告是單一靜態 HTML，`file://` 直開也能看。

60 秒上手

隨附一個三頁的 demo app（登入 → 首頁清單＋banner → 明細），**不需要 Figma 帳號**， 基準圖已放在 `demo/baselines/`，第一次跑就會看到 0.00% 的真報告。

npm install && npm run setup      # 裝 Chromium、建 GUI、產生 .env（demo 帳密 demo/demo）
npm run demo                      # 另開終端：demo app 在 http://localhost:5174
npm run vfv -- run --manifest example --no-ai && npm run vfv -- serve

打開 看報告。想驗「同一節點連跑三次 diff 必須 0%」：

npm run vfv -- run --manifest example --no-ai --determinism 3

demo 裡故意放了三個「真實 app 都會有」的麻煩，讓你看 vfv 怎麼處理： 登入後跳一次的「What's new」對話框（`session.interstitials`）、登入時種下的一次性「Welcome back」旗標 （`session.stripStorageKeys`）、以及首頁上會變的「今天日期」和 `Math.random()` 選的小提示（凍結時間／確定性 PRNG）。 demo server 重啟後 token 全部失效，你會看到 runner 記錄 `快照驗證 invalid → 重熱身`，而不是給你一張假 diff。

需求：Node 20+。L3 AI 裁決需本機有 `claude` CLI（沒有也能跑，`--no-ai` 或結果標 `inconclusive`）。

為什麼不用其他工具

你可能會想用	為什麼 vfv 不一樣
Storybook / Chromatic 視覺測試	它們驗的是元件在隔離環境的長相。vfv 驗的是使用者流程：真 app、真登入、走到第 7 步、API 全部 mock 成固定種子，然後對稿。
Playwright toHaveScreenshot()	沒有凍結時間／隨機／動畫＋API 全 mock 的紀律，截圖測試三天就開始 flaky；基準是「上次的自己」，不是設計稿；失敗只給你一張 diff，沒有疊圖給人判。vfv 的 L1 就是那套紀律，基準綁 Figma node，報告有 overlay 滑桿。
Figma 開一邊、瀏覽器開一邊肉眼比	比得出「不一樣」，比不出「哪裡差幾 px」，也沒辦法第二次重現同一個狀態。vfv 給 diff 熱區、POST /api/figma/spec 直接讀稿上字級／字重／色值真值，不靠肉眼猜。

三層漏斗：AI 操作，人裁決

這是整個工具的核心想法。三層由便宜到貴，**只有前面失敗才進下一層**：

| 層 | 做什麼 | 誰做 | |---|