Quinus/screen-flow

螢幕流程 Montage

從實際截圖建立獨立 HTML 螢幕流程。包含三個部分：

1. 繪製地圖：主要從程式碼中，將螢幕與之間的連結繪製成 flow.json。
2. 擷取畫面：使用您擁有的 Agent 工具在執行中的應用程式裡擷取每個螢幕。對於每個連結，也要記錄其熱點：觸發連結的按鈕、分頁或列在截圖上的位置。檢視器會從該點開始繪製箭頭。
3. 建置頁面：使用 scripts/build_flow.py 腳本。該腳本負責版面配置、箭頭繪製、平移與縮放，並嵌入圖片。切勿自行撰寫檢視器的 HTML。請將心力花在正確的地圖和良好的截圖上。

以下路徑皆相對於此技能所在的資料夾（即此檔案所在的資料夾）。

0. 範圍與輸出

• 範圍：feature（單一功能或流程，例如「結帳」或「家長控制」）或 app（所有螢幕）。如果要求沒有明確說明，則使用他們提到的功能。若未提及功能名稱，則使用整個應用程式。
• 功能範圍：包含導向該功能的入口螢幕，例如開啟該功能的按鈕所在的分頁或主畫面。將它們放在一個小的 nav 群組中，以便讀者能知道功能從哪裡開始。不要擷取應用程式的其餘部分。
• 輸出資料夾：使用使用者要求的資料夾。否則使用專案中的 screen-flows/<slug>/：flow.json、screens/<screen-id>.png、和 screen-flow.html。在寫入儲存庫之前，檢查是否需要將 screen-flows/ 加入 .gitignore。PNG 檔案可能很大。

1. 繪製導覽地圖（在截圖之前）

閱讀程式碼以建立清單。不要隨意點擊。查閱位置：

技術堆疊	導覽存放位置
React Router / TanStack Router	路由設定、createBrowserRouter、<Route>、routes/ 資料夾
Next.js / Remix / Nuxt / SvelteKit	基於檔案的路由：app/、pages/、routes/、src/routes/
Angular / Vue	*-routing.module.ts、router/index.ts
SwiftUI / UIKit	NavigationStack、TabView、.sheet、.fullScreenCover、協調器、storyboard / segue
Android	NavHost / composable(...) 路由、nav_graph.xml、Manifest 中的 Activity、底部導覽選單
Flutter	GoRouter / routes: / Navigator.push、BottomNavigationBar
React Native	createNativeStackNavigator、createBottomTabNavigator、Expo Router app/ 資料夾
TV / 10 英尺應用程式	基於焦點的選單、輪播軌道、遙控器的返回鍵、深度連結處理器

然後找出連結螢幕的觸發器：按鈕、連結、分頁列、選單、navigate(...)、router.push、.sheet(isPresented:)、登入後的重定向、守衛（guard）。每個觸發器成為一條邊（edge）。

先寫一個不包含圖片的 flow.json。完整格式請參閱 references/flow-schema.md。簡而言之：

• 群組
  • 為主要導覽外殼建立一個 kind: "nav" 群組：包含分頁列或側邊欄的目的地、主畫面及全域選單。這些螢幕會並排顯示在畫布頂端的一行中。
  • 每個功能建立一個 kind: "feature" 群組，其螢幕按任務順序排列（例如：列表 → 詳情 → 編輯 → 確認）。
  • 將入門引導、登入和註冊流程放在它們自己的功能群組中。
• 螢幕：每個不同的視圖作為一個螢幕。當 modals、sheets、對話框和重要狀態（空白、錯誤、付費牆）對流程有影響時，也將其算作螢幕。使用 state 標記它們。在群組開始處的螢幕設定 entry: true。
• 邊（Edges）：將使用者的操作寫為標籤，例如 "點擊『結帳』" 或 "向左滑動"。對於返回路徑使用 kind 為 back，modal 用於模態，redirect 用於自動導航。除非必要，否則省略顯而易見的返回連結。不要將每個分頁都連結到其他每個分頁。僅從預設分頁連結到其他分頁，因此一個有 5 個分頁的應用程式只有 4 條邊，而不是 20 條。

使用 python3 scripts/build_flow.py flow.json --check 檢查地圖。對於超過約 25 個螢幕的完整應用程式，在擷取任何內容之前，向使用者顯示群組和螢幕列表，並請其確認。

2. 擷取實際截圖

閱讀 references/capture.md 以了解每個平台應使用的工具和命令。適用於所有平台的規則：

• 優先使用您的工具框架提供的工具。 這些工具包括瀏覽器或預覽工具、裝置或模擬器工具，以及 Playwright/Chrome DevTools MCP 伺服器。如果您沒有這些工具，請使用 capture.md 中的備用方案：scripts/capture_web.mjs (Playwright)、xcrun simctl io 或 adb exec-out screencap。
• 自行執行應用程式。 使用專案自己的執行說明（README、AGENTS.md/CLAUDE.md、package.json 腳本、執行設定）。使用本機或開發建置版本，並搭配測試資料。
• 使用測試帳戶登入。 如果需要憑證，請詢問使用者。切勿猜測、切勿使用真實客戶帳戶，也切勿將機密貼入 flow.json。
• 為整個流程使用單一裝置和視埠。 對於行動網頁，使用 390×844 解析度，2× 倍率。對於桌面網頁，使用 1440×900。對於原生應用程式，使用一個模擬器或模擬器型號。全程使用相同的主題和語言。
• 盡可能模擬使用者操作到達每個螢幕。 這也能驗證您的邊。如果某個步驟很慢或不穩定，請使用深度連結或 URL 直接開啟螢幕。如果實際路徑與您的地圖不同，請修正地圖。
• 等待螢幕穩定後再截圖。 沒有載入動畫、沒有骨架畫面、圖片已載入、沒有 toast 通知（除非它們是重點）。關閉開發者疊加層和除錯橫幅。
• 絕不做任何破壞性或不可逆的操作，例如付款、刪除、或發送電子郵件或訊息（除非在沙盒環境中）。擷取確認畫面後即停止。
• 將每張截圖儲存為 screens/<screen-id>.png，並在 flow.json 中設定 image。
• 為每個連結記錄熱點：在來源螢幕上，記錄使用者點擊的元素邊界框。使用與截圖相同的座標系統（圖片的像素，或 0 到 1 之間的分數）。在網頁上，scripts/capture_web.mjs 會透過選擇器為您執行此操作，並寫入 hotspots.json。在原生平台上，從 UI 樹中取得元素邊界（請參閱 capture.md）。對於非可見元素的連結，例如滑動、自動重定向或系統返回按鈕，則跳過此步驟。
• 儲存每張截圖後立即檢查：使用您的圖片檢視器或 Read 工具。重新擷取任何空白、被裁剪、畫面錯誤、有登入阻擋或錯誤頁面的截圖。
• 如果無法到達某個螢幕，將其保留在地圖中但不帶 image，並在 notes 中寫明原因。檢視器會為其顯示一張「未擷取截圖」的卡片。

3. 建置與檢查

python3 scripts/build_flow.py <out>/flow.json            # 寫入 <out>/screen-flow.html
python3 scripts/build_flow.py <out>/flow.json -o docs/flow.html --max-width 900

該腳本僅需 Python 標準函式庫。它會讀取 flow.json 旁邊的 hotspots.json（如果該檔案存在），或您使用 --hotspots 傳入的檔案。為保持檔案小巧，當 Pillow 或 macOS 的 sips 可用時，它會縮小寬度超過 --max-width（預設 1000 像素）的截圖。

開啟 HTML 並查看。使用瀏覽器工具截圖，或直接為使用者開啟。然後透過 flow.json 修正版面配置並重新建置：

問題	修正方法
群組內的螢幕順序錯誤	重新排列 screens、設定 entry: true、或使用 "column": n 固定螢幕
群組是鬆散的螢幕集合，而非序列	在群組上設定 "layout": "grid"
長序列應排成一行	設定 "layout": "row"
某個功能離其起始點很遠	加入導向該功能的邊，或設定 "parent": "<group-id>"
箭頭太多	移除不需要的返回連結，或僅從預設分頁連結其他分頁
箭頭從截圖上的錯誤位置開始	修正該邊的 hotspot（在詳情面板中檢查）

PNG 與 PDF 匯出

如果使用者要求圖片或 PDF，或者流程需要放入 pull request、工單、Confluence 或簡報中，請以無頭模式匯出。這使用了與頁面上「匯出」按鈕相同的渲染器：

node scripts/export.mjs <out>/screen-flow.html <out>/screen-flow.png                 # 整個流程
node scripts/export.mjs <out>/screen-flow.html <out>/checkout.png --scope checkout   # 單一群組
node scripts/export.mjs <out>/screen-flow.html <out>/screen-flow.pdf                 # 概覽 + 每個群組一頁

選項：--theme light|dark（預設 light）、--no-hotspots、--no-group-pages（PDF）。此腳本需要 Playwright，其設定方式與 capture_web.mjs 相同。在交給使用者之前，請先查看 PNG 結果。

4. 回報

將 screen-flow.html 的路徑以及螢幕和群組的數量提供給使用者。列出任何沒有截圖的螢幕及其原因。提及以下檢視器控制項：

• 拖曳平移；滾輪或捏合縮放。
• 點擊螢幕可放大檢視，並顯示其傳入和傳出的連結。
• 拖曳螢幕，或拖曳群組的標題，可重新排列；此操作會儲存在該瀏覽器中。
• 熱點（工具欄按鈕，或按 H 鍵）會讓每個箭頭從觸發它的按鈕起點開始。在詳情面板中，熱點是可以點擊的，因此讀者可以像原型一樣點擊瀏覽流程。
• / 搜尋，F 讓所有內容適應畫面。
• 匯出（工具欄）可下載整個流程、目前檢視畫面或單一群組的 PNG 或 PDF，可選擇淺色或深色主題。PDF 有一個概覽頁面加上每個群組一頁。匯出會遵循目前的切換開關設定（標籤、跨群組連結、返回連結、熱點）。
• 在 URL 末尾加上 #<screen-id> 可直接開啟該螢幕。