README Screenshots
將一個可運作的專案轉化為有文件、有視覺效果的專案：執行應用程式、擷取其界面的真實螢幕擷圖，並圍繞它們組合成一個生動、清晰的 README.md。最終結果應讀起來像一個受歡迎開源專案的 Landing Page。
不論平台為何，以下原則不可妥協：
- 螢幕擷圖必須是真實執行中應用程式的擷取畫面。絕不繪製、模擬或偽造圖片。
- 圖片必須存放在儲存庫中（
docs/screenshots/），且 README 使用相對路徑引用，以便在 GitHub 上正確呈現。 - 不可進行破壞性操作：絕不修改專案的原始程式碼來產生螢幕擷圖——如有必要，可在執行時注入示範狀態，但必須明確說明。
工作流程
第一階段 — 偵測平台
在專案根目錄中尋找以下跡象，然後從 references/ 載入一個對應的執行手冊：
| 跡象 | → 執行手冊 |
|---|---|
帶有 dev/start 腳本的 package.json，或 index.html，或 src/public 資料夾中的純網頁前端 | references/web.md |
manifest.json（WebExtension/MV3/V2） | references/web.md（擴充功能章節） |
Android：build.gradle(.kts)、AndroidManifest.xml、settings.gradle、Kotlin/Java 應用程式原始碼 | references/android.md |
iOS：*.xcodeproj、*.xcworkspace、Info.plist、Swift 應用程式程式碼 | references/ios.md |
Flutter：pubspec.yaml 包含 flutter: 和 lib/main.dart | references/flutter.md |
| 多平台（例如 Flutter + 原生，或 monorepo） | 先記錄旗艦 UI 的平台；在 README 中註明其他平台 |
如果平台確實不明確，則先向使用者詢問一次，並呈現你對儲存庫的最佳解析結果。如果專案沒有使用者可見的界面（純函式庫/CLI），不要偽造 UI 畫面——改為使用終端機示範、精煉的圖表或產生的橫幅，並仍然產出一個出色的 README。
第二階段 — 依照執行手冊執行應用程式
每個執行手冊會說明：
- 本機必須已經安裝了什麼（工具鏈檢查，可重複的單行命令）。
- 如何啟動應用程式使其 UI 呈現在螢幕上。
- 如何實際擷取像素（
scripts/中的捆綁腳本或原生命令）。 - 當畫面空白時如何恢復（「等待渲染完成」優於「盲目重試」）。
第三階段 — 擷取
適用於所有平台的慣例：
- 儲存到
<repo>/docs/screenshots/，使用 kebab-case 命名來描述該畫面（例如hero-dashboard.png、settings-screen.png），絕對不要使用工具自動產生的名稱（例如screenshot-2026-01-04-14-22.png）。 - 以每個界面的自然形狀進行擷取：對話框/彈出視窗以其原始大小，頁面以 1280×800 或全頁面。在手機上，直接擷取裝置螢幕（其本身解析度就是故事的一部分）。
- 如果應用程式有深色模式，優先為主打畫面使用深色模式——深色 UI 在 README 中更顯眼——但僅限於應用程式確實具有真實的深色主題；不要強制啟用。
- 允許使用示範狀態（例如空計數器、「載入中…」的佔位文字在行銷畫面中看起來很糟糕），但必須在執行時注入，而非寫入專案程式碼，並且必須在你的摘要中向使用者揭露。
- 空白或閃爍的畫面通常是時序錯誤，而非應用程式的問題：等待載入完成，並再多等一會讓字型、圖示和轉場動畫完成；如果仍有問題，以更長的等待時間重試一次。
第四階段 — 撰寫 README
在儲存庫根目錄撰寫（或重寫）README.md。如果已經有豐富的 README 內容（git-readme.md、散文檔案、docs），則提取所有資訊——你是在升級呈現方式，絕不刪除資訊。
目標結構（可自由調整，保持易於掃讀）：
# <專案名稱>
<p align="center"><img src="docs/screenshots/hero.png" width="…"></p>
> 一句話介紹，帶有個性。
徽章：授權條款、語言、安裝連結
## 為何存在 ← 痛點，2–4 行，如果數據屬實則使用粗體
## 功能說明 ← ✨ 緊湊的功能列表（在功能旁放置擷圖）
## 螢幕擷圖導覽 ← 附有一行說明的圖庫
## 運作原理 ← 用白話文說明的架構；表格優於散文
## 安裝方式 ← 編號、可複製貼上的指令
## 配置選項 ← 如果應用程式有設定，則使用參數表格
## 隱私 / 安全性 ← 僅在有意義時加入
## 授權條款
風格規則：
- 主打畫面置於摺頁上方，明確指定寬度（手機畫面使用
width="400"，桌面畫面約 728px 以下），以確保在 GitHub 上排版良好。 - 每個章節一個想法；段落簡短；粗體僅用於輔助掃讀。
- 相容性矩陣和設定使用表格——它們比散文更有效。
- 可在標題中使用少量、有品味的 emoji（⏱ 🎨 🚀），但不要每一行都加。
- 始終使用相對路徑的圖片並附上替代文字。
- 切勿在 README 中敘述螢幕擷圖的過程；這會讓 README 看起來像是專案自己寫的。
第五階段 — 驗證
- README 中的每個圖片路徑都必須對應到一個實際存在的檔案。
- 沒有任何螢幕擷圖超過約 1.5 MB；如果超過，請壓縮（PNG → WebP 或降低解析度）。
- 告知使用者：README 的位置、有哪些擷圖、哪些擷圖包含注入的示範資料，並提供更換主打圖、主題或順序的選項。
工具鏈政策（缺少依賴項處理）
此技能使用機器上既有的工具鏈，絕不靜默安裝平台 SDK（Android SDK、Xcode、Android 模擬器——這些是需要使用者同意的數 GB 下載）。如果執行手冊的工具鏈檢查失敗，則以以下格式乾淨地停止：
[平台] 擷圖需要 [工具]，但尚未安裝。若要啟用此功能：
<確切的安裝命令或步驟>。安裝完成後，請說「retry」，我將繼續——目前已完成的工作（偵測、README 骨架）已保存。
iOS 是一個特殊情況：如果主機不是 macOS，則用一句話說明並跳過——在 Windows/Linux 上無法透過重試啟用。提供使用者一個選項，讓他們可以提供自己手動擷取的螢幕擷圖。