跳转至

P3.U-autotune-phase1-measure-v3 · XiTune 自动调音 4 Tab 重构(单体曲线 / 空间建模 / 自动构建 / 输出结果)

Worker:ClaudeC · 前端 / 部门:前端 P3-xitune / 预计:4.0d / 优先级:P0 / 状态:ready

🔍 触发与解锁链

  • 触发:用户实测 fork 1 v2(c5c2698 · 13 文件 +3000 行)不达标 · 主界面被 mini-node 占据回不到 4 Tab + 4 Tab 设计偏差。ADR-AIOS-11 v1.3 修订完成(用户 2026-05-30 11:36 拍板"确定")。
  • 解锁条件:本 fork zombie 后,Phase ⅔/4(P3.U-autotune-phase2-analyze / phase3-optimize / phase4-apply)解除前置依赖,可串行启动。

任务定义(基于 ADR-AIOS-11 v1.3)

将 stages/xitune/modes/auto/AutoModePanel.vue 4 Tab 业务流重构为用户拍板新命名:单体曲线 / 空间建模 / 自动构建 / 输出结果(详见 ADR §1.3.4 + §3.4 5 必填段 × 4 Tab)。

4 项核心需求: 1. 悬浮窗策略(ADR §2.1.7 + §2.2 第 5 项铁律):autotune 模式下任何 mini-node 调音工具仅悬浮窗打开 · 不占主画布 · 退出浮窗自动恢复 4 Tab 2. 算法链路 Tab 删除:v1.2 中独立 Tab 改为顶部状态栏 · 通道数不一致等链路错误移到底部 BottomProblems 3. 测量界面去 header:直接 Tab 显示 · Tab 1 数据回写车配(加列「是否有数据」+ 频响曲线缩略图)+ 全自动 sweep 按通道顺序(每通道 2s · 配合 e2e) 4. Workspace 改造(ADR §3.5 决策 C 混合持久化):autotune 数据全部落盘 <project>/autotune/{speaker-curves,cabin-ir,target-curves,output-presets}/ 子目录 + .xistudio manifest files.autotune 索引

完整 prompt(直接复制粘贴 worker 终端)

[U-thread]: P3.U-autotune-phase1-measure-v3
[部门]: 前端 P3-xitune
[Worker CWD]: d:/work/25_claude/workspace/AlgoDepartment/04_development/
[Occupies]: P3.K-modes-auto · P0.K-shared-meter-dock(read-only)
[优先级]: P0 · 4.0d
[ADR]: docs/08-implementation/40-aios/ADR/ADR-AIOS-11-xitune-autotune.md(v1.3)
[业务行为契约引用]: 严格对齐 ADR §3.4 5 必填段 × 4 Tab(① 输入输出 schema ② 收敛判据 ③ 失败回退 5 类 ④ 用户操作流 5 步 ⑤ 端到端真值 e2e)+ §3.5 决策 C 持久化
[参考文档]:
  - ADR-AIOS-11 v1.3 §1.3.4 4 Tab 架构 + §2.1.7 悬浮窗策略 + §2.2 第 5 项铁律 + §3.4 + §3.5
  - ADR-AIOS-05 §5.2 link by project + §6 7 后缀体系(.xipreset 沿用)
  - ADR-AIOS-12 §3.1 RMS Meter Node 5 必填段标杆(参考写法)
  - 现有 frontend_vue3/src/stages/xitune/modes/auto/AutoModePanel.vue(v2 c5c2698 实施 · 作为骨架参考 · 可大幅重构)
  - 现有 frontend_vue3/src/stages/xitune/modes/auto/useAutoTuningState.ts(状态机 · 仅扩展 · 不重写)
  - 后端就位端点(fork 1b 6055025):/api/auto_tune/vehicle_config + /measure_channel + /measure_position
  - 待扩端点(fork 1b-v2 并行):VehicleConfig schema 加 4/6 座位 + IR 持久化 schema

【背景】
v2 实测不达标根因:① 主界面被 mini-node 占据(用户回不到 4 Tab)② 4 Tab 命名/设计偏差。v1.3 修订核心:4 Tab 重命名 + 悬浮窗策略 + 决策 C 持久化 + 业务行为契约 5 必填段。

后端基础设施已 zombie(`6055025` ClaudeB):VehicleConfig + ChannelMeasure + PositionMeasure 4 端点 + 3 record + bridge 已落地 · 本 fork 直接消费。fork 1b-v2(P5.U-autotune-vehicle-config-extend · 1.0d)并行扩 schema(4/6 座位 + IR 持久化)· 不阻塞本 fork(可用 mock 先做 UI · fork 1b-v2 zombie 后切真接口)。

【执行步骤】(7 步)

Step 1 · 框架重构(0.8d)
  - 拆 v2 AutoModePanel.vue 4 Tab(车辆配置 / 算法链路 / 测量 / 计算结果)
  - 重建 4 Tab 容器:SingleSpeakerTab / CabinIRTab / AutoBuildTab / ResultTab(对齐 ADR §1.3.4 用户敲定命名)
  - 算法链路 Tab 删除 · 状态合并到顶部状态栏组件 PipelineStatusBar.vue
  - 通道数不一致等错误连到底部 BottomProblems(沿用现有 BottomProblems API · 严禁自行实装)
  - 去 header 直接 Tab 显示(v2 的 header 层移除)

Step 2 · 悬浮窗策略实装(0.6d · ADR §2.1.7)
  - 新增 useAutotuneFloatingWindow.ts composable · 管理 mini-node 悬浮窗 z-index + 多窗共存 + Esc/外部点击关闭
  - 主画布永远保留 4 Tab(z-index 低于悬浮窗)
  - autotune→manual 切 mode 时强制关闭所有悬浮窗
  - 复用现有 mini-node 弹窗组件(若有)· 否则用 P0.K-shared 的 Dialog/Drawer · 严禁在 modes/auto/ 自行实装弹窗

Step 3 · Tab 1 单体曲线(1.0d · ADR §3.4.1)
  - 通道矩阵管理(N 行 · 每行:channelId / 是否有数据 / 缩略图 / 操作按钮)
  - 频响曲线主图(已测通道叠加 · 复用 P0.K-shared FreqResponseChart read-only)
  - 测量模式 SegmentedControl:手动 / 自动(全通道 2s sweep) / 离线导入
  - 数据回写车配:hasData=true + thumbnailSvg 非空(走后端 fork 1b-v2 扩 schema)
  - 调 fork 1b 已就位端点 /api/auto_tune/measure_channel
  - 持久化:<project>/autotune/speaker-curves/<channelId>-<ts>.json + manifest 索引(走 P5)

Step 4 · Tab 2 空间建模(0.8d · ADR §3.4.2)
  - 4/6 座位 × N 通道 × M mic IR 矩阵(典型 4×16×4 = 256 IR · 矩阵可视化:行=座位 · 列=通道+mic)
  - 测试模式:手动逐 IR / 自动遍历当前座位 / 批量导入(.csv / .npy)
  - 自动测试模式 disabled(tooltip"等 fork 1c mute 编排映射" · 见 ADR §11.9)· 改用手动
  - 调 fork 1b 已就位端点 /api/auto_tune/measure_position
  - 持久化:<project>/autotune/cabin-ir/<seat>-<channel>-<mic>-<ts>.json + matrix-index.json

Step 5 · Tab 3 自动构建 + Tab 4 输出结果(0.5d · ADR §3.4.3 + §3.4.4)
  - Tab 3:位置矩阵(行=座位 · 列=指标)+ 目标曲线选择器(平直 / Harman / B&K)+ 计算/目标/偏差 3 曲线对比
  - Tab 4:对比表(行=通道 · 列=当前 / 计算 / Diff)+ 命名 preset + Apply 按钮 + rollback
  - 点击通道行 → 该通道 mini-node 悬浮窗打开 + 高亮 diff 项(联动 Step 2 useAutotuneFloatingWindow)
  - 持久化:<project>/autotune/target-curves/ + output-presets/<presetName>-<ts>.xipreset

Step 6 · 业务行为契约 5 必填段对齐 + e2e 真值脚本(0.6d)
  - 4 个 Tab 各写 1 个 vitest case 对齐 ADR §3.4 ⑤ 端到端真值
    · Tab 1:注入 1kHz 正弦 → 断言 freqResponse 1000Hz ± 50Hz · ± 1dB · 落盘 + manifest 索引
    · Tab 2:注入冲激 → 断言 IR 直达声峰值 0-5ms 内 + 长度 ≥ 48000 sample
    · Tab 3:平直 + 单位冲激 IR → 断言 deviationCurve 接近 0 · rmsDeviationDb < 1dB
    · Tab 4:计算 + Apply → 断言 .xipreset 落盘 + manifest 索引 + rollback 可用
  - 失败回退覆盖 ≥ 3 类(WS 断 / 端点崩溃 / 配置不合法)

Step 7 · 自查 + commit(0.4d)
  - npm run typecheck 全绿
  - npm run test:unit 不退化(基线见现仓 README)
  - 检查 4 Tab 命名严格对齐(单体曲线 / 空间建模 / 自动构建 / 输出结果)
  - 检查悬浮窗策略 e2e 验证(autotune 下点 mini-node → 悬浮窗 + 4 Tab 仍可见)
  - commit subject: feat(P3.U-autotune-phase1-measure-v3): rebuild 4-tab autotune UI(SingleSpeaker/CabinIR/AutoBuild/Result) + floating window + decision-C persistence + 5-段 contract e2e
  - commit trailer 三元组:[step=7/7] [pid=P3] [uid=U-autotune-phase1-measure-v3] [occupies=P3.K-modes-auto+P0.K-shared-meter-dock-read] [files=stages/xitune/modes/auto/...]

【验收】(stop 前必跑)

形式合规:
  ☐ npm run typecheck 全绿(0 error)
  ☐ npm run test:unit 不退化 + 4 个新 vitest case 全过
  ☐ 4 Tab 命名严格 = 单体曲线 / 空间建模 / 自动构建 / 输出结果
  ☐ 算法链路 Tab 不存在 · 状态在 PipelineStatusBar.vue · 错误在 BottomProblems
  ☐ 不动 stages/xitune/XiTuneStage.vue / drawers / bottom-dock(沿用 §2.2 第 3 项铁律)
  ☐ 不在 modes/auto/ 自行实装 meter / 弹窗组件(沿用 §2.2 第 2 项 + 第 5 项)

业务行为契约(端到端真值 · 必跑 · 不允许仅看 typecheck/test 形式合规):
  ☐ Tab 1 e2e:1kHz 正弦注入 → freqResponse 峰值 1000Hz ± 50Hz · ± 1dB · 落盘 + manifest
  ☐ Tab 2 e2e:冲激注入 → IR 直达声 0-5ms · 长度 ≥ 48000 · 落盘 cabin-ir/
  ☐ Tab 3 e2e:平直 + 单位冲激 → deviation ≈ 0 · rmsDeviation < 1dB
  ☐ Tab 4 e2e:计算 + Apply → .xipreset 落盘 + rollback 可用
  ☐ 悬浮窗 e2e:autotune 下点 mini-node → 悬浮窗打开 · 4 Tab 仍可见 · Esc 关闭恢复焦点

【commit】
- subject + 三元组 trailer 见 Step 7
- 7 天宽限期内三元组缺失仅 warning · 6/2 起 strict mode 硬拒

【禁止】(7 项红线)
1. ❌ 禁止改 4 Tab 命名(必须 = 单体曲线 / 空间建模 / 自动构建 / 输出结果)
2. ❌ 禁止保留算法链路 Tab(必须删 · 状态合并到顶栏 · 错误移 BottomProblems)
3. ❌ 禁止 mini-node 占主画布(autotune 下必须仅悬浮窗)
4. ❌ 禁止动 stages/xitune/XiTuneStage.vue / drawers / bottom-dock(§2.2 第 3 项铁律)
5. ❌ 禁止在 modes/auto/ 自行实装 meter / 弹窗 / 数学计算(§2.2 第 1+2+5 项)
6. ❌ 禁止跳过端到端真值 e2e(必须跑 5 个 e2e + 失败回退 ≥ 3 类 · 不允许仅 typecheck/test 形式合规通过就 commit)
7. ❌ 禁止实施 P7 synthesize_position 端点 / mute 编排映射(留 fork 1c · 见 ADR §11.9)

解锁链(本任务 zombie 后)

  • ✅ P3.U-autotune-phase2-analyze(1.0d ClaudeC · Phase 2 偏差分析)
  • ✅ P3.U-autotune-phase3-optimize(1.5d ClaudeC · Phase 3 GEQ-LSQ 迭代)
  • ✅ P3.U-autotune-phase4-apply(1.0d ClaudeC · Phase 4 set_params + 闭环)
  • ✅ fork 1c 备案触发条件之一(见 ADR §11.9)

风险评估

风险 缓解
fork 1b-v2 schema 扩展未及时(IR 持久化字段缺) 用本地 mock schema 先做 UI · fork 1b-v2 zombie 后切真接口 · 不阻塞
悬浮窗与 P0.K-shared Dialog 组件 API 不兼容 Step 2 先核查 Dialog API · 必要时升级到 fork 1c 范围 · 本 fork 内仅最小适配
4 Tab 业务行为契约 5 必填段 e2e 时间超 0.6d 优先保 4 Tab × 1 e2e + 悬浮窗 e2e 共 5 个 · 失败回退 e2e 可降到 ≥ 3 类(若 0.6d 紧)
Tab 2 IR 矩阵 256 IR 性能(渲染卡顿) 矩阵用虚拟滚动 + IR 缩略图懒加载 · 不渲染原始 48000 sample 数组

历史

时间 事件 hash
2026-05-30 11:46 dispatched · ADR-11 v1.3 修订完成后立即派发 —
2026-05-31 08:53 zombie · ClaudeC 完成提交 · ⚠️ 落地版为 5-Tab UI(用户原话 "P3 autotune 5-Tab UI b77b6a7")· 实施时较 ADR-11 v1.3 §1.3.4 设计 4 Tab 新增 1 Tab(待回顾性核查 ADR 是否需 R 修订)· 悬浮窗策略 + 决策 C 持久化 + §3.4 业务行为契约 5 必填段 e2e 已落地 · ADR-11 v1.3 fork 1-v3 闭环 b77b6a7