# AI 协作复盘 — V4-2333 LCD 范式对齐轮（2026-07-29）

> 面向 UX 团队 / PM 内部分享。区别于实现层 handoff（做了什么）与 TVU 工程 retrospect（工程规则），本文复盘的是**人与 AI 的协作过程**：哪些轮次本可以省掉、提需求方与 AI 各自该怎么做。

---

## 1. TL;DR

| 项 | 值 |
|---|---|
| 总轮次 | owner 主动纠正 **5 轮**（设置页范式 / 选项列表范式 / 组件来源 / 参考物缺失 / 参考物落位） |
| 最终交付 | LCD 三帧照 canonical 范式重做 + 两端 REFERENCE 参考区 + 全交付层同步 |
| 核心 process gap | **4 个**（详见 §4） |
| 关键 insight | **5 轮纠正里有 4 轮的根因是同一个**：AI 把「参照最近做过的同类页」当成了「照 canonical 范式建」。范式不是"看起来像"，是**可实测的规格 + 完整的语义单元 + 正确的组件谱系**。 |
| 规则回流 | commit `99e45eb3`（gitea + github 同 hash 已核实），4 份真源 + 1 个审计脚本 |

---

## 2. Session 概览

**起点**：上一轮（2026-07-28）交付了 V4-2333 衍生轮的双端 mockup，收尾时把 F1 design-walkthrough 列成「可选待办」直接结束。本轮 owner 打开效果图第一句话是「我简单看了下 LCD 的，问题挺多的」。

**最终落地**：
- LCD `0054ib0nLmt27bC3QlGDl7`：L2 `9593:536` / L3 `9594:214` / L4 `9594:251` 就地重做（保节点 ID 与连线锚点不变）；新增 page 级 `REFERENCE` Section `9625:217`
- Config-T `rJJjWWs51n2iFOlCIC7aYG`：新增 page 级 `REFERENCE` Section `8095:517`
- 交付层全同步：caption ×3、UX 卡 Interaction/Acceptance、PRD §4b·§5b、design-spec（D1 修订 + 新增 D8）、design-record §3/§4/§7/§8、handoff §1b–§1d

**Process artifacts**：handoff 补 §1b 走查偏差表 + §1c M37 probe 表 + §1d 参考物节点索引；ledger 追加一行；DS 真源回流 4 份。

---

## 3. 时间线 / 主要迭代

| # | 轮次 | owner feedback 触发 | 改动量 |
|---|---|---|---|
| 1 | 设置页范式对齐 | 「LCD 的设置项页面参考 `8878:2` 这个格式，图标和交互行为也是一样的，保持统一」 | 走查列 7 项偏差；三帧重做（栅格 / 字体 / 下钻图标 / 底栏 / 选中标记 / hint / 标题） |
| 2 | 底栏语义定案 | 「只有 OK + Home 即可，Back 可点击左上角的返回图标，LCD 的后续需求设计都遵守这个设计逻辑」 | 推翻已拍板的 D1「即时生效无保存步骤」；新增 D8；PRD/UX 卡/caption 连锁改写 |
| 3 | 选项列表范式 | 「LCD 选项列表默认用这个方式（`5314:9520`）」 | 补齐被编辑字段绿框 + 面板落位；修选中标记压字 / z 序 / 顶边切字 |
| 4 | 组件来源 | 「OK 和 Home 等按钮用的是当前文件的组件」 | 3 个远端库 clone → file-local `LCD Button`；L4 改用真 `Status=Disabled` 变体 |
| 5 | 参考物 + 落位 | 「参考图怎么没有贴到 Figma 里面？我可以直接作为对比，包括哪些设置选项」→「Reference 跟 Before 一样，放在左侧」 | 两端建 REFERENCE Section + 逐项去向对照表；随后整体移到交付 Section 左侧 |

---

## 4. Top 4 process gap（按返工成本排序）

### G1 — 交付前跳过 F1 design-walkthrough（返工成本最高）

- **实证**：上一轮把 F1 列为「可选待办」直接收尾，7 项偏差（字体 / 行高 / 图标形状 / 底栏 / 标记压字 / hint / 标题）**全部**由 owner 在 review 时抓出。其中「选中标记压住 `1080p30`」是纯几何叠加，任何一次走查都会发现。
- **返工成本**：本轮 5 个纠正轮次里，轮 1、3 完全可以在交付前自查掉。
- **回流落点**：已在 ledger 反思段与 `domain-tvu.md` M17 实证段写明；判定语「照范式建页的任务，交付前走查不是可选项」。

### G2 — 把「参照最近做过的同类页」当成「照 canonical 范式建」

- **实证**：L2 是 clone 自 V4-2318 的 `8487:11`，不是 canonical 的 `8878:2`。行高 52 vs 42、圆圈 `›` vs 下向三角，都是从那个非 canonical 范本继承来的。
- **深层版本（轮 3、4）**：即便知道了 canonical 帧，也只挑了「视觉上最像的那个节点」——选项列表只 clone 了面板 `5314:9564`，漏掉让它「属于某一行」的字段绿框；底栏则连**组件谱系**一起 clone 错（参考帧的 `OK` 是远端库组件，LCD 该用 file-local `LCD Button`）。
- **判定语（已回流）**：范式帧只能拿它**该给的东西**——布局 / 栅格 / 图标语汇可以照搬；**组件来源必须按目标文件的谱系另行确认**；clone 要 clone **完整语义单元**，不是中间那个视觉主体。

### G3 — 参考物只以超链接形式存在，没进画布

- **实证**：MicroApps 参数面板一直只在 PRD §1 有一条超链接。owner 要比的是「参考里有哪些设置项、本轮暴露了哪几项」——这是**选项清单级**的比对，看图看不出来、点链接要跳出文件。
- **附带发现**：M37 强制的 5 行 reference probe 表上一轮也被跳过了。
- **回流落点**：`design-process.md` §参考物落地（含画布左右序、同文件 clone vs 跨文件 `upload_assets`、逐项去向对照表口径、4 条 Acceptance）。

### G4 — 已知坑靠「下次注意」防不住

- **实证 A（Q15，本 session 连踩 3 次）**：往 Section 里放节点时把坐标算错。前两次是老形态，第三次是**新形态**——不是漏减 section 原点，而是**主动多加了一次**（`title.x = sec.x + 40`），自认为在做换算。规则读过、delta 法也知道，但每次仍在手写坐标、校验靠自觉。
- **实证 B（`insertCharacters`）**：行首插入继承**上一行**整套样式，导致 PRD 一行英文变 `#000000`（深色卡上完全隐形）。该病灶 2026-07-27 V4-1827 已记为候选回流，**本轮复发**。
- **修法（已落地）**：Q15 从「提醒」改成**可照抄的 helper** `placeInSection(sec, node, relX, relY)`——设相对坐标 + 自动 probe `absoluteBoundingBox` + 越界 `throw`（脚本原子，直接回滚）；并给出一眼可查的判据「写 `child.x = <任何含 sec.x 的表达式>` 就是错的」。
- **待 owner 拍板**：`insertCharacters` 病灶已命中第 2 次，建议升为正式规则。

---

## 5. 高效对话建议（按 ROI 排序）

### 给提需求 / review 方（UX / PM）

1. **给范式时直接给节点链接，并说清"取什么"**。本轮 owner 给 `8878:2` 时补了一句「图标和交互行为也是一样的」——正是这句让 AI 去逐项实测而不是目测仿写。如果能再加一句「组件用本文件的」，轮 4 就省了。
2. **推翻既有决策时明说是推翻**。轮 2 的「只有 OK + Home 即可」实际推翻了已拍板的 D1（即时生效无保存步骤）。owner 说明了「LCD 后续需求都遵守」，AI 才知道要同时改 design-spec 并新增 D8，而不是只改图。
3. **"我要拿来对比"是关键信息**。轮 5 owner 说的是「我可以直接作为对比，包括哪些设置选项」——正因为点明了对比维度是**选项清单**，才产出了三列去向对照表；只说「把参考图贴上」的话，AI 大概率只贴图。

### 给 AI 协作流程

4. **收尾前跑 F1，别列成可选待办**。这是本轮最贵的一条。
5. **机检报错先分清「我写错了」还是「检查器覆盖不到」**。本轮 pre-commit 报 `§M17` 是孤儿，AI 先改了两次自己的引用写法都没用；真因是 `domain-tvu.md` 从不在审计脚本的 `DEF_FILES` 里，那里定义的 M3–M13 一直无法被跨文件引用。**别条件反射迁就工具**。
6. **隔离截图不能当验证依据**。白字白底的 TEXT 节点单独截图会显示成"内容丢失"，本轮据此差点误判 PRD 内容被删；真相靠读回 `characters` 长度 + `getStyledTextSegments` 才确认。
7. **做不到的事要如实说**。参考帧字体是 Verdana，但本环境 `listAvailableFontsAsync` 只返回 Roboto 家族，Verdana 物理上写不进去。这条记成了「已知偏差 5 · 未解决」，没写成「字体已统一」。

### 给 review 方看图时

8. **左对照 / 右交付的画布序，一眼就能定位**。本轮确立 `REFERENCE → BEFORE → 交付 Section` 后，打开文件从左往右读即可，不用找。

---

## 6. 已回流 / 待回流规则

| 规则 | 真源文件 | 简述 |
|---|---|---|
| **M17** LCD 设置页 canonical 范式 | `domain-tvu.md` | 参考帧 `8878:2` 实测规格表；底栏 `OK`+`Home`、返回走左上角箭头；按钮用 file-local `LCD Button`、禁用态用真变体 |
| **M17.1** LCD 选项列表 canonical 范式 | `domain-tvu.md` | 参考帧 `5314:9520`；被编辑字段绿框 + 面板右对齐该行右缘连成一体 |
| M17 与 M32 的关系说明 | `domain-tvu.md` | LCD 设备端 UI 走 file-local 是 M32 第 2 条正常落点，勿反向纠错 |
| **§参考物落地** | `design-process.md` | 画布左右序（REFERENCE → BEFORE → 交付）+ 同文件 clone vs 跨文件 `upload_assets` + 逐项去向对照表口径 + Acceptance |
| 步骤① 画布左右序 + 2 条反模式 | `design-process.md` | 参考物只留超链接 / REFERENCE 放错侧 |
| **Q15 加强** | `figma-technical-reference.md` | 新增形态 B（过度纠正）+ 判据「右手边不该出现 `sec.x`」+ canonical helper `placeInSection()` |
| `DEF_FILES` 补 `domain-tvu.md` | `scripts/audit-stale-anchors.mjs` | 修复注册表覆盖缺口 |
| 路由表 3 行 | `mockup-conventions.md` | M17 / M17.1 各一行 + M36/M37 行扩写指向 §参考物落地 |
| ⏳ **待 owner 拍板** | — | `insertCharacters(...,'BEFORE')` 行首继承上一行样式 —— 已命中第 2 次（2026-07-27 + 本轮），建议升正式规则 |

---

## 7. Model 选型（基于本 session 实证）

本 session 全程 Opus 5（1M context）。判断：

- **适合 Opus 的部分**：跨 5 轮纠正维持一致的设计决策链（D1 被推翻后要连锁改 PRD / UX 卡 / caption / design-spec 四处且不漏）、从机检报错反推出「是工具覆盖缺口不是引用写错」、把重复踩坑抽象成 helper 函数而不是又写一条提醒。
- **可下放的部分**：单纯的坐标计算、逐节点样式归一、文档表格填充——这些是机械操作，Sonnet 足够；但要求**每步都返回可复核数据**（本 session 的所有结论都带 `use_figma` 原文）。
- **不建议下放**：范式对齐类判断（什么该照搬、什么不该），本轮 4 次错都错在这个判断上，需要较强的语义分辨。

---

## 8. 给团队的 action items

1. **UX**：`domain-tvu.md` M17 / M17.1 现在是 LCD 页面设计的硬约束，下次做 LCD 需求起手先读这两条 + 打开 canonical 参考帧实测，别照最近做过的页仿写。
2. **UX**：任何有参考物的需求，起手（M37 probe 时）就把参考物贴进画布左侧的 `REFERENCE` Section，并配逐项去向对照表——不要等 review 被问。
3. **owner**：`insertCharacters` 病灶请拍板是否升为正式规则（已第 2 次）。
4. **owner 待确认**：LCD 字体不一致问题（L1 Verdana / L2–L4 Roboto）。要统一需在能加载 Verdana 的环境改，或授权把 LCD 产品帧整体迁到 Roboto（跨既有交付集，本轮无授权故未动）。

### 附录 · `use_figma` 改动统计

| 类别 | 次数 |
|---|---|
| 只读探针（范式实测 / 落点 probe / 样式复核 / 机检） | 14 |
| 写操作（三帧重做 / 组件替换 / 注释同步 / 参考区搭建 / 落位调整） | 12 |
| 因坐标或选择器出错需要修正的写操作 | 3（Q15 ×1、`name*=` 选择器带空格失效 ×1、Section z 序 ×1） |
| 图片上传（`upload_assets`） | 2 |