TL;DR

• 轮次：~8 轮 user feedback (v1 → v8) · 50+ use_figma calls
• 交付：MC + MS 双页 mockup + 10 条 UX 标注 + 13 条 polyline connector + 24 health wrapper swap
• 规则回流：4 条（library key filter / 颜色不假设 / connector workaround / read-only viewer）
• 核心 insight：

前 7 轮没读 PRODUCT_CONTEXT.md spec — v8 拿到真源一次全量重写，前面 80% 细节作废

起点 & 落地

起点：MC / MS 有早期 mockup，但 UX 交付标注是中英混合的散框，连接线乱，内容陈旧。

最终落地：

• 删 11 旧框，建 10 个 anchored 卡片（A1–A8 + A_State + A_Order）
• 13 条 polyline 折线（VECTOR + vectorNetwork — design mode 没原生 Connector）
• 24 个 health wrapper component swap 到 TVU UX Design System 库
• 3 份产品 decisions 文档落地

时间线（精选 6 个转折点）

Gap 1 · 画图前没读 spec 真源

实证：v1-v7 按"已有 mockup + 用户口头"画 — 没主动读 PRODUCT_CONTEXT.md
返工：~6 轮标注作废（v1-v7 80% 细节在 v8 重写中被覆盖）
原因：AI 信任「在场 UI + 口头反馈」 > 「未读 spec 文件」

解决方案：

• 当下修复：v8 按 PRODUCT_CONTEXT.md 全量重写 10 条标注（术语 Enterprise→Company / 4-state 平铺→3 个 type-specific 状态机 / 删伪造 default sort + XL/L/M breakpoint）
• 长期防护：@TVU mockup skill Phase 0 强制 read product context spec → 把"术语 / 状态机 / cardinality"清单贴 user verify 后才能调 use_figma
• 真源落地： 待回流 tvu-design-mockup skill SKILL.md（已 2 例：Video Sync + 本 session）

Gap 2 · A_State 颜色凭印象写

实证：我默认 on-air = 绿（运行中）— 错。页面真值：On-air=#ea4233 红 / Preview=#2fb54e 绿 / Analyzing=蓝 / Inactive=灰
返工：A_State 整段重写 + cross-context 红绿色复用警告
原因：UX 交付的颜色含义 = 产品规范，不允许 AI 凭直觉

解决方案：

• 当下修复：getFills 抓页面 Counter Pills / State Pill / Card badge 真色 → setRangeFills 让每行 ● dot 渲染真色 + 加 cross-context 红绿色复用警告
• 长期防护：写任何产品语义颜色描述前强制 probe目标节点真值 → 贴出"我抓到的真值是 X"给 user verify 再写交付
• 真源落地： 已落 TVU mockup-conventions.md "颜色含义不假设" 规则

Gap 3 · TVU library key 混淆

实证：两个名字很像的独立库 — TVU UX Library（旧）vs TVU UX Design System（新），component 名几乎一样但 libraryKey 不同
返工：24 health wrapper 全 swap 一遍 + decision log + PRODUCT_CONTEXT 双向更新
原因：search_design_system 默认跨库返回，AI 不会自动校验 libraryKey

解决方案：

• 当下修复：24 个 health wrapper swap 到 TVU UX Design System 库 + Success/warning/Error 三态绑色 variable（UX/Brand/Brand / UX/Orange/Default / UX/Red/Default）
• 长期防护：search_design_system 任何写操作前显式传 includeLibraryKeys 锁库；search 后贴"我从 <libraryKey> 拿到 X" 给 user verify
• 真源落地： 已落 TVU retrospection 2026-05-11-library-key-confusion.md + figma-technical-reference.md

Gap 4 · Master Console = 监控页

实证：v1-v5 当 MC 和 MS 是 1:1 镜像页面画 — 留了 8 个 + New Session 按钮 + 16 个 Clone 图标 + URL placeholder 可编辑。v6 用户纠正：「MC 纯查看 / New Session 和 Clone 只在 MS」
返工：29 个元素隐藏 + A4 标注重写按 MC vs MS 分列
原因：cardinality 问题 — MC/MS 是 viewer/editor 不是 1:1 镜像。和 Video Sync session 同模式

解决方案：

• 当下修复：隐藏 8 + New Session + 16 Clone + 5 URL → "—"；A4 重写为 MC（read-only viewer）vs MS（CRUD editor）差异表
• 长期防护：起手必问 5 个 cardinality 问题 — (1) viewer/editor (2) 1:1/1:N/N:N (3) 状态机数+触发者 (4) 默认规则来源 (5) 多页之间关系
• 真源落地： 产品 decision 已落 docs/decisions/2026-05-09-master-console-readonly.md； M-CARDINALITY 5 问待累积第 3 例上 design-process.md

Gap 5 · Connector design mode 限制

实证：v2 改折线 connector，v4 发现 abs 位置错位（用 v.x/y 直接设导致页级绝对坐标错）
返工：~3 轮 connector 重绘 + 1 轮 abs 坐标 bug 修复
原因：Figma plugin API 在 design mode 不允许 CONNECTOR 节点（只 FigJam 支持）— AI 按 FigJam 经验直接试报错才转向

解决方案：

• 当下修复：用 VECTOR + vectorNetwork 双 vertex + 端点 strokeCap = ARROW_LINES 模拟 connector；abs 坐标用 relativeTransform 替代 v.x/y 直设；每条 connector 用 setSharedPluginData('uxAnno','meta',JSON) 存 anchor
• 长期防护：design mode 写 connector 类需求前先查 figma-technical-reference.md Connector workaround 段；半自动 routing pattern（"用户拖节点 + rebuild" → 脚本读 metadata → fetch → 重画）成为标准
• 真源落地： 已落 TVU figma-technical-reference.md "Connector workaround" 段

给 UX / PM（提需求方）

(1) 第一句话就交 spec 真源路径

"给 MC / MS 加交付标注，全英化"

"给 MC / MS 加交付标注，全英化，先读 docs/MICROAPPS_PRODUCT_CONTEXT.md §3-5 的产品术语 / 状态机 / 3-type action matrix，确认理解后再画"

给 UX / PM（续）

(2) 颜色 / 术语 / 状态机 = 产品规范，要求 AI probe

让 AI 自己决定 on-air 是红还是绿

"State 列颜色从页面 Counter Pills getFills 抓真值，不要凭印象写"

给 AI 协作流程

(3) Phase 0 强制 read product context 真源
@TVU mockup skill 应检查 cwd docs/ 下是否有 product spec，有就先读。

(4) 产品语义字段强制 probe
颜色含义 / 状态名 / 术语都必须从现有节点抓真值，不允许"based on common UX patterns"推理。

给 PM / Stakeholder（review 方）

(5) Cardinality checklist 上墙

Review 时先过 4 问：

1. 这页是 viewer 还是 editor？
2. 对象之间 1:1 / 1:N / N:N？
3. 状态机几个 state？谁能触发？
4. 默认排序 / 默认过滤是 产品决策还是 AI 推理？

已落回流（4 条）

待回流（累积触发）

• Phase 0 强制 read product context（已 2 例：Video Sync + 本 session）
• M-CARDINALITY 起手必问 5 问题（已 2 例，待累积第 3 例）

Opus vs Sonnet vs Haiku

Hybrid：Opus plan owner + Sonnet executor
本 session 全 Opus 跑 → 估算可省 ~40% token

Action Items

1. 起手交付 spec 真源

UX / PM 在 task 第一句话里给具体路径 + 段号，不依赖 AI 找。

2. 产品语义字段强制 probe

AI 写颜色 / 状态 / 术语前必须 getFills / getCharacters 抓现有节点真值，写完贴出真值给 user verify。

3. Cardinality checklist 上墙

Review 时先过 4 问，不在 v6 / v7 才发现架构错了。