跳转至

P5.U-meter-tap-multi-tool · ADR-12 Phase 2 后端 · 7 类 toolKind 路由

Worker:TBD(用户分配)· 部门:后端 (backend-csharp) 预计:1.5d · 优先级:P1 · 状态:dispatched 隔离:文件隔离(Services/Meter/ 子目录 · 与 aios-cpu1 ADR-11 P5.U-autotune-batch-pipeline 改 Services/AutoTune/ 完全不重叠)

🔍 触发与解锁链

  • 触发:ADR-AIOS-12 v2.1 accepted(2026-05-29 14:18 用户原话"start 3 fork")· Phase 2 #8 后端
  • 前置就位:Services/Meter/MeterTapService.cs(P5.U-meter-source-tap 4adda88 · 30fps WS + WASAPI + sink-pre tap · 本任务扩展为多 toolKind 路由)
  • 本任务 zombie 后解锁:前端 Phase 2 P0.U-measurement-* 4 fork mock 数据 → 真后端 WS 联调

任务定义(基于 ADR-AIOS-12 §2.10 + §3.1-§3.7)

按 ADR-12 §2.10 三层分工铁律(P5 仅 I/O · 零数学)+ §3.1-§3.7 输入输出契约,扩展 MeterTapService 7 类 toolKind 路由 · 升级 WS 帧 schema · 加限流。仅 Services/Meter/ + Models/ + Routes/MeterDevApiRoutes.cs · 完全不动 Services/AutoTune/* 子目录。

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

[U-thread] P5.U-meter-tap-multi-tool
[部门] 后端 (backend-csharp) · 推荐 skill: dotnet-realtime-communication
[Worker CWD] d:/work/25_claude/workspace/AlgoDepartment/04_development/(由用户分配的 worker / worktree 决定)
[Occupies] P5.K2-services(写 · Services/Meter/*) · P5.K3-models(写 · Models/Meter*) · P5.K5-routes(写 · Routes/MeterDevApiRoutes.cs)
[隔离] 文件隔离 · 仅写 backend_csharp/Services/Meter/* + Models/Meter*.cs + Routes/MeterDevApiRoutes.cs
       严禁动 Services/AutoTune/*(aios-cpu1 ADR-11 P5.U-autotune-batch-pipeline 写权)
[优先级] P1 · 1.5d · ADR-12 Phase 2 后端 · 解锁前端 4 fork mock→真后端
[ADR] docs/08-implementation/40-aios/ADR/ADR-AIOS-12-xitest-realtime-arch.md(§2.10 三层分工 + §3.1-§3.7 契约 必读)
[业务行为契约引用] ADR-AIOS-12 §3.1-§3.7 7 类 MeterFrame_*(本任务实施 toolKind 路由 · WS 帧 schema 必含 toolKind 字段 + 物理元信息)
[参考文档](绝对路径)
  - d:/work/25_claude/workspace/AlgoDepartment/06_docs/site-build/docs/08-implementation/40-aios/ADR/ADR-AIOS-12-xitest-realtime-arch.md(§2.10 + §3 必读)
  - d:/work/25_claude/workspace/AlgoDepartment/06_docs/site-build/docs/08-implementation/40-aios/ADR/ADR-AIOS-07-p3-p4-overlap.md(§1.3.4 三层分工铁律 · 严守"P5 .NET 端零数学")
  - d:/work/25_claude/workspace/AlgoDepartment/04_development/backend_csharp/Services/Meter/MeterTapService.cs(现有 30fps + sink-pre tap · 复用扩展)
  - d:/work/25_claude/workspace/AlgoDepartment/06_docs/site-build/docs/08-implementation/40-aios/prompts/done/P5.U-meter-source-tap--4adda88.md(同部门标本 · 严格仿写风格)

【背景】
ADR-12 §2.10 三层分工:**.NET P5 仅 I/O 中转 · 零数学** · 数学(FFT/RMS/相位/THD/群延迟/相干 等)全部交 P7 pysidecar。本任务扩展现有 MeterTapService 30fps 单 toolKind 路由 → 7 类 toolKind 路由(rms-meter/fft-analyzer/transfer-fn/phase-meter/waveform-scope/electrical-meter/recorder)· WS 帧 schema 升级带 toolKind 字段 · 限流 30fps/tool/client。

【执行步骤】

Step 1 · read 现有基础(只读)
- read backend_csharp/Services/Meter/MeterTapService.cs(P5.U-meter-source-tap 4adda88 落地 · 30fps WS + WASAPI + sink-pre tap)
- read backend_csharp/Models/MeterDataFrame.cs(3 record · 本任务扩展为 7 toolKind)
- read backend_csharp/Routes/MeterDevApiRoutes.cs(GET /nodes + WS /stream · 本任务 WS 帧加 toolKind 字段)

Step 2 · 扩展 Models/Meter/(新建 + 改)
- 新建 7 个 record(对齐 ADR-12 §3.1-§3.7 ① 输入输出契约):
  - MeterFrame_RMS / MeterFrame_FFT / MeterFrame_Transfer / MeterFrame_Phase / MeterFrame_Waveform / MeterFrame_Electrical / RecordingSession
- 字段单位注释完整(Hz/dBFS/ms 等 · 物理元信息 noiseFloorDb/averagedCount/resolution)

Step 3 · 扩展 Services/Meter/MeterTapService.cs
- 新增 IMeterToolRouter 接口 · 按 toolKind 路由到不同 P7 端点
- toolKind="rms-meter" → 调 P7 /analyze/rms
- toolKind="fft-analyzer" → 调 P7 /analyze/freq_response
- toolKind="transfer-fn" → 调 P7 /analyze/transfer_function(等 P7.U-analyze-extensions 落地)
- toolKind="phase-meter" → 调 P7 /analyze/phase
- toolKind="waveform-scope" → 后端直接抓 raw samples + buffer cache · 不调 P7
- toolKind="electrical-meter" → 调 P7 /analyze/thd(等 P7 落地)
- toolKind="recorder" → ring buffer 内存模式
- ⚠️ 严守 ADR-07 §1.3.4 三层分工铁律 · 不实施任何数学(FFT/RMS/相位等全部 HTTP 桥接 P7)

Step 4 · 升级 WS 帧 schema
- 现有 WS 帧增加 `toolKind` 字段 + 各 toolKind 物理元信息字段
- 兼容旧客户端(toolKind 字段缺失时默认 'rms-meter')

Step 5 · 限流
- 30fps/tool/client 限流(防多客户端 fan-out 过载)
- 每客户端 × 每 toolKind 独立帧率计数器
- 超限 backoff(简单丢帧 · 不阻塞)

Step 6 · 单元测试
- 新增 MeterToolRouterTests · 7 toolKind 路由分别 mock P7 返回 · 验证 WS 帧 schema 含 toolKind
- 新增 RateLimitTests · 验证 30fps/tool/client 限流不丢真实帧
- dotnet test 基线 111/0 → 目标 ≥ 130(+19 用例)

Step 7 · 验收
- dotnet build → 0 错 0 警
- dotnet test → ≥ 130 通过(基线 111 + 新增 ≥ 19)
- contract-v1.0 零改动(WS 帧 schema 升级是非破坏性扩展 · toolKind 字段缺失时降级)
- 与 aios-cpu1 ADR-11 P5.U-autotune-batch-pipeline 子目录完全不重叠(Services/AutoTune/* 不动)

【验收】

- dotnet build 0 错 0 警 · dotnet test ≥ 130/0(基线 +19)
- 7 toolKind 路由 + WS schema 升级 + 限流全部就位
- 严守三层分工铁律(零数学 · 全部交 P7)
- 与 ADR-11 P5 fork 子目录隔离(Services/Meter vs Services/AutoTune)

**端到端真值** ⭐(.clinerules v1.8 §业务行为契约必填段强制要求)
- toolKind=rms-meter:WS 客户端订阅后 · P5 调 P7 /analyze/rms · 返回帧含 rmsDb[8]/peakDb[8]/peakHoldDb[8]/noiseFloorDb · 字段全
- toolKind=transfer-fn:P5 调 P7 /analyze/transfer_function(P7 fork 6 zombie 后联调)· 返回帧含 magnitudeDb/phaseWrapped/coherence/delayFinderMs
- toolKind=waveform-scope:P5 直接抓 raw samples · 不调 P7 · 返回 MeterFrame_Waveform.samples[][] + triggered + bufferSize
- 限流真值:同一客户端 50fps 请求 → 后端响应 30fps + warning log

【commit】
- subject:`feat(P5.U-meter-tap-multi-tool/services-meter): 7-toolKind routing for ADR-12 Phase 2`
- trailer:`[step=7/7] [pid=P5] [uid=U-meter-tap-multi-tool] [occupies=P5.K2+P5.K3+P5.K5] [files=Services/Meter/*+Models/Meter*+Routes/MeterDevApiRoutes.cs+Tests/*]`

【禁止】
1. ❌ 不动 Services/AutoTune/*(aios-cpu1 ADR-11 P5.U-autotune-batch-pipeline 写权 · 子目录隔离)
2. ❌ 不实施任何数学(FFT/RMS/相位/相干/群延迟/THD)· 全部交 P7 HTTP 桥接(ADR-07 §1.3.4 + ADR-12 §2.10)
3. ❌ 不破坏现有 WS 客户端(toolKind 字段缺失时默认 'rms-meter')
4. ❌ 不修改 contract-v1.0 frozen(K1 永久 sleeping · WS 帧扩展是非破坏性)
5. ❌ 不绑定 CPU(本 prompt frontmatter worker: TBD · 用户分配)
6. ❌ 不验"dotnet build 全绿就 commit"——必须按业务行为契约 5 项自查 · §3.1-§3.7 字段单位完整
7. ❌ 不与 P7.U-analyze-extensions 重叠(P7 端点扩展是 P7 fork · 本任务只调用)

解锁链(本任务 zombie 后)

  • ✅ 前端 Phase 2 P0.U-measurement-rms-fft-phase + P0.U-measurement-transfer-waveform + P0.U-measurement-electrical-recorder-stub · mock 数据 → 真后端 WS 联调

风险评估

风险 缓解
⚠️ WS 帧 schema 升级破坏旧客户端 toolKind 字段缺失降级 'rms-meter' · 旧客户端零改动
⚠️ 限流过严丢真实帧 30fps/tool/client 是 ADR-12 §2.10 锁定 · 单元测试覆盖
⚠️ 与 aios-cpu1 P5 fork race condition 子目录完全隔离(Services/Meter vs Services/AutoTune)· 文件级零冲突

历史

时间 事件 hash
2026-05-29 14:18 dispatched · ADR-12 accepted 后 Phase 2 #8 起手 (待 stop 时回填)