Communitygithub.com

BrainLiuYH/ui-quality-workbench

用於本地 UI 視覺檢查的工作台,可作為 Codex Skill 安裝。

ui-quality-workbench 是什麼?

UI Quality Workbench 是一個專為開發者與 AI 代理設計的本地 UI 視覺比對檢查工具,支援 Codex 平台。此技能的核心功能是將設計稿截圖與實作截圖進行像素級比對,並將視覺差異分組為「候選差異」,供人工確認與匯出。整個比對流程在瀏覽器 Worker 中執行,無需上傳圖片至外部伺服器,保障隱私。它支援三種來源:本機圖片上傳、透過個人存取權杖 (PAT) 匯入 Figma 框架,以及使用無頭瀏覽器擷取指定網頁。比對引擎採保守啟發式演算法,在運算前會先判斷兩張圖片的可比性,降低誤報。所有未經人工審查的結果皆應以「候選項目」或「可能不符」稱呼,而非直接斷定為錯誤,強調人類驗證的重要性。此工作台也提供視覺化比較面板與詳細清單,方便開發者逐項檢查、歸類、設定嚴重性與優先級,最後匯出已確認的差異列表。

相容平台✓Claude Code✓Codex CLI~Cursor
npx skills add BrainLiuYH/ui-quality-workbench

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

UI 品質工作台

使用此技能來執行本機的 UI 走查 模組。它會在瀏覽器 Worker 中比較設計圖與實作截圖,將可見差異分組為審查候選項目,並支援人工確認與匯出。

此分析器是啟發式的。在人員驗證預期的設計、路由、狀態、內容與視口之前,請將其輸出稱為候選項目或可能的不匹配。切勿將未經審查的結果呈現為已確認的缺陷。

啟動工作台

  1. 從選定的 SKILL.md 解析此技能的目錄。不要假定為儲存庫根目錄或硬編碼安裝位置。

  2. 在會話中首次啟動前,驗證 bundle 與本地源橋接器:

    python3 <skill-directory>/scripts/serve_workbench.py --check
    
  3. 將伺服器作為長時間執行的程序啟動:

    python3 <skill-directory>/scripts/serve_workbench.py
    

    啟動器會輸出一行 JSON,包含 event: "ready"、protocol: 2、動態回送 URL 以及處理程序元資料。請精確使用回傳的 URL;其片段包含瀏覽器應用程式使用的每次啟動令牌。

  4. 如果瀏覽器控制可用且使用者希望開啟介面,則導航至該 URL。否則,將 URL 提供給使用者。

  5. 在工作台使用期間保持程序執行。當使用者要求關閉或會話不再需要時,使用 Ctrl+C 停止程序。

如果啟動因 EPERM 或明確的回送 socket 限制而失敗,請請求本地執行權限並重試相同的指令。請勿變更綁定位址、替換為託管副本或將本地圖片上傳至其他地方。

選擇來源

工作台需要一張設計圖和一張實作圖。每次來源變更都會使先前的結果失效;在更換任一來源後重新執行稽核。

  • 本地圖片: 點擊選擇或將一張 PNG、JPEG 或 WebP 圖片拖曳至對應的設計/實作區域。解碼、光柵比較與分組操作均留在本地瀏覽器會話中。
  • Figma 框架: 提供包含一個 node-id 的 Figma design 或 file URL,以及一個個人存取權杖 (PAT),或使用 FIGMA_ACCESS_TOKEN 啟動啟動器。這會透過 Figma 的 API 匯入該框架的 PNG 渲染;它不會瀏覽檔案也不會繼承 Figma 登入狀態。
  • 網頁擷取: 提供 HTTP(S) URL、視口尺寸以及選擇性的渲染等待時間。橋接器會啟動一個暫用的無頭 Chrome/Chromium/Edge 設定檔並擷取該視口。它不會繼承使用者的瀏覽器設定檔、Cookie、擴充功能或已驗證的會話。

在操作或疑難排解 Figma 匯入或網頁擷取之前,請閱讀 references/source-imports.md。

執行與審查稽核

  1. 確認兩個來源盡可能代表相同的路由、UI 狀態、語言地區、內容、視口與滾動位置。
  2. 檢視顯示的正規化預覽。引擎會以較寬的來源作為目標寬度,保持 1× 尺寸,僅將較窄的來源按比例放大至該寬度,然後將兩張圖片左上角對齊。它不會拉伸或裁剪任一來源,比較中會保留剩餘的底部高度差。
  3. 開始稽核。在本地分類之前,Worker 會檢查正規化的光柵是否適合直接比較。低可比性的配對會在不產生候選項目的情況下停止;中等可比性的配對則會繼續但附帶明確警告。這是一個保守的啟發式閘道,不是機率,也不是判斷哪張圖片正確的語義判斷。
  4. 在視覺比較、列表和詳細資訊面板中檢查候選項目。單側透明內容僅作為區域存在/佈局差異報告。對於模糊的媒體或內容變更,使用中性措辭,而不是強制歸類為顏色、文字、圖示或幾何缺陷。檢查是否由抗鋸齒、字型載入、動畫、動態資料、響應式行為或過時的設計導致差異。
  5. 僅確認經過驗證的候選項目。故意忽略真實差異或駁回誤報時,需要提供理由。
  6. 獨立指派嚴重性與優先級,然後匯出已審查的清單。不要僅從像素面積或色彩距離推斷優先級。

在分類、設定優先級、變更審查狀態或決定匯出內容時,請閱讀 references/audit-model.md。在解釋隱私、支援的整合、擷取行為或分析限制之前,請閱讀 references/v0-boundaries.md。

保持說法準確

  • 此比較引擎改編自 SemineChen/yangao 的固定提交 beac836ba3c81b9a1d40bac8fe75af08444ab742,並根據使用者所報告的作者許可。請參閱 THIRD_PARTY_NOTICES.md。
  • Figma 匯入需要 PAT 和對 Figma 的出站存取。它不是 OAuth、帳戶連結、設計 Token 提取或一般的 Figma 檔案解析。
  • 網頁擷取是隔離的當前視口截圖。它不是全頁拼接、互動式瀏覽、登入狀態繼承、DOM 檢查或計算樣式提取。
  • 本地瀏覽器處理並非安全認證。Figma 匯入必定會將 PAT 發送給 Figma 並下載選定的框架;網頁抓取必定會請求提供的 URL。
  • 可比性閘道沒有 OCR、DOM 或產品語義。它可以阻止廣泛不匹配的輸入並對局部變更發出警告,但無法證明兩個畫面代表相同的路由/狀態或識別權威方。
  • UI 走查是已實作的模組。請勿聲稱規劃中的互動體驗、無障礙或協作模組已經執行。

相關技能