# 差异图分析规则 - Figma组件还原视觉调试指南

## 差异图颜色含义

### 基础颜色系统（基于 pixelmatch 库）
- **红色 (255, 0, 0)** = 显著的像素差异 (diffColor)
- **黄色 (255, 255, 0)** = 抗锯齿差异 (aaColor) - 通常是文本/边缘渲染差异
- **橙色 (255, 128, 0)** = 中等程度差异 (diffColorAlt)
- **透明/无色区域** = 完全匹配的像素
- **白色/透明背景** = 两张图像都没有内容的区域

**重要**: 这不是叠加图，而是差异检测图！颜色表示差异程度，不是图像内容本身。

## 问题诊断规则

### 🚨 严重问题 (需要立即修复)

#### 1. 大面积红色区域
- **含义**: 显著的像素差异，结构性问题
- **问题**: 元素位置、尺寸或颜色严重不匹配
- **常见原因**: 
  - 布局结构错误
  - 元素尺寸差异
  - 颜色值不匹配
  - 位置严重偏移
- **修复优先级**: 最高

#### 2. 集中的红色区域  
- **含义**: 局部区域的显著差异
- **问题**: 特定元素的实现问题
- **常见原因**:
  - 单个元素缺失或多余
  - 局部布局错误
  - 特定样式不匹配
- **修复优先级**: 高

### ⚠️ 中等问题 (布局偏移)

#### 3. 橙色区域
- **含义**: 中等程度的像素差异
- **问题**: 布局或样式的中等偏差
- **常见原因**:
  - margin/padding计算错误
  - flex布局对齐问题
  - 颜色值轻微差异
  - 尺寸计算偏差
- **修复优先级**: 中

#### 4. 黄色区域（抗锯齿差异）
- **含义**: 主要是文本和边缘的渲染差异
- **问题**: 字体渲染、边缘处理差异
- **常见原因**:
  - 字体平滑算法差异
  - 边缘抗锯齿处理不同
  - 文本渲染引擎差异
  - 图形边缘处理差异
- **修复优先级**: 低（通常可接受）

## 标准分析流程

### 第一步: 差异图视觉扫描
1. **识别主要颜色区域**: 红色、橙色、黄色区域的分布和密度
2. **评估问题严重程度**: 按颜色类型和面积确定优先级
3. **定位问题区域**: 标记需要重点修复的区域
4. **记录观察结果**: 描述差异区域的位置、形状、颜色

### 第二步: 差异原因分析
1. **差异模式识别**:
   - **块状分布**: 整个元素的结构性差异（位置、尺寸、颜色）
   - **条带状分布**: 元素边界、间距的结构性偏移
   - **细线状分布**: 像素级渲染差异（抗锯齿、边缘处理）
   
2. **结构性问题分析** (块状/条带状):
   - **Figma JSON 对比**: 检查原始布局定义与实现差异
   - **sizing 属性**: hug vs fixed vs fill 的实现差异
   - **布局模式**: column/row vs flex 的行为差异
   - **定位方式**: 绝对定位 vs 相对定位的差异
   
3. **渲染问题分析** (细线状):
   - **颜色精度**: 十六进制 vs RGB 值差异
   - **字体渲染**: 抗锯齿算法差异
   - **边缘处理**: 浏览器渲染引擎差异

### 第三步: 知识库查询 (使用 Memory MCP)
**必须步骤**: 根据分析出的差异原因，使用 Memory MCP 在知识库中查询相关解决方案
1. **按症状查询**: 使用 `mcp_memory_search_nodes` 搜索差异特征关键词
2. **按还原度范围查询**: 使用 `mcp_memory_search_nodes` 查找相似还原度问题的解决方案
3. **按组件类型查询**: 使用 `mcp_memory_search_nodes` 查找类似组件的优化经验
4. **详细内容获取**: 使用 `mcp_memory_open_nodes` 获取找到节点的完整内容
5. **验证解决方案**: 确认知识库中的方案适用于当前问题

### 第四步: 根因诊断
基于差异分析和知识库查询结果，确定根本原因:
1. **结构性问题**: 元素缺失、多余、严重错位
2. **布局问题**: 位置偏移、尺寸差异、间距错误
3. **样式问题**: 颜色、字体、边框差异
4. **渲染问题**: 抗锯齿、像素精度差异

## 常见模式识别

### 模式1: 整体下移
- **表现**: 所有元素都显示红色在上，黄色在下
- **原因**: 容器padding或margin设置错误
- **解决**: 调整容器的顶部间距

### 模式2: 文本缺失
- **表现**: 文本区域只显示黄色
- **原因**: 文本未正确渲染或颜色问题
- **解决**: 检查文本样式和可见性

### 模式3: 元素溢出
- **表现**: 边缘出现纯红色条带
- **原因**: 元素尺寸超出容器
- **解决**: 调整元素尺寸或容器大小

### 模式4: 布局错位
- **表现**: 红黄色块呈对角或平行分布
- **原因**: flex布局或定位计算错误
- **解决**: 重新计算布局参数

## 修复策略优先级

### 1. 立即修复 (影响>20%还原度)
- 纯黄色区域 (元素缺失)
- 大面积纯红色区域 (严重溢出)
- 整体布局错位

### 2. 重要修复 (影响5-20%还原度)  
- 局部红黄错位
- 元素尺寸差异
- 位置偏移

### 3. 精细优化 (影响<5%还原度)
- 边缘像素差异
- 字体渲染差异
- 颜色精度差异

## 验证方法

### 修复前后对比
1. **记录修复前的差异图**
2. **应用修复方案**
3. **生成新的差异图**
4. **对比差异区域变化**
5. **验证还原度提升**

### 成功标准
- **纯色区域减少**: 黄色和红色区域明显减少
- **重叠区域增加**: 正确匹配的区域增加
- **还原度提升**: 数值提升≥2%

## 知识库查询策略

### 1. 症状关键词查询 (使用 Memory MCP)
根据差异图特征，使用 `mcp_memory_search_nodes` 搜索以下关键词:
- **红色块状差异**: `mcp_memory_search_nodes` 查询 "颜色差异", "背景色", "色值不匹配"
- **红色条带差异**: `mcp_memory_search_nodes` 查询 "边框", "outline", "border", "尺寸偏移"
- **红色点状差异**: `mcp_memory_search_nodes` 查询 "像素精度", "定位偏移", "margin", "padding"
- **橙色区域**: `mcp_memory_search_nodes` 查询 "布局偏移", "flex布局", "对齐问题"
- **黄色区域**: `mcp_memory_search_nodes` 查询 "文本渲染", "字体平滑", "抗锯齿"

### 2. 还原度范围查询 (使用 Memory MCP)
- **<90%**: `mcp_memory_search_nodes` 查询 "严重布局问题", "结构性错误"
- **90-95%**: `mcp_memory_search_nodes` 查询 "布局偏移", "尺寸差异", "盒模型"
- **95-98%**: `mcp_memory_search_nodes` 查询 "文本渲染", "像素精度", "细节优化"

### 3. 组件类型查询 (使用 Memory MCP)
- **简单布局组件**: `mcp_memory_search_nodes` 查询 "基础布局", "flex布局", "间距问题"
- **文本密集组件**: `mcp_memory_search_nodes` 查询 "文本渲染", "字体优化"
- **复杂视觉组件**: `mcp_memory_search_nodes` 查询 "复杂元素", "素材化", "切图策略"

### 4. Memory MCP 查询验证流程
1. **使用 mcp_memory_search_nodes 搜索**: 在知识图谱中搜索相关关键词
2. **使用 mcp_memory_open_nodes 读取详情**: 获取找到节点的完整内容和解决方案
3. **获取详细解决方案**: 从节点观察中提取具体的实施步骤
4. **验证适用性**: 确认解决方案适用于当前差异特征

## 调试技巧

### 1. 系统化分析流程
- **差异图分析** → **知识库查询** → **方案选择** → **实施验证**
- 每个步骤都要有明确的输出和记录
- 避免跳过知识库查询直接修复

### 2. 对比参考方法
- 将差异图与expected.png对比
- 识别缺失的元素和区域
- 确认元素的正确位置
- 记录观察到的具体差异特征

### 3. 渐进修复策略
- 一次只修复一个主要问题
- 每次修复后重新生成差异图
- 对比修复前后的差异变化
- 记录有效的修复方案到知识库

## 常见错误避免

### ❌ 错误做法
- 忽略纯色区域，只关注重叠区域
- 同时修改多个布局属性
- 不重新生成差异图就继续修复
- 把渲染差异当作布局问题处理

### ✅ 正确做法
- 优先解决纯色区域问题
- 单一变量修复，逐步验证
- 每次修复后重新对比
- 区分结构问题和渲染问题

## 完整分析示例

### 示例: DesignV1 组件 (89.58% 还原度)

#### 第一步: 差异图视觉扫描
- **观察结果**: 文本区域透明(完全匹配)，灰色方块区域显示红色差异
- **问题严重程度**: 中等(红色区域集中在方块区域)
- **主要差异区域**: 上下两排灰色方块，中间矩形边缘

#### 第二步: 差异原因分析
- **红色区域特征**: 主要在灰色方块内部，呈块状分布
- **推测原因**: 颜色值差异或轻微的位置偏移
- **影响评估**: 主要还原度损失来源

#### 第三步: 知识库查询
```
搜索关键词: "颜色差异", "灰色方块", "90%还原度"
查询结果: 
- 边框盒模型差异文档
- 颜色精度优化策略
- 布局偏移解决方案
```

#### 第四步: 根因诊断
- **确定问题**: 灰色背景色 #D9D9D9 在不同环境下渲染差异
- **选择方案**: 使用RGB值替代十六进制，微调颜色精度
- **预期效果**: 还原度提升2-3%

### 标准输出格式
每次差异分析都应该产生以下标准化输出：
1. **差异特征描述**: 颜色、位置、形状、面积
2. **知识库查询记录**: 搜索关键词、找到的相关文档
3. **根因诊断结果**: 确定的问题类型和原因
4. **修复方案选择**: 基于知识库的具体解决方案
5. **预期效果评估**: 预计的还原度提升幅度

## 总结

差异图分析是Figma组件还原的核心调试流程，标准化的分析过程包括：
1. **视觉扫描** - 识别差异区域和特征
2. **原因分析** - 推测可能的技术原因  
3. **知识库查询** - 寻找已验证的解决方案
4. **根因诊断** - 确定具体问题和修复方案

**关键原则**: 先分析，再查询，后修复。每个步骤都要有明确的输出和记录。