IR 技术：在网页视觉转换中的应用

1. 背景：大模型设计的 UI/UE 如何落地私有框架

核心问题：大模型已经能高质量地"设计"UI/UE——直接产出可运行的 HTML 原型 （我们的全部原型即由 LLM 生成）。但企业内部的落地目标往往是私有技术框架 （自研组件引擎、私有组件库），二者之间隔着组件模型、样式体系与布局引擎的巨大差异。 "设计产出"到"框架程序"之间的转换效率，决定了设计迭代能否当天生效。

1.1 常用技术路径对比

1.2 最终选择：IR（中间表示）

这是编译器的经典思路：前端语言无关，后端目标无关。 任何来源（HTML/CSS 原型、未来的设计稿格式）都编译成同一份 IR； IR 再由各自的代码生成器输出到任意私有框架。选它的三个决定性理由：

1. 确定性：转换是纯函数式的编译过程，同一输入永远同一输出——LLM 只负责"设计"，落地交给工具链；
2. 可审计：IR 与产物同构，质量指标（文本承载率、样式保真率）可自动对账、可接 CI；
3. 可演进：引擎 API 变化只影响"IR → 框架"一层的映射表，前端提取层完全不动。

1.3 OODUI 框架简介

OODUI 是自研的移动端优先 UI 引擎，本管的转换目标即它：

• 组件 = 虚拟节点树：每个组件（ood.UI.Block / Label / Button / Gallery / List / ToolBar…） 由模板定义若干虚拟节点（KEY 根节点、CAPTION 文本、ICON、BORDER、PANEL 内层容器…）， 样式与内容必须"投递"到正确的虚拟节点才会生效；
• 样式 = CS：组件级自定义样式，按虚拟节点键下发（对 KEY/BORDER 可靠，个别键有坑，见 §3）；
• 布局：列布局 conLayoutColumns + dock 停靠 + 绝对定位三件套， 与浏览器 flex 不等价；
• 载体：组件树以 .cls（JSON）描述，服务端反序列化后由 showModule 渲染进 DOM。

1.4 为什么还需要"一层"IR，而不是直转

直转器（HTML 直接映射组件）很快撞上三堵墙：

• 样式真相分散——外部 CSS、<style> 块、内联 style 三处叠加，还要经过级联与特异性排序；
• 无法审计——没有与产物同构的中间表示，"字号保真率多少"这类问题无法回答；
• 判定无落脚点——"6 个同构卡片应聚合成 Gallery"这类判断需要同时看结构、样式与内容。

IR（中间表示）把这三件事一次性编译完成：先物化出每个节点的计算样式与规范化结构， 后续所有语义判定、组件映射、审计对账都只依赖 IR、只读不猜。

2. 管线总览

图 1 ｜ 五级管线与三条保障带、审计闭环

提取层 html2ir.mjs 把 CSS 级联 + 内联 style 展开为每节点的计算样式； 语义层 semantic2ouc.mjs 完成角色推断、组件映射与样式注入，产出 .ouc.json， 服务端反序列化为 .cls 组件树交引擎渲染。

2.1 IR 节点结构（技术细节）

图 2 ｜ IRNode 字段与三大消费方

{
  "tag": "section", "classes": ["gt-stat-grid"],
  "children": [ /* 规范化 DOM 树 */ ],
  "icon": "ri-user-line", "src": null,
  "text": ["872", "刷题总数"],
  "style": {
    "layout":     { "display": "grid", "position": "absolute", "top": "0" },
    "paint":      { "background": "linear-gradient(...)", "color": "#fff" },
    "typography": { "font-size": "1.667em", "font-weight": "700" },
    "box":        { "width": "394px", "border-radius": "1em" }
  }
}

级联展开算法：收集所有命中节点的规则（外部 CSS 按 specificity × 出现序、 <style> 次之、内联 style 最高），排序后逐属性覆盖写入 flat， 再按属性分类归入四组。这一步等价于浏览器 getComputedStyle 的离线实现， 是整条管线的地基——初版漏掉内联 style 时，字号/颜色覆盖率长期失真、进度条完全无法识别。

3. 角色推断：判定链（顺序即语义）

图 3 ｜ inferRole 从上到下短路命中；三个历史事故全部源于顺序错误

⚠ 同构签名 = tag + classes（阈值 ≥3），类名仅用于结构分组、严禁参与语义推断； 复杂子项（item 内层仍是列表）递归拆分为嵌套节点，避免整段内容被压扁丢弃。

3.1 组件转换类型对照表

对照表各槽位在真实页面上的落地效果——首页集中了 Banner、Gallery 宫格、统计组、List、ToolBar 五类组件：

首页 ｜ 左：HTML 原型，右：产物在 OODUI 引擎渲染（HeroBanner + GridGroup + StatGroup + List + TabBar）

个人中心 ｜ 两组 StatGroup（含彩色数值）与 NavList，"value 会渲染"结论的来源页面

4. 布局归一与审计闭环

容器布局只有两种合法形态：A 自由布局（conLayoutColumns:1，子节点交引擎列布局）、 B 绝对定位（展示型容器，工具从 IR 算出子节点 left/top/height 显式下发）。 配套约束：容器去 padding（折进子坐标防双计）、去 flex/gap 无效属性但 display 必须定为 block。

审计闭环：IR 与产物同构，审计工具逐页量化文本/图标承载与样式保真。 修复一轮后（17 页）：文本 81.1%→86.2%、图标 49.5%→80.4%、空壳组件 29→0。 宿主页 ?probe=1 输出组件 computed box+背景、?shot=1 支持无头截图—— 所有观察都可复现。

布局归一的效果在"视频课程"页最为直观：顶部深红渐变 Banner（HeroBanner）满宽上色、 分区卡片（Panel + Gallery）撑满列宽——这两处正是"白 PANEL 盖渐变"与"壳层收缩"两个通病的主战场：

视频课程 ｜ 布局归一后的 Banner 渐变与满宽卡片

5. 转换质量实拍：多组件嵌套页面

智能家居首页覆盖了问候区、快捷场景宫格、房间 2×2 宫格与设备列表的嵌套组合， 是多组件协同转换的代表性页面（首页/个人中心/视频课程的截图已按主题分布在前文 §3、§4）：

智能家居 ｜ 场景宫格、房间 2×2 宫格、设备列表（左原型 / 右引擎渲染）

剩余差距：Banner 内头像/图标定位有偏差；无头环境图标字体偶发缺字。均在审计"未解决"清单中。

6. 方法论小结

1. 中间表示是审计的前提：没有同构 IR，"转换质量"只能是主观印象；
2. 判定顺序是语义的一部分，要像接口契约一样对待并注释清楚；
3. 对引擎每个字段约定都要追溯到模板源码，猜槽位 = 静默丢数据；
4. 样式真相一次性物化（级联+内联+特异性），之后只读不猜；
5. 不可重现的观察不算证据：缓存、时序、截图都要做成确定性开关。

7. 下一步

• 用几何审计（computed box 对比）把 Banner 子元素定位误差量化进指标；
• 组件能力缺口（卡片多槽位、列表双图标、圆形、进度条）已提交引擎侧评估；
• 审计报告接入 CI，指标回退即阻断合入。

—— 完 ——