參考資料研究員 (ref-researcher) 是做什麼的？

總覽

ref-researcher 將原始靈感（即時網站、設計圖庫、應用程式錄影、UI 截圖或已儲存的 HTML）轉化為有觀點且可立即執行的 .md 設計與產品操作手冊，在設計或編碼開始之前完成。

當你需要深度檢查來自外部參考資料的視覺工藝、動畫線索、文案模式與反模式，同時又不失對專案實際品牌標記、平台規則與發佈範圍的忠誠度時，請使用此技能。這適用於行動應用程式功能、網頁應用程式流程或行銷網站。

相依技能

協調使用下列已安裝的技能，而非重複它們的職責：

uv — 透過 uv run 簡潔地檢查並執行 Python CLI 指令碼（若在完全離線/無 uv 環境下僅使用標準函式庫，才退而使用 python3）。
chrome-devtools — 渲染 JavaScript 密集型單頁應用程式 (SPA)、檢查即時版面/動畫行為，並在靜態 HTTP 擷取遇到客戶端外殼 (needs_browser_capture: true) 或需登入的網站時，擷取全頁螢幕截圖或進行互動式瀏覽器工作階段。
frontend-design — 在整合網頁應用程式或行銷網站的參考資料時，引導視覺觀點、字體配對、空間克制與反模板批評。
apple-hig-designer — 在整合行動應用程式功能或原生 Apple 裝置展示時，驗證原生 iOS/iPadOS/watchOS 元件的細節、安全區域、表單、動態字型與無障礙功能。

快速開始

從即時 URL（擷取公開 HTML/資源並擷取瀏覽器螢幕截圖）或從現有的本端參考資料資料夾開始：

# 1. 將已儲存的 HTML 參考資料解析為結構化 JSON
uv run ~/.gemini/config/skills/ref-researcher/scripts/ref_researcher.py extract-html \
  --input-dir "./Docs/References & Inspo" \
  --limit 25 \
  --output "/tmp/ref_html_summary.json"

# 2. 分割超高螢幕截圖 + 從影片中提取關鍵影格到暫存目錄 (寬度 1024px)
uv run ~/.gemini/config/skills/ref-researcher/scripts/ref_researcher.py slice-media \
  --input-dir "./Docs/References & Inspo" \
  --scratch-dir "/tmp/ref_slices" \
  --slice-height 1400 \
  --out-width 1024 \
  --max-slices 12 \
  --frames-per-video 3 \
  --output "/tmp/ref_media_manifest.json"

工具指令碼

所有程式化的提取、分割、禮貌性 HTTP 擷取與連結稽核都位於 scripts/ref_researcher.py 中。每個指令都需明確的限制與 --output <file.json>（僅將簡潔狀態輸出至 stdout）。

1. `fetch-page` — 禮貌性公開 URL 與資源擷取器

從公開 URL 下載靜態 HTML 與頂層樣式表/圖片，同時偵測登入牆、機器人驗證挑戰與客戶端 JavaScript 外殼 (needs_browser_capture: true)。

uv run ~/.gemini/config/skills/ref-researcher/scripts/ref_researcher.py fetch-page \
  --url "https://example.com" \
  --asset-dir "./refs/example" \
  --max-assets 20 \
  --output "/tmp/fetch_example.json"

2. `extract-html` — 程式碼、文案、字體與標記提取器

解析已儲存的 .html 與 .css 檔案（上限為 --limit 個），輸出標題、導航連結、H1–H3 階層、行動呼籲按鈕 (CTA)、內文文案範例、十六進位顏色值、font-family 宣告與動畫庫提示 (@keyframes、framer、gsap、lottie)。

uv run ~/.gemini/config/skills/ref-researcher/scripts/ref_researcher.py extract-html \
  --input-dir "./refs" \
  --limit 25 \
  --output "/tmp/html_summary.json"

3. `slice-media` — 高螢幕截圖與影片關鍵影格分割器

讀取真實圖片像素尺寸（處理格式錯誤的副檔名，例如儲存為 .webp 的 JPEG），將超高的全頁螢幕截圖分割為清晰的 1024px 寬視口切片，並透過 ffmpeg 從 MP4/MOV/WebM 影片中提取均勻間隔的關鍵影格。

uv run ~/.gemini/config/skills/ref-researcher/scripts/ref_researcher.py slice-media \
  --input-dir "./refs" \
  --scratch-dir "<scratch_dir>/slices" \
  --slice-height 1400 \
  --out-width 1024 \
  --max-slices 12 \
  --frames-per-video 3 \
  --output "/tmp/slice_manifest.json"

工作區衛生： 始終將 --scratch-dir 指向你的對話暫存目錄（或 /tmp/），絕不要指向使用者的儲存庫工作區。

4. `verify-links` — 操作手冊資源連結稽核器

驗證已產生 .md 檔案內的每個相對 Markdown 連結是否存在於磁碟上，若任何路徑損壞則以結束碼 1 退出。

uv run ~/.gemini/config/skills/ref-researcher/scripts/ref_researcher.py verify-links \
  --markdown "./Docs/References & Inspo/PLAYBOOK.md" \
  --markdown "./Docs/References & Inspo/README.md" \
  --output "/tmp/verify_links.json"

工作流程

1. 先稽核目標產品與限制

在開啟任何靈感連結之前，先閱讀目標專案的權威文件（PRD、品牌顏色/標記、設計系統、平台限制）。記錄：

目標表面： 行動應用程式功能、網頁應用程式流程或行銷網站。
視覺標記與對比陷阱： 精確的十六進位值與 WCAG AA 最低要求（例如低對比度的深色模式強調色）。
產品事實矩陣： 區分今日發佈 vs 路線圖 / 禁止宣稱。

2. 收集參考資料（即時擷取、瀏覽器捕捉或現有資料夾）

現有本地參考資料： 立即對提供的目錄執行 extract-html 與 slice-media。
公開 URL / 從頭研究：
1. 首先執行 fetch-page 以快速、有限速地擷取靜態 HTML + 資源。
2. 當 needs_browser_capture 為 true（React/Next/Vite CSR 外殼）或需要全頁視覺螢幕截圖時，使用 chrome-devtools 技能（或瀏覽器工作流程）來渲染並擷取全頁圖片/DOM。
3. 驗證 / 封鎖網站協定（嚴格）： 如果網站回傳 HTTP 401/403、重新導向至 /login 或顯示付費牆/機器人牆：
  - 要求使用者先登入，然後最多重試 2 次。
  - 如果 2 次重試後仍無法存取，清楚地記錄被封鎖的來源並自動轉向可存取的公開網站/頁面或同類替代方案，以免進度停滯。

3. 視覺化與程式化檢查（切勿盲目檢查高擷取內容）

全頁擷取（3840w × 15000px+）如果整體檢視，會縮小為難以辨識的縮圖。始終檢查由 slice-media 在所有收集的參考資料上生成的連續視口切片，以及來自 extract-html 的提取文案/CSS 標記。
將視覺研究與平台指南配對：
- 針對 iOS/iPadOS 導航、表單、SF Symbols 與觸控/動態字型人體工學，調用 apple-hig-designer 的提示。
- 針對網頁字體對比度、有意的空白與避免 AI 模板預設值，調用 frontend-design 的提示。

4. 整合 `.md` 操作手冊

遵循 references/playbook_template.md 在目標專案的參考資料資料夾內撰寫交付的操作手冊。將藍圖調整為目標表面，同時始終包含：

產品事實與限制矩陣（包括淺色/深色模式對比陷阱）
執行創意與 UX 方向
架構 / 螢幕流程藍圖
狀態與邊界案例清單（空狀態、載入/串流、部分/達到上限、錯誤/權限）
平台與響應式轉換矩陣
字體、表面、動畫與文案規則
嚴格的該做與不該做，引用批次中的具體正面與負面範例
索引參考資源查詢表（相對 Markdown 連結）
建置前執行與 QA 檢查清單

更新目錄中的 README.md（若存在），將新的操作手冊置頂顯示。

5. 驗證所有相對連結

對操作手冊（及更新後的 README.md）執行 verify-links。在向使用者報告完成之前，修正任何非零的退出狀態。

速率限制

fetch-page 透過檔案鎖 (/tmp/ref_researcher_fetch.lock) 與單調計時器 (time.monotonic()) 在並發代理程序之間強制執行 1.0 請求/秒 (REQUESTS_PER_SECOND = 1.0)。
HTTP 429 會觸發指數退避（Retry-After 或 2^attempt 次），記錄到 stderr，然後引發 RateLimitError。
HTTP 5xx 會使用指數退避重試；永久性的 HTTP 錯誤包含 URL 與截斷的回應主體，以便快速診斷。

常見錯誤

直接檢查未分割的 15,000px 高螢幕截圖： 導致模糊的猜測與遺漏微互動。始終先使用 slice-media 進行分割。
永遠繞過被封鎖的登入或在一個付費牆上停滯不前： 要求使用者登入一次，最多重試 2 次，然後乾淨地轉向可存取的來源並記錄缺口。
相信競爭對手的行銷宣稱而不是你自己的程式碼庫/PRD： 盲目複製對手的「雲端同步」或「Mac 應用程式」主視覺會產生虛假的行銷宣稱。始終透過產品事實矩陣來審查每個模式。
留下損壞的相對連結或將暫存影像傾倒在專案儲存庫內： 始終將切片寫入暫存目錄，並在結束前執行 verify-links。

參考資料研究員 (ref-researcher)