slimabbadi/ui-diff

ui-diff 是做什麼的？

先擷取頁面修改前的狀態，修改後再擷取一次，然後閱讀發生了什麼變更。比對在本地執行：像素會像文字 diff 那樣對齊，每個變更區域都會對應到造成變更的 DOM 元素。模型只有在有可見變更時才會負擔圖片成本。即使如此，圖片也只包含變更的元素，經過裁切，在 Token 預算內（預設 400；兩張全頁截圖通常需要 2,000–5,000 Token）。

scripts/ 位於此檔案旁。以下，$UI_DIFF 代表 node <此技能目錄>/scripts/ui-diff.mjs。

設定（每台機器一次）

1. 將 agent-browser 加入 PATH（npm i -g agent-browser，然後執行 agent-browser install 安裝 Chromium；在 Linux 上執行 agent-browser install --with-deps）。
2. 安裝影像函式庫：在 <此技能目錄>/scripts 內執行 npm install。
3. （可選）驗證機器已準備就緒：node <此技能目錄>/scripts/selftest/selftest.mjs。當所有情境都通過時，會以狀態碼 0 退出。

步驟

1. 第一次編輯前的基準線： $UI_DIFF baseline <url> --name <slug>。每個頁面或狀態使用一個 slug，例如 home 或 checkout-mobile。基準線會載入頁面兩次，以了解哪些部分會自行閃爍。
2. 進行修改。
3. 檢查： $UI_DIFF check <url> --name <slug>。退出碼 0 表示沒有視覺變更，1 表示發現變更，2 表示發生錯誤。
4. 先閱讀文字報告，再決定是否開啟圖片：
   • 如果每一項列出的 DOM 變更都是你預期的，且報告顯示 0 unexplained：文字就是證據，所以不用開啟圖片。
   • 如果報告列出了未解釋的區域（U1....），或者你需要判斷某個變更的視覺效果：請開啟報告中列出的審查圖片路徑。請在整個工作最後再開啟一次，因為在任務中途讀取圖片，後續的每個回合都會被重新計費。
5. 反覆迭代，針對同一基準線重新執行 check。只有當你接受當前狀態作為新的參考點時，才建立新的基準線。

當報告中列出的變更完全是你預期的，且所有未解釋的區域都已理解或修正時，此步驟即算完成。

閱讀報告

• DOM changes 是原因：元素標籤，接著是 屬性 before -> after（顏色以十六進位顯示）或 文字 "舊" -> "新"。相同的變更會合併顯示（x3）。未觸及變更像素的變更僅被計數。
• layout 列出結果：元素移動了 (dx,dy)、元素尺寸改變，以及內容相同但位移的像素行。這些是尺寸或間距變更時預期的效果，因此不提供圖片。
• pixel regions 將每個變更區域分為四類：
  • by DOM changes 和 by layout only 是已解釋的。
  • volatile 表示頁面在兩次相同的擷取之間也在該處發生了變更。
  • unexplained 表示像素變更了，但 DOM 中沒有任何元素能解釋這個變更，例如 canvas、圖片或偽元素。未解釋的區域一定會出現在圖片中：它們是回歸缺陷可能隱藏的地方。
• SUBTLE 標記一個因太微弱而難以察覺的變更，例如設計 Token 的微調。請相信文字中的十六進位值，而非圖片。
• Spacing changes（margin、padding、gap）只會在與相鄰元素比較的裁切中顯示。文字會提供精確的數值。

干擾與選項

• ⚠ page kept changing between shots 表示即時內容（動畫、輪播、計時器）。使用 --hide "<css 選擇器>" 將其隱藏，或使用 --selector <css> 將檢查範圍限定在你修改的元素上。
• 同意橫幅和聊天小工具應加入 --hide。被隱藏的元素一定會列在報告中。
• 專案預設值可以放在工作目錄的 .ui-diff.json 中，例如 { "hide": "#cookie-banner", "width": 1440 }。命令列旗標會覆蓋這些設定。
• position:fixed 元素會固定在頁面上的位置，因此它們會保留在比對中。
• 擷取結果會儲存在工作目錄的 .ui-diff/ 中。該資料夾會自行在 git 中忽略。
• 不帶任何參數執行 $UI_DIFF 即可顯示所有旗標。