ui-walkthrough

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
      └── ...