# UI 走查工具 · 技术现状总结 > 更新时间:2026-05-25 > 分支:feature/local-measure > 服务:主 5050 / 实验 5051 --- ## 一、架构总览 ``` ┌─────────────┐ ┌──────────────┐ ┌───────────────┐ │ Figma API │ │ 截图 (PNG) │ │ PaddleOCR │ │ 节点树 │ │ impl_input │ │ 文字识别 │ └──────┬──────┘ └──────┬───────┘ └───────┬───────┘ │ │ │ ▼ ▼ ▼ ┌──────────────────────────────────────────────────────┐ │ alignment.py — 截图对齐到设计画布 │ │ (OCR 锚点平移 / ORB warpAffine) │ └──────────────────────────┬───────────────────────────┘ │ ┌───────────────┼───────────────┐ ▼ ▼ ▼ ┌──────────────┐ ┌────────────┐ ┌──────────────┐ │ 颜色走查 │ │ 模块内部 │ │ 手动对比 │ │ figma_color_ │ │ 测量 V3 │ │ manual_ │ │ check.py │ │ local_ │ │ compare │ │ │ │ measure.py │ │ (webapp.py) │ └──────┬───────┘ └─────┬──────┘ └──────┬───────┘ │ │ │ ▼ ▼ ▼ ┌──────────────────────────────────────────────┐ │ visualize_icar.py — HTML 报告生成 │ │ webapp.py — Flask 服务 (5050/5051) │ └──────────────────────────────────────────────┘ ``` ### 核心文件 | 文件 | 行数 | 职责 | |------|------|------| | `src/local_measure.py` | 1428 | 模块内部测量(V1 + V3),层级分片、聚合 | | `visualize_icar.py` | 2513 | HTML 报告生成,crop 标注,findings 表 | | `src/figma_color_check.py` | 1135 | OCR 封装、颜色对比、填充/描边/圆角走查 | | `webapp.py` | 722 | Flask 服务、手动对比接口、运行管理 | | `src/alignment.py` | 216 | 截图 → 设计画布对齐 | ### 关键常量 | 常量 | 值 | 含义 | |------|-----|------| | `EXPORT_SCALE` | 2 | Figma 导出倍率,Figma px × 2 = canvas px | | `DIFF_TOL_FIG` | 5.0 | 差异容忍阈值(Figma px) | | `ANCHOR_FUZZY_RATIO` | 0.85 | OCR 文字匹配相似度阈值 | | `PAIR_MAX_NORM_DIST` | 0.25 | 归一化位置配对最大距离 | --- ## 二、已完成能力 ### 2.1 基础设施 | 能力 | 文件 | 说明 | |------|------|------| | Figma 节点树获取 | `figma_client.py` | API 拉取 + `figma_root.json` 持久化 | | 设计稿导出 @2× | `figma_client.py` | PNG 导出,`EXPORT_SCALE=2` | | 截图对齐 | `alignment.py` | OCR 锚点平移 或 ORB warpAffine | | OCR 文字检测 | `figma_color_check.py` | PaddleOCR → `{text, bbox_canvas, height_fig}` | | 颜色走查 | `figma_color_check.py` | 填充色 / 描边 / 圆角逐节点对比 | | HTML 报告 | `visualize_icar.py` | 模块卡片 + crop 标注 + findings 表 | | 实验环境隔离 | `webapp_lab.py` | 5051 端口 + `runs_lab/` 独立历史 | ### 2.2 模块内部测量(V3 — 当前版本) 三层审计架构,入口 `run_local_measure_v2()`: **层 ① 字号审计** — `_audit_font_sizes()` - 从 Figma 树提取所有 `fontSize` 声明 - 从截图 OCR 提取字高分布 - 对比:Figma 声明的字号在截图里有没有对应高度的文字 - 粒度:全局 **层 ② 间距审计** — `_audit_container_spacing()` → 分派 - 有 ≥2 个子容器 → `_audit_card_container()`(层级分片) - 无子容器 → `_audit_flat_container()`(扁平 OCR) - 粒度:每个 Figma auto-layout 容器 **层 ③ 锚点精确对比** — `_audit_anchors()` - 找 Figma 里的短文本 UI 标签("查看全部"、"进店"等) - 在截图 OCR 里找内容一致的,逐个比字高 - 粒度:单个文案 ### 2.3 层级分片(核心创新点) 解决的问题:**内容不同时的模块匹配**(设计稿"好想来" vs 截图"鸿潮汕") ``` 容器 (HORIZONTAL, gap=8) ├── 卡片1 (INSTANCE) ← Figma 子节点 bbox 作为分割线 │ ├── 标题 TEXT "好想来" │ ├── 价格 TEXT "¥268" │ └── 按钮 TEXT "进店" ├── 卡片2 (INSTANCE) │ ├── 标题 TEXT "鸿潮汕" ← 内容不同但位置结构相同 │ └── ... └── 卡片3 ... ``` **实现流程**: 1. `_extract_design_spec()` 遍历 Figma 树,为每个容器收集 `children_containers`(直接子 FRAME/INSTANCE/COMPONENT,含 bbox + TEXT 后代) 2. `_audit_card_container()` 对每张卡片: - 用子节点 `bbox_canvas` 从截图 OCR 里**分片**(只取落在该卡片区域的 OCR 项) - `_match_by_relative_position()` 归一化位置贪婪配对(不看文字内容) - 逐配对比:字号(fontSize vs OCR 高度)、内部间距(TEXT 间 gap) - 卡片间:Figma bbox 边缘间距 vs OCR 极值间距 3. `_aggregate_card_findings()` 聚合同类: - 按 `design_fig`(字号规格)分组字号 findings - 按 `_pair_idx`(间距位置)分组间距 findings - N 张卡片同一问题 → 合并为 1 条 `"14px 字号偏差(3/4张卡片)"` 4. `_audit()` 中 `covered_bboxes` 去重,避免子容器被父级和自身双重审计 ### 2.4 手动框选对比 入口:`POST /r//manual_compare` 设计稿和截图各框一个区域 → 摘要级对比(不逐 OCR 碎片配对): | 指标 | 来源 | 说明 | |------|------|------| | 选区尺寸 | 框选坐标 | 宽×高 对比 | | 文字行数 | OCR 按 Y 聚行 | 行数是否一致 | | 主要字高 | OCR bbox 高度中位数 | 整体字号偏差 | | 字高分布 | OCR 去重字高列表 | 用了哪些字号 | | 行间距 | 相邻行 bbox 间距中位数 | 排版松紧 | | Figma 参考 | 覆盖该选区的 Figma 节点 | gap + 字号规范 | --- ## 三、当前难点 ### 难点 1:内容不同时的模块匹配 ⭐ 核心 | 阶段 | 方案 | 结果 | |------|------|------| | V1 | 文字内容匹配 (`match_anchor_in_impl`) | ❌ 内容不同时完全失效 | | V2 | 空间最近邻 | ❌ 对齐偏差 20-30px 导致全部错配 | | V2 | 模板匹配 (Canny + matchTemplate) | ❌ 内容不同时边缘也不同 | | V3 | 扁平 OCR 间距审计 | ⚠️ 不分卡片,混入噪声,间距 -39px 等垃圾数据 | | **V3+** | **层级分片 + 归一化位置配对** | **✅ 按 Figma 子 bbox 分割,位置配对不看内容** | **当前状态**:基本解决。对有 ≥2 个子容器的 auto-layout 容器有效。 **残留限制**: - 非 auto-layout 容器或只有 1 个子容器 → 退回扁平模式 - 嵌套子容器(卡片内的卡片)未递归处理 - 归一化配对在卡片内只有 1 个 TEXT 时退化 ### 难点 2:OCR 噪声 **问题**:食物图片水印/装饰文字被 OCR 误检。 **当前缓解**: - 层级分片把 OCR 限制在子容器 bbox 内 - 归一化配对跳过距离 >0.35 的噪声项 **残留**:卡片内图片区域的 OCR 误检仍可能与 Figma TEXT 位置接近时误配。 ### 难点 3:非文字元素 **问题**:icon、图片、分割线等不被 OCR 检测,但影响间距测量。 **当前状态**:未处理。`_collect_text_descendants` 只收 TEXT 类型。 **可行方案**:把 VECTOR / RECTANGLE / 小 FRAME 也纳入 Figma 侧配对,用 bbox 位置匹配截图色块。不需要 ML。 ### 难点 4:对齐精度 **问题**:全局对齐误差 20-30px。 **当前缓解**:V3 只比相对值(卡片内间距、字号),不依赖绝对坐标。 ### 难点 5:输出可读性 **问题**:几十行碎片 findings。 **已解决**: - ✅ 卡片容器聚合:`"14px 字号偏差(3/4张卡片)"` 替代 3 条碎片 - ✅ 扁平容器聚合:`"间距整体偏差(5/7处)"` 替代 7 条碎片 - ✅ 手动对比重写:7 行摘要替代 15+ 行 OCR 碎片配对 --- ## 四、版本演进 ``` V1 · 内容锚定 文字内容匹配 design↔impl → 模块内 4 边距 + 文字间距 ✅ 内容一致时精确 ❌ 内容不同时完全失效 V2 · 空间 / 模板匹配(已废弃) 最近邻 + Canny 模板匹配 ❌ 对齐偏差 + 内容差异双重打击 V3 · 规范审计 三层审计:字号 / 间距 / 锚点 ⚠️ 间距层扁平 OCR 不分卡片,噪声大 V3+ · 层级分片(当前) Figma 子节点 bbox 分割 → 归一化位置配对 → 聚合输出 ✅ 内容无关,结构驱动 ✅ 输出简洁,按角色聚合 ``` --- ## 五、下一步优先级 | 优先级 | 方向 | 预估 | 价值 | |--------|------|------|------| | **P0** | 真实项目测试 + 调参 | 1-2h | 验证层级分片效果,调整配对阈值 | | **P1** | 非 TEXT 元素纳入 | 3-4h | icon/图片参与间距,覆盖面 +30% | | **P1** | 清理 V1/V2 死代码 | 1h | `run_local_measure` / `measure_local` 等 | | **P2** | 嵌套子容器递归 | 2-3h | 卡片内的卡片 | | **P2** | 对齐质量检测 | 2h | 对齐差时自动降级到纯 spec 审计 | | **P3** | 多模态 LLM 兜底 | 4-6h | 可疑区域 crop → Claude Vision 二次确认 | --- ## 六、关键函数索引 | 函数 | 行号 | 用途 | |------|------|------| | `run_local_measure_v2()` | L737 | V3 主入口 | | `_extract_design_spec()` | L766 | 提取 Figma 设计规范(含子容器层级) | | `_audit()` | L886 | 三层审计调度 | | `_audit_font_sizes()` | L968 | 层① 字号审计 | | `_audit_container_spacing()` | L1013 | 层② 间距分派(card / flat) | | `_match_by_relative_position()` | L1027 | 归一化位置配对(内容无关) | | `_audit_card_container()` | L1076 | 卡片容器层级分片审计 | | `_aggregate_card_findings()` | L1226 | 同类 findings 跨卡片聚合 | | `_audit_flat_container()` | L1289 | 扁平容器 OCR 间距审计 | | `_audit_anchors()` | L1364 | 层③ 固定文案锚点对比 | | `manual_compare()` | webapp L358 | 手动框选摘要级对比 |