前言¶
做界面開發或讓智能體操作頁面時，經常要回答一個問題：這次改動之後，頁面到底變沒變？肉眼對比兩張截圖容易漏掉細節，每次現寫 pixelmatch 腳本又太重複。
dsh-screenshot-diff 是 DeepSeek Harness（DSH）生態裏的一個工作流類插件。DSH 的理念是「一切皆插件」，這類重複性的驗證動作正適合沉澱成插件：一條命令，輸入兩張已有的截圖，輸出標紅差異的 diff 圖、一張帶標籤的三聯對比圖和一段可被腳本消費的 JSON。它不負責截圖採集，輸入必須是你已經截好的兩張圖。
這是什麼¶
dsh-screenshot-diff 由 PangYiMing 維護，當前版本 0.1.1，許可證爲 MIT。一句話定位：基於 pixelmatch 對兩張已有截圖做像素 diff，產出兩個文件：
<out>/diff.png 差異標紅（[255,0,0]）
<out>/compare-triple.png 三聯圖：左 A | 中 B | 右 diff <相似度>，各自左上角帶標籤
同時通過 stdout 輸出一段 JSON，字段爲 similarity、numDiffPixels、total、sensitivity、threshold，方便在腳本里繼續判斷。
核心功能¶
1、三檔靈敏度：
normal：灰度 + 閾值 0.1 + 忽略抗鋸齒，結果穩；high：彩色 + 閾值 0.02 + 計入抗鋸齒；ultra：閾值 0.01，最靈敏，噪點也最多。
2、細節控制：--threshold N 可顯式覆蓋 pixelmatch 閾值，壓過靈敏度預設；--crop-top PX 把兩張圖同時裁掉頂部若干物理像素，適合過濾固定頁頭。
3、依賴自動發現，順序爲：--compare-tool 參數 > COMPARE_TOOL_ENV 環境變量 > 倉庫內 scripts/compare-tool。底層依賴是 sharp / pngjs / pixelmatch。
4、尺寸不一致時直接失敗，不做拉伸——這是刻意設計，避免佈局差異被縮放掩蓋。
安裝與啓用¶
用下面的命令從 GitHub 安裝：
dsh plugin --profile demo add github:PangYiMing/dsh-screenshot-diff
README 中還列了一條 dsh plugin --profile demo add dsh-screenshot-diff，標註爲「發佈到 npm 後」可用，目前以 GitHub 方式安裝爲準。
安裝前建議先瀏覽倉庫源碼和 LICENSE：插件會以當前 dsh 進程的權限運行，確認代碼行爲和許可證（本插件爲 MIT）符合你的預期再裝。
典型用法¶
先準備好兩張同一視口、同一分辨率下的截圖，然後運行：
bash scripts/diff.sh /abs/path/imgA.png /abs/path/imgB.png \
--label-a before \
--label-b after \
--sensitivity high \
--out /tmp/diff-out
這條命令對 imgA.png 和 imgB.png 做對比，以 high 靈敏度輸出到 /tmp/diff-out。可用參數如下：
| 參數 | 說明 |
|---|---|
--out DIR |
輸出目錄，默認第一張圖所在目錄 |
--label-a/--label-b TEXT |
左右圖標籤，默認 a / b |
--sensitivity LEVEL |
normal / high / ultra |
--threshold N |
顯式指定 pixelmatch 閾值，覆蓋靈敏度預設 |
--crop-top PX |
兩圖同時裁掉頂部 PX 物理像素 |
--compare-tool DIR |
指定 sharp/pngjs/pixelmatch 依賴目錄，或設 COMPARE_TOOL_ENV |
判讀建議¶
README 裏給出幾條使用紀律，值得照做：
- 相似度不等於結論。90% 以上的「大體一致」也要人工看 diff 區是否集中在應改的位置；
- 先用
normal跑一版；需要抓淡灰、白漸變這類低對比差異時再升high；ultra噪點最多，慎用； - 兩張圖必須同一視口/分辨率、同一頁面狀態（滾動位置、彈窗、加載態），否則 diff 結果沒有意義。
適用場景與注意¶
適合前端開發、UI 迴歸檢查，以及讓智能體操作瀏覽器後需要驗證頁面變化的場景。前提是你已有截圖採集手段，這個插件只補上「對比」這一環。
安全方面再強調一次：插件以當前 dsh 進程權限運行，安裝前請自行檢查倉庫源碼與許可證。
結尾¶
dsh-screenshot-diff 把「兩張截圖哪裏不一樣」這件事壓成了一條命令：diff 圖定位差異、三聯圖方便人工複覈、JSON 結果供腳本判斷，配合三檔靈敏度和閾值覆蓋，夠覆蓋大多數日常對比需求。
- 社區目錄頁：https://www.skillhub.cn/plugins/PangYiMing/dsh-screenshot-diff （獨立站點，與 DeepSeek / 幻方無官方從屬關係）
- GitHub 倉庫：https://github.com/PangYiMing/dsh-screenshot-diff
