diff --git a/.claude/skills/d8d-dev/visual-diff-mode-pencil.md b/.claude/skills/d8d-dev/visual-diff-mode-pencil.md index 72d82d6..4734ff1 100644 --- a/.claude/skills/d8d-dev/visual-diff-mode-pencil.md +++ b/.claude/skills/d8d-dev/visual-diff-mode-pencil.md @@ -117,75 +117,154 @@ mkdir -p tests/e2e/screenshots/visual-diff-pencil --- -## Phase PVD-1: 逐页对比循环 +## Phase PVD-1: 逐页门禁对比循环 -对映射表中每个 `status: active` 的页面执行以下流程。 +⛔ **核心原则：逐页执行，每页必须通过门禁才能继续下一页。禁止全量截图后批量对比。** + +对映射表中每个 `status: active` 的页面，依次执行以下完整循环： + +``` +PVD-1 PER-PAGE LOOP: + A. 导出设计截图 + B. 截取实际页面 + C. AI 视觉对比 + D. 差异分级 + E. PAGE GATE-CHECK ⛔ + ├── 🟢 通过 → G. 记录 → NEXT PAGE + └── 🔴/🟡 未通过 → F. AUTO-FIX → 重截 → 重比 → 重新 GATE-CHECK + G. 记录结果到 pipeline-state.yaml +``` ### 1.A Pencil MCP 导出设计帧截图 ``` 工具: mcp__pencil__export_nodes 参数: - - filePath: "VividSpark1.2.pen" - - nodeIds: ["{design_frame_id}"] # 从映射表获取 + - filePath: "ui.pen" + - nodeIds: ["{当前页面的帧 ID}"] # 每次只导出 1 个 - outputDir: "tests/e2e/screenshots/visual-diff-pencil" - format: "png" - scale: 2 # 2x 高清 ``` -导出后的文件路径： -- `tests/e2e/screenshots/visual-diff-pencil/{design_frame_id}.png` - 重命名为可读名称： - `tests/e2e/screenshots/visual-diff-pencil/{name}-design.png` ### 1.B 截取实际页面截图 -同 HTML 原型版，使用 Playwright： +使用 Playwright： ``` -1. browser_navigate → {实际 URL}{route} -2. browser_resize → 1440x900（与设计帧尺寸匹配） +1. browser_resize → 375x812（移动端）或 1440x900（管理后台） +2. browser_navigate → {实际 URL}{route} 3. 处理认证（如需要） 4. browser_wait_for → time=3 5. browser_take_screenshot(fullPage=false) → tests/e2e/screenshots/visual-diff-pencil/{name}-actual.png ``` -### 1.C UI 差异对比 +### 1.C AI 视觉对比 + +使用 Read 工具分别查看设计截图和实际截图，然后综合分析差异： ``` -工具: ui_diff_check -参数: - - expected_image_source: "tests/e2e/screenshots/visual-diff-pencil/{name}-design.png" - - actual_image_source: "tests/e2e/screenshots/visual-diff-pencil/{name}-actual.png" - - prompt: "对比这两张截图：第一张是 Pencil 设计稿，第二张是实际实现。列出所有视觉差异，包括布局结构、组件排列、颜色、间距、字体、图标等。按严重程度排序。" +步骤: + 1. Read 工具查看设计截图 → 理解设计意图（布局、颜色、组件） + 2. Read 工具查看实际截图 → 识别实现状态 + 3. 综合两图分析差异，关注: + - 布局结构（网格/弹性/定位） + - 组件排列（导航栏、卡片、按钮、图标） + - 颜色（Neon Pulse 规范：#000000 背景、#ffb3b5 粉色、#e8b3ff 紫色、#00dce5 青色） + - 间距（内边距、外边距、元素间距） + - 字体（大小、粗细、颜色） + - 图标（是否存在、是否 emoji 替代、是否损坏） ``` ### 1.D 差异分级 -同 HTML 原型版： - | 级别 | 标准 | 示例 | |------|------|------| | 🔴 严重 | 布局结构不同、关键组件缺失 | 原型有两列布局实际一列 | | 🟡 中等 | 颜色/间距偏差、图标不一致 | 卡片圆角不一致 | | 🟢 轻微 | 微小像素差异 | 1-2px 偏移 | +### 1.E PAGE GATE-CHECK ⛔（每页门禁） + +**每页对比完成后必须执行门禁检查。不通过则阻断，进入修复循环。** + +``` +GATE-CHECK 规则: +├── 🔴 critical_count > 0 → FIX REQUIRED（阻断） +├── 🟡 moderate_count > 3 → FIX REQUIRED（阻断） +└── 🟢 匹配或轻微差异 → PASS（放行） + +通过条件: critical_count == 0 AND moderate_count <= 3 +``` + +### 1.F AUTO-FIX LOOP（每页修复循环，max 3x） + +门禁未通过时自动触发修复。修复后重新截图、重新对比、重新门禁。 + +``` +FIX LOOP (最多 3 轮): + F1. 分析差异描述 → 定位需要修改的代码文件 + - 移动端页面: app/mini-program/src/pages/{page}/index.vue + - 管理后台页面: app/admin/src/app/dashboard/{page}/page.tsx + - 全局样式: app/mini-program/src/App.vue 或 app/admin/src/app/globals.css + F2. 修改代码（CSS/组件/布局/颜色） + - 使用 Edit 工具修改对应文件 + - 参照设计稿的 Neon Pulse 设计规范 + F3. 重启服务（如修改了后端或需要刷新构建） + - Bash: pm2 restart mini-h5（移动端）或 pm2 restart admin（管理后台） + F4. 重截实际页面 + - Playwright: browser_navigate → browser_wait_for → browser_take_screenshot + - 保存为 {name}-actual-v{N}.png（N 为修复轮次） + F5. 重新对比（重复 1.C + 1.D） + F6. GATE-CHECK → 通过? → RECORD → NEXT PAGE + 未通过? → 重试 (回到 F1，max 3x) + + 3 轮修复后仍未通过: + → 记录为 "fix-failed"，记录剩余差异描述 + → 继续下一页（不阻塞整体流程） +``` + +### 1.G 记录结果 + +每页完成后立即更新 `pipeline-state.yaml`： + +```yaml +visual_diff_pencil: + status: in_progress + pages: + "{page_name}": + design_frame: "{frame_id}" + actual_route: "{route}" + diff_level: "match|minor|moderate|critical" + critical_count: N + moderate_count: N + minor_count: N + auto_fix_attempted: true/false + auto_fix_rounds: N + auto_fix_files: ["file1.vue", "file2.tsx"] + auto_fix_result: "PASS (N critical fixed)" | "fix-failed (remaining: ...)" + gate_check: "pass|fix-failed" +``` + --- ## Phase PVD-2: 汇总报告 ### 2.1 生成报告 -生成 `tests/e2e/screenshots/visual-diff-pencil/visual-diff-pencil-report.md`： +所有页面完成 PVD-1 循环后，生成 `tests/e2e/screenshots/visual-diff-pencil/visual-diff-pencil-report.md`： ```markdown # Visual Diff Report (Pencil MCP Direct) 生成时间: {timestamp} 对比页面数: {total_pages} -数据来源: VividSpark1.2.pen (Pencil MCP 直接导出) +数据来源: ui.pen (Pencil MCP 直接导出) +模式: 逐页门禁对比（含 AUTO-FIX 循环） ## Summary @@ -196,11 +275,21 @@ mkdir -p tests/e2e/screenshots/visual-diff-pencil | 🟢 轻微 | {minor_count} | | ✅ 匹配 | {match_count} | +## 修复统计 + +| 指标 | 数值 | +|------|------| +| 触发 AUTO-FIX 页面数 | {fix_attempted_count} | +| 修复成功页面数 | {fix_pass_count} | +| 修复失败页面数 | {fix_failed_count} | + ## 详细对比结果 -### 🔴 {page_name} -- 设计截图: `visual-diff-pencil/{name}-design.png` -- 实际截图: `visual-diff-pencil/{name}-actual.png` +### {page_name} — {gate_check_result} +- 设计截图: `{name}-design.png` +- 实际截图: `{name}-actual.png` +- 差异级别: {diff_level} +- AUTO-FIX: {auto_fix_result} - 差异描述... ... @@ -211,14 +300,19 @@ mkdir -p tests/e2e/screenshots/visual-diff-pencil ```yaml visual_diff_pencil: status: completed - total_pages: 11 - compared_pages: 11 - critical_count: 0 - moderate_count: 3 - minor_count: 5 - match_count: 3 + total_pages: {total} + compared_pages: {compared} + critical_count: {total_critical} + moderate_count: {total_moderate} + minor_count: {total_minor} + match_count: {total_match} + fix_attempted_count: {fix_attempted} + fix_pass_count: {fix_pass} + fix_failed_count: {fix_failed} + pages: + "{page_name}": { ... } # 来自 1.G 的逐页记录 report_path: "tests/e2e/screenshots/visual-diff-pencil/visual-diff-pencil-report.md" - timestamp: "2026-04-08T12:00:00Z" + timestamp: "{ISO timestamp}" ``` --- @@ -231,4 +325,6 @@ visual_diff_pencil: | 截图工具 | `mcp__pencil__export_nodes` | Playwright 访问 `localhost:8080` | | 保真度 | 100% 设计稿 | 可能有转换损耗 | | 启动依赖 | 无 | 需启动 `prototype/server.js` | +| 门禁机制 | ✅ 逐页 GATE-CHECK + AUTO-FIX | N/A | +| 修复循环 | ✅ max 3x per page | N/A | | 推荐场景 | 有 `.pen` 文件时首选 | 无 `.pen` 或需 HTML 交互时 |