2026-04-13 22:23:53 +08:00
1 changed files with 126 additions and 30 deletions
--- 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 交互时 |