跳转至

P0.U-measurement-transfer-waveform · ADR-12 Phase 2 #6 · Transfer Function (Smaart) + Waveform Scope 真业务

Worker:TBD(用户分配 · 建议 ClaudeD 副战场)· 部门:前端 (frontend_vue3) 预计:2.0d · 优先级:P1 · 状态:dispatched 隔离:文件隔离(widgets/{transfer,waveform}/* + test-aux/meter/{FreqResponseChart,WaveformChart}.vue 升级 · 与 #5/#7 正交)

🔍 触发与解锁链

  • 触发:2026-05-29 19:48 ADR-12 Phase 1 全栈闭环(a7df354)→ Phase 2 #5/#6/#7 解锁;2026-05-30 08:35 #5 已派发(ClaudeA)· 本 #6 副战场并行
  • 前置就位(同 #5):
  • 前端容器层:DashboardCanvas + WidgetContainer + 4 套 Preset 切换(a7df354)
  • 前端 types:MeterFrame_Transfer + MeterFrame_Waveform(9fc31c4)+ NodeFactory(6050959)+ Inspector 6 段(77b7a50)
  • 后端中转:7 toolKind 路由 + 30fps/tool/client 限流(48cf0ba · 含 transfer + waveform)
  • sidecar 算:transfer_function + group_delay endpoints(153a109)
  • 本任务 zombie 后解锁:与 #5 + #7 合流 → ADR-12 §3 7 类 MeasurementNode 真业务全实施 · Smaart Tuning Workspace Preset 端到端可用
  • 用户期待:⭐ Smaart Delay Finder 真值闭环(注入 ch0=粉噪 + ch1=粉噪延迟 4ms → Transfer widget 显示 Delay Locked: 4±0.5ms · Coherence > 0.7;Waveform widget 注入 1kHz 方波 → trigger 锁后 buffer 包含完整周期)

任务定义(基于 ADR-AIOS-12 §3.3 + §3.5)

按 ADR-12 §3.3 Transfer Function Node(Smaart 核心 · 双通道 + Delay Finder + 相干性)+ §3.5 Waveform Scope Node(时域抓取 + 触发 + 冻结)各 5 项契约,填实容器层(a7df354)中 Transfer/Waveform 两类 widget 的真实业务行为。仅升级现有 2 stub(test-aux/meter/FreqResponseChart.vue + WaveformChart.vue · ea5e9e4)+ 新增 widgets/{transfer,waveform}/ 业务壳 · 不动 #5 widgets/{rms,fft,phase}/* 与 #7 widgets/{electrical,recorder}/。

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

[U-thread] P0.U-measurement-transfer-waveform
[部门] 前端 (frontend_vue3) · 推荐 skill: vuejs-typescript-best-practices
[Worker CWD] d:/work/25_claude/workspace/AlgoDepartment/04_development/(由用户分配的 worker / worktree 决定)
[Occupies] P0.K-shared-meter-dock(写) · P0.K-shared-types(read) · P4.K1-page-layout(read)
[隔离] 文件隔离 · 仅写:
       - frontend_vue3/src/stages/xitest/dashboard/widgets/{transfer,waveform}/*(全新)
       - frontend_vue3/src/test-aux/meter/{FreqResponseChart,WaveformChart}.vue(stub→真业务升级 · 仅这 2 个文件)
       - frontend_vue3/src/stores/xiTestWorkspaceStore.ts(只读引用 · #2 actions 已实施)
       - tests/* 新增
       严禁动 widgets/{rms,fft,phase,electrical,recorder}/*(留 #5/#7)· 严禁动 test-aux/meter/{RMSMeter,SpectrumChart,PhaseChart}.vue(留 #5)· 严禁动 stages/xitest/modes/*(P4.U3 ceecccf 实装)
[优先级] P1 · 2.0d · ADR-12 Phase 2 #6 · ⭐ Smaart Delay Finder 真值闭环
[ADR] docs/08-implementation/40-aios/ADR/ADR-AIOS-12-xitest-realtime-arch.md(必读 §3.3 + §3.5 + §2.11)
[业务行为契约引用] ADR-AIOS-12 §3.3 Transfer Function + §3.5 Waveform Scope · 5 项契约 × 2 类(① 输入输出 schema · ② 收敛判据 · ③ 失败回退 5 类 · ④ 用户操作流 5 步 · ⑤ 端到端真值 e2e)
[参考文档](绝对路径)
  - d:/work/25_claude/workspace/AlgoDepartment/06_docs/site-build/docs/08-implementation/40-aios/ADR/ADR-AIOS-12-xitest-realtime-arch.md(主 ADR · §3.3 L610-718 + §3.5 L774-839 必读)
  - d:/work/25_claude/workspace/AlgoDepartment/04_development/frontend_vue3/src/types/measurement-node.ts(MeasurementNode 7 子能力 schema · 9fc31c4)
  - d:/work/25_claude/workspace/AlgoDepartment/04_development/frontend_vue3/src/types/meter-frame-transfer.ts + meter-frame-waveform.ts(MeterFrame_Transfer 字段 freqs/magnitudeDb/phaseWrapped/coherence/delayFinderMs/delayLocked · MeterFrame_Waveform 字段 samples/triggered/triggerLevel/preRollPercent/frozen · 9fc31c4 落地 · 单位 dB/°/ms)
  - d:/work/25_claude/workspace/AlgoDepartment/04_development/frontend_vue3/src/stages/xitest/dashboard/{DashboardCanvas,WidgetContainer,WorkspacePresetSwitcher}.vue(a7df354 · 容器层就位 · 本任务在 WidgetContainer 内挂 widget 业务)
  - d:/work/25_claude/workspace/AlgoDepartment/04_development/frontend_vue3/src/test-aux/meter/{FreqResponseChart,WaveformChart}.vue(ea5e9e4 · 6 stub 之 2 · 本任务升级为真业务)
  - d:/work/25_claude/workspace/AlgoDepartment/04_development/frontend_vue3/src/stores/xiTestWorkspaceStore.ts(#2 actions 已实施 · 本任务 read-only 引用 measurementNodes/widgets/loadPreset)
  - d:/work/25_claude/workspace/AlgoDepartment/04_development/backend_csharp/Services/Meter/MeterTapService.cs(P5 48cf0ba · 7 toolKind 路由 · 本任务 WS 消费 toolKind=transfer + waveform)
  - d:/work/25_claude/workspace/AlgoDepartment/06_docs/site-build/docs/08-implementation/40-aios/prompts/active/P0.U-measurement-rms-fft-phase.md(#5 同 Phase 2 标本 · 严格仿写 frontmatter + 8 段格式 + 验收 5 项契约自查清单结构)
  - d:/work/25_claude/workspace/AlgoDepartment/06_docs/site-build/docs/08-implementation/40-aios/prompts/done/P0.U-widget-workspace-framework--a7df354.md(同 ADR · #2 标本)

【背景】
ADR-12 Phase 2 #5(RMS+FFT+Phase · ClaudeA)+ #6(本任务 Transfer+Waveform)+ #7(Electrical+Recorder)文件正交可并行。Transfer 是 Smaart suite 核心(双通道 ref+measure · Delay Finder + Coherence + 频响 + 相位 + 群延迟);Waveform 是时域抓取(samples buffer + 触发 + 冻结 · 类似 ocenaudio Scope)· 注入信号 → 后端 MeterTapService 路由 toolKind=transfer/waveform → sidecar pysidecar 算 transfer_function/group_delay → WS 帧推回前端 → FreqResponseChart/WaveformChart 渲染 + Inspector 元信息(Delay Locked / Coherence / Trigger State)· 本任务 zombie 后用户首次看到"Smaart Delay Finder 锁定 4ms"端到端真值。

【执行步骤】

Step 1 · read 已有基础(只读 · 必做)
- read ADR-AIOS-12 §3.3 Transfer L610-718 + §3.5 Waveform L774-839 全文(5 项契约逐段)
- read types/{measurement-node, meter-frame-transfer, meter-frame-waveform}.ts 字段定义 + 单位
- read stages/xitest/dashboard/{DashboardCanvas, WidgetContainer}.vue 容器接口(props.widget · slot 注入点)· 仿写 #5 widget 路由表注册风格
- read test-aux/meter/{FreqResponseChart, WaveformChart}.vue 当前 stub(ea5e9e4)
- read stores/xiTestWorkspaceStore.ts 当前 actions(loadPreset/addWidget/removeWidget)

Step 2 · 升级 FreqResponseChart.vue(stub → Transfer 真业务)
- 订阅 WS 帧(toolKind=transfer · 30fps · 双通道 refChannel + measureChannel)· 渲染 magnitudeDb 曲线 + phaseWrapped 副图 + Coherence 阴影带
- 字段对齐 ADR §3.3 ① 输入输出契约(freqs / magnitudeDb / phaseWrapped / phaseUnwrapped / groupDelay / coherence / delayFinderMs / delayLocked · 单位 Hz/dB/°/ms)
- 收敛判据 §3.3 ②:Delay Locked 显示绿色徽章 · mean(coherence[100~10kHz]) > 0.7 显示实线 · < 0.7 显示虚线 · std(magnitudeDb) < 0.5dB 跨 8 帧 → "稳定"标志
- 失败回退 §3.3 ③ 5 类:延时未锁定 / 相干性过低 / 单通道断开 / 相位环绕异常 / 通道选择错误(ref===measure)· 各有 UI 表现 + 恢复路径
- Inspector 元信息 6 段(Source/Measurement/Display/Validation/Automation/Storage)展示:Ref/Measure 通道选择 · Delay Tracking ☑ · Coherence Threshold 0.7 · 相位 Wrapped/Unwrapped 切换 · Group Delay 显示开关

Step 3 · 升级 WaveformChart.vue(stub → Waveform Scope 真业务)
- 订阅 WS 帧(toolKind=waveform · 30fps · samples buffer 100ms-5s)· 渲染多通道波形(channels × bufferSize)+ 触发标记
- 字段对齐 ADR §3.5 ① 输入输出契约(samples / bufferSize / triggered / triggerLevel / triggerEdge / preRollPercent / frozen · 单位 dBFS/% · samples Float32Array per channel)
- 收敛判据 §3.5 ②:triggered === true(若启用 trigger)显示红色 ▼ 标记 · samples.length === bufferSize 显示 "Buffer Full"
- 失败回退 §3.5 ③(简版):触发等待超时(60s 未触发)显示"等待触发超时 · 降低 trigger level" · 数据丢帧(buffer underrun)顶栏红警 + XRUN 计数 +1
- Freeze 按钮(frozen=true 后停止刷新 · 用户对比 A/B 快照用)

Step 4 · 新建 widgets/transfer/TransferWidget.vue(business shell)
- WidgetContainer 内层 · 接 props: DashboardWidget · 内嵌升级版 FreqResponseChart + Inspector 元信息按钮
- Inspector § Source 选 ref/measure 通道(默认 ch0/ch1)· § Measurement 配 fftSize / coherenceThreshold / delay tracking · § Display 切 magnitude/phase/coherence 三视图 · § Validation 加 ±3dB Mask 规则
- Top Toolbar 集成 [▶ Run] 按钮 · 触发 sidecar 启动测量

Step 5 · 新建 widgets/waveform/WaveformWidget.vue(business shell)
- WidgetContainer 内层 · 接 props: DashboardWidget · 内嵌升级版 WaveformChart + Inspector
- Inspector § Source 选源(sink-pre/physical-input/recording-replay)+ 通道 · § Measurement 配 bufferSize / triggerLevel / triggerEdge / preRollPercent · § Display 切单通道/多通道叠加 · § Storage [💾 Snapshot A] [💾 Snapshot B] [Overlay 对比]
- 在 stages/xitest/dashboard/DashboardCanvas.vue widget 路由表注册 type='transfer-fn' → TransferWidget · type='waveform-scope' → WaveformWidget(WidgetContainer 内 dynamic component · 与 #5 路由表合并不冲突)

Step 6 · 单元测试 + 端到端真值 ⭐
- 新增 transfer-widget.test.ts / waveform-widget.test.ts(WS mock 帧 + 字段渲染 + Delay Locked 徽章 + 触发标记)
- 新增 vitest 端到端真值脚本:
  · Transfer:注入 ch0=粉噪 + ch1=粉噪延迟 4ms → 等 8s 内 delayLocked === true · 断言 delayFinderMs ∈ [3.5, 4.5]
  · Transfer:注入 ch0=粉噪 + ch1=粉噪经 PEQ -3dB@1kHz → averagedCount ≥ 16 · 断言 magnitudeDb(1000Hz) ∈ [-3.5, -2.5]
  · Waveform:注入 1kHz 方波 -6dBFS · trigger level=-10 / edge=rising / preroll=20% → 5s 内 triggered === true · 断言 periodSamples ∈ [46, 50](48000Hz/1kHz=48 samples)
- test:unit 基线 356/3 → 目标 ≥ 380(+24 用例 · 与 #5 合并后总目标 ≥ 400)

【验收】

形式合规(必要不充分):
- npm run typecheck → ✓ exit 0
- npm run build → ✓ 零错误
- npm run test:unit → ≥ 380/3
- 两 stub 升级 + 两 widget 业务壳 + dynamic component 注册(transfer-fn / waveform-scope)

**端到端真值** ⭐(.clinerules v1.8 §业务行为契约必填段强制要求 · 不可仅"typecheck 全绿就 commit")

ADR §3.3 + §3.5 5 项契约自查清单:
- [ ] ① 输入输出契约:Transfer 字段 freqs/magnitudeDb/phaseWrapped/coherence/delayFinderMs/delayLocked 全显示 · Waveform 字段 samples/bufferSize/triggered/preRollPercent/frozen 全显示(单位 Hz/dB/°/ms/dBFS/% · noiseFloorDb/averagedCount/coherenceThreshold 物理元信息显示)
- [ ] ② 收敛判据:Transfer Delay Locked 跨 ≥16 帧不变 · Coherence > 0.7 实线 / < 0.7 虚线 · magnitudeDb std < 0.5dB 显示稳定 · Waveform triggered 显示 ▼ 标记 · Buffer Full 显示完成
- [ ] ③ 失败回退:Transfer 5 类(延时未锁定 / 相干性过低 / 单通道断 / 相位环绕异常 / ref===measure 拒派)各 UI 表现 + 恢复路径 · Waveform 2 类(触发超时 / 丢帧)各 UI 表现
- [ ] ④ 用户操作流 5 步:打开 /xitest?mode=realtime → 切 Tuning Preset(自动加载 Transfer + RMS + FFT + Phase 4 widget · 2x2)→ 配 Ref/Measure 通道 + Delay Tracking ☑ → [▶ Run] 播粉噪/扫频 → 看 Delay Locked + Coherence > 0.7 + 频响曲线
- [ ] ⑤ 端到端真值 e2e:vitest 真值脚本 3 用例(注入 4ms 延迟 ref/measure → delay 锁 4±0.5ms · PEQ -3dB@1kHz → mag1k -3±0.5dB · 1kHz 方波 → period 48±2 samples)

【commit】
- subject:`feat(P0.U-measurement-transfer-waveform/widgets): Transfer Smaart 双通道 + Waveform Scope 真业务 + e2e 真值 · ADR-12 Phase 2 #6`
- trailer:`[step=6/6] [pid=P0] [uid=U-measurement-transfer-waveform] [occupies=P0.K-shared-meter-dock+P0.K-shared-types+P4.K1] [files=stages/xitest/dashboard/widgets/{transfer,waveform}/*+test-aux/meter/{FreqResponseChart,WaveformChart}.vue+tests/*]`

【禁止】
1. ❌ 不动 widgets/{rms,fft,phase,electrical,recorder}/*(留 #5/#7)
2. ❌ 不动 test-aux/meter/{RMSMeter,SpectrumChart,PhaseChart}.vue(留 #5 · 与本任务正交)
3. ❌ 不动 stages/xitest/modes/*(P4.U3 ceecccf 实装的 regression/realtime mode)
4. ❌ 不动 dashboard 容器层(DashboardCanvas / WidgetContainer / WorkspacePresetSwitcher · #2 a7df354 已就位 · 仅在 widget 路由表追加 2 type 注册)
5. ❌ 不嵌入完整 Vue SFC 骨架(.clinerules v1.6 §prompt 内容硬约束)· worker 自决具体实现风格
6. ❌ 不绑定 CPU(本 prompt frontmatter worker: TBD · 用户分配 worker/worktree · 建议 ClaudeD 与 #5 ClaudeA 副战场分工)
7. ❌ 不与 ADR-11 P3 fork 冲突(P3 改 stages/xitune/* · 本任务改 stages/xitest/*)· 不与 #5 文件冲突(本任务 transfer/waveform · #5 rms/fft/phase)
8. ❌ 不验"typecheck 全绿就 commit"——必须按 ADR §3.3/§3.5 5 项契约自查 + 3 用例 e2e 真值脚本(4ms 延迟 / PEQ -3dB / 1kHz 方波)
9. ❌ 不实施 sidecar 高级算子改动(transfer_function/group_delay 已由 P7 153a109 落地 · 本任务仅消费)· 不实施 thd/electrical/recorder(留 #7)

解锁链(本任务 zombie 后)

  • ✅ ADR-12 §3.3 Smaart Transfer + §3.5 Waveform 业务行为契约 e2e 真值跑通(.clinerules v1.8 §业务行为契约必填段第 2 类标杆落地)
  • ✅ 与 #5(RMS/FFT/Phase)+ #7(Electrical/Recorder)合流后 ADR-12 §3 7 类 MeasurementNode 真业务全实施 · Tuning Workspace Preset 端到端可用
  • ✅ 解锁 Phase 3 #10 P0.U-engine-session-snapshots(LeftDock § Engine + Session)+ #11 P0.U-bottom-dock-storage-engine

风险评估

风险 缓解
⚠️ Smaart Delay Finder 锁定 3-5s · 测试 e2e 易超时 timeout 设 8s · 测试夹具用稳定的"延迟粉噪"信号(非真实回放)· ADR §3.3 ⑤ 已用 8000ms 余量
⚠️ 相干性曲线低区间易闪烁(实线/虚线切换) 用 EMA 平滑 + 阈值滞后(hysteresis · 0.7 入 / 0.65 出)· 不要硬切换
⚠️ Waveform samples Float32Array per channel 渲染卡顿(高采样率 + 多通道) requestAnimationFrame 节流 · canvas 直绘(避免 svg path 大数据量)· bufferSize 默认 4096 samples 起步 · 大缓冲降采样显示
⚠️ stub 升级可能影响现有 modes/regression 调用方(FreqResponseChart 在 P4.U3 regression mode 中已 stub) 保持 props 向后兼容(不破坏 ceecccf 调用)· 新业务通过新 props 开关启用 · 回归测试覆盖 modes/regression
⚠️ 与 #5 widget 路由表合并冲突 DashboardCanvas dynamic component 注册表追加(不替换)· #5 commit 先到时本任务仿写 #5 注册风格 · #5/#6 commit 顺序无关(各自只追加自己的 type)

历史

时间 事件 hash
2026-05-30 08:48 dispatched · ADR-12 Phase 2 #6 解锁 · 与 #5(08:35 dispatched)文件正交并行 —