用途:对两张截图做像素级比对,输出差异可视化图与统计数据,适合比对 Figma 设计稿与网页截图、检测 CSS 变更造成的视觉回归、追踪前后版本 UI 变化。
主要能力:生成差异图(差异区域以半透明红色标记),并在 stdout 输出 JSON 统计,包括 total_pixels、diff_pixels、diff_percentage 与 diff_regions(含 x、y、width、height、label)。
前置条件:安装 Pillow 和 numpy:pip install Pillow numpy
使用方式:脚本位于插件目录,路径必须用 ${CLAUDE_PLUGIN_ROOT},写相对路径会找不到文件: python "${CLAUDE_PLUGIN_ROOT}/scripts/pixel-diff.py" <image_a> <image_b> --output diff.png [--threshold 10] [--pass-below 5] [--block-above 15] [--ignore-region x,y,w,h]
参数:image_a 为参考图(设计稿),image_b 为比对图(网页截图),均必填;--output 为差异图输出路径(默认 diff.png);--threshold 为每像素色差敏感度 0-100(默认 10,越低越严格,指色差多大才算不同,不是整体容许比例);--pass-below 为整体差异低于此百分比判 PASS(默认 5);--block-above 为整体差异高于此百分比判 BLOCK(默认 15),之间为 WARNING;--ignore-region 为忽略区域 x,y,w,h,可重复,用于遮掉时钟、轮播等动态内容;--background 为透明图层合成背景色(默认 white);--highlight-color 为差异标记颜色(默认 red)。
限制与注意:尺寸不同时会等比缩到共同宽度再裁高度,不各轴独立拉伸,长宽比差太多会警告;最好从源头对齐尺寸,Figma 导出的 --scale 与网页截图的 device pixel ratio 要一致;--threshold 默认 10 会滤掉字体反锯齿、浏览器渲染等细微色差,降到 5 更细但假差异增多;透明背景的 Figma 导出会自动合成白底再比对,可用 --background 修改。其他平台支持与收费信息暂未提供。