UI 走查（UI 还原度走查 Skill）

研发把页面做上线后，用这个 skill 把 PM 提供的 UI 设计 HTML 和线上实现，同视口、同状态逐区块比对，产出可直接发研发的 UI 还原度差异清单。

判差异不靠肉眼猜——肉眼能看出"颜色不对"，但说不清"线上 #1677ff vs 设计 #fc7913"。每个可疑处都要在两边各读一次 computed style 实锤具体值，研发才能照着改。

一、输入约定

每次启动走查，PM 给两样：

2.1. 设计 HTML 路径：UI 设计好的那一份单文件 HTML（浏览器可直接打开）。这是唯一参照系——线上对不对，全看跟这份 HTML 一不一致，不引入其他设计规范、不掺个人审美。 2.2. 线上 URL：研发部署好的页面入口。

只给了 PRD / 模块名没给 HTML：在 PRD 同目录的 prototype/ 子目录里找对应 HTML，找到多个按文件名匹配，不确定就问 PM。

特殊情况：

2.3. HTML 和线上 URL 明显不是同一个页面 / 功能：停下来问 PM，不要硬比。 2.4. 一份 HTML 用 page-switch JS 承载多个状态（列表 / 详情 / 弹窗 / 各 tab）：每个状态都是一个独立走查单元，比的时候两边都要切到对应状态。

二、走查前准备

3.1. 摸清设计 HTML 有哪些状态

先打开设计 HTML 看一遍：是单状态，还是用 page-switch JS / 多文件承载列表、详情、弹窗、多个 tab。把所有状态列出来——每个状态是一个走查单元，线上要逐个对上。

3.2. 统一视口宽度

设计 HTML 一般按全视口设计、无 max-width。线上和 HTML 必须用同一视口宽度截图，否则布局错位、留白这些差异全是假的，白费功夫。

默认 1440 宽（常用桌面断点）。如果设计稿明显是按别的断点画的（如内容在 1280 才不挤），跟着改，两边一起改。

3.3. 接管浏览器（默认 MCP，可选高速）

默认路径：chrome-devtools MCP。设计 HTML 用 file:// 绝对路径 navigate，线上用 URL navigate；同一 Chrome 实例切换 tab 即可。MCP 是单 Chrome 天生串行，状态多的情况下逐个跑。

可选高速路径：browser-cap。装了 BROWSER_CAP_DIR 才能用。设计 HTML 和线上页面各开一个 Chrome 实例，互不干扰：

1. bash ${BROWSER_CAP_DIR}/bin/cap-launch-chrome.sh <端口>（端口 9222-9299，已占自动拒绝，换一个）。
2. node ${BROWSER_CAP_DIR}/bin/capture.js <端口> <配方.json> 驱动：导航 / 切状态 / 截图 / 读 computed style。
3. 截图先落临时目录，再 bash ${BROWSER_CAP_DIR}/bin/stash-shots.sh <源> <目标> 入库到 <ACCEPTANCE_DIR>/.../screenshots/。

设计 HTML 用 file:// 绝对路径作 url，capture.js 直接能导航。

怎么选：未装 browser-cap 或 PM 要手过登录 / 验证码 → 走 MCP；装了且状态多（多 tab / 多弹窗 / 列表 + 详情）→ 走 browser-cap 并行模式。

三、走查执行

4.1. 执行模式

1. MCP 模式：单 Chrome 串行，按状态顺序逐个走查。
2. browser-cap 模式：状态多时按状态拆分区并行：一条消息里用 Agent 工具同时起 N 个子代理，每个子代理认领一个状态、起两个端口（一个开设计 HTML、一个开线上）、回传该状态的差异行 + 截图。主代理汇总成一份报告。

4.2. 同视口、同状态，两边分别截全图

1. 设计 HTML：导航 file:// URL → 切到目标状态 → fullPage:true 截全图。
2. 线上：同视口、同状态、fullPage:true 截全图。
3. 线上是真实数据、设计 HTML 是 mock 数据——截图只用来比结构和样式，不比内容文字、不比数据条数。

4.3. 两图并排，先肉眼定位可疑区块

两张图入库后，用 Read 都读进来并排看，找"长得不一样"的地方：区块缺失 / 多余 / 错位、组件形态不同、颜色或字体明显不对。肉眼这一步只负责定位到哪个区块可疑，不负责下结论。

4.4. 可疑处读 computed style 实锤，不靠肉眼猜数值

这是 UI 走查的"真点开"——肉眼说不出具体差多少，研发就没法改。对每个可疑部位，在设计 HTML 的 DOM 和线上的 DOM 上各跑一次 getComputedStyle，拿真实值再比。

probe 模板（MCP 用 evaluate_script、browser-cap 配方用 eval 字段，两边各跑一次；选择器按各自页面的类名改）：

JSON.stringify((()=>{
  const r=el=>{if(!el)return null;const g=getComputedStyle(el),b=el.getBoundingClientRect();
    return{bg:g.backgroundColor,color:g.color,radius:g.borderRadius,
           border:g.borderWidth+' '+g.borderColor,font:g.fontFamily,
           size:g.fontSize,weight:g.fontWeight,lh:g.lineHeight,
           pad:g.padding,h:Math.round(b.height),w:Math.round(b.width)};};
  return{
    侧栏:   r(document.querySelector('选择器')),
    激活导航项: r(document.querySelector('选择器')),
    主按钮: r(document.querySelector('选择器')),
    卡片:   r(document.querySelector('选择器')),
    输入框: r(document.querySelector('选择器')),
    表头:   r(document.querySelector('选择器')),
    表格行: r(document.querySelector('选择器')),
    body:   r(document.body),
  };
})())

设计 HTML 和线上的类名通常不一样，要各自定位"对应的那个元素"再读，不能套同一个选择器。

4.5. 七个维度逐一过，别只挑扎眼的

每个走查单元都按下面七维过一遍。只看最扎眼的那一两处，一定漏：

4.6. 实锤后才下差异

拿到两边真实值，能命名的偏差才写进报告（"线上圆角 8px，设计 24px"）。说不清是否有意的微调——差 2-3px、抗锯齿引起的色值末位差、headless 字体回退造成的渲染差——不写，那是噪声。

四、报告产出

5.1. 文件结构

每次走查新建一个文件夹，用绝对路径建：

<ACCEPTANCE_DIR>/{YYYY-MM-DD}-{模块名}-UI走查/
  ├── 报告.md
  └── screenshots/
      ├── 设计-01-侧栏.png
      ├── 线上-01-侧栏.png
      └── ...

<ACCEPTANCE_DIR> 由用户在 CLAUDE.md 中配置，建议加入 .gitignore。{模块名} 取页面最有辨识度的那段（如「Agent 列表」「会话看板」）。文件夹名带 -UI走查 后缀，跟功能验收的文件夹区分开。建完用 ls 确认真实路径。

5.2. 报告模板

# UI 走查报告：{模块名}

| 项 | 值 |
|----|----|
| 设计 HTML | `{相对路径}` |
| 线上 URL | `{URL}` |
| 走查视口 | 1440 宽 |
| 走查时间 | {YYYY-MM-DD HH:mm} |
| 走查人 | PM + Claude |

## 一、总体结论

不堆统计数字。按下面「二、逐项走查」的区块标题组织，每组只列该组里有明确差异的点，没差异的组不写。组标题加粗，每个差异点单独一行、有序序号，每条 ≤ 30 字。

> **1. 侧栏**
>
> 1. 激活态用蓝色，设计稿是青色
> 2. 菜单项用 emoji 当图标，设计稿是线性图标
>
> **2. Agent 列表表格**
>
> 1. 表头高 56px，设计稿 40px
> 2. 行圆角缺失，设计稿表头两端 24px

## 二、逐项走查

按页面区块分组，每组先一张表，表后贴设计图、线上图各一张。

### 2.1 {区块}

| # | 部位 | 维度 | 设计稿 | 线上 |
|---|------|------|--------|------|
| 1 | … | … | … | … |

设计稿：![](screenshots/设计-01-xxx.png)
线上：  ![](screenshots/线上-01-xxx.png)

## 三、未能走查

只列确实没比到的（线上需登录态 / 某状态线上没有入口 / 某弹窗需特定数据触发），每条带上对应 #N。

每列说明：

1. 部位：用大白话点名页面上那块东西（"侧栏激活项""主按钮""列表表头"），不用压缩黑话。
2. 维度：七维之一（结构 / 组件 / 颜色 / 字体 / 圆角 / 图标 / 间距）。
3. 设计稿：写设计 HTML 上的真实值（"圆角 24px""#fc7913""字重 600"），不写"标准""规范"这种空话。
4. 线上：写线上的真实值。禁止"偏离 / 不符 / 不一致"这类判断词——把不一样摊成具体的：圆角 8px、#1677ff、字重 400。

报告是纯差异清单：线上和设计稿一致的项不进报告，也不写"XX 一致，不单列"这类注释。不写"影响""建议修复方式"——PM 只要"哪里不一样"，方案研发自己判断。三节到此为止，没有别的章节。

5.3. 实时打印 + 完成后报路径

边走查边在对话里报进展（一行一项，简短）。走查完一次性把 报告.md 写出来，然后必须告诉 PM：

报告写到了 {绝对路径}
截图在 {绝对路径}/screenshots/

五、约束与边界

6.1. 设计 HTML 是唯一参照系：线上对不对只跟这份 HTML 比。不拿其他规范 / 个人审美去挑线上的错——那会变成借走查改需求。 6.2. 内容差异不是 UI 差异：线上真数据 vs 设计稿 mock 数据，文字不同、条数不同、头像不同都不算差异，只比结构和样式。 6.3. 不操作 PM 日常 Chrome：MCP 默认 headless 或 9222 隔离实例；browser-cap 用 cap-launch-chrome.sh 起的隔离实例。 6.4. 只读：不在线上创建 / 删除数据。 6.5. 遇验证码 / 登录态过期：暂停，让 PM 手动过，不硬闯。 6.6. 不替研发圆话：还原差异如实记，不因为"可能是小问题"就不写。 6.7. 设计 HTML 自己就有问题时（如某组件画错）：照常以它为参照系记线上差异，把 HTML 本身的疑点单独半句带给 PM，不自行判断哪个对。

六、高频错误

7.1. 两边视口宽度不一致 —— 布局错位、留白差异全是假的，整轮白做。 7.2. 没切到同状态就比（设计稿停在列表态、线上停在详情态）。 7.3. 把真数据 vs mock 数据 的内容差异当成 UI 差异。 7.4. 肉眼看截图猜色值 / 圆角 —— 说不出具体差多少，研发没法改，必须读 computed style。 7.5. 报"差 2px""色值末位差 1" 这种微调 —— 噪声，不写。 7.6. 只挑最扎眼的一两处，七维没逐项过 —— 必漏。 7.7. 拿其他规范 / 个人审美挑线上的错，而不是拿设计 HTML 比 —— 越界，见 6.1。 7.8. 报告里写一致项、写"影响 / 建议" —— 报告只留差异结论。 7.9. 漏说报告路径 —— 「四、5.3」末尾必有那句「报告写到了 {绝对路径}」。