视觉验收
对比 设计工具基准（Figma / MasterGo / Pixso / 即时设计等）与 开发页面截图，按《视觉验收》PDF（视觉要素 24 项 VA-* 检查点）验收，输出计分与标注报告。
> PDF 路径：将 视觉验收.pdf 放在 skill 根目录，或设置环境变量 VA_PDF_PATH 指向本地副本。权威规则来源为宁波银行 UED《设计还原度量化标准》视觉要素部分。
必读参考
| 文件 | 用途 |
|---|---|
| rules-reference.md | 检查点与扣分 |
| scoring-algorithm.md | 计分与 ledger |
| design-link-baseline.md | 多平台设计链接 → 设计基准（总览） |
| figma-baseline.md | Figma 链接 → baseline |
| mastergo-baseline.md | MasterGo 链接 → baseline |
| full-checkpoint-checklist.md | 24 项全量走查 |
| annotation-guide.md | bbox 标注 |
| acceptance-guardrails.md | 防误判：路由/采图/DSL/CDP 取样 + 复检锁判 |
| dev-capture.md | 开发页采图：Cursor 复用登录 / CLI headed 登录 |
| report-generation.md | HTML 报告：H5 长页布局 + 设计链接展示 |
| examples.md | 示例 |
推荐输入（设计稿链接 + 开发截图）
| 必填 | 说明 |
|---|---|
| 设计稿链接 | Figma / MasterGo / Pixso / 即时设计等，指向整页验收 Frame |
| 开发截图 | 已登录、与设计帧 同宽高 的 PNG（推荐用户本机截取） |
| 可选 | 说明 |
|---|---|
| 开发 URL | Cursor 复用已登录标签采图；Codex/CC 有头登录一次后读页；可 CDP 抽测 |
| 设计导出 PNG | 报告并排展示设计稿（DSL 无数图时） |
不推荐：仅用肉眼扫截图且不拉设计 DSL — 会导致 20+ 项 untested。
工作流
Task Progress:
- [ ] 0. 读 acceptance-guardrails.md 开验前清单
- [ ] 1. 识别设计平台 → 拉 DSL → design-baseline.json（文案/Token 仅引 DSL）
- [ ] 2. 确认路由与端型（H5：/app/ + iPhone UA；bodyW ≈ innerWidth）
- [ ] 3. 采图：CDP clip frame.width；PNG 宽 ≈ width×DPR
- [ ] 4. L1 宏观 + L2 Token（24 项 pass/fail/na；文案差异先观察项）
- [ ] 5. L3 CDP：字体/阴影/渐变取最内层文字或卡片本体（见 guardrails §C）
- [ ] 6. 计分 + checkpoint_ledger（禁止无理由 untested）；**validate_findings.py 通过后再出报告**
- [ ] 7. HTML 报告 + crops/ 逐条烘焙图 + annotated-dev.png + report-meta.json
复检（用户要求再验、对某条有异议）时额外：
- [ ] 读取上一轮 findings.json，禁止无证据删 fail / 降扣分
- [ ] 取样错误 → corrections.reason=sampling_error（old_actual + new_actual）
- [ ] 产品书面确认 → close_observation.py，不得口头 pass
- [ ] generate-report.py --previous <上一轮 findings.json>
Step 0：设计基准（必做）
- 识别链接平台 — 见 design-link-baseline.md；可用
parse_design_link(url)（scripts/va_utils.py） - 按平台拉取设计数据：
- Figma → figma-baseline.md →plugin-figma-figma/user-Figma
- MasterGo → mastergo-baseline.md →user-mastergo-magic-mcp
- Pixso / 即时设计 / 其他 → 对应 MCP 或设计导出 + 填入统一 baseline 结构 - 归纳
design-baseline.json：须含source_tool、frame.width/height、tokens、components、icons - 记录帧尺寸，作为开发截图/URL 视口的目标宽高
Step 1：视口对齐
dev 宽/高与frame 宽/高误差 ≤2% → 可做 px 级 Token 验收- 否则：仅 L1 布局验收；L2 px 级标
untested并注明「需重采同尺寸截图」
Step 2：路由、端型与采图
详见 acceptance-guardrails.md §A–§C。
H5 页面（设计帧宽 ≤480）
- 打开用户给的 H5 生产链接（如
/app/），勿用/fips/桌面路由代替 Emulation.setUserAgentOverride（iPhone）+setDeviceMetricsOverride(width=frame.width)- 确认
body.scrollWidth ≈ innerWidth且关键模块出现在innerText - 采图：
Page.captureScreenshot+clip.width = frame.width（PNG 宽 ≈width × DPR） - 勿仅依赖
browser_take_screenshot（易按面板宽度出图、带白边）
用户本机上传截图（推荐内网）
- DevTools 设备模式 → 与设计帧同宽 → 只截视口
- Agent 校验 PNG 宽度 ≈
frame.width × DPR后再验收
登录 — 先判环境，再读页。不要要密码，不要新开无痕窗口再登。详见 dev-capture.md。
- Cursor（能调
browser_tabs/browser_navigate/browser_cdp）：先browser_tabslist。同站已登录标签 → lock 后直接读，禁止再navigate打回登录页。用LOGIN_WALL_JS（CDPRuntime.evaluate）判断是否仍在登录墙。仍是登录页则 unlock，请用户在同一内嵌浏览器登录后再读。 - Codex / Claude Code 等（无 Cursor 浏览器 MCP）：
scripts/capture_dev_page.mjs --headed --wait-login，会话写入~/.visual-acceptance-check/storage/<host>.json，下次复用。无会话且无头则退出并提示 headed。 - 落地页仍为登录墙 →
blocked_login，禁止对登录页计分；记录resolved写入report-meta.json
Step 3：全量检查点走查
严格按 full-checkpoint-checklist.md 与 acceptance-guardrails.md §D：
- L1：baseline
components+ TEXT 文案 vs 截图/innerText → 模块缺失才 fail - L2：baseline Token vs 截图/CDP；文案仅差异 →
observations.json，不扣分，待设计/产品确认 - L3：CDP 抽测间距/圆角/阴影；字体取最内层文字节点（如
span.title-name），不取.card-head父级
每条 fail 须：design 可追溯 DSL/styleId、actual 有 CDP 选择器或截图依据、含 bbox_px。
pass 写入 styles-audit.json。误判撤销写入 report-meta.json → corrections[]。
复检不得因对话语气、组件库默认、或「看起来接近」改判，见 acceptance-guardrails.md §H。
id: F-003
checkpoint_code: VA-COLOR-BRAND
severity: general
deduction: 1
region: "待办表-审批中状态点"
bbox_px: [545, 162, 78, 16]
design: "Figma variable/brand-warning → #F5A623" # 或 MasterGo Token 等
actual: "截图取样 → 蓝色 #1890FF"
fix: "使用设计 Token brand-warning"
verified_by: figma_dsl # 或 mastergo_dsl
Step 4：计分
见 scoring-algorithm.md。ledger 24 行；untested 仅 L3 且缺 URL 时允许，须写 note。等级阈值以 rules-reference.md 为准：优秀 ≥95、达标 90–94、有条件通过 80–89、不达标 <80。出报告前：
python3 "$SKILL/scripts/validate_findings.py" --dir "$OUT"
Step 5：HTML 报告
见 report-generation.md。
- 产物目录
reports/visual-acceptance-<page>-<timestamp>/ - 设计侧：有 PNG 则嵌入；仅有设计链接时写入
designLink+designFrame+designSource，禁止空designImageBase64触发破图 - 开发侧：全页 PNG + 像素 viewBox SVG 总览；H5 长页在模板内 375px 居中 + 限高滚动
- 差异点：
generate-report.py自动裁剪crops/F-*.png并烘焙标注；HTML「差异点详情」双列卡片（截图 + 设计/实际值 + 优化建议）。禁止对裁剪图再套 SVG - 优先用脚本生成，勿手改
REPORT_DATA：
# skill 根目录：在仓库内执行可省略；否则 export VA_SKILL_ROOT=/path/to/visual-acceptance-check
SKILL="${VA_SKILL_ROOT:-.}"
OUT=reports/visual-acceptance-<page>-<timestamp>
python3 "$SKILL/scripts/generate-report.py" \
--dir "$OUT" \
--title "<页面>视觉验收" \
--meta "375×812 · H5 · $(date +%F)" \
--dev dev.png \
--baseline design-baseline.json \
--findings findings.json \
--ledger checkpoint-ledger.json
python3 "$SKILL/scripts/bake-annotations.py" \
"$OUT/dev.png" "$OUT/findings.json" -o "$OUT/annotated-dev.png" \
--reported-size 375x812
REPORT_DATA 必填字段：designLink、designFrame、designSource、viewportMode（H5 填 "mobile"）、image_size、png_size；fail 项须有 cropSrc/cropBase64。
与 design-fidelity-audit 区分
| 项目 | 本 skill | design-fidelity-audit |
|---|---|---|
| 设计源 | Figma / MasterGo 等链接 DSL 为主 | PNG / Figma |
| 编码 | VA-*（24 项视觉） |
V/I/A-*（三维度） |
| 计分 | 单维度 100 | 加权 40/35/25 |
输出检查
- [ ] 已读并执行 acceptance-guardrails.md 开验前清单
- [ ]
design-baseline.json（含source_tool）+report-meta.json（含 resolved_url、capture_method） - [ ] 24/24 checkpoint 有 pass/fail/na（untested 有 note）
- [ ] fail 项均有
bbox_px；design引设计 DSL，非猜测 - [ ] HTML 报告：H5 截图限高可滚动；设计侧链接可点、平台徽章正确、无破图
- [ ] 每条 fail 有独立烘焙裁剪图；框贴元素、缩放不错位；卡片含详情与优化建议
- [ ] CDP 字体/阴影/渐变取样符合 guardrails §C
- [ ] 文案变更已区分：观察项 / 已确认正式需求 / fail
- [ ] 复检若改判：
corrections[]reason 合法且有证据；未用人因话术把 fail 改 pass - [ ]
validate_findings.py已通过
