前言¶
在 DeepSeek Harness（DSH）里做界面或截图相关能力时，常见插件会走「看懂内容」：识图、OCR、元素定位、多模态问答。视觉回归里更基础的一步往往是另一件事：两张图在像素层面是否一致、差在哪里，而且结论要能被脚本断言，而不是靠人再扫一眼。
dsh-vision-diff 面向这一步：两张本地 PNG 进去，一行机器可读的 PIXEL_CHANGED=true|false 出来，附带差异区域和自包含 HTML 对照页。全程本地、零外部依赖、不调用模型、不联网。
这是什么¶
- 仓库： dingchenhui0618-arch/dsh-vision-diff
- 维护者： dingchenhui0618-arch
- 社区分类：工作流（SkillHub 目录页：dsh-vision-diff）
- 定位：Pixel-level screenshot diff for DeepSeek Harness — 两张本地 PNG 入；
PIXEL_CHANGED结论、差异区域、自包含 HTML 对照页出。
它不做内容识别（不判断「这个按钮是什么」），只回答「有没有变、变在哪」，用确定性像素比较完成。
核心功能¶
机器可读结论¶
输出以一行字符串为断言入口，例如：
PIXEL_CHANGED=false
一致为 false，不一致为 true，便于在流水线里 grep 或解析 JSON 中的 verdict / pixelChanged。
Agent 工具与界面¶
安装并重启宿主后，对话视图会出现「视觉差异」Tab，Agent 可使用 vision_diff 工具。
参数与忽略区¶
| 参数 | 必填 | 说明 |
|---|---|---|
before |
✅ | 第一张 PNG（绝对路径或相对 cwd） |
after |
✅ | 第二张 PNG |
ignore |
忽略区域（时钟、光标、广告等） | |
threshold |
通道差须大于该值才算变化，默认 0；有压缩噪声时可用 2~8 |
|
blockSize |
差异像素连通性分块粒度，默认 16，只影响区域聚类，不改变区域边界 |
|
regionLimit |
最多返回差异区域数，默认 20，按差异像素数从大到小 |
|
cwd |
解析相对路径的目录 | |
label |
本次比对说明，写入报告与对照页 |
忽略区支持多种 JSON 写法（矩形坐标、regions 数组、unit: "fraction" 按比例跨分辨率等）。解析失败的忽略区不会静默丢弃，会进入 ignoreRejected 并在结论、对照页与 Tab 中标出。
输出与产物¶
结构化结果包含尺寸、比对/忽略像素数、diffPixels、diffPercent（保留 6 位小数）、regions、阈值与忽略配置等。每次运行在 $DSH_HOME/vision-diff/runs/<id>/ 留下 index.html（自包含对照页）、report.json、diff.png（红=变化、蓝=已忽略）及可选输入副本。
尺寸不一致时，以 before 的完整面积 为比对范围，无对应像素计为已变化，并设置 dimensionChanged。
PNG 支持范围¶
支持非交错 PNG，颜色类型 0/2/3/4/6，位深 8 或 16（16 位取高字节）。Adam7 交错、低位深打包格式、非 PNG、CRC 失败等会明确报错，不做近似解码。
隐私与依赖¶
全部本地执行；host 半区仅使用 node: 内置模块与同目录模块，PNG 编解码为自实现（src/png.js），以满足零依赖。
安装与启用¶
插件以 DSH 进程权限运行，安装前请自行查看仓库源码与 MIT 许可证。package.json 声明引擎：dsh >=0.2.1-rc.2 <0.3.0。
下面命令来自仓库 README，请用插件目录替换 <插件目录>（不要凭仓库名拼接未在文档出现的 github:owner/repo 安装串）。
npm 版 CLI 管理的 profile：
dsh plugin --profile <name> add <插件目录>
桌面版（desktop profile 由 Electron 独占，npm 版 CLI 会被拒绝）：
需使用应用自带的 CLI（路径在 app 的 resources/runtime/cli/bin/dsh 下）：
"<app>/resources/runtime/cli/bin/dsh" plugin --profile desktop add <插件目录>
装完后重启一次 app：host 半区改动需重启进程加载；已加载的 ES 模块不会因关开插件而替换。
典型用法¶
让 Agent 调用¶
vision_diff(before: "shots/home-dark.png", after: "shots/home-light.png")
命令行查看产物¶
每次比对在 $DSH_HOME/vision-diff/runs/<id>/ 留证，可直接打开 index.html 查看，无需本地 HTTP 服务。
宿主若注册了 webServer，还可通过 /dsh-vision-diff 前缀访问统计、历史与对照页（注册失败时 vision_diff 工具仍可用）。
配置（插件级默认值）¶
apply(ctx, config) 中各项可覆盖，例如：
| key | 默认 | 说明 |
|---|---|---|
dataDir |
$DSH_HOME/vision-diff |
产物与索引目录 |
baseDir |
process.cwd() |
相对路径基准 |
maxBytes |
64 MB |
单文件上限 |
maxPixels |
4000 万（与宿主图像策略取较小值） |
单图像素上限 |
threshold / blockSize / regionLimit |
0 / 16 / 20 |
可被单次调用覆盖 |
historyKeep |
30 |
保留记录数 |
keepInputs |
true |
是否在产物目录保留输入副本 |
适用场景与注意¶
适合：UI 视觉回归、同一页面两次渲染对比、需要在 Agent 工作流里用 PIXEL_CHANGED 做断言、需要本地归档对照页与差异图的场景。
注意：
- 与侧重「这屏是什么」的识图类能力（如社区中的
dsh-client-vision类插件）互补，不替代 OCR 或多模态理解。 - 插件在 harness 内运行，读文件优先走
ctx.fs；有像素上限与单文件大小限制，超限在解码前拒绝。 - SkillHub 等为社区目录，与 DeepSeek / 幻方无官方从属关系；安装插件属于扩展宿主能力，请自行评估信任边界。
结尾¶
dsh-vision-diff 把「两张截图是否像素级一致」做成可脚本化的本地工具：一行 PIXEL_CHANGED、结构化 JSON、可双击打开的对照页，适合挂在 DSH 工作流里做确定性视觉检查。
- 目录页：https://www.skillhub.cn/plugins/dingchenhui0618-arch/dsh-vision-diff
- GitHub：https://github.com/dingchenhui0618-arch/dsh-vision-diff
