Download TECH_STATUS.md from Hnnnhn/UI_review: direct link, hf CLI and curl.
- Browser
- Download file 10.9 kB
-
https://huggingface.co/spaces/Hnnnhn/UI_review/resolve/main/TECH_STATUS.md
- Command line
-
hf download hf://spaces/Hnnnhn/UI_review/TECH_STATUS.md
-
curl -L -o TECH_STATUS.md https://huggingface.co/spaces/Hnnnhn/UI_review/resolve/main/TECH_STATUS.md
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 ...
实现流程:
_extract_design_spec()遍历 Figma 树,为每个容器收集children_containers(直接子 FRAME/INSTANCE/COMPONENT,含 bbox + TEXT 后代)_audit_card_container()对每张卡片:- 用子节点
bbox_canvas从截图 OCR 里分片(只取落在该卡片区域的 OCR 项) _match_by_relative_position()归一化位置贪婪配对(不看文字内容)- 逐配对比:字号(fontSize vs OCR 高度)、内部间距(TEXT 间 gap)
- 卡片间:Figma bbox 边缘间距 vs OCR 极值间距
- 用子节点
_aggregate_card_findings()聚合同类:- 按
design_fig(字号规格)分组字号 findings - 按
_pair_idx(间距位置)分组间距 findings - N 张卡片同一问题 → 合并为 1 条
"14px 字号偏差(3/4张卡片)"
- 按
_audit()中covered_bboxes去重,避免子容器被父级和自身双重审计
2.4 手动框选对比
入口:POST /r/<run_id>/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 | 手动框选摘要级对比 |