前言¶
做界面开发或让智能体操作页面时，经常要回答一个问题：这次改动之后，页面到底变没变？肉眼对比两张截图容易漏掉细节，每次现写 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
