ACCEPTED

ADR-AIOS-07 · P3-xitune / P4-xitest 业务边界与共享 Meter Dock 决议

1. 上下文(Context)

1.1 触发事件

2026-05-27 v2.7.6 主仓真值核查时,Cline-AIOS 发现 P3-xitune 与 P4-xitest 在概念层有"mode 撞名"现象(P3 4 mode vs P4 5 mode),挂入 DASHBOARD §🤔 标注"🆕 待评估 ADR-07(P3/P4 重合)" + §📋 派 P3.U-xitest-overlap-adr ready(P2 · 0.5d)。

2026-05-28 用户拍板进入下一阶段 ADR 起草,Cline-AIOS 通过 3 份并行 subagent 真值核查后给出方向 A/B/C 三选项。用户拍板方向 A,但同时纠正核心重合点定义并给出全部业务流程真值定义:

用户原话(2026-05-28 11:03): "P3/P4 的重合是指右侧 dock 的 rms / 频响 / 相位曲线的显示是重合的; P3 的 mode 就按照 手动调音 / 自动调音 / 兼容旧调音 / 反向调音 来; P4 的 单元 / 集成 / E2E / 回归 / 实时; 其中 P3 的手动调音基本已经能够正常使用 兼容调音其实和自动调音差不多,只不过他加载的都是 legacy 的链路; 自动调音的策略目前还没有定义,你可以先按照 harman 等主流公司的自动调音流程做一个初步定义; 反向调音,也可以给出一个大概方案,他其实主要还是自动调音拿到数据后做反向模块搭建; P4 的单元测试主要是算法各个模块的 单体冒烟测试,如果是运行 PC 上的,完全可以自动将所有测试项目跑完拿到测试结果就可以,如果是运行在 DSP 那就需要前后端配合来完成; 集成测试就是针对当前 xilink 链路的整体测试出声情况基本的电信号测量, E2E 就是前后端加算法整体链路的冒烟测试; 回归就是针对最终的调音参数加算法链路做电性能和声学的频响相位等测试,这里可以配合 xi 硬件产品进行测量; 实时模式,就是 smaart suit 或者 AP 软件的对标产物,有显示,甚至可以通过 api 之直接使用 ap 产品; 注意一点右侧 dock 的 rms 和 频响等检测工具都可以选择节点,第一个节点就是如果 pc 模式可以直接返回进入 sink 之前的音频数据也就是出播放设备之前的状态,然后就是振声的声卡设备 或者 mic 输入设备"

1.2 真值核查发现(3 份 subagent 并行核查)

第一份(P3-xitune PROCESS.md): - ✅ K-thread 实际是 7 个(K1-K7),非过时认知中的 K1-K6 - ✅ 14 TuningDialog 已实装(K2 · 接 P0.K4-floating 多窗口) - ✅ 6 drawer 已实装(K3 · 扁平结构 · AuxTools/FlowReadonly/History/Profile/Project/XiCal) - ⚠️ 4 mode 类型骨架已建(TUNING_MODE_CONFIGS 冻结)· 业务逻辑未实装(P3.U-tune-modes-impl ready · 3.0d)

第二份(P4-xitest PROCESS.md): - ✅ K-thread 6 个(K1-K6 全 sleeping)· P4.U1+U2 zombie · 199 unit pass · /xitest 真可用 - ✅ P4.K5 stage-toolbar 5 mode chip 已实装(原命名:unit/integration/e2e/perf/visual) - ✅ P4.K6 testStore 5 mode 状态机 + vitest 反代真跑(dev-only POST /dev-api/test/vitest/run) - ✅ P4.K3 right-dock 复用 P0.K-shared-test-aux 4 组件(read-only 包装)+ 3 独有

第三份(共享重合点核查 · 用户纠正后重做): - 🔥 关键重合点:右侧 dock 的 RMS / 频响 / 相位曲线显示 → P3 与 P4 都需要 · 但目前没有共享抽象 - ✅ P0.K-shared-test-aux/ 已存在(P3.U4 抽出 · 写所有者 P0)· 但仅含 P3 → P4 复用的"测试辅助组件",不含 meter 工具 - ⚠️ 当前 meter 工具(RMS/频响/相位)各 stage 自行实装 → 重复劳动 + 不一致风险** · 应抽到 P0.K-shared-meter-dock

1.3 用户的关键架构定义(本 ADR 必须锁定)

1.3.1 右侧 dock Meter 工具节点选择(本 ADR 核心架构契约)

所有 RMS / 频响 / 相位 / 时域波形 / 频谱图等检测工具,**必须支持节点选择**:

节点 1 · sink-pre(PC 模式专用):
  - 数据源 = 进入物理 sink 之前的音频流
  - 等价于"出播放设备之前的最终算法链路输出"
  - 用途 = PC 模式调音 / 测试时 · 不依赖外部硬件即可看到调音效果
  - 实施侧 = 后端 P5(I/O 中转 · sink 前 tap 钩子 + 调 P7 分析 + WS 转发) → P7-pysidecar(数学分析 · FFT/RMS/相位)→ 前端(显示)
  - 契约:P_contracts.K1-protocol-v1 §4 sourceList 待扩 'sink-pre' 类型 · 实时帧通过 P5 WS 推送(详见 §1.3.4 数据流分工)

节点 2 · physical-input(物理硬件输入):
  - 数据源 = 振声声卡 / 通用 mic 输入设备
  - 用途 = 真实声学测量(配合 xi 硬件) · 回归测试 / 实时模式必备
  - 实施侧 = 后端 P5(WASAPI 设备枚举 + OS 音频采集 + 调 P7 分析 + WS 转发) → P7-pysidecar(数学分析) → 前端(显示)
  - 契约:同上 'physical-input' 类型 · 数据流详见 §1.3.4

1.3.2 P3-xitune 4 调音模式(本 ADR 业务流程定义)

Mode	状态	核心流程	数据流
手动调音 manual	✅ 已实装	工程师在 14 TuningDialog 中拖动控件 → 实时下发参数 → 听感反馈	UI → set_params → DSP
自动调音 auto	⚠️ 策略待定义(本 ADR §2.2.2 给初步定义 · 参考 Harman 流程)	① 加载目标曲线 ② 测量当前响应(用 §1.3.1 节点 2)③ 算法迭代调整 ④ 收敛后下发	测量数据 → 算法 → set_params
兼容调音 compat	⚠️ 业务逻辑同 auto · 区别在加载 legacy 链路	与 auto 相同 · 但加载入口指向 legacy 工程文件(.xml/.legacy.xilink)	同 auto · legacy 数据源
反向调音 reverse	⚠️ 大概方案待细化(本 ADR §2.2.3 给框架)	拿到 auto 调音的最终参数 → 反向解析 → 自动搭建模块拓扑(简化重构)	auto 结果 → 反向 → 模块图

1.3.3 P4-xitest 5 测试模式(本 ADR 业务流程定义 · 与之前 unit/perf/visual 命名替换)

Mode	旧命名(已废弃)	新命名(本 ADR 锁定)	核心流程	适用场景
单元 unit	unit	unit	算法各模块单体冒烟测试 · PC 模式自动跑 / DSP 模式前后端配合	算法开发自测
集成 integration	integration	integration	当前 xilink 链路整体出声 + 基本电信号测量	链路联调
E2E	e2e	e2e	前后端 + 算法整体链路冒烟	发版前回归
回归 regression	perf	regression ⭐	调音参数 + 算法链路的电性能 + 声学频响相位测量(配合 xi 硬件)	产品质量门禁
实时 realtime	visual	realtime ⭐	对标 Smaart Suite / AP 软件 · 可通过 API 直接调用 AP 产品	工程师实测调试

⚠️ 命名变更影响:P4.U2 已实装的 5 mode chip(unit/integration/e2e/perf/visual)中,perf → regression + visual → realtime。本 ADR 决议后需起一个轻量 P4.U-mode-rename U-thread 同步代码层命名(0.3d · 仅类型 + UI 标签 · 业务逻辑零改动)。

1.3.4 数据流三层分工(P5 / P7 / 前端 · v1.6 真值锁定)

背景:2026-05-28 15:50 用户洞察 + Cline-AIOS 真值核查(3 份 subagent)· 发现 ADR-07 §1.3.1 实施侧描述把"音频分析"硬塞给 P5 后端 .NET · 与现有架构(backend_csharp.PysidecarProcessManager 拉起 pysidecar:8001 + POST /auto_tune/realtime_frame 同步调用)不符。本节锁定真实分工 · 防 P5.U-meter-source-tap 派发时 worker 误把 FFT/RMS/相位算法写到 .NET。

1.3.4.1 三层职责

层	进程	职责	不做
L1 I/O 与编排	P5-backend-csharp (.NET)	① WASAPI 设备枚举 + 物理音频输入采集 ② sink-pre tap(从算法链路最后一级取 raw samples) ③ 拉起 pysidecar 子进程 + 健康检查 + 自动重启 ④ 同步 HTTP POST 调用 P7 分析端点 ⑤ 把 P7 返回的 JSON 包装成 WS 帧 _broadcastToAll 推前端 ⑥ 限流 / 节流 / 多客户端 fan-out / 录制	❌ 不做任何数学计算(FFT / RMS / 相位 / 群延迟 / 相干 / 倍频程 / 瀑布图全部交 P7)
L2 数学分析	P7-pysidecar (Python · numpy/scipy)	暴露 19 个 REST 端点(已实装):/analyze/freq_response /analyze/rms /analyze/phase /auto_tune/realtime_frame /analyze/coherence /analyze/octave_band /analyze/waterfall ... · 端口 8001 · 监听 localhost only	❌ 不直接对接前端(浏览器)· 不管理多客户端 · 不做 WS 广播
L3 显示	前端 P0/P1/P3/P4 stage	订阅 P5 WS /ws · 反序列化 MeterDataFrame · stub 组件渲染(RMSMeter / FreqResponseChart / PhaseChart / SpectrumChart / WaveformChart)	❌ 不直连 pysidecar:8001(AutoTunePanel 的 /auto_tune/calculate 直连为历史遗留 · 标记技术债待清理 · 见 §2.5)

1.3.4.2 标准数据流(实时帧 30 fps · 95% 流量)

前端订阅 WS /ws (channel=meter, node=sink-pre|physical-input)
  ↓
P5 接收订阅 → 启动定时 tap(33ms/帧)
  ↓
P5 采集 raw samples(WASAPI 输入 / sink 前钩子)
  ↓
P5 → POST http://localhost:8001/analyze/realtime_frame  (HTTP 同步 · ~3-8ms)
       body: { samples: float[], sr: int, node: string, timestamp: long }
  ↓
P7 numpy/scipy FFT + RMS + 相位计算 → 返回 JSON
       { freq_hz, magnitude_db, phase_deg, group_delay_ms, rms_db, peak_db, t, sr, node }
  ↓
P5 包装成 WS 帧 → _broadcastToAll(所有连前端)
  ↓
前端反序列化 MeterDataFrame → stub 组件渲染

端到端延迟预算:tap(<1ms) + HTTP 调 P7(3-8ms) + FFT 计算(~5ms · numpy)+ WS 广播(~2ms) ≈ 10-15ms · 远低于 33ms/帧上限 · 30 fps 显示零感知。

1.3.4.3 一次性计算(离线 · EQ 参数求解 · 5% 流量)

走相同路径:前端 → P5 /api/auto_tune/calculate → P5 转发 P7 /auto_tune/calculate → P5 返回前端。禁止前端直连 P7:8001(端口暴露 / 跨域 / 鉴权 / 重试 4 个问题)。

1.3.4.4 选择 P7→P5→前端 而非 P7→前端直连的科学依据

维度	P7→P5→前端 WS(标准)	P7→前端直连
进程管理	✅ P5 拉起 + 健康检查 + 自动重启	❌ 前端无法管理 Python 子进程
多客户端广播	✅ P5 单次 fan-out	❌ pysidecar 需自实现
跨域 / 鉴权 / 端口暴露	✅ 仅暴露 P5 单端口 · pysidecar 监听 localhost	❌ 必须把 8001 暴露浏览器
限流 / 录制 / 多路合并	✅ P5 集中治理	❌ 分散每前端
端到端延迟差	~10-15ms(基线)	~7-12ms(少 1 跳 3ms)
30 fps 显示场景感知	零感知(33ms/帧 · 3ms 差<10%)	同

→ 3ms 延迟差对 30 fps 显示零感知 · 但绕过 P5 会丢掉全部基础设施 · 不划算。

---

2. 决议(Decision)

2.1 主决议 · 4 项架构级方向

2.1.1 P3 与 P4 业务正交不合并

• 决议:P3-xitune(产品调音运行时)与 P4-xitest(工程测试套件)是两个完全不同的业务域,"mode"撞名是巧合
• 依据:
• 业务域:P3 服务终端用户(产品工程师调音)· P4 服务开发者(算法+前后端测试)
• 触发场景:P3 在产品发布后持续运行 · P4 在开发期 + 发版前运行
• K-thread 拓扑:P3.K1-K7(7 个)· P4.K1-K6(6 个)· 各自独立无主写权重叠
• 维持现状:9 CPU 实例 + Roster v4 + 进程拓扑全部不变

2.1.2 抽出 P0.K-shared-meter-dock 共享栈 K-thread

新增 P0 daemon 第 9 个 K-thread(继 K-shared-types / K-shared-contracts / K-shared-test-aux 之后):

- kid: P0.K-shared-meter-dock
  name: shared-meter-dock
  state: sleeping
  file_claims:
    - frontend_vue3/src/test-aux/meter/**          # 新增子目录
    - frontend_vue3/src/types/meter.ts             # 新增类型文件
  description: |
    跨进程共享 meter dock 工具组件 · P3 + P4 都通过 occupies 引用。
    包含:
      - RMSMeter.vue            (RMS 实时电平表)
      - FreqResponseChart.vue   (频响曲线 · 含相位)
      - PhaseChart.vue          (独立相位曲线)
      - SpectrumChart.vue       (频谱瀑布图 · realtime mode 必备)
      - WaveformChart.vue       (时域波形)
      - MeterNodeSelector.vue   (节点选择器 · sink-pre / physical-input)
    类型定义:
      - MeterNode = 'sink-pre' | 'physical-input'
      - MeterDataFrame = { t: number; samples: Float32Array; sr: number; node: MeterNode }
      - MeterToolKind = 'rms' | 'freq-response' | 'phase' | 'spectrum' | 'waveform'
    写所有者 = P0(本 daemon)· 其他进程(P3 / P4 / 任何 stage)只能 read-only
    写需通过 occupies 声明 P0.K-shared-meter-dock
  access: read-write   # P0 是写所有者 · 其他进程 read-only 引用

file_claims 协议: - P3.U-tune-modes-impl(auto/reverse 模式实施时)· occupies = [P3.K7, P0.K-shared-meter-dock(read)] - P4.U3-perf-visual-stub-upgrade(回归/实时模式实施时)· occupies = [P4.K6, P0.K-shared-meter-dock(read)] - 任何 P0.K-shared-meter-dock 写操作必须 fork 新 U-thread 占用 P0.K-shared-meter-dock(写)· 默认派给 ClaudeA(P0 主战场)

2.1.3 Meter 工具节点选择架构(契约级)

前端契约(types/meter.ts · 本 ADR 落地):

export type MeterNode =
  | 'sink-pre'        // PC 模式 · sink 之前的音频流(算法链路最终输出)
  | 'physical-input'  // 物理输入 · 振声声卡 / mic

export interface MeterNodeOption {
  id: MeterNode
  label: string                    // UI 显示标签(本地化键)
  available: boolean               // 当前模式下是否可用(由后端能力决定)
  unavailableReason?: string       // 不可用时的原因(如"DSP 模式不支持 sink-pre")
}

export interface MeterToolConfig {
  kind: MeterToolKind
  node: MeterNode                  // 当前选定节点
  fftSize?: number                 // 频谱类工具参数
  averaging?: 'none' | 'fast' | 'slow'  // RMS 平均
}

后端契约扩展(P_contracts.K1-protocol-v1 §4 sourceList · 需起 P_contracts.K2-protocol-v2 fork ADR):

当前 sourceList 10 类音源 → 新增 2 类 meter-source:
  + 'meter-sink-pre' · 后端 sink 前 tap · 仅 PC 模式
  + 'meter-physical-input' · 后端调用 OS 输入设备 API

⚠️ 契约影响评估:contract-v1.0 已永久 frozen(P_contracts B4 zombie · K1.state = sleeping-permanent)。本 ADR-07 不直接修改 protocol-v1.md · 而是记录 meter-source 扩展为 v2 候选项 · 等 v2 正式起 ADR 时一并并入。当前 P3/P4 实施时可先用前端 mock 数据 + 临时 dev-api 桥接(类比 P4.U2 的 vitestRunnerPlugin 路径 · dev-only)。

2.1.4 P4 mode 命名修订(perf → regression · visual → realtime)

• 触发:用户在 §1.1 给出的真实业务定义与 P4.U2 已落地的 mode 名(perf/visual)不匹配
• 决议:fork P4.U-mode-rename(0.3d · ClaudeD)· 仅同步代码层命名 · 业务逻辑零改动
• 范围:
• types/test.ts TestMode 联合类型:'perf' → 'regression' · 'visual' → 'realtime'
• testStore.ts mode 默认值 / 切换逻辑保持不变
• TestRunnerPanel.vue mode chip UI 标签同步
• 单测(199 baseline)中涉及 mode 字符串的断言同步更新
• 添加 LEGACY_TEST_MODE_MAP: { perf: 'regression', visual: 'realtime' } 兼容历史 .test 持久化数据(参考 LEGACY_MODULE_ID_MAP / LEGACY_PRESET_STEM_MAP / LEGACY_LINK_FILE_MAP 体系)
• 优先级:P2(非阻塞 · ClaudeD 闲时)· 但 P4.U3-perf-visual-stub-upgrade 派发前必须先完成此 rename(否则新代码会再次写错命名)

2.2 子决议 · P3 4 调音模式业务流程框架

2.2.1 手动调音 manual(✅ 已实装 · 维持现状)

无变更 · P3.K2 14 TuningDialog 体系已能满足。

2.2.2 自动调音 auto(⚠️ 初步框架 · 参考 Harman / 主流厂商流程)

Harman 自动调音参考流程(从公开资料 + 主流厂商实践提炼):

Phase 1 · 测量(Measure)
  ① 用户选择目标曲线(平直 / Harman 曲线 / 自定义模板)
  ② 系统播放扫频信号(20Hz-20kHz log sweep)或粉噪
  ③ 通过 §1.3.1 节点 2(physical-input)采集真实响应
  ④ 多点平均(避免单点驻波)+ 平滑(1/3 oct)

Phase 2 · 分析(Analyze)
  ⑤ 当前响应 vs 目标曲线 → 计算偏差曲线
  ⑥ 识别共振峰 / 谷 / 高低频滚降
  ⑦ 输出"建议调整清单"(频段 + 增益 + Q 值)

Phase 3 · 优化(Optimize · 算法迭代)
  ⑧ 自动生成 PEQ / GEQ 滤波器组(满足偏差最小化)
  ⑨ 加入约束条件:相位连续性 / 群延迟最小化 / 工程师自定义边界
  ⑩ 模拟应用后的预测响应 → 与目标对比 → 不达标则迭代

Phase 4 · 应用与验证(Apply & Verify)
  ⑪ 一键下发参数到 DSP(走 set_params 协议)
  ⑫ 重新测量(回到 Phase 1 ②)→ 闭环验证
  ⑬ 收敛后保存为 .xipreset

P3.U-tune-modes-impl 实施约束: - ✅ 必须支持 §1.3.1 节点选择(用户可在测量阶段切换 sink-pre / physical-input) - ✅ 必须复用 P0.K-shared-meter-dock(频响 / 相位 / 频谱图) - ✅ 算法层独立可测(单元测试覆盖 Phase 2 + Phase 3 核心算子) - ⚠️ 算法库选型(LMS / 遗传 / 凸优化)留待 P3.U-tune-modes-impl 实施时具体评估 · 不在本 ADR 锁定

2.2.3 兼容调音 compat(⚠️ 业务逻辑同 auto · 仅入口区别)

决议: - 业务逻辑 = 复用 auto 调音的全部 4 个 Phase(measure/analyze/optimize/apply) - 唯一区别 = 链路加载入口指向 legacy 工程 - legacy 工程定义:加载 .xml/.legacy.xilink/.legacy.xistudio 等遗留格式 · 与 ADR-04 P-1 xml-decommission 留下的兼容协议(legacy_set_param)对接 - 实施代价:复用 auto 80%+ 代码 · 仅在加载层新增 legacy 解析路径

2.2.4 反向调音 reverse(⚠️ 大概方案 · 自动调音结果 → 反向模块搭建)

思路:

输入:auto 调音收敛后的最终参数集(滤波器组 / 增益 / 延迟链)
处理:① 参数聚类(把上百个 PEQ 段位归并到几个语义模块)
     ② 模块拓扑推导(EQ → Crossover → Compressor → Limiter 等典型链路)
     ③ 输出 .xilink 工程(XiForge 模块图 + 参数注入)
输出:工程师可读、可微调的模块化工程文件

P3.U-tune-modes-impl 实施约束: - ⚠️ 复杂度:高(涉及参数聚类 + 拓扑识别 · 类似机器学习问题) - 📋 建议:先做 MVP(支持简化场景:纯 EQ 链路 → EQ 模块栈)· 复杂场景留下季度 - 🔗 与 P2-xiforge 联动:输出格式必须严格符合 ADR-04 §2.1.2 Module UID 规范

2.3 边界铁律(强制约束)

1. P3 与 P4 进程边界不可越界:
2. P3 业务代码(stages/xitune/)禁止 import P4 业务代码(stages/xitest/)· 反之亦然
3. 共享逻辑必须经 P0.K-shared-* 共享栈中转(types / test-aux / meter-dock / contracts)
4. P0.K-shared-meter-dock 写权排他:
5. 任何 stage 想加新 meter 工具(如声学测量专用 STIPA / RT60)· 必须 fork U-thread 占 P0.K-shared-meter-dock(写)· 派 ClaudeA
6. 严禁在 P3 / P4 stage 自行实装 meter 组件后再"提议合并"(避免重复劳动)
7. Meter 节点选择是 ADR 级契约:
8. 任何新增 meter 工具必须支持 MeterNode 切换 · 不允许硬编码"只支持 mic"
9. 新增 MeterNode 类型(如未来 'dsp-tap')必须先起 ADR 修订本文件 + P_contracts v2

---

3. 后果(Consequences)

3.1 正面后果

✅ 明确边界 · 防误判:后续开发者不会再陷入"P3/P4 是否合并"的误判循环 ✅ 抽出共享 meter dock:P3 + P4 + 未来任何需 meter 的 stage 都能复用 · 避免重复劳动 ✅ 节点选择契约化:sink-pre / physical-input 升级为架构级概念 · 后端 P5 可针对性实施 tap 钩子 ✅ P3 4 mode 业务流程锁定:P3.U-tune-modes-impl 派发时有明确实施依据 · 不再"摸石头过河" ✅ P4 5 mode 命名修订:perf → regression / visual → realtime 与用户真实业务匹配 · 避免后续每次都要解释命名 ✅ 解锁 P3.U-tune-modes-impl 派发:阻塞条件解除(P0.K-shared-meter-dock 抽出工作量已纳入 §4 实施清单)

3.2 负面后果与缓解

后果	影响	缓解措施
⚠️ P0 daemon 多一个 K-thread	P0 PROCESS.md 字段增加 · 复杂度 +10%	同共享栈协议 · K-shared-* 已经形成体系 · 可控
⚠️ P4.U-mode-rename 临时工作量 0.3d	占 ClaudeD 短时 · 推迟 P4.U3 派发 0.5d	命名一致性收益 >>> 短期工作量 · 必做
⚠️ Meter 节点选择需后端 P5 配合(sink-pre tap)	跨栈协调 · 阻塞前端 mock 数据期	前端先用 mock + dev-api 桥接 · 后端 P5 工作量纳入 §4.4
⚠️ 自动调音算法选型推迟	P3.U-tune-modes-impl 实施时还需具体评估	本 ADR 给框架 · 算法选型 fork 子 ADR-07.1(P3.U-tune-modes-impl 实施期决定)
⚠️ 反向调音 MVP 限定纯 EQ	无法覆盖复杂调音场景	用户已认可"先大概方案"· 复杂场景下季度迭代
⚠️ 契约 v2 待定(meter-source 2 类)	当前用 dev-api 桥接 · 不算正式协议	待 P_contracts v2 ADR 起时一并并入 · 不阻塞 P3/P4 实施

3.3 关键非目标(Non-Goals · 本 ADR 不解决)

• ❌ 不锁定自动调音算法选型(LMS / 遗传 / 凸优化)
• ❌ 不锁定反向调音的具体聚类算法
• ❌ 不修改 contract-v1.0(已 frozen · meter-source 留 v2)
• ❌ 不评估第三方 AP 软件 API 集成方案(realtime mode · 留 P4.U3 实施时)
• ❌ 不重新评估 9 CPU 实例边界 + Roster v4(本 ADR 仅在 P0 加 1 个 K-thread)

---

4. 实施清单(Implementation)

4.1 立即行动(本 ADR accepted 后立即派)

#	U-thread	部门	CPU	工作量	描述
1	P0.U-add-meter-dock-kthread	前端	ClaudeA(主仓)	0.5d	新增 P0.K-shared-meter-dock K-thread · 创建 frontend_vue3/src/test-aux/meter/ 目录 + 6 个 stub 组件骨架(空壳 + props 接口) + types/meter.ts
2	P4.U-mode-rename(perf→regression / visual→realtime)	前端	ClaudeD	0.3d	同步 P4.U2 已实装代码层命名 · 加 LEGACY_TEST_MODE_MAP 兼容 · 单测断言更新

4.2 短期解锁(立即行动后 1-2 周内)

#	U-thread	部门	CPU	工作量	描述
3	P3.U-tune-modes-impl(已 ready · 现可派)	前端	ClaudeC 机动	3.0d	auto / reverse / compat 三模式业务实装(manual 已实装维持现状)· 必须复用 P0.K-shared-meter-dock
4	P4.U3-perf-visual-stub-upgrade(已 ready · 现可派)	前端	ClaudeD	2.0d	regression / realtime 两模式 stub → 真跑 · 必须复用 P0.K-shared-meter-dock + 节点选择

4.3 中期协调(下个迭代)

#	U-thread	部门	CPU	工作量	描述
5	P5.U-meter-source-tap	后端	ClaudeB	1.5d	后端实装 sink-pre tap 钩子 + physical-input 设备枚举 + dev-api 桥接(待 v2 转正式协议)
6	(推迟)P_contracts.K2-protocol-v2 fork ADR	契约	ClaudeB	TBD	meter-source 2 类正式入 v2 · 触发条件:有第二个 ADR-NN 也需要扩契约时一并起(避免单 ADR 撬动 K2 fork)

4.4 长期演进(下季度+)

#	议题	触发条件
7	自动调音算法选型 ADR-07.1(LMS / 遗传 / 凸优化)	P3.U-tune-modes-impl Phase 1 完成后
8	反向调音复杂场景拓展(Crossover + Compressor 链路识别)	P3.U-tune-modes-impl reverse MVP 落地后
9	AP 软件 API 集成方案(realtime mode)	P4.U3 实施时 · 评估第三方 SDK 授权
10	新增 MeterNode 'dsp-tap'(DSP 内部 tap)	DSP 算法库 P6 提供 tap 接口后

---

5. 验收(Acceptance)

5.1 文档验收(本 ADR 自身)

• ADR-AIOS-07 主文件落盘(本文件)
• P_arch/ADR-AIOS-07-p3-p4-overlap/ 子进程目录创建
• P_arch/ADR-AIOS-07-p3-p4-overlap/PROCESS.md(子进程 PCB)
• P_arch/PROCESS.md 加 ADR-07 子事件 user_thread
• DASHBOARD.md v2.7.14 → v2.7.15(§🤔 加决策行 · §📋 加新派 U-thread)

5.2 实施验收(§4 全部 U-thread 完成)

检查项	通过条件
P0.U-add-meter-dock-kthread	P0 PROCESS.md 加 K-shared-meter-dock(state: sleeping)· 6 stub 组件可通过 typecheck · types/meter.ts 落地
P4.U-mode-rename	testStore.ts mode 联合类型 = 'unit' \| 'integration' \| 'e2e' \| 'regression' \| 'realtime' · LEGACY_TEST_MODE_MAP 落地 · 单测全过 · TestRunnerPanel UI 标签同步
P3.U-tune-modes-impl	manual 维持 · auto Phase 1+2 实装(测量+分析)· compat 复用 auto · reverse MVP(纯 EQ 场景)· 全程使用 P0.K-shared-meter-dock
P4.U3	regression / realtime 真跑 · 节点选择切换正常 · 测试基线 ≥ 现有 261/3
P5.U-meter-source-tap	sink-pre / physical-input 后端 dev-api 可用 · 前端 mock 切到真数据

5.3 边界铁律验收(长期)

• 任何 P3 / P4 新增 meter 类需求 → 必须 fork U-thread 占 P0.K-shared-meter-dock(写)· 不允许在 stage 内自行实装
• 任何新增 MeterNode 类型 → 必须先起子 ADR(本文件 §2.3 边界铁律 #3)

---

6. 替代方案(Alternatives Considered)

6.1 方向 B(已废弃)· 抽通用 mode-switcher 框架

• 描述:把 P4 的 5-mode toolbar + store + 状态机抽到 P0.K-shared-mode-switcher · 给 P3.U-tune-modes-impl 复用
• 废弃理由:
• P3 4 mode 与 P4 5 mode 业务流程完全不同(调音流程 vs 测试流程)· 仅"切换器 UI"层有微弱共性
• 抽框架收益(<10% 代码复用)< 抽框架成本(0.5d ClaudeA + 引入新共享栈)
• 不如让两边自行实装 · 各自最优化 UX
• 本 ADR 选择:仅抽 meter-dock(真实重合)· 不抽 mode-switcher(伪重合)

6.2 方向 C(已废弃)· 合并 P3 + P4

• 描述:把 P4-xitest 合并进 P3-xitune · P4 进程注销
• 废弃理由:
• P4.U2 已 release-candidate · 推翻测试基线损失大
• Roster v4 已稳定 · 9 CPU 实例边界变化破坏性高
• 业务域真实正交(产品调音 vs 工程测试)
• 本 ADR 选择:维持 P3 / P4 独立进程

6.3 替代方案 D · meter-dock 抽到 P4(而非 P0)

• 描述:把 meter-dock 抽到 P4-xitest 下 · P3 通过 IPC 引用
• 废弃理由:
• 违反"共享栈写所有者集中在 P0"的 v0.3 拓扑铁律
• P3 引用 P4 = 业务进程互相耦合 · 与 §2.3 边界铁律 #1 冲突
• 本 ADR 选择:meter-dock 写所有者 = P0(沿用 K-shared-* 体系)

---

7. 相关决议与文档

7.1 相关 ADR

• ADR-AIOS-01:multi-agent-collaboration(P_contracts B1-B4 · contract-v1.0 frozen)— meter-source v2 候选项与本 ADR 协作
• ADR-AIOS-03:multi-agent-stage-partition(P4 stage 链 U1+U2)— P4 框架前置
• ADR-AIOS-04:XiForge 架构(Module UID + ModuleMode 4→2)— P3 reverse 调音输出格式依赖 Module UID
• ADR-AIOS-05:XiStudio Workspace(7 后缀 + LEGACY_*_MAP 三件套)— P3 compat 调音的 legacy 工程加载入口依赖
• ADR-AIOS-06:OS 化任务调度(K-thread / U-thread / PCB / RUNQ)— 本 ADR 全程使用其调度协议

7.2 相关 PROCESS.md

• processes/P0-xishell/PROCESS.md(本 ADR 后将新增 K-shared-meter-dock K-thread · v1.8 → v1.9)
• processes/P3-xitune/PROCESS.md(P3.U-tune-modes-impl ready · 本 ADR 给业务流程依据)
• processes/P4-xitest/PROCESS.md(P4.U-mode-rename + P4.U3 · 本 ADR 触发)
• processes/P5-backend-csharp/PROCESS.md(P5.U-meter-source-tap · 中期协调)
• processes/P_arch/PROCESS.md(本 ADR 子事件 user_thread)

7.3 关联契约

• contracts/protocol-v1.md §4 sourceList(本 ADR 不修改 · 标注 meter-source 为 v2 候选)
• contracts/protocol-v1.md §8 test-runner-api(P4 5 mode 命名修订后需同步,但 §8 已 frozen · 改为 LEGACY_TEST_MODE_MAP 兼容路径)

---

8. 状态流转(Status History)

日期	状态	操作	说明
2026-05-27 16:12	候选(v2.7.6 真值核查)	DASHBOARD §🏭 标"🆕 待评估 ADR-07"	P3/P4 mode 撞名引发评估需求
2026-05-28 10:38	起草触发	用户拍板进入下一阶段 ADR	DASHBOARD §🤔
2026-05-28 10:42	真值核查	Cline-AIOS 3 份 subagent 并行核查 P3/P4 PROCESS.md	发现真实重合点 ≠ mode 撞名
2026-05-28 11:03	方案拍板	用户选方向 A + 给出 P3 4 mode + P4 5 mode + meter dock 节点选择全部业务真值	本 ADR 内容深度大幅扩展
2026-05-28 11:05	accepted(本版)	ADR-AIOS-07 v1.0 落盘	待派 §4.1 立即行动 2 个 U-thread

---

9. 关键术语表(Glossary)

术语	定义
MeterNode	meter 工具的数据来源节点 · 当前 2 类:sink-pre(算法链路最终输出 · PC 模式)/ physical-input(物理硬件输入)
sink-pre	进入物理 sink 之前的音频流 · 等价于"算法链路最终输出但尚未送到播放设备"
physical-input	物理硬件输入 · 振声声卡 / mic 等 OS 音频输入设备
K-shared-meter-dock	P0 daemon 持有的共享栈 K-thread · 收纳跨 stage 共享的 meter 工具组件 · 写所有者 P0 · 其他进程 read-only
手动调音 manual	P3 4 mode 之一 · 工程师在 14 TuningDialog 中拖动控件实时下发(已实装)
自动调音 auto	P3 4 mode 之一 · 4 Phase 流程(measure/analyze/optimize/apply)· 参考 Harman
兼容调音 compat	P3 4 mode 之一 · 业务逻辑同 auto · 加载 legacy 链路
反向调音 reverse	P3 4 mode 之一 · 从 auto 结果反向搭建模块拓扑 · MVP 限定纯 EQ 场景
回归测试 regression	P4 5 mode 之一(原 perf · 本 ADR 重命名)· 调音参数+算法链路的电性能+声学频响相位测量 · 配合 xi 硬件
实时模式 realtime	P4 5 mode 之一(原 visual · 本 ADR 重命名)· 对标 Smaart Suite / AP 软件 · 可调用 AP API

---

10. 决议者签名(Approvers)

• 拍板:用户(2026-05-28 11:03 选方向 A · 给出业务真值定义)
• 起草:Cline-AIOS · cwd=d:/work/25_claude/workspace/AlgoDepartment/06_docs/site-build/
• 真值核查:Cline-AIOS 3 份 subagent 并行核查(2026-05-28 10:42)
• 后续修订:任何修改本 ADR 必须先 fork ADR-07-RX(R = Revision)子进程 · 不允许直接编辑 accepted 状态文档

---

本 ADR 落地 = AIOS v7 OS 化模型下第 1 个由"业务真值补全"驱动的 ADR · 验证了"用户拍板大方向 + AIOS 真值核查 + 用户补全业务定义 + ADR 起草"的迭代工作流可行性。