Community影像github.com

before-after

製作一張包含前後對比截圖表格的圖片,展示目前分支相對於基礎分支的每個視覺變更——每個變更的畫面、元件和狀態皆從基礎分支與目前分支的本地建置版本中捕捉,在相同資料、視窗、主題下拍攝,並透過像素檢查確保每對截圖確實不同。當使用者要求前後截圖、前後對比表格、視覺差異比對、截圖比較,或為 Pull Request、審查、設計師提供視覺變更圖片時使用。本技能僅負責捕捉與合成圖片,不會編輯專案程式碼。

before-after 是什麼?

此技能(`before-after`)會自動產生一張 PNG 圖片,以表格形式列出目前分支相對於基礎分支的所有視覺變更。每一列包含變更名稱、簡短說明,以及來自基礎分支與目前分支的截圖。主要用途是幫助開發者、審查者或設計師快速理解程式碼變更對使用者介面產生的視覺影響,特別適合在 Pull Request 審查時使用。 此技能支援的平台包括任何可使用 Playwright 進行自動化瀏覽器操作的環境(例如 macOS 終端機),並透過本機建置伺服器(生產環境建置或開發伺服器)來進行截圖。其運作流程如下:先找出所有視覺變更(包含受影響的頁面、元件、資料狀態與互動狀態),接著建立基礎分支的獨立工作目錄並分別啟動兩個版本的本機伺服器,然後使用 Playwright 腳本在相同條件下(相同資料、視窗、主題)擷取每組截圖,最後由合成腳本生成對比表格圖片,並執行像素差異檢查以確保每對截圖確實不同。 技能會將所有產出檔案存放在使用者的 Documents 資料夾內,並支援環境變數 `BEFORE_AFTER_DIR` 自訂輸出根目錄。此外,它提供進階功能如 `--diff`(以洋紅色標示變更像素)與 `--stack`(在畫面過寬時自動堆疊版面),並會自動處理無視覺變更或截圖相同等邊界情況。

相容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/MagnusBrogie/agent-skills/tree/HEAD/before-after

Installed? Explore more 影像 skills: steipete/songsee, affaan-m/frontend-design, mattpocock/improve-codebase-architecture · View all 6 →

在你喜歡的 AI 中提問

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

說明文件

前後對比 (Before and After)

產生一張 PNG 表格:每一列對應一個視覺變更,包含變更名稱、一行備註、基礎分支的截圖與目前分支的截圖。即使未讀過程式碼,閱讀者也能從圖片中看出哪裡不同、差異何在。

圖片的品質完全取決於變更清單的完整性。一份僅呈現五項變更中的三項,或顯示由不同資料(而非程式碼)導致的差異的表格,會誤導閱讀者。主要工作在於找出所有視覺變更,並確保每對截圖的唯一變因就是程式碼本身。

圖片存放位置。 此技能產生的所有檔案皆存放在使用者的 Documents 資料夾中:~/Documents/before-after/<repository>/<branch>/,包含截圖、清單、shots.mjs 副本以及最終的 before-after.png。腳本會自行選擇此資料夾,不接收輸出路徑參數;若使用者想變更根目錄為 ~/Documents/before-after 以外的地方,可設定環境變數 BEFORE_AFTER_DIR(此為使用者自行設定的變數,並非由你設定)。請勿將圖片寫入其他位置,之後也無需移動或複製;暫存區僅供基礎分支工作目錄與 shots.mjs 草稿使用。後續對同一分支再次執行時,會重複使用該資料夾。

此檔案旁 scripts/ 目錄下有兩個腳本:capture.mjs 負責拍攝截圖,compose.mjs 負責建構與檢查表格。每個腳本的標頭區塊皆說明其輸入格式。開始前請先閱讀兩個腳本的標頭。

本地註記。 如果此檔案旁存在名為 LOCAL.md 的檔案,請在開始前閱讀它。該檔案記錄使用者針對其專案的自訂預設值(指令、主機、帳號、路徑),不屬於已發布的技能內容。若其內容涵蓋當前專案,則視為專案指示的一部分;若未涵蓋,則忽略它。

1. 收集變更

若未指定基礎分支,則使用 Pull Request 的基礎分支(gh pr view --json baseRefName --jq .baseRefName),否則使用預設分支(git symbolic-ref --short refs/remotes/origin/HEAD),再否則使用 origin/main。優先使用遠端追蹤參考。包含未提交的工作:

base=$(git merge-base <base> HEAD)
git diff --stat "$base"; git diff "$base"; git status --short   # 也讀取未追蹤檔案
git log --oneline "$base"..HEAD

同時閱讀 Pull Request 描述以及對應的 Issue(如果有的話)。它們通常會指出變更目標是哪些畫面,並包含使用者預期會看到的截圖。

2. 列出所有視覺變更

將每個 diff 片段向外追蹤至使用者所見:

  • 檢視程式碼、樣式、設計代碼、圖示、文案、翻譯。 每一項都是候選對象。針對共用程式碼(UI 元件、格式化輔助程式、CSS token),搜尋其呼叫者,並列出所有會渲染該程式碼的畫面。共用程式碼的變更通常會影響比原本預期更多的畫面。
  • 資料狀態。 針對每個畫面,讀取變更的程式碼所涵蓋的分支:載入中、載入完成、空資料、錯誤、缺少值、零與負數、長文字、單一項目與多項目、每種模式或設定。僅保留 diff 會改變其渲染方式的狀態。
  • 互動狀態。 懸停、聚焦、按下、停用、選取;開啟的彈出視窗、選單、側邊欄或對話框;顯示驗證錯誤的欄位。這些需要在拍攝前執行步驟(步驟 4)。
  • 目前分支新增或移除的畫面。 這類畫面只有一邊有內容;表格中將以佔位符表示另一邊。
  • 專案支援的環境,其中變更可能看起來不同:深色主題、行動版與桌面版寬度、其他語系。

將候選對象分為三個清單:

  1. 視覺類: 畫面上的某處不同。這些會成為表格的列。
  2. 非視覺類: 變更僅影響無障礙樹、屬性、螢幕閱讀器專用文字、行為或程式碼結構。這些不會成為表格列。在報告中列出它們的名稱,讓閱讀者知道已經考慮過且未被遺漏。如果使用者無論如何都想顯示它們,則可以將可存取性樹的摘錄(以圖像方式捕捉)作為一列,並標明為此類。
  3. 不確定類: 標記或類別變更,本意是不可見的,但可能移動或重新著色某個元素(新的包裝元素、定位類別、交換的輔助程式)。請拍攝這類變更,讓像素檢查來決定結果。

對於動畫、過渡效果或其時間設定的變更,無法在靜態圖片中顯示。將其置於報告中的「未顯示」區塊,並說明如何查看。

合理分組列:每個不同的外觀對應一列,而非每個呼叫位置。如果十個畫面以相同方式使用變更的儲存格,則僅顯示其中一到兩個,並在備註中列出其餘名稱。目標是製作讓人願意閱讀的表格;大約超過十二列時,請依區域製作第二張圖片並加以說明。

如果視覺類與不確定類清單皆為空,請在此停止。 通知使用者該分支沒有視覺變更,列出已考慮的事項以及每個項目為何不屬於視覺類,且不產出圖片。如果僅有不確定類項目,且每對截圖結果完全相同,則結果相同,而這些相同的截圖對即為證據:報告為已檢查且未變更。

3. 在本機建置基礎分支與目前分支

從本地建置(而非部署環境)捕捉兩側的畫面:部署環境落後於工作目錄,且無法顯示未提交的工作。

  • 目前分支: 目前的工作目錄,在最後一次變更後建置。

  • 基礎分支: 在合併基礎點建立一個獨立的工作目錄,永遠不觸碰使用者原本的工作目錄。絕對不要在使用者的 checkout 中切換分支或進行 stash。

    git worktree add --detach <scratchpad>/before-after-base "$base"
    

    在那裡安裝相依套件。僅在 diff 未觸及 lockfile 時,可以將主要 checkout 的相依目錄建立符號連結。完成後移除該工作目錄(git worktree remove)。

使用專案文件中的指令(閱讀其 README、AGENTS.md、CLAUDE.md、開發文件以及任何 run 技能)。兩側都必須連線到相同的測試或測試後端,絕對不能是正式環境。如果不清楚哪個指令對應哪個後端,請閱讀建置配置;若仍有疑問,請停止並提問。在開始捕捉之前,檢查兩側實際 API 請求的主機。

優先使用專案的正式建置(build 後接 preview 或任何靜態伺服器),而非開發伺服器。開發伺服器會加入熱重載客戶端與覆蓋層,可能需要為每個工作目錄執行監控程序,且可能與最終發布版本顯示不同。如果你使用的建置工具並非專案本身的建置指令,請確認頁面能正常渲染:有些專案會對其 bundle 進行後處理。建置也可能清空或覆寫使用者工作目錄中的輸出目錄。這些都是產生出的檔案,但請在報告中說明你重建了什麼,並將開發環境所需的內容復原(如果建置移除了它們)。

在信任任何截圖之前,請確認兩個建置版本確實不同:讀取兩側變更元素的標記,確認 diff 中的變更確實存在。兩個提供相同程式碼的伺服器會產生完全相同的截圖對,這無法證明任何事情。

選擇如何提供兩個建置版本的內容:

  • 同時執行,使用兩個閒置埠。 這是最簡單的方式,且每對截圖的拍攝時間僅相隔數秒。此方法適用於畫面無需登入,或登入狀態在埠號變更後仍可保留的情況。Cookie 在同一個主機的不同埠之間可共用,但本地儲存不行,且後端可能僅接受特定來源。在依賴此方法之前,請確認登入後的畫面在第二個埠上確實能載入。
  • 依序執行,使用同一個埠。 先在專案常用的埠上提供基礎分支內容,使用 --side=before 拍攝,停止該伺服器,再於同一埠上提供目前分支內容,使用 --side=after 拍攝。這樣做可以讓儲存的登入狀態與允許的來源同時適用於兩側。但由於拍攝時間相隔數分鐘,因此資料必須是模擬的或是已知穩定的。

如果專案有元件目錄(如 Storybook、「workshop」應用程式等),且變更位於共用元件中,在元件目錄中拍攝會比在完整應用程式中更省資源且更穩定,通常也無需登入。不過,仍然至少要為每個變更捕捉一個真實畫面的截圖,以便圖片能顯示其上下文。如果無法存取真實畫面(例如沒有測試用登入帳號),請在「未顯示」區塊中說明原因。

4. 在相同條件下捕捉每組截圖

在暫存區中撰寫 shots.mjs,格式須符合 scripts/capture.mjs 標頭中的規定,並從專案根目錄執行,以便 Playwright 能解析且輸出資料夾能取得正確的儲存庫與分支名稱:

node <this skill>/scripts/capture.mjs <scratchpad>/shots.mjs --before=http://localhost:<p1> --after=http://localhost:<p2>

此腳本會對兩個 URL 執行相同的步驟。它使用已安裝的 Chrome 瀏覽器,裝置像素比例設為 2,並啟用減少動畫效果。它會關閉過渡效果、將無限循環動畫(如 shimmer、spinner)重設為第一影格並完成有限動畫、等待字型與網路穩定,並在指定時間時凍結時鐘。它會將截圖寫入 shots/<slug>.before.png、shots/<slug>.after.png 以及步驟 5 所需的 manifest.json 至前述的 Documents 資料夾,並將 shots.mjs 複製到該資料夾,最後輸出該資料夾的路徑作為最後一行。--only=<slug> 可用於重新捕捉單一列。失敗的截圖會留下 <slug>.<side>.FAILED.png(整個視窗的截圖),顯示當時頁面的狀況。

如果專案的端對端設定中有儲存的登入狀態,請以 storageState 參數傳入(請閱讀專案文件了解如何產生)。在 Orca 中,嵌入式瀏覽器(orca-cli 技能)也可用於一兩組截圖,但使用腳本能讓截圖對具有可重複性。

你必須在 shots.mjs 中正確處理的事項:

  • 兩側使用相同資料。 即時資料在兩次截圖之間會變動:價格會跳動、清單會重新排序。建議在該列截圖的 mock 中模擬畫面所需的回應:從測試環境捕捉一個真實回應內容,並將其用於兩側的 fulfill。但有以下兩個限制:
    • 如果目前分支變更了請求或回應的格式(新的端點、新的欄位、改變的解碼器),則一個回應內容無法同時服務兩側。請為每一側提供其程式碼所預期的回應內容,但使用相同的底層基礎值來建構,並在副標題中說明。
    • 透過 WebSocket 或伺服器傳送事件送達的資料不受 page.route 影響。請使用 page.routeWebSocket,或選擇串流較為安靜的畫面或時間點,或者如果即時元素並非主題,則將其隱藏。
  • 有意識地觸發狀態。 載入中、錯誤、缺少值等狀態在測試帳號中很少出現:請在 mock 中製造這些狀態(延遲回應、使回應失敗、將某個欄位設為 null)。請根據程式碼推導請求路徑與欄位名稱,而非猜測。透過 steps 觸發互動狀態(懸停、聚焦、點擊以開啟)。
  • 裁切至變更區域並保留上下文。 將 target 設為能顯示變更且仍可辨識為其所屬畫面一部分的最小元素:卡片、表格、側邊欄,而非整個頁面。目標是裁切至最寬約 650 CSS px:這是並排顯示時能完整呈現的寬度。更寬的畫面會改為上下堆疊(before 在上、after 在下),而寬度超過約 1300 CSS px 時則會縮小,導致文字難以閱讀。兩側使用相同的目標,以確保裁切位置一致。
  • 隱藏非主題且持續移動的元素(如報價機、時鐘、延遲載入的頭像),在兩側的 steps 中透過 style 標籤處理。

5. 合成與檢查

node <this skill>/scripts/compose.mjs <folder>/manifest.json [--diff] [--stack]

圖片會產生在清單旁,名為 before-after.png,其路徑為輸出的最後一行。--diff 會為每一列新增一張以洋紅色標示變更像素的圖片。當變更較小或不明顯(間距、顏色、單一字形)時使用此選項;若變更明顯則可省略。當一列的兩張截圖尺寸不同時,比較會以左上角為基準對齊,因此位移之後的內容都會被視為變更;該列會顯示此資訊,而差異圖片僅作為粗略參考。

腳本會以相同比例繪製每列的兩張截圖。它會輸出每列的變更像素比例以及每列的版面配置方式,若任何一對截圖完全相同則以 exit code 3 結束。接著:

  1. 完全相同的一對截圖 表示拍攝遺漏了變更(狀態錯誤、畫面錯誤、快取問題、基礎分支建置並非真正的基礎分支),或該變更並非視覺性的。請找出原因。修復拍攝內容,或將該列從清單中移除,並將該項目移至非視覺清單,標注為「已檢查,無像素差異」。絕對不要將完全相同的一對截圖作為表格中的一列。
  2. 檢視圖片(讀取 PNG)並檢查每一列:你所見的差異應與備註描述的一致,且不應有其他差異。任何無法由 diff 解釋的差異(不同的價格、缺少的列、版面其他位置的偏移)都代表資料偏移或非預期的回歸。請重新拍攝,或向使用者報告為可能的回歸問題。切勿隱瞞。
  3. 確認每張截圖中的文字都可讀。 若腳本發出「文字可能無法閱讀」的警告,請採取行動:將裁切範圍縮小,並使用 --only 參數重新拍攝該列。
  4. 如果圖片過長,請依區域分割:在分支資料夾內為每個區域建立子資料夾,每個子資料夾擁有自己的 manifest.json,其路徑指向 ../shots/...,並分別進行合成。

6. 報告

向使用者提供:

  • PNG 檔案的完整絕對路徑。
  • 各列內容,每列一行。
  • 未顯示: 非視覺變更、像素檢查後未發現變化的不確定項目、動畫變更、你無法捕捉的視覺變更(並說明原因),以及因與顯示的列重複而被省略的呼叫位置。
  • 像素檢查或你自行檢視時發現的任何非預期狀況。
  • 截圖對的產製方式(使用真實測試環境資料,或哪些回應被模擬;使用元件目錄還是真實應用程式),以便閱讀者了解圖片的證明力。

停止你啟動的開發伺服器,並移除基礎分支的工作目錄。截圖、shots.mjs 副本以及清單會保留在輸出資料夾中,以便後續執行時可使用 --only 重新拍攝單一列。

Individual skills in this repo

This repo contains 1 individual skill — each has its own dedicated page.

相關技能