跳转至

P7.U-analyze-extensions · ADR-12 Phase 2 pysidecar · 5 数学端点扩展

Worker:TBD(用户分配)· 部门:Python sidecar (pysidecar) 预计:1.0d · 优先级:P1 · 状态:dispatched 隔离:文件隔离(pysidecar/analyze/ 子目录 · 与 aios-cpu1 ADR-11 P7.U-autotune-multi-target 改 pysidecar/auto_tune/ 完全不重叠)

🔍 触发与解锁链

  • 触发:ADR-AIOS-12 v2.1 accepted(2026-05-29 14:18)· Phase 2 #9 pysidecar
  • 前置就位:pysidecar 19 端点已实装(/analyze/freq_response, /analyze/rms, /analyze/phase, /analyze/coherence, /analyze/octave_band, /analyze/waterfall 等)· 本任务新增 5 个
  • 本任务 zombie 后解锁:P5.U-meter-tap-multi-tool transfer-fn/phase-meter/electrical-meter 路由可调真实端点 + 前端 Phase 2 P0.U-measurement-transfer-waveform 真实数据联调

任务定义(基于 ADR-AIOS-12 §3.2/§3.3/§3.4/§3.6 + §2.10)

按 ADR-12 §2.10 三层分工铁律(P7 全部数学)+ §3 业务行为契约,新增 5 个 pysidecar REST 端点 + 升级现有 19 端点返回值 schema(加物理元信息字段)。仅 pysidecar/analyze/ + 端点注册文件 · 完全不动 pysidecar/auto_tune/ 子目录。

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

[U-thread] P7.U-analyze-extensions
[部门] Python sidecar (pysidecar) · 通用 Python(numpy/scipy)
[Worker CWD] d:/work/25_claude/workspace/AlgoDepartment/04_development/(由用户分配的 worker / worktree 决定)
[Occupies] P7.K1-analyzer(写 · pysidecar/analyze/*)
[隔离] 文件隔离 · 仅写 pysidecar/analyze/* + 端点注册 · 严禁动 pysidecar/auto_tune/*(aios-cpu1 ADR-11 P7.U-autotune-multi-target 写权)
[优先级] P1 · 1.0d · ADR-12 Phase 2 pysidecar · 解锁 P5 多路由真实联调
[ADR] docs/08-implementation/40-aios/ADR/ADR-AIOS-12-xitest-realtime-arch.md(§3.2/§3.3/§3.4/§3.6 + §2.10 必读)
[业务行为契约引用] ADR-AIOS-12 §3.2 FFT + §3.3 Transfer + §3.4 Phase + §3.6 Electrical 5 项契约示范(本任务实施 5 数学算子 + 物理元信息字段)
[参考文档](绝对路径)
  - d:/work/25_claude/workspace/AlgoDepartment/06_docs/site-build/docs/08-implementation/40-aios/ADR/ADR-AIOS-12-xitest-realtime-arch.md(§3 + §2.10 必读)
  - 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 三层分工铁律 · P7 持有所有数学)
  - d:/work/25_claude/workspace/AlgoDepartment/04_development/pysidecar/analyze/(现有 19 端点 · 仿写风格)

【背景】
ADR-12 §2.10 三层分工:数学(FFT/RMS/相位/THD/群延迟/相干 等)全部归 P7 numpy/scipy。本任务新增 5 端点支持 P5.U-meter-tap-multi-tool 7 toolKind 路由的 transfer-fn/phase-meter/electrical-meter/snapshot-diff/peak-hold 路由。同时升级现有 19 端点返回值加物理元信息(resolution/noiseFloorDb/averagedCount)。

【执行步骤】

Step 1 · read 现有基础(只读)
- read pysidecar/analyze/ 现有 19 端点(/analyze/freq_response, /analyze/rms, /analyze/phase, /analyze/coherence, /analyze/octave_band, /analyze/waterfall 等)
- 确认风格(numpy 数组 + JSON 序列化 + 端点装饰器)

Step 2 · 新增 5 个 REST 端点(对齐 ADR-12 §3 业务行为契约)
- POST /analyze/transfer_function(对齐 §3.3.① MeterFrame_Transfer)
  - 输入:refSamples + measureSamples + sampleRate + fftSize
  - 输出:freqs + magnitudeDb + phaseWrapped + phaseUnwrapped + groupDelay + coherence + delayFinderMs + delayLocked + averagedCount + coherenceThreshold + resolution
  - 算法:Smaart 风格双通道传递函数(参考通道相对测量通道 FFT 比值 + 相干性 + Delay Finder)
- POST /analyze/group_delay(对齐 §3.4 phaseUnwrapped 选项)
  - 输入:phaseUnwrapped + freqs
  - 输出:groupDelay[](ms · -dφ/dω)
- POST /analyze/peak_hold(对齐 §3.2 peakHoldDb 状态机)
  - 输入:magsDb + sessionId
  - 输出:peakHoldDb · 衰减 0.995/帧 · sessionId 持久化状态
- POST /analyze/snapshot_diff(对齐 §3 Storage Engine Golden 对比)
  - 输入:current[] + golden[]
  - 输出:diff[] · maxDeviationDb · maxDeviationFreq
- POST /analyze/thd(对齐 §3.6 MeterFrame_Electrical · APx500 核心)
  - 输入:samples + sampleRate + fundamentalFreq?
  - 输出:vrms + dbu + frequency + thd + thdN + sinad + snr · 含校准状态字段

Step 3 · 升级现有 19 端点返回值(物理元信息字段)
- 所有返回 freqs[] 的端点加 `resolution: sampleRate / fftSize`(Hz/bin)
- 所有返回幅度的端点加 `noiseFloorDb`(估计噪声地板 · -120 ~ -60 范围)
- 所有支持平均的端点加 `averagedCount` + `averagingType`('linear'|'exponential'|'peak')
- ⚠️ 非破坏性扩展:旧客户端不依赖新字段时仍能解析(JSON 默认忽略未知字段)

Step 4 · 单元测试(numpy 注入 + 断言)
- 测试 1:transfer_function 已知 4ms 延迟 · 断言 delayFinderMs 在 4±0.5ms · delayLocked = true
- 测试 2:group_delay 单频信号 · 断言 groupDelay 全段无 NaN/Inf
- 测试 3:peak_hold 衰减 200 帧后 · 断言 peakHoldDb 接近 magsDb 当前
- 测试 4:snapshot_diff 故意注入 +6dB@1kHz · 断言 maxDeviationDb ≈ 6 · maxDeviationFreq ≈ 1000
- 测试 5:thd 1kHz 正弦 + 2kHz/3kHz 谐波 · 断言 thd 与已知值一致(±0.01%)

Step 5 · 验收
- pytest pysidecar/tests/ → ≥ 现有基线 + 新增 5+ 用例
- 启动 sidecar :8001 · 5 新端点 curl/POST 真值断言成功
- 现有 19 端点回归测试不破坏(物理元信息字段非破坏性)
- 与 aios-cpu1 ADR-11 P7.U-autotune-multi-target 子目录完全不重叠(auto_tune/* 不动)

【验收】

- 5 新端点 + 现有 19 端点 schema 升级 · pytest 全绿
- 严守三层分工铁律(P7 持有所有数学 · 不依赖任何业务进程)
- 子目录隔离(analyze/* vs auto_tune/*)· 与 ADR-11 fork 零冲突

**端到端真值** ⭐(.clinerules v1.8 §业务行为契约必填段强制要求)
- transfer_function:已知 4ms 延迟双通道粉噪 · delayFinderMs ∈ [3.5, 4.5] · delayLocked = true(对齐 §3.3.⑤)
- group_delay:1kHz 单频 · groupDelay[1000Hz] ≈ 0(无延时)· 全段无 NaN
- peak_hold:1kHz -3dBFS 持续 1s · peakHoldDb[1000Hz] ≈ -3dB · 衰减 0.995/帧
- snapshot_diff:加 PEQ +6dB@1kHz · maxDeviationDb ∈ [5.5, 6.5] · maxDeviationFreq ∈ [950, 1050]
- thd:1kHz + 1% 二次谐波 · thd 输出 ≈ 1%(±0.05%)

【commit】
- subject:`feat(P7.U-analyze-extensions/analyze): 5 new endpoints + meta upgrade for ADR-12 Phase 2`
- trailer:`[step=5/5] [pid=P7] [uid=U-analyze-extensions] [occupies=P7.K1-analyzer] [files=pysidecar/analyze/transfer_function.py+group_delay.py+peak_hold.py+snapshot_diff.py+thd.py+tests/*]`

【禁止】
1. ❌ 不动 pysidecar/auto_tune/*(aios-cpu1 ADR-11 P7.U-autotune-multi-target 写权 · 子目录隔离)
2. ❌ 不破坏现有 19 端点(物理元信息字段是非破坏性扩展 · JSON 兼容)
3. ❌ 不实施前后端 I/O(P7 只做数学算子 · 不做 WS / 不连前端 / 不连 .NET · 完全独立)
4. ❌ 不修改 contract-v1.0 frozen(P_contracts §9 py-subprocess 永久 sleeping · 本任务是协议外扩展)
5. ❌ 不绑定 CPU(本 prompt frontmatter worker: TBD · 用户分配)
6. ❌ 不验"pytest 全绿就 commit"——必须按业务行为契约 5 项 e2e 真值过(已知信号注入断言)
7. ❌ 不与 P5.U-meter-tap-multi-tool 重叠(P5 是 .NET 路由层 · 本任务只暴露 P7 端点)

解锁链(本任务 zombie 后)

  • ✅ P5.U-meter-tap-multi-tool transfer-fn/phase-meter/electrical-meter 路由可调真实 P7 端点
  • ✅ 前端 Phase 2 P0.U-measurement-transfer-waveform 真实数据联调

风险评估

风险 缓解
⚠️ Smaart 双通道算法实施复杂(transfer_function) 参考成熟 numpy/scipy 实现 + 已知 4ms 延迟单元测试覆盖
⚠️ 物理元信息字段升级破坏旧客户端 JSON 兼容(未知字段忽略)· 旧客户端零改动
⚠️ 与 aios-cpu1 P7 fork race condition 子目录完全隔离(analyze/ vs auto_tune/)· 文件级零冲突

历史

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