# Embedded Audio X/Y 矩阵 mockup — AI 协作过程复盘（内部分享）

> **Jira**: V4-2285（外部音频嵌入任意 SDI）+ V4-2286（支持 4/8CH 外接设备）
> **Figma**: `rJJjWWs51n2iFOlCIC7aYG` · page `6716:2`（V4 → To be confirmed）· Section `6748:443`
> **日期**: 2026-06-22（续 2026-06-18 的 X/Y 矩阵 session）
> **受众**: UX 团队 / PM 内部分享 —— 复盘的是 **AI 与用户的协作过程**，不是实现细节 handoff。

---

## 1. TL;DR

- **总轮次**：约 30+ 轮工具交互 + 8 次用户决策（AskUserQuestion）+ 4 次用户中途插话/手改。
- **最终交付**：Embedded Audio X/Y 矩阵从「2 列改造起点」推进到接近交付——7 个矩阵（主矩阵 + Hover 对比卡 + 5 状态稿）全部撑宽 480 与集成页 Audio Mapping 的 Transmitter dropdown 等宽对齐；UX 交付说明、5 张运行态状态稿、DS Notification 弹窗、Jira 组件改正、Hover 十字高亮重构全部落地。
- **核心 process gap 数**：6 个（按返工成本见 §4），最贵的是 **MCP 污染骗过了截图抽查**。
- **关键 insight**：**subagent 的回报 + 它自己存的截图都不可信，抽查 Figma 交付必须用 `get_metadata` 验关键属性**——本 session 因为信了 subagent 截图（显示 "Src CH1-2"），漏掉了「Src 列头根本没生效 + 主矩阵 col-header 被改坏」，直到几轮后用户提对齐需求、我用 get_metadata 调查才发现。

---

## 2. Session 概览

- **起点**：续跑记忆 `embedded-audio-xy-matrix-progress.md`，X/Y 矩阵模型已锁定，待办 = 删旧交付说明 / 设备名一致性 / 补状态稿 / 走查 / 总闸。
- **最终落地**：上述待办全做完 + 用户后续追加的「撑宽对齐 Audio Mapping / CH 加空格 / 去 Src·Output / Hover 十字清晰化 / page 移回分组」全部完成。
- **Process artifacts**：记忆更新（含 page 移位纪律 + MCP 污染再实证）、work log（2 条）、本复盘、续跑 prompt。

---

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

| # | 阶段 | 用户 feedback 触发 | 改动量 |
|---|---|---|---|
| 1 | 删旧 routing-list 交付说明 6728:443 | 续跑待办 | 1 删除 |
| 2 | 矩阵 4→2 列 + 超级表头 UMC404HD（主矩阵+Hover） | AskUserQuestion：跟随真实设备 4CH=2列 | 删 40 cell + 文字 |
| 3 | UX 说明加「Source channels 2/4/8CH」小节 | 用户要在已有基础上更新 | clone 3 节点 |
| 4 | 补 3 状态稿（subagent，401 中途挂但做完） | AskUserQuestion：补全部 3 个 | 3 clone + 改造 |
| 5 | F1 design-walkthrough（subagent）→ 修 6 findings | 走查协议 | report + 6 修复 |
| 6 | 查 Jira → 6750:11/21 误挂 V4-1865 → 改 V4-2285/2286 | AskUserQuestion：我去查 | Jira 组件改号 |
| 7 | F2 persona（subagent）→ 修 3 项（subagent） | 走查协议 + AskUserQuestion | report + 3 修复 |
| 8 | 机械总闸（token 过期→更新→sync 撑爆→子 audit 局部跑） | 用户提供新 token | 子 audit ×N |
| 9 | overlap 修复 Jira-PRD（下移 144px） | 机检 FAIL | 移 3 节点 |
| 10 | **撑宽 480 对齐 Audio Mapping**（调查中发现 F2 改坏的 col-header） | 用户：参考 col-header 对齐 | 拆 bug + 7 矩阵撑宽 |
| 11 | CH 加空格 / 去 Src·Output / 重排状态稿 / Hover 十字重构 | 用户连续手改+反馈 | 文字 + 重排 + overlay |
| 12 | page 6716:2 移回 To be confirmed 分组 | 用户：怎么挪到别处了 | insertChild 移回 |
| 13 | **手搓色 → 库现成变量绑定**（Hover 十字白 ×2 + 选中绿底 cell ×7；Tips 灰证早已绑） | 续跑待办 + AskUserQuestion：用库现成变量 | teamLibrary 导入 + setBoundVariableForPaint ×9（+ opacity 修回 2 步） |

---

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

| # | Gap | 实证 | 返工成本 | 回流落点 |
|---|---|---|---|---|
| 1 | **MCP 污染骗过截图抽查** | F2 subagent 报告"6 矩阵改了 Src 列头"，存的截图显示 "Src CH1-2"；我抽查信了截图。实际 get_metadata 证明 Src 全没生效 + 主矩阵 col-header 被改坏成 Frame 1988+FILL 撑到 483、列错位。 | 高——几轮后才发现，需重新拆 Frame 1988 + 修 sizing + 重做撑宽 | 记忆已记；待回流 TVU：「抽查 subagent Figma 交付必用 get_metadata 验关键属性（文字/结构/sizing），不信 subagent 回报或它存的截图」 |
| 2 | **subagent 精细 Figma 操作翻车** | F2 subagent 把 col-header cell 包进新建 Frame 1988 + sizing 改 FILL（本意只是加 Src 文字）。另两次 subagent 401 中途挂（但 atomic 特性下已落地的修复完整）。 | 中——盘点 + 修复 | 待回流：「精细/纪律敏感的矩阵 cell/sizing 改动主线做 + get_metadata 验，不全交 subagent」 |
| 3 | **token/凭证过期** | subagent 401（MCP OAuth 过期，whoami 可测活）；`.env` FIGMA_TOKEN（PAT）403 Token expired。 | 中——用户重新生成 token + 重跑 | 记忆已记：起手 whoami 测凭证 |
| 4 | **sync:mockup 对超大文件撑爆** | 产品文件 66 pages，`JSON.stringify` 整文件超 V8 字符串上限（RangeError）。 | 中——改用子 audit `--node` 局部拉数据绕过 | 记忆已记；design-system 侧已有同 backlog |
| 5 | **Jira 组件挂错号** | 6750:11/21 显示 V4-1865（实为无关的"TM1100 第二 WiFi 模块"需求·已 Done）。 | 低——查 Jira 确认 + 改号 | — |
| 6 | **page 列表移位 + 节点位移** | page 6716:2 被移出 To be confirmed 到列表底部（疑 setCurrentPageAsync 副作用/协作）；AFTER 集成页因 overlap 修复下移 144px，用户一度"看不到页面"。 | 低——insertChild 移回 + 解释 | 记忆已记：操作后检查 page 位置、发现移位移回 |

---

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

**给 UX / PM 提需求方**
1. **一次性给清硬规格**：设备几进几出（UMC404HD = 4-in）、对齐意图（矩阵要不要和上方 dropdown 等宽）、文字范式（CH 带空格 / 无前缀）——本 session 这些是逐轮澄清的，导致矩阵宽度（324↔480）、列数（4↔2）、文字（Src/Output 加了又去）反复返工。
2. **位置敏感的诉求早说**：page 必须留在 To be confirmed、集成页节点不要位移——这类约束如果开头讲明，能避免 overlap 修复时的位移引发"页面不见了"的惊吓。

**给 AI 协作流程**
3. **抽查 subagent 交付用 get_metadata，不信截图**（本 session 最贵教训）。
4. **精细矩阵改动主线做**，批量/独立只读任务才外包 subagent。

**给 review 方**
5. 「page 列表位置」和「page 内节点位置」是两回事，反馈时说清是哪个。

---

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

| 规则 | 真源文件 | 状态 |
|---|---|---|
| MCP 污染骗截图实证 + 抽查用 get_metadata | 记忆 `embedded-audio-xy-matrix-progress.md` | ✅ 已记记忆；待用户拍板回流 TVU mockup-conventions（MCP 污染 sub-clause） |
| 精细矩阵改动主线做、不全交 subagent | 记忆 | 待回流 |
| page 移位检测 + insertChild 移回 | 记忆 | ✅ 已记记忆 |
| sync 撑爆 → 子 audit --node 局部跑 | 记忆 | ✅ 已记；design-system 侧有同 backlog |
| 手搓色 → 库现成变量绑定（Hover 白=`UX/Grey/grey-1`·绿底=`UX/Brand/Brand`·Tips 灰=`Color Type/Text/Tips`） | 本复盘 + handoff | ✅ 已完成（2026-06-22 续跑）；用户定用库现成变量，teamLibrary `importVariableByKeyAsync` 导入后 `setBoundVariableForPaint` 绑定（库**已有**对应现成变量，无需新增） |
| **`setBoundVariableForPaint` 重置 paint opacity→1**（同脚本内 spread 覆盖也不生效，须绑后独立赋值 `fills[i].opacity`） | handoff 工程坑段 | 待回流候选：TVU mockup-conventions / figma-use gotchas（hover 0.10 / 绿底 0.12 两次复现） |
| **binding-fidelity 局部 `--node` audit 跑通**（破「sync 撑爆跑不了」defer 前提）暴露预存 B-TYPO(21)+B-SCALE(63) | handoff Rule checklist | 非本次引入；待 owner 拍是否另开任务补 binding 完整度 |

---

## 7. Model 选型推荐

- **主线 = Opus**：本 session 大量纪律敏感判断（MCP 污染识别、col-header bug 诊断、对齐方案权衡、page 移位排查）+ 多轮用户交互澄清，需强推理 + 严守纪律。Opus 表现稳。
- **subagent = 谨慎用**：批量状态稿生成、F1/F2 走查（大输出只读/半独立）适合 subagent；但**精细 Figma cell/sizing 改动 subagent 翻车率高**（本 session F2 实证），这类应主线做。

---

## 8. 给团队的 Action Items + 附录

**Action items**
1. UX/PM：提 mockup 需求时一次性给清设备规格 / 对齐意图 / 文字范式 / 位置约束。
2. 用户拍板：§6 待回流 2 条规则是否抽象进 TVU `design-process.md` / `mockup-conventions.md`。
3. ✅ 已完成（2026-06-22 续跑）：手搓色用库**现成**变量绑定（Hover 白=`UX/Grey/grey-1`·绿底=`UX/Brand/Brand`·Tips 灰早已绑 `Color Type/Text/Tips`）——库本就有对应现成变量，无需新增。**新待 owner 拍**：binding-fidelity 局部 audit 暴露**预存** B-TYPO(21 文字未套 Text Style)+B-SCALE(63 间距/圆角未绑)，是否另开任务补 binding 完整度（部分为组件实例内部不可改）。
4. 交付 PM 前：按 6-JIRA gate 发 Jira/Slack（@PM + Section smart link + FYI 待开发负责人 + ADF 真 mention）。

**附录：use_figma 改动统计（约数）**
- 删除：旧 routing-list 交付说明 1 + 矩阵旧列 40+ cell。
- 创建/改造：UX 小节 3 节点、5 状态稿（clone+改造）、DS Notification 弹窗、Hover 十字 overlay 2 条、Jira 组件改号 2。
- 撑宽：7 矩阵 × ~20 cell resize + src-span。
- 文字：CH 加空格 ~70 处、去 Src/Output（用户手改全局）。
- 重排：状态稿 3+2 + Section 宽→3720 + page 移回。
- 机检：colors/library-origin/bilingual/overlap 子 audit（子 audit 局部跑绕过 sync 撑爆）。
- subagent：3 个（状态稿 / F1 走查 / F2 修复）+ F2 persona 评审。