像素差异从6%到0%:dsh-vision-toolkit UI还原校验与热力图修复工作流
像素差异从6%到0%:dsh-vision-toolkit UI还原校验与热力图修复工作流
UI还原做得像不像,靠肉眼对比往往说不清。dsh-vision-toolkit(DSH Vision Toolkit)为纯文本模型提供了一套可量化的校验工作流:用 vision_pixel_diff 对参考图与还原页面做真实像素级差异分析,输出热力图(heatmap)和结构化 JSON 报告,让 AI 精准定位"哪里不一样",再迭代修复,最终把像素差异从 6.04% 一路降到 0%。
为什么肉眼不够: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),完整演示了这条闭环。它通过真实运行时执行五步:
- 渲染参考页:用
vision_html_screenshot将 tests/fixtures/ui-restoration-reference.html 在 1200 × 720 视口下渲染为参考图; - 准备初版与终版:
initial.html是故意留错的还原结果,implementation.html是预期匹配参考页的最终实现; - 像素差异分析:用
vision_pixel_diff以 8 × 8 网格、取最差 6 个区域,分别对比初版和终版; - 执行数值验收:check 模式核对已提交证据,write 模式只在阈值通过后替换证据;
- 一键复现:整个流程无需视觉服务 Key,只依赖 Python(Pillow/NumPy)与 Chrome 系浏览器。
1️⃣ 参考页:校验的"标尺"
参考页是整条工作流的基准。所有对比都始终针对它,而不是某次中间版本的渲染结果。
2️⃣ 初版还原:故意留下 6.04% 的差距
初版页面刻意不准确,用来证明比较流程能检测出有意义的偏差:
3️⃣ 热力图:差异一目了然
初版与参考图对比后,整体差异 6.04%,最差区域差异高达 27.51%(坐标 300,540 → 450,630,集中在画面中下部)。热力图把"该先修哪里"直接画了出来:
完整的初版对比报告见 initial-report.json,6 个最差区域的百分比和坐标框全部可查。
4️⃣ AI 对话中定位问题:数字 + 语义双保险
在 DSH 对话里,AI 拿到差异报告后会把数字结论翻译成人话:整体像素差异 6.04%,最差区域 25.76%(400,480–600,600),经语义比对确认是三处还原不到位——金卡片边框缺失、背景网格纹理缺失、底部胶囊条高亮色未还原。热力图告诉你"在哪",语义比对告诉你"为什么",然后逐项修复。
5️⃣ 最终实现:0% 差异
修复后的最终实现与参考页完全一致,整体差异 0%,最差区域数从 6 个降到 0 个:
验收阈值与 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 的一套可复现验收标准——差异有数字,位置有坐标,修复有依据。





