验收（功能验收 Skill）

研发开发完成后，用这个 skill 把 PRD 描述的业务逻辑和 HTML 原型表达的交互效果，逐项对照线上实现，产出可直接发研发的差异清单。

一、输入约定

每次启动验收，PM 至少给两样：

2.1. PRD 路径：明确指定某份 .md，不要猜。 2.2. 线上 URL：研发提测的页面入口。

HTML 原型自动找：

2.3. 在 PRD 同目录下找 prototype/ 或 原型/ 子目录。 2.4. 找不到就退化为「两方对照」（PRD ↔ 线上），并在报告里注明 HTML 缺失。 2.5. 找到多个 HTML 时，按文件名匹配 PRD 名字优先；不确定就问 PM。

特殊情况：

2.6. URL 与 PRD 描述对象明显不是同一个（如 PRD 写新系统页面、URL 是老系统页面）：先停下来问 PM 这次验收意图——迁移前差异盘点 / 用错 URL / 中止——再继续。不要默默按其中一种跑下去。 2.7. PRD 内有「现状说明 / 迁移依据」章节引用了一个老系统页面，而 PM 给的就是这个 URL：默认按"迁移盘点"模式处理，逐项写"PRD 新需求 vs 老页面现状"差异。这只是验收口径，不写进报告——不要前置说明章节，也不要在总体结论里加"线上为待迁移老页面…"这类背景句。PM 已知背景，报告只留差异。

二、验收前准备

3.1. 读 PRD 提取期望清单

只拉与本次验收直接相关的章节，重点提：

1. 功能清单（本期做 / 不做）—— 验收的最外层 checklist。
2. 页面与交互 —— 每页有哪些区块、字段、按钮。
3. 操作逻辑 —— 主路径 + 校验 + 异常处理。
4. 字段表 —— 必填、限制、校验规则。
5. 指标口径（数据类 PRD）—— 公式、环比、展示格式。

把这些转成一张 checklist，每条都能在线上验真。

3.2. 读 HTML 提取视觉口径

只看：

1. 页面结构（左侧栏 / tab / 主区分块）。
2. 字段位置和默认态。
3. 关键按钮和状态切换。
4. 弹窗 / 浮层 / 二级页。

不要纠结圆角、间距、像素 —— 那是设计交付（视觉还原度走查见 ui-walkthrough skill）。

如果原型本身已与 PRD 不一致（命名 / 数量 / 流转），不要默认以 HTML 为准。把这些记下来作为 🔍 候选项，最终以 PRD 为准给状态，原型偏离在备注里单独说。

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

默认路径：chrome-devtools MCP。所有验收能力（导航 / 截图 / 点击 / hover / 读 DOM / 抓接口）都走 MCP 工具。一次起一个 Chrome，串行执行。无需任何额外安装。

可选高速路径：browser-cap。当用户在 CLAUDE.md 中配置了 BROWSER_CAP_DIR（指向 claude-browser-cap 安装位置），可走并行高速模式：

1. bash ${BROWSER_CAP_DIR}/bin/cap-launch-chrome.sh <端口>（端口 9222-9299，已占自动拒绝，换一个）。
2. node ${BROWSER_CAP_DIR}/bin/capture.js <端口> <配方.json> 驱动该 Chrome：一次跑完导航 / 点击 / hover / 读 DOM 断言 / 抓接口响应 / 截图。
3. 截图先落临时目录，再 bash ${BROWSER_CAP_DIR}/bin/stash-shots.sh 入库到 <ACCEPTANCE_DIR>/.../screenshots/。

高速模式的本质是「一次 node 调用跑完 N 步」+ 「每个子代理一个独立 Chrome 端口」，节省 token 和回合数。

怎么选：未装 browser-cap → 走 MCP；装了且本次验收量大（多页面 / 多状态）→ 走 browser-cap；需要 PM 亲自盯着或手过登录 / 验证码 → 不管装没装都走 MCP（人在浏览器前更直接）。

三、验收执行流程

4.1. 执行模式（按工具决定串并行）

1. MCP 模式：单 Chrome 天生串行。按 PRD 章节 / 页面顺序逐区跑。
2. browser-cap 模式：可并行。把验收按 PRD 章节 / 页面拆成 N 个独立分区，一条消息里用 Agent 工具同时起 N 个子代理：每个子代理认领一个分区 + 一个端口 → cap-launch-chrome.sh 起自己的 Chrome → capture.js 跑该分区的检查 → 回传该分区的差异行 + 截图。主代理汇总成一份报告。

不管串并行，下面的方法论（真点开、抓接口、足量数据）一条不变。

4.2. 按 PRD 功能清单逐项验

不要乱点。按 PRD 章节顺序逐项：

1. 找入口 → 点击进入。
2. 截图存档。
3. 对照 HTML 看布局。
4. 对照 PRD 看字段 / 操作 / 校验 / 异常。
5. 记录三方差异。

4.3. 每个可交互控件都要真点开，不靠快照推断

a11y 快照里 combobox、button、tab 只是角色名，看不出单选还是多选、点了会怎样、有没有搜索框 / 二级弹层。每一个筛选项、下拉、日期选择器、按钮、tab、齿轮、可点数字，都要：

1. 真点开 / 真点击，看展开后的真实形态（有没有 checkbox = 多选；有没有搜索框；有没有取消 / 确定；listbox 单选还是 checkbox 多选）。
2. 筛选区逐个字段点开，一个都不能跳过——"看着像单选"就标单选是最常见的误判。
3. 点开后截图存证，再关掉换下一个。
4. 拿不准会不会改数据的（查询 / 重置 / 导出属只读，安全；新建 / 删除 / 提交不安全）按「六、约束与边界」处理。

ⓘ / tooltip / 悬停态：必须真 hover 看弹出内容，不能标"未验证"。 PRD 常要求"每个指标名旁 ⓘ 悬浮显示定义 + 公式"——要 hover 上去抓浮层文本，逐条对 PRD：是逐指标各一个 ⓘ 还是区块级一个合集？公式口径对不对？标题与公式名是否自相矛盾？这些只 hover 一下就能查实，留"未验证"是偷懒。

重置 / 联动 / 自动触发这类行为：必须真点真测，不能标"未单独验证"。 重置就真点重置，看筛选有没有还原默认值、有没有自动发查询请求（看 network 有没有新的数据接口调用）；联动就改上游字段看下游有没有跟着变。能点的行为都要点出来，不留"未验证"。

导出 / 下载类按钮：必须真点，然后把文件搞到手验内容，不能写"未触发验证"了事。 很多导出是异步任务（点击 → POST 提交 → 轮询 getStatus → 返回 exportUrl），浏览器不一定自动下载。用 list_network_requests 找到那个 export 接口，从响应里取 exportUrl，curl 下载到验收文件夹，再用 openpyxl / unzip 读出来全部核一遍：① 文件名是否符合 PRD 命名规则；② 格式；③ 行数是否 = 页面总条数；④ 列字段逐个对 PRD。光看按钮在不在 = 没验。 但报告里只写没通过的：文件名符合、格式对、行数对——这些通过项一个字都不写（报告是差异清单，格子里也一样只留问题，不写"✅ 符合 / 不受分页 ✅"）。下载的样本文件不用在报告里再提一句"已留存 XX（重复上文）"，留在文件夹即可。

漏点一个控件，状态判定大概率就是错的——这一步不能省。

4.4. 图表类先把时间拉到足量数据再看

桑基图 / 趋势图 / 占比图这类，数据不足时根本不渲染或显示"暂无数据"。默认时间范围常是"今天"，老环境当天往往没数据，这时候图表区空白——绝不能据此判"图表缺失 / 未实现"。

验图表前先把时间字段调到有足量数据的范围（一般选最近两个月，或 PRD 允许的最大范围内挑数据多的区间），点查询，等渲染出来，再看：图表类型对不对、点击 / 悬停交互是否实现。

但"某节点 / 系列没出现"≠"图表缺这个节点"。 图表完全由数据驱动，某分支数据为 0 就不渲染（如全部会话已结束时"进行中会话"节点不画）。所以绝不能从一份数据样本判"缺 X 节点 / 多 Y 节点"——那大概率是数据没覆盖到，不是结构缺陷（这是继"图表缺失"之后第二个最容易犯的误判）。能观察到的只写"命名是否与 PRD 一致"；节点 / 系列完整性，要么找一个能跑出全部分支的数据范围再验，验不到就如实标"节点完整性未能验收"，不要替它下"缺/多"的结论。

4.5. 每项的四步

① 从 PRD 拿期望 → ② 在线上定位实现 → ③ 实操一次（按上一条真点开）→ ④ 落一个状态（✅ / 🟡 / ❌ / 🔍）。

✅ 一致项验过就行，彻底不出现在报告里。 报告是纯差异清单，只列 🟡 / ❌ / 🔍。每项仍要真验，只是 ✅ 不占行，也不要写"XX 与 PRD 一致，不单列""逐个点开验过…"这类说明性注释——PM 不要这种 meta 提示，验证过程不进文档，文档只留差异结论。

字段 / 列 / 选项数量对不上时，必须逐个列举，写进那一行的「线上实现」单元格里（不另起小节、不写"少 N 列"了事）。用有序序号在单元格内拆三类：1）改了名（PRD 名 → 线上名，标"需确认是否同义"）；2）线上完全没有的，逐个列名；3）线上多出 PRD 没有的；4）净差数。这一格会偏长，是为了让研发直接拿列名干活，可以超 30 字。

4.6. 主路径 + 异常两条都要试

主路径：用户最常走的成功流程。 异常：PRD「操作逻辑」里写的每个分支（空值、超限、网络失败、权限不足等）至少抽样试一两个。

异常需要 PM 配合（验证码、新建数据、切角色）时，在报告里标"未能验收"，不要硬闯。

4.7. 截图证据

每项验收都截一张图，存到本次验收文件夹的 screenshots/ 下，文件名 {序号}-{功能简述}.png。差异处必须截图；一致处可选。

截图路径不能写 /tmp/...（沙箱拒绝），用 $TMPDIR 子目录或直接写到工作区下 <ACCEPTANCE_DIR>/{...}/screenshots/。

四、报告产出

5.1. 文件结构

每次验收新建一个文件夹，用绝对路径建，别用相对路径（验收目录有固定的绝对路径家，cwd 不确定，拼相对路径会落错地方、PM 找不到）：

<ACCEPTANCE_DIR>/{YYYY-MM-DD}-{模块名}/
  ├── 报告.md
  └── screenshots/
      ├── 01-入口.png
      ├── 02-列表页.png
      └── ...

<ACCEPTANCE_DIR> 由用户在 CLAUDE.md 中配置，建议放在项目仓库根下、和 PRD 目录平级，且加入 .gitignore（验收产物不进版本库）。{模块名} 取 PRD 标题里最有辨识度的那段（如「工作台-调优模式」「会话看板」）。建完用 ls 确认真实落地路径，最后报给 PM 的必须是这个绝对路径。

5.2. 报告模板

# 验收报告：{模块名}

| 项 | 值 |
|----|----|
| PRD | `{相对路径}`（版本号、日期） |
| HTML 原型 | `{相对路径}` 或「无」 |
| 线上 URL | `{URL}` |
| 验收时间 | {YYYY-MM-DD HH:mm} |
| 验收人 | PM + Claude |

## 一、总体结论

**不堆统计数字**（不写"共验收 N 项 / ✅ X 项 / 阻塞 K 个"）。**按下面「二、逐项验收」的分组标题组织**，每组只列该组里有明确差异的点；没差异的组不写。组标题加粗，**每个差异点单独一行、有序序号**（不要 1）2）　内联挤一行——一行一条更清晰），每条 ≤ 30 字。

格式示例：

> **1. 入口与页面骨架**
>
> 1. 入口仍在老系统，未落数据中心
> 2. 无顶部订阅按钮
>
> **2. 全局筛选栏**
>
> 1. 无时区筛选
> 2. 默认时间范围非近 7 天
> 3. 重置按钮点击后未还原默认、未自动触发查询

关键 / 阻塞问题就放在这套分组序号里（它本身就是按严重度组织的差异清单），**不单开"阻塞 / 关键问题"章节，不写"影响""建议修复方式"**——PM 只要"哪里有差异"，原因和方案研发自己判断。每条只写现象，必要时半句带上 PRD 期望。**结论段到此为止，不要再补一段"线上为待迁移老页面…需整体重写…最大风险是…"这类总结判断**——差异清单本身就是结论，迁移范围 / 老页面这类背景一个字都不要写进文档（PM 已知背景，不需要复述）。

## 二、逐项验收

按 PRD 章节分组（避免一张大表 50+ 行）。每个分组先表；**表后只贴"能看出问题"的截图**——截图必须直观体现该组的差异（如老系统入口、无分组的指标卡、列名不符的表格）。**与 PRD 一致 / 没问题的区域不要贴图**（如本身就符合的多选弹层、渲染正常的图表），贴了等于噪声。某组没有能体现问题的图就不贴。

**表里只放 🟡 / ❌ / 🔍 的项，✅ 一致项不进表，也不写"不单列"之类注释**（验过即可，验证过程不进文档）。编号按"只含差异项"连续编（1、2、3…）。某组全部一致就整组不写。

**「线上实现」单元格：多个点用有序序号 + `<br>` 换行**（`1. xxx<br>2. xxx<br>3. xxx`），不要挤成一长串 prose。字段 / 列数差异那格按"改名 / 缺失 / 多出 / 净差"分条写全，可超 30 字。**不要写"图表存在并渲染（足量数据才显示）"这种通识**——数据类页面都是按查询数据渲染的，PM 不需要这句，直接写差异本身。

### 2.1 {功能组 1}

| # | 功能 | PRD 章节 | PRD 期望 | 原型 | 线上实现 | 状态 |
|---|------|---------|---------|------|---------|------|
| 1 | … | … | … | … | … | … |

![{功能组 1}](screenshots/01-xxx.png)

### 2.2 {功能组 2}

…

每行说明：

1. **功能**：用大白话点名页面上那块东西（如"核心指标卡片""会话明细列""时区筛选"），**不要用"卡片数与分组""命名口径""列数与命名口径"这种压缩黑话**——评审看不懂。
2. **PRD 章节**：定位到具体节号，便于研发回查。
3. **PRD 期望**：具体写要什么（"10 张卡片分 3 组、每组有组标题"），不写"符合规范"这种空话。
4. **原型**：原型实际画了什么（"11 张卡片、有 3 组标题"），**不要写"原型已偏离""原型 X 已偏离"**——"偏离"是判断词不是事实，读者看不懂偏在哪。没原型写「-」。
5. **线上实现**：实际看到什么，**用有几个 / 有没有 / 叫什么 / 哪里不一样的大白话**。禁止"偏离 / 不一致 / 维度不同 / 口径不符"这类抽象结论——要把"不一样"摊开成具体的：页面叫 A，PRD 要 B；页面 11 个，PRD 10 个；页面平铺无标题，PRD 要 3 组标题。
6. **状态**：四种之一。

「线上实现」格里**只写不对的点，不写对的点**：别写"文件名符合 ✅""格式对""行数=页面总数 ✅"——通过的不进报告（验证照样要做，只是结论里不留）。也别写"31 减 25 差 6 列"这种算术小结，差哪几列已经列清了，减法是废话。

写之前自检：每个格子，一个没看过这页面、不懂产品黑话的人能不能照着字面看懂"哪里不对"？看不懂就是没写好。

证据不单列一列，改为每个分组表后嵌入"能体现问题"的截图；一张图覆盖多行时贴一次即可。

## 三、未能验收

只列**确实没验到**的项（权限不足 / 数据没覆盖到 / 需构造特殊场景 / 验证码挡住），每条带上对应 #N。
**不要写"已知差异"段、不要写"原型偏离 PRD"段**——差异都在「二」表里了，备注只留"哪些没验到、为什么"。

（注意：报告只有 一、总体结论 / 二、逐项验收 / 三、未能验收 三节，没有"阻塞""已知差异""原型偏离"这些节。）

5.3. 实时打印 + 写文件

边验边在对话里报进展（一行一项，简短）：

✅ 1. 入口菜单：左侧栏第 2 项，符合
🟡 2. 列表字段：缺「最后操作人」列
❌ 3. 批量删除：未实现
🔍 4. 详情页 tab 顺序：日志在历史前面
...

5.4. 完成后必报告路径

验收完成后一次性把完整 报告.md 写出来，然后必须给 PM 报告路径：

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

少了这一句，PM 翻不到东西。

五、Chrome DevTools MCP 工具速查

MCP 模式核心工具（也是 browser-cap 配方字段的语义来源 —— navigate_page→url、click→clicks、hover→hover、take_screenshot→shot/fullPage、evaluate_script/take_snapshot→eval、list_network_requests+取响应→recordNetwork/grabBody）：

页面内主区滚动时优先 evaluate_script 操作内层滚动容器（如 .content___xxx），整体 window.scrollTo 经常不动。

六、约束与边界

7.1. 不操作 PM 日常 Chrome：MCP 模式默认拉 headless Chromium 或 9222 隔离实例；browser-cap 模式 cap-launch-chrome.sh 起的隔离实例 user-data-dir 在临时目录、并行各占各端口。日常 Chrome 的标签 / 密码 / 扩展不该被自动化扰动。 7.2. 只读默认，不在系统里创建 / 删除真实数据，除非 PM 明说「试一下创建流程」（验收对象是实现完成度而非产品后台本身；误创建会污染演示账号，误删除会让后续验收无数据可用）。 7.3. 遇验证码 / 二次验证不硬闯，暂停让 PM 手动过那一步（验证码意味着风控介入或登录态失效，硬闯只会被封 IP 或锁号）。 7.4. 遇登录态过期：暂停，让 PM 重新登录。 7.5. 接口报错：用 list_console_messages + list_network_requests 看错误，写进报告备注。 7.6. 不替研发圆话：实现差异如实记，不要因为「可能是小问题」就降级状态。 7.7. PRD 自己有矛盾时：暂停问 PM，不要自己判断哪条对。 7.8. HTML 和 PRD 冲突时：以 PRD 为准，HTML 不一致单独标记 🔍。

七、高频错误

8.1. 没读完 PRD 功能清单就开始点 —— 容易漏验。 8.2. 只验主路径不验异常处理 —— 实际事故多在边界。 8.3. 把视觉差异和业务逻辑差异混到同一行 —— 🔍 和 🟡 要分清。 8.4. 默认时间范围空数据时判"图表缺失 / 未实现"，或从一份数据判图表"缺 X 节点 / 多 Y 节点" —— 都是数据没覆盖到，不是结构缺陷，见 4.4。 8.5. 单元格里堆长句 —— 一般 ≤ 30 字；唯一例外是字段 / 列差异那格，按三类有序序号列全（见 4.5）。 8.6. URL 指向老系统 / 旧版本 / 子集页面，却按"全量新页面"标 ❌ —— 先按 2.6 问意图。 8.7. 漏说报告路径 —— 「四、报告产出」末尾必有那句「报告写到了 {绝对路径}」。 8.8. 看 a11y 快照角色名（combobox / button）就推断单选 / 多选 / 行为 —— 必须真点开，见 4.3；筛选项一个都不能跳过。 8.9. 报告里写"影响 / 建议修复方式 / 一致项不单列 / 线上为待迁移老页面…"这类 —— 报告只留差异结论，不写原因方案、验证旁白、迁移背景、收尾判断段。 8.10. 导出 / 下载按钮只看"按钮在"就标完 —— 必须真点、把文件下下来核文件名 / 格式 / 行数 / 列字段，见 4.3。 8.11. ⓘ / tooltip / 重置 / 联动 标"未验证 / 未单独验证" —— 这些 hover / 点一下就能查实，不许留白，见 4.3。 8.12. 给没问题的区域贴截图 —— 报告里图只贴能体现差异的，符合 PRD 的区域不贴。 8.13. 总体结论一行挤多条（1）2）3）　） —— 改成一条一行有序序号；线上实现多点用 <br> 分行。 8.14. 写"已偏离 / 口径不一致 / 维度不同 / 卡片数与分组"这种判断词或压缩黑话 —— 摊成大白话事实：几个 vs 几个、叫 A vs 要 B、有没有组标题，见 5.2「每行说明」。 8.15. 格子里写通过项（"符合 ✅""格式对""行数对"）、写算术小结（"31−25=6"）、写重复指引（"样本已留存 XX"上文已说） —— 报告只留没通过的，废话一律删。