@@ -4,12 +4,12 @@ title: "把蓝湖验收写成工程流程：如何让 AI 自动化完成 UI 审
 date: 2026-05-15 14:00:00 +0800
 categories: [技术, AI]
 tags: [Lanhu, UI, Design Token, Android, Flutter, HarmonyOS, AI Agent]
-description: "蓝湖稿还原不应是依靠人眼的截图比对游戏。走向自动化 UI 验收的关键，是向 AI 提供结构化的设计数据与页面级盒模型，让大语言模型通过映射 Token 和运行态约束，实现精准的代码级审核。"
+description: "蓝湖稿还原不应是依靠人眼的截图比对游戏。走向自动化 UI 验收的关键，是向 AI 提供结构化设计数据、页面级盒模型、背景归属链和运行态约束，让大语言模型完成稳定的代码级审核。"
 ---
 
-蓝湖稿 UI 还原最常见的误区，是把验收简化为「让人眼确认与截图看起来差不多」。这种判断成本高、误差大：文本节点位置看似正确，父容器外边距可能依然错误；颜色十六进制值相同，Design Token 语义可能已经偏离。
+蓝湖稿 UI 还原最常见的误区，是把验收简化为「让人眼确认与截图看起来差不多」。这种判断成本高、误差大：文本节点位置看似正确，父容器外边距可能依然错误；颜色十六进制值相同，Design Token 语义可能已经偏离；长列表截图看不出问题，短内容或空列表时才暴露底部空白底色错误。
 
-更具工程前瞻性的做法，是把 UI 验收拆解为机器可读的工作流。只有以蓝湖结构化数据为规格，以页面级盒模型为检查对象，才能将大语言模型（LLM）或 AI Agent 引入验收环节，真正实现高精度的自动化 UI 审核。
+更稳定的做法，是把 UI 验收拆解为机器可读的工作流。只有以蓝湖结构化数据为规格，以页面级盒模型和背景归属链为检查对象，才能将大语言模型（LLM）或 AI Agent 引入验收环节，完成高精度的自动化 UI 审核。
 
 ---
 
@@ -24,7 +24,9 @@ UI 还原的误差通常不源于单个属性的绝对值错误，而源于属
 - 首个内容模块的 `layout_marginTop=8dp`。
 - 列表 Header 生成的间距。
 
-在单纯的截图对比中，这几种方式的视觉结果完全相同。即使是先进的多模态视觉大模型（Vision Model），仅凭两张截图也极难判定底层实现是否合理。后续一旦涉及视图隐藏、列表复用或主题切换，布局差异就会暴露。因此，想要让 AI 准确审核代码，不能仅输入视觉截图，必须为其提供精确的节点结构上下文。
+再比如，设计稿要求页面使用某个「页面背景 Token」，代码中可能是 Activity 根、Fragment 根、Tab 容器、刷新容器、RecyclerView 父容器或 Item 根节点中的任意一层在提供最终可见颜色。长列表被 Item 填满时，截图可能看不出差异；内容不足一屏、空列表、加载态或切换 Tab 后，错误的父级背景才会露出来。
+
+在单纯的截图对比中，这些实现方式的视觉结果可能完全相同。即使是先进的多模态视觉大模型（Vision Model），仅凭两张截图也很难判定底层实现是否合理。后续一旦涉及视图隐藏、列表复用、短内容、空状态或主题切换，布局和背景差异就会暴露。因此，让 AI 准确审核代码，不能仅输入视觉截图，必须提供精确的节点结构上下文。
 
 ---
 
@@ -41,6 +43,8 @@ agent -> analyze(include: html, tokens, layout, layers, codebase)
 对于 `detailDetach` 类型的 URL，AI 需要完整提取所有设计节点。将这些结构化信息作为 Prompt 注入，AI 就能明确以下工程标准：
 
 - 页面根容器宽度、背景色、模块边界。
+- 从窗口根到 Item 根的背景归属关系。
+- 短内容、空列表、加载态、隐藏模块和底部空白区域的最终可见颜色。
 - 每个可见模块的外边距、内边距、宽高、圆角和背景。
 - 文字的字体族、字号、行高、字重、颜色和截断规则。
 - Design Token 名称，而不只是渲染后的十六进制硬编码。
@@ -53,26 +57,52 @@ UI 缺陷反复修改却难以修复的根本原因，通常是只关注了子
 
 | 属性 | 蓝湖规范 | 静态代码提取值 | 审核判定 | AI 处理建议 |
 |---|---|---|---|---|
+| 底部空白区域底色 | 页面背景 Token | 父容器使用旧背景资源，列表透明 | 空列表时露出错误底色 | 将页面背景放到父容器 |
 | 页面卡片左右边距 | `8dp` | `16dp` | 不符合同页基准 `8dp` | 建议修改为 `8dp` |
-| 卡片背景 | `jz_b1` | `@color/bg_level1` | Token 语义不匹配 | 建议替换为 `@color/jz_b1` |
+| 卡片背景 | 卡片背景 Token | 旧卡片背景资源 | Token 语义不匹配 | 建议替换为语义匹配资源 |
 | 标题字重 | `Medium` | `TextView` 默认 | 缺失字重声明 | 建议添加 `font_weight="medium"` |
 
 通过明确指令约束 AI 生成该检查表，不仅能覆盖内部的文本和图片节点，更能强制 AI 检查页面背景、Header 高度、列表视口边距等全局维度。完成盒模型的结构化梳理后，AI 就能准确界定 UI 偏差究竟属于间距、排版、约束关系，还是资源类型的错误。
 
 ---
 
+## 背景归属：底色不是列表项属性
+
+新版蓝湖验收流程中，背景和底色需要作为一等检查对象处理。页面底色并不总是由当前可见的卡片或列表项决定，真正需要审查的是从外到内的背景归属链。
+
+典型背景归属链如下：
+
+```text
+Activity/window root
+-> Fragment/page root
+-> Tab/page container
+-> refresh/layout parent
+-> RecyclerView/ListView/ScrollView
+-> item/module root
+```
+
+每一层都需要记录三件事：是否显式设置背景、透明时继承哪一层颜色、最终暴露给用户的颜色是什么。尤其在 Android 列表页中，RecyclerView 通常应保持透明，页面底色由父容器或页面根节点承担；卡片和模块背景则属于 Item 或模块根节点。把页面底色直接涂到列表控件上，可能掩盖短内容和空状态问题，也可能破坏同一页面内不同 Tab 的背景语义。
+
+底部空白区域是最容易漏掉的检查点。短内容、空列表、加载态、模块隐藏、最后一个 Item 下方 padding、列表 overscroll，都可能暴露真实页面背景。只验证长列表满屏状态，不能证明页面底色正确。
+
+因此，背景检查至少应覆盖：
+
+- Activity 根、Fragment 根、Tab 容器、刷新容器、列表控件和 Item 根节点。
+- 短内容、空列表、加载态、隐藏模块和 Tab 切换后的可见底色。
+- RecyclerView/ListView/ScrollView 的透明默认值，以及父容器是否承担设计稿要求的页面背景。
+- 每个背景 Token 的日间、夜间或皮肤覆盖资源。
+
+---
+
 ## Design Token：将语义审核交给代码分析
 
 当蓝湖数据包含命名 Token 时，必须要求 AI 将 Token 名称作为还原规格。
 
-例如，蓝湖给出 `白皮/背景色/jz_b1`，代码中存在两个当前值相同的资源：
+例如，蓝湖给出一个「卡片背景 Token」，代码中同时存在「语义匹配资源」和「旧版近似资源」。二者当前渲染值可能相同，但语义并不一定相同。
 
-```xml
-@color/jz_b1
-@color/jz_color_v4_bg_level1
-```
+如果项目色彩规范未明确声明两者互为别名，AI 在执行静态代码分析时，应找出使用了非语义化资源的节点，并给出警告。在主题切换、深色模式适配等场景下，这种基于语义的自动化审查，能提前拦截因硬编码导致的分化问题。
 
-如果项目色彩规范未明确声明两者互为别名，AI 在执行静态代码分析时，会严格根据词法树（AST）或文本检索，找出使用了非语义化资源的节点，并给出警告。在主题切换、深色模式适配等场景下，这种基于语义的自动化审查，能提前拦截因硬编码导致的分化问题。
+背景 Token 也要按同样原则处理。即使两个资源在当前皮肤下看起来接近，只要设计稿指定的是页面背景 Token，就不能用相近旧资源或截图采样色替代。Token 的意义在于跨主题保持语义稳定，而不是只保证当前截图像素相近。
 
 ---
 
@@ -85,6 +115,7 @@ Android 的 XML、Flutter 的 Widget 树或 HarmonyOS 的 ArkUI 声明只能反
 - **数据绑定追踪**：让 AI 顺着 ViewModel 或 Controller 的执行路径，检查运行时是否会动态追加前缀、后缀或空状态占位文案。
 - **动态修饰符**：检查字重属性是否在代码中被 `setTypeface` 或 ArkUI 的修饰符错误覆盖。
 - **列表间距溯源**：在 RecyclerView 或 Flutter ListView 中，项间距可能由 Item 根布局、ItemDecoration 或分割线机制共同作用。AI 能够跨文件检索相关的 Provider 模型与装饰器代码，避免人工审核极易漏掉的间距生成源。
+- **空白态背景追踪**：列表内容不足一屏时，最终可见背景来自父容器、刷新布局还是列表控件本身，需要沿布局绑定、适配器和容器层级追到运行态。
 
 ---
 
@@ -94,12 +125,14 @@ Android 的 XML、Flutter 的 Widget 树或 HarmonyOS 的 ArkUI 声明只能反
 
 | 平台 | 几何与间距 | 字体 | AI 重点检索目标 |
 |---|---|---|---|
-| Android View/XML | `dp` | `sp` | `layout_margin`、约束关系、运行时 Typeface |
+| Android View/XML | `dp` | `sp` | `layout_margin`、约束关系、运行时 Typeface、列表父容器背景 |
 | Flutter | logical pixels | `TextStyle` | `EdgeInsets`、`SizedBox`、`FontWeight` |
-| HarmonyOS | `vp` | `fp` | `.margin`、`.padding`、父布局对齐方式 |
+| HarmonyOS | `vp` | `fp` | `.margin`、`.padding`、父布局约束 |
 
 字重（Font Weight）还原是高频误差项。若基础控件仅支持 `normal` 和 `bold` 的粗略枚举，AI 可以自动参考同类页面的工程实现惯例，提供符合项目历史规范的替换建议，而非生硬报错。
 
+对 Android 列表页还要补充一条规则：不要只看 Item XML。需要检查生成或绑定出来的根布局、刷新容器、RecyclerView/ListView 背景、`clipToPadding`、padding，以及 adapter 内容少于视口高度时露出的区域。若设计稿要求的是页面背景，通常应由父容器或页面根节点承担，而不是由透明列表控件或单个 Item 承担。
+
 ---
 
 ## 标准化 AI 验收执行清单
@@ -108,16 +141,18 @@ Android 的 XML、Flutter 的 Widget 树或 HarmonyOS 的 ArkUI 声明只能反
 
 1. **上下文注入**：向 AI 明确目标页面、交互状态、应用主题及对应的蓝湖设计节点 ID。
 2. **结构化提取**：利用 API 或自动化工具获取精确节点的 `HTML/CSS/Token` 规格。
-3. **建立校验表**：指令 AI 构建页面级盒模型检查表，全面覆盖容器约束、排版格式及 Design Token。
-4. **基准核对**：AI 自动抽查项目内 1 至 3 个同类组件，确认本地代码的实现惯例。
-5. **精准定位**：AI 输出视觉偏差分类（如：间距异常、约束关系错误或资源调用不当）。
-6. **自动化修复**：让 AI 严格按单一视觉维度，输出小范围、细粒度的代码修正补丁。
-7. **回归验证**：运行本地 UI 静态检查脚本或抓取设备截图提供最终结果比对。
+3. **建立校验表**：指令 AI 构建页面级盒模型检查表，全面覆盖容器约束、背景归属、排版格式及 Design Token。
+4. **背景归属审计**：沿窗口根、页面根、Tab 容器、刷新容器、列表和 Item 根节点记录背景来源，覆盖短内容和空列表状态。
+5. **基准核对**：AI 自动抽查项目内 1 至 3 个同类组件，确认本地代码的实现惯例。
+6. **精准定位**：AI 输出视觉偏差分类，如间距异常、背景归属错误、约束关系错误或资源调用不当。
+7. **自动化修复**：让 AI 严格按单一视觉维度，输出小范围、细粒度的代码修正补丁。
+8. **回归验证**：运行本地 UI 静态检查脚本或抓取设备截图提供最终结果比对。
 
 结论输出时，AI 报告至少需明确交代以下三项工程事实：
 
 - 页面级全局边距和各主要模块根节点的属性已全部核对完毕。
 - 列表组件涉及的动态机制（Provider/ItemDecoration 等）已通过跨文件逻辑检查。
+- 页面背景归属链、短内容底部空白区域和空列表状态已完成检查。
 - 可见文本和图标资源的加载路径，已完成从布局到运行逻辑的完整追溯。
 
 ---
@@ -130,6 +165,7 @@ Android 的 XML、Flutter 的 Widget 树或 HarmonyOS 的 ArkUI 声明只能反
 
 - 坚持以结构化数据作为唯一规格来源，严禁使用视觉截图来覆盖或推测 Token、Layout 和 Layer 的真实属性。
 - 遵循自顶向下的检查路径，优先审查页面级盒模型与容器约束，其次再排查子控件的细枝末节。
+- 把背景和底色纳入页面级审计，沿窗口根、页面根、Tab 容器、刷新容器、列表和 Item 根节点确认归属。
 - 突破静态代码文件的限制，将布局追踪至运行态的数据绑定、列表动态生成逻辑以及主题资源的加载过程。
 
 通过上述工程化流程的处理，UI 缺陷的拦截将真正摆脱人工直觉的不可靠性。每一次布局改动都可以在代码评审（Code Review）阶段被 AI 代理自动拦截，并提供具备设计理论值和代码坐标的修正建议。唯有如此，高精度的视觉还原才能在复杂的业务迭代中保持极高的稳定性。