| name | ui-diff |
| description | 对比 UI 设计稿和 App 截图，检查元素间距、位置、对齐、颜色、字号等差异。
TRIGGER when: 用户提供设计稿和截图要求对比；用户说 UI 走查、UI 对比、检查还原度、看看差异；用户贴两张 App 界面图片说「对比一下」「看看有什么不同」「帮我检查 UI」；提到设计稿 vs 截图/实现；用户给出图片目录要求批量对比。
SKIP: 代码 review、架构图对比、线框图、非 UI 图片（照片、文档截图等）。
|
UI 对比 Skill
对比 UI 设计稿与 App 实际截图，找出视觉差异。
使用方式
方式一：批量对比（推荐）
/ui-diff <目录路径>
目录结构如下，每个子文件夹是一组对比：
pages/
├── 确认订单/
│ ├── xxx.png ← 不需要特定命名，自动识别哪个是设计稿
│ └── yyy.png
├── 全部功能-热门/
│ ├── aaa.png
│ └── bbb.jpg
执行流程：
- 用 Glob 扫描目录下所有子文件夹
- 每个子文件夹读取图片（支持 png/jpg/jpeg，不区分大小写）
- 预处理：检查图片尺寸，任一边超过 1999 像素时自动缩放（避免 API 图片尺寸限制）：
sips -g pixelHeight -g pixelWidth <图片路径>
sips --resampleHeightWidthMax 1999 <图片路径> --out <同目录/原文件名_resized.扩展名>
后续读取使用缩放后的文件。对比完成后删除 _resized 临时文件。
- 自动识别哪个是设计稿、哪个是实际截图（见下方识别规则）
- 逐组对比，输出结果
如果某个子文件夹不是恰好 2 张图片，跳过并提示。
每组对比完成后，在该子文件夹中生成 diff.md 文件保存对比结果。例如：
pages/
├── 确认订单/
│ ├── 1.png
│ ├── 2.png
│ └── diff.md ← 自动生成的对比报告
├── 全部功能-热门/
│ ├── 1.png
│ ├── 2.png
│ └── diff.md
方式二：直接指定两张图
/ui-diff <设计稿路径> <截图路径>
方式三：对话中直接贴图
用户在对话中粘贴两张图片并说明哪个是设计稿即可，自动识别也会生效。
自动识别规则
按优先级从高到低判断哪张是设计稿、哪张是实际截图：
优先级 1：文件名编号
如果文件名为纯数字（如 1.png、2.png），编号小的是设计稿，编号大的是实际截图。
优先级 2：状态栏时间
- 状态栏时间为 9:41 → 设计稿（Apple 设计模板默认时间，最可靠的视觉信号）
- 状态栏时间为真实时间（非 9:41）→ 实际截图
优先级 3：其他视觉特征
- **设计稿特征：**信号/WiFi/电量为标准满格样式，无运营商名称，画面干净
- **实际截图特征：**有 debug 悬浮按钮、真实运营商/VPN 图标、测试标注（红框等）
无法自动识别时
如果以上规则都无法判断（如都没有状态栏且文件名无规律），询问用户。
对比维度
按以下维度逐项检查，只报告有差异的项，没问题的不要列出来：
1. 布局与间距
- 元素之间的间距是否一致（上下左右）
- 内边距（padding）和外边距（margin）
- 整体布局结构是否匹配
2. 对齐
- 水平对齐：左对齐、居中、右对齐
- 垂直对齐：顶部、居中、底部
- 多个元素之间的对齐关系
3. 尺寸
- 元素宽高是否匹配
- 图片/图标尺寸
- 按钮、输入框等控件尺寸
4. 文字
- 字号大小
- 字重（粗细）
- 行高 / 行间距
- 文字颜色
- 文字内容是否一致
5. 颜色与样式
- 背景色
- 边框颜色和粗细
- 圆角大小
- 阴影效果
- 透明度
6. 其他
- 缺失的元素（设计稿有但截图没有）
- 多余的元素（截图有但设计稿没有）
输出格式
写作要求（严格遵守）
每个字段严格控制在一句话内（不超过 30 字），超过就是写多了。
规则：
- 只陈述事实，不解释、不分析、不给理由
- 「建议修改」只说动作（改什么），不说条件（若需…则…）
- 不要用括号补充说明，如「（表示可切换）」「（收起状态）」
- 问题简述不超过 15 字
禁止的表述：
- 「若需还原设计稿」「确认产品期望」「确认产品状态」
- 「建议确认」「需确认」「需同步更新」
- 「避免…」「保持…」「确保…」
- 「强调…」「体现…」「表示…」
正确示例：
#### 1. 底部按钮文案和样式不同 `确定`
- **位置：**底部固定按钮
- **设计稿：**黄色按钮，「应付总额 ¥500 立即支付」
- **实际截图：**蓝色按钮「提交订单」，无金额
- **建议修改：**按钮改黄色，补上金额，文案改「立即支付」
#### 2. 标题与副标题间距偏大 `高度疑似`
- **位置：**页面标题下方
- **设计稿：**标题与副标题间距约 4pt
- **实际截图：**间距约 8pt，参照导航栏高度估算
- **建议修改：**标题下间距减半
置信度标签（放在标题末尾）：
确定 — 肉眼可见的明显差异高度疑似 — 非常可能有差异，需开发核实具体数值待确认 — 看不清或不确定，需要检查代码
错误示例（太啰嗦）：
#### 1. 底部主操作按钮文案与样式
- **位置：**屏幕底部固定操作区
- **设计稿：**黄色背景横条，左侧展示「应付总额 ¥500」，右侧为「立即支付」文案，强调价格与支付动作。
- **实际截图：**蓝紫色圆角按钮，文案为「提交订单」，无金额展示。
- **建议修改：**若需还原设计稿，应在底部操作区体现总价信息，并将按钮文案改为「立即支付」，背景色调整为黄色。
批量对比时
对每一组输出（注意：文件开头不要写 ---，--- 只用于组与组之间的分隔；每个分类的序号独立，从 1 开始）：
# {文件夹名}
<table>
<tr>
<th>设计稿</th>
<th>实际截图</th>
</tr>
<tr>
<td><img src="{设计稿文件名}" width="375"></td>
<td><img src="{截图文件名}" width="375"></td>
</tr>
</table>
## 差异汇总
共计 {N} 条差异项，其中功能差异 {X} 条，UI 细节差异 {Y} 条。
## 功能差异
涉及交互行为、业务流程、功能缺失等，需要和产品确认。
### 1. {问题简述（不超过 15 字）} `确定`
- **位置：**{2-5 字}
- **设计稿：**{一句话，不超过 30 字}
- **实际截图：**{一句话，不超过 30 字}
- **建议修改：**{一句话，不超过 30 字}
## UI 细节差异
间距、颜色、字号、对齐等纯视觉还原问题，开发可直接修复。
### 1. {问题简述} `高度疑似`
...
## 其他
不确定归类的差异，或需要进一步确认的问题。如果没有则省略此分类。
---
# {下一个文件夹名}
...
单组对比时
# UI 对比结果
<table>
<tr>
<th>设计稿</th>
<th>实际截图</th>
</tr>
<tr>
<td><img src="{设计稿文件名}" width="375"></td>
<td><img src="{截图文件名}" width="375"></td>
</tr>
</table>
## 差异汇总
共计 {N} 条差异项，其中功能差异 {X} 条，UI 细节差异 {Y} 条。
## 功能差异
### 1. {问题简述}
- **位置：**{简短描述}
- **设计稿：**{一句话}
- **实际截图：**{一句话}
- **建议修改：**{一句话}
## UI 细节差异
### 1. {问题简述}
...
## 其他（没有则省略）
忽略项（不要报告为差异）
系统 UI
Debug 工具悬浮按钮
截图中可能出现开发阶段的 debug 悬浮按钮，通常位于屏幕边缘（右下角居多），有三种：
- H5 调试工具：橙色/灰色齿轮图标悬浮球，可能带有「H5离线」等文字
- Flutter 调试工具：带有「SIT」「Flutter」等文字的齿轮图标，橙色调
- iOS 原生调试工具：蓝色甲壳虫（bug）图标，带下载/上传箭头，这是 iOS 端的 debug 入口
以上可能单独出现，也可能多个叠在一起（如 Flutter 齿轮 + H5 齿轮 + iOS 甲壳虫同时出现）。这些是开发调试工具，不属于正式 UI，对比时直接忽略，不要报告为差异。
截图标注
截图上可能有测试人员用工具画的红框、红色数字编号、箭头等标注，这些不是 UI 元素，忽略即可。
业务数据差异
设计稿和截图的业务数据（公司名称、金额、条数、邮箱等）通常不同，这是正常的测试数据差异，不是 UI 问题，不要报告。只有当数据差异导致布局明显变形时才提及。
注意事项
- 基于视觉判断，间距/尺寸的数值是估算，标注为「约 Xpx」
- 如果设计稿和截图的分辨率/比例不同，先说明这一点
- 优先报告影响视觉效果明显的差异，细微的放后面
- 不要编造差异，看不清的标注「无法确认」
