像素差异从6%到0%:dsh-vision-toolkit UI还原校验与热力图修复工作流

原创2026-10-23 16:12:181,872 阅读
文章标签:dsh-plugin计算机视觉OCRAI 插件GUI 自动化AI 技能大模型

像素差异从6%到0%:dsh-vision-toolkit UI还原校验与热力图修复工作流

UI还原做得像不像,靠肉眼对比往往说不清。dsh-vision-toolkit(DSH Vision Toolkit)为纯文本模型提供了一套可量化的校验工作流:用 vision_pixel_diff 对参考图与还原页面做真实像素级差异分析,输出热力图(heatmap)和结构化 JSON 报告,让 AI 精准定位"哪里不一样",再迭代修复,最终把像素差异从 6.04% 一路降到 0%。

DSH Vision Toolkit 视觉工具箱主视觉,支持图片问答与UI还原校验

为什么肉眼不够:UI还原需要可量化的校验

把一张设计图或截图还原成 HTML 页面,最大的难题不是"写不出来",而是验证不了:

  • 整体感觉"差不多",但间距、颜色、边框细节其实差了很多;
  • 差异藏在页面下半部分或某个卡片里,肉眼很难稳定复现对比;
  • 修了一版之后,无法证明是变好了还是变坏了。

dsh-vision-toolkit 的答案是 vision_pixel_diff 工具:它对两张图片做逐像素比较,把画面切成网格,排序出差异最大的区域,并同时交付 PNG 热力图 + JSON 报告。工具的参数与返回结构定义在 src/tools.ts。

产出 内容 作用
overallDifferencePct 整体差异百分比 量化"像不像"
worstRegions 最差网格区域列表(含坐标 box) 定位"哪里不像"
heatmap 热力图 PNG 红区即重点修复区
report JSON 结构化报告 可存档、可回归、可验收

闭环工作流:从参考页到 0% 差异

仓库内置了一个确定性示例 examples/ui-restoration/(中文说明见 README.zh.md),完整演示了这条闭环。它通过真实运行时执行五步:

  1. 渲染参考页:用 vision_html_screenshot 将 tests/fixtures/ui-restoration-reference.html 在 1200 × 720 视口下渲染为参考图;
  2. 准备初版与终版:initial.html 是故意留错的还原结果,implementation.html 是预期匹配参考页的最终实现;
  3. 像素差异分析:用 vision_pixel_diff 以 8 × 8 网格、取最差 6 个区域,分别对比初版和终版;
  4. 执行数值验收:check 模式核对已提交证据,write 模式只在阈值通过后替换证据;
  5. 一键复现:整个流程无需视觉服务 Key,只依赖 Python(Pillow/NumPy)与 Chrome 系浏览器。

1️⃣ 参考页:校验的"标尺"

参考页是整条工作流的基准。所有对比都始终针对它,而不是某次中间版本的渲染结果。

UI还原校验参考页 reference.png,浏览器渲染的1200×720基准截图

2️⃣ 初版还原:故意留下 6.04% 的差距

初版页面刻意不准确,用来证明比较流程能检测出有意义的偏差:

UI还原初版结果 initial.png,与参考页存在像素差异

3️⃣ 热力图:差异一目了然

初版与参考图对比后,整体差异 6.04%,最差区域差异高达 27.51%(坐标 300,540 → 450,630,集中在画面中下部)。热力图把"该先修哪里"直接画了出来:

UI还原像素差异热力图 initial-heatmap.png,红色区域标记出差异最大的网格

完整的初版对比报告见 initial-report.json,6 个最差区域的百分比和坐标框全部可查。

4️⃣ AI 对话中定位问题:数字 + 语义双保险

在 DSH 对话里,AI 拿到差异报告后会把数字结论翻译成人话:整体像素差异 6.04%,最差区域 25.76%(400,480–600,600),经语义比对确认是三处还原不到位——金卡片边框缺失、背景网格纹理缺失、底部胶囊条高亮色未还原。热力图告诉你"在哪",语义比对告诉你"为什么",然后逐项修复。

AI对话中的像素差异报告 dsh-conversation-pixel-diff.png,显示6.04%整体差异与最差区域定位

5️⃣ 最终实现:0% 差异

修复后的最终实现与参考页完全一致,整体差异 0%,最差区域数从 6 个降到 0 个:

UI还原最终实现 implementation.png,与参考页像素级一致

UI还原最终热力图 final-heatmap.png,全黑表示零像素差异

验收阈值与 check / write 双模式

示例把验收标准固化在 metrics.json 中,避免"两个等价页面也能通过"的假阳性:

{
  "initialDifferencePct": 6.04,
  "finalDifferencePct": 0,
  "initialWorstRegions": 6,
  "finalWorstRegions": 0
}
规则 阈值 目的
初版差异 ≥ 1% 证明对比确实检测到了偏差
终版差异 ≤ 0.02% 证明最终实现达到像素级验收

在 dsh-vision-toolkit/ 目录下运行即可复现(check 模式只做验证,不符合契约时以非零状态退出):

npm run example:ui-restoration

只有当你有意修改参考页、还原页、视口或渲染器契约时,才运行 write 模式刷新证据,并紧接一次 check 模式确认可复现:

npm run example:ui-restoration:write
npm run example:ui-restoration

对应的回归测试是 tests/ui-restoration-example.spec.ts,截图器的 Profile 隔离契约由 tests/html-screenshot-guard.spec.ts 独立覆盖。

方法论:来自 restore-ui 技能的校验原则

这套工作流背后的完整方法论写在随包 Skill 的 assets/skill/references/restore-ui.md 中,几个关键原则值得借鉴:

  • vision_pixel_diff 是定位器,不是验收目标——不要为了压低总百分比而无限迭代;
  • 始终与原始参考对比,永远不要只跟自己的上一版渲染结果比;
  • 修到"用户可见的缺陷"为止——剩下的若只是字体光栅化、抗锯齿、亚像素排布等不可感知差异,就停下;
  • 追求速度时可用 fast restore 模式(约 3 分钟出可辨认截图),此时明确放弃逐像素保真,不做迭代式 vision_pixel_diff。

小结

dsh-vision-toolkit 把"UI还原像不像"从主观判断题变成了可量化、可定位、可验收的工程流程:渲染参考页 → 像素差异分析 → 热力图定位 → 语义修复 → 复验归零。6.04% 到 0% 的闭环不仅是一个示例,更是给 AI Agent 的一套可复现验收标准——差异有数字,位置有坐标,修复有依据。

登录后查看全文
dsh-vision-toolkit