P5.A26.F1-runtime-target-backend-extension · IRuntimeTargetService 加 NativeSubKind 枚举 + RuntimeTargetRegistry 注册 8 项 native target
Worker:ClaudeB · 部门:后端 P5 · 预计:1.5d · 优先级:P0 关键路径起点 · 状态:dispatched · isolation:🧵 file(同 worktree 同 branch · 解锁 F1-2 前端消费 NativeSubKind)
🔍 触发与解锁链
触发:用户 2026-06-18 16:50 accept ADR-AIOS-26 + 16:55 三连 start P5.A26.F1 + start P3.A26.F2 + start P3.A26.F3(三 worker 文件正交并行 max=1.5d)。
用户原话(verbatim · ADR-26 §1.1 第 1 轮 4.b + 4.c):
"b)target 的类型应该有连接类型来决定 · 在左侧 dock 连接中底层 DSP 通信中添加一个 native 的选项 · 如果是 native 代表是 CPU 模式; c)如果连接是 native 模式 · 那么资源监控的 target 就需要改为:CPU0 CPU1 CPU2 CPU3 VDSP0~VDSP3 · VDSP 表明是虚拟 DSP 模式 · 这种模式和 CPU 模式的区别就是 source 到底走的是 DSP 还是 CPU"
架构契约(ADR-26 §3.1 ① 输入/输出契约 · 业务契约 5 必填段):
- 契约 A · 枚举扩展:NativeSubKind enum(Cpu0/Cpu1/Cpu2/Cpu3/Vdsp0/Vdsp1/Vdsp2/Vdsp3 共 8 项)· 加入 IRuntimeTargetService 接口属性 ActiveNativeSubKind: NativeSubKind? + 重载 SetActive(string id, NativeSubKind? subKind = null)
- 契约 B · 注册表扩展:RuntimeTargetRegistry 新增 8 个 PcNative 子目标(每个 NativeSubKind 一个 RuntimeTargetDescriptor · Kind=PcNative · NativeSubKind 字段标记)· 现有 PcNative0 / PcNativeLegacy / DspHardware 三注册保留不动
- 契约 C · 引擎兼容:AudioEngineService.cs:120 if (target.Kind == RuntimeKind.DspHardware) 分支不破坏 · NativeSubKind 仅作元信息透传(VDSP 子类型当 source 信号路径切换标记 · 实际 source 路径切换由后续 F1-2 / 或独立 fork 实施 · 本 fork 不变更 SourceSignalService.cs 行为)
- 契约 D · 持久化:NativeSubKind 写入 workspace state(复用 ADR-15 持久化协议 · 加 runtimeNativeSubKind 字段)
- 契约 E · API 端点:GET /api/runtime/targets 返回包含 NativeSubKind 元数据 · POST /api/runtime/active 接受 { id, nativeSubKind }(可选)
- 5 类失败回退(ADR-26 §3.1 ③):native 选项点击但后端未响应 → 退化 PcNative0 / VDSP source 走 DSP 算法栈失败 → 退化 CPU 模式 / 资源监控数据丢失 → fallback / 跨连接类型切换 → 二次确认 / 拖动 Dock → 布局自由
解锁链(本任务 zombie 后):
- ✅ F1-2 P3.A26.F1-runtime-target-frontend-ui(ClaudeA 2.0d)消费 NativeSubKind enum · 渲染 8 项 target 池下拉
- ⏳ F4-1 P_e2e.A26.F4-truth-e2e-meter-dual-link(ClaudeC 1.5d · blocked-by-F1-1+F1-2+F2-1+F3-1+F3-2 五齐)→ ADR-26 整体闭环 🏆
任务定义(基于 ADR-26 §3.1 ① + §4.1 F1-1)
子任务 ① · NativeSubKind enum 定义(0.2d)
Step 1.1:在 backend_csharp/Services/Runtime/IRuntimeTargetService.cs L21-27(RuntimeKind enum 紧邻位置)新增 NativeSubKind enum:
public enum NativeSubKind
{
Cpu0 = 0, Cpu1 = 1, Cpu2 = 2, Cpu3 = 3,
Vdsp0 = 10, Vdsp1 = 11, Vdsp2 = 12, Vdsp3 = 13,
}
子任务 ② · IRuntimeTargetService 接口扩展(0.2d)
Step 2.1:为 IRuntimeTargetService 接口加 NativeSubKind? ActiveNativeSubKind { get; } 属性 + 重载 void SetActive(string id, NativeSubKind? subKind = null)(append-only · 不破坏现有方法签名)。
子任务 ③ · RuntimeTargetRegistry 注册 8 项 native target(0.4d)
Step 3.1:在 RuntimeTargetRegistry.cs 现有 L15/25/35 三注册下方追加 8 项 PcNative 子目标(Kind=PcNative · NativeSubKind=Cpu0~Vdsp3)· id 命名规范 pc-native-cpu0 ~ pc-native-vdsp3。RuntimeTargetDescriptor 加 NativeSubKind? 字段(可选)。
子任务 ④ · AudioEngineService.cs:120 分支兼容 + workspace 持久化(0.3d)
Step 4.1:AudioEngineService.cs:120 if (target.Kind == RuntimeKind.DspHardware) 分支零修改 · NativeSubKind 仅在日志中输出(logger.LogInformation("Engine starting · target={id} · nativeSubKind={subKind}"))。
Step 4.2:复用 ADR-15 workspace 持久化协议 · 在 workspace state 加 runtimeNativeSubKind: string? 字段 · 启动时读 + 切换时写。
子任务 ⑤ · API 端点 + 单元测试 + 全测试基线零回归(0.4d)
Step 5.1:Routes/RuntimeRoutes.cs(若不存在则新建)GET /api/runtime/targets 返回 [{ id, kind, nativeSubKind?, ... }] · POST /api/runtime/active body { id: string, nativeSubKind?: string }。
Step 5.2:新建 Services/Runtime/Tests/RuntimeTargetServiceTests.cs ≥ 8 case:
- T1 NativeSubKind enum 8 值齐全
- T2 IRuntimeTargetService.ActiveNativeSubKind 可读
- T3 SetActive(id, subKind) 持久化
- T4 RuntimeTargetRegistry 8 native 子目标全部可枚举
- T5 GET /api/runtime/targets 返回含 nativeSubKind 元数据
- T6 POST /api/runtime/active 接受 nativeSubKind body
- T7 AudioEngineService DspHardware 分支零回归(切 DspHardware 后 Engine 启动正常)
- T8 workspace state 持久化 NativeSubKind round-trip
Step 5.3:dotnet build 0 errors · dotnet test 全测试基线零回归(后端基线 217+12+8=237/0)。
完整 prompt(直接复制粘贴 ClaudeB 终端)
[U-thread] P5.A26.F1-runtime-target-backend-extension · ADR-26 §3.1 ① + §4.1 F1-1
[部门] 后端 P5
[Worker CWD] d:/work/25_claude/workspace/AlgoDepartment/04_development/
[Occupies] P5.K-shared-runtime-target + P5.K-shared-audio-engine
[优先级] P0(1.5d · 关键路径起点 · 解锁 F1-2 前端 UI)
[ADR] docs/08-implementation/40-aios/ADR/ADR-AIOS-26-meter-dual-link-runtime-target-tri-stage.md(必读 §3.1 ① 输入/输出契约 + §4.1 F1-1 + §1.3 现有组件清单 #1 RuntimeTarget grep 真值 + §5 风险表第 1/2 行)
[isolation] file(同 worktree 同 branch · backend_csharp 4 文件改+1 文件新建)
[参考文档绝对路径]
- 业务契约:ADR-26 §3.1 完整 5 必填段(① TS 接口扩展 / ② 6 行收敛判据 / ③ 5 类失败回退 / ④ 6 步操作流 / ⑤ playwright e2e 模板 native+VDSP 切换)
- 用户 2026-06-18 12:30 verbatim 第 1 轮 4.b + 4.c(ADR-26 §1.1):"native 选项 · CPU0~CPU3 + VDSP0~VDSP3 · VDSP source 走 DSP 算法栈"
- 用户 2026-06-18 16:50 拍板 accept ADR-AIOS-26 + 16:55 三连 start
- 教训承接标本(必读避坑 · ADR-26 §9):
* §9.1 框图先行 + ADR 跟进(v3.0 标杆模式)
* §9.2 ADR-23→25→25-R1 三连教训严格执行(本 prompt [现有组件 grep 真值] 段已落实)
* §9.3 校正 ADR-21-R1 3 类→4 类(本 fork 不动 selector · F2-1 范围)
- 范式 commits(worker 必读 · 强制 read 全文对齐格式):
* P3.UA25R1.F1--0bb4422(2026-06-18 v3.0 标本 · ClaudeA combo hotfix · 8 段格式 + 七元组完美对齐)
* P5.A22.F2--eac5b69(同 P5 后端 ClaudeB · realtime persistence service · API + WS + audit 模式参考)
[现有组件 grep 真值(.clinerules v3.0 ADR-23→25→25-R1 三连教训铁律 · 派发前已核查 ADR-26 §1.3 #1)]
① backend_csharp/Services/Runtime/IRuntimeTargetService.cs:
- L21-27:public enum RuntimeKind { PcNative, PcSimulator, DspHardware, Remote }(保留 · NativeSubKind 紧邻新增)
- 接口 IRuntimeTargetService 现有:Active / SetActive(id) / Available(append-only 加 ActiveNativeSubKind + SetActive 重载)
② backend_csharp/Services/Runtime/RuntimeTargetRegistry.cs:
- L15:第 1 注册 PcNative0(保留)
- L25:第 2 注册 PcNativeLegacy(保留)
- L35:第 3 注册 DspHardware(保留)
- 第 4-11 项位置:8 个 PcNative 子目标(NativeSubKind=Cpu0~Vdsp3)新增追加
③ backend_csharp/Services/AudioEngine/AudioEngineService.cs:
- L120:if (target.Kind == RuntimeKind.DspHardware) { ... } else { ... } · 严禁修改分支逻辑 · 只在日志中加 NativeSubKind 元信息输出
④ backend_csharp/Services/Source/SourceSignalService.cs L7-19:
- 注释证实"PC 模式 backend 直接合成 PCM 喂 dspalgo" · 本 fork 不变更 source 信号路径(VDSP 真实路径切换由后续 fork · 本 fork NativeSubKind 仅作元信息标记)
⑤ workspace 持久化 ADR-15:复用 workspace state 加 runtimeNativeSubKind 字段 · 不新建持久化栈
[文件正交策略](.clinerules v3.0 §UID 命名铁律 + §isolation):
isolation: file · backend_csharp 范围内改 IRuntimeTargetService.cs + RuntimeTargetRegistry.cs + AudioEngineService.cs(仅日志)+ workspace state migration + 新建 Routes/RuntimeRoutes.cs(若不存在)+ 新建 RuntimeTargetServiceTests.cs
与 F2-1(改 frontend_vue3/src/stages/xilink/drawers/RightDock*.vue)+ F3-1(改 LogModuleNode.vue + Routes/LogModuleRoutes.cs)文件 100% 正交 · 三 worker 同时跑零冲突
【背景】
用户 2026-06-18 12:30 + 15:45 + 16:46 三轮 verbatim 拍板锚定 Meter 双链路 + RuntimeTarget UI 改造 + 三 Stage 统一 · 16:50 ADR-AIOS-26 v0.1 accepted(v3.0 直接 accepted 起步)· 16:55 拍板三连 start(F1-1 + F2-1 + F3-1)文件正交并行 max=1.5d。
本 fork 是 ADR-26 §4 实施清单关键路径起点(F1-1 → F1-2 → F4-1 = 5.0d)· 解锁 F1-2 ClaudeA 前端 RuntimeTarget UI(资源监控 Dock 左移 + 改名 + native 选项 + 8 项 target 池下拉)。
教训承接(ADR-26 §9.2):用户原话名词必须 grep 找具体文件+行号 → 本 prompt [现有组件 grep 真值] 段已落实 IRuntimeTargetService.cs L21-27 + RuntimeTargetRegistry.cs L15/25/35 + AudioEngineService.cs:120 共 5 处真值锚点。
【架构关键约束】
⚡ 严守 .clinerules v3.0 ADR-23→25→25-R1 三连教训铁律:用户原话名词 grep 找具体文件+行号 · "完善"指代词必须解析为现有组件 · 本 fork 是完善 RuntimeTarget(加 NativeSubKind enum + 8 注册)· 不新建独立栈
🎨 RuntimeKind 4 枚举值零修改(PcNative/PcSimulator/DspHardware/Remote)· NativeSubKind 是子类型 · 仅当 Kind=PcNative 时有效
📋 AudioEngineService.cs:120 if (target.Kind == RuntimeKind.DspHardware) 分支零修改:NativeSubKind 仅作元信息透传(日志输出)· 实际 source 路径切换不在本 fork 范围
📋 SourceSignalService.cs 零修改:VDSP source 走 DSP 算法栈的真实路径切换由后续 fork(独立任务 · 待用户拍板)· 本 fork NativeSubKind 仅元信息标记
📋 workspace 持久化复用 ADR-15:加 runtimeNativeSubKind 字段 · 不新建持久化栈
📋 三层分工(ADR-07 §1.3.4):L1/L2 后端服务层 · 只暴露 enum + API + 持久化 · 不做前端 UI(F1-2 范围)· 不做 DSP 数学
🚫 严禁动 RuntimeKind enum 4 枚举值(append-only 加新 NativeSubKind)
🚫 严禁动 AudioEngineService.cs:120 分支逻辑(仅加日志元信息)
🚫 严禁动 SourceSignalService.cs(VDSP 路径切换是后续 fork)
🚫 严禁动前端 frontend_vue3 任何文件(F1-2 / F2-1 / F3-1 范围)
【执行步骤】
Step 0 · 文件注入真值核查(强制门槛 · ADR-26 §9.2 三连教训承接)
- read backend_csharp/Services/Runtime/IRuntimeTargetService.cs 全文 · 确认 L21-27 RuntimeKind enum 4 值 + 接口现有 3 成员(Active / SetActive / Available)
- read backend_csharp/Services/Runtime/RuntimeTargetRegistry.cs 全文 · 确认 L15/25/35 三注册(PcNative0 / PcNativeLegacy / DspHardware)
- read backend_csharp/Services/AudioEngine/AudioEngineService.cs L80-150 · 确认 L120 if (target.Kind == RuntimeKind.DspHardware) 分支
- read backend_csharp/Services/Source/SourceSignalService.cs L1-30 · 确认"PC 模式 backend 直接合成 PCM 喂 dspalgo"注释
- grep "RuntimeKind" backend_csharp/ 全 · 列出所有消费点(应仅在 RuntimeTargetRegistry/AudioEngineService 等少数文件)· 确认无破坏性影响
- 留 commit log:Step 0 五层核查记录
Step 1 · NativeSubKind enum 定义 0.2d(子任务 ①)
- 在 IRuntimeTargetService.cs L21-27 RuntimeKind enum 紧邻新增 public enum NativeSubKind { Cpu0=0, Cpu1=1, Cpu2=2, Cpu3=3, Vdsp0=10, Vdsp1=11, Vdsp2=12, Vdsp3=13 }
- RuntimeKind enum 4 值零修改
Step 2 · 接口扩展 0.2d(子任务 ②)
- IRuntimeTargetService 加 NativeSubKind? ActiveNativeSubKind { get; }
- 重载 void SetActive(string id, NativeSubKind? subKind = null)(默认参数 · 现有调用点零回归)
- 实现类(若存在 RuntimeTargetService.cs)同步实现新成员
Step 3 · RuntimeTargetRegistry 注册 8 项 native target 0.4d(子任务 ③)
- RuntimeTargetDescriptor 加可选字段 NativeSubKind? NativeSubKind { get; init; }
- 在 L35 之后追加 8 个 PcNative 子目标:id="pc-native-cpu0" ~ "pc-native-vdsp3" · Kind=PcNative · NativeSubKind=Cpu0..Vdsp3 · DisplayName=英文标签
- 现有 PcNative0 / PcNativeLegacy / DspHardware 三注册零修改
Step 4 · AudioEngineService 日志 + workspace 持久化 0.3d(子任务 ④)
- AudioEngineService.cs:120 分支逻辑零修改 · 在 Engine 启动日志中加 nativeSubKind 元信息 logger.LogInformation("Engine starting target={id} kind={kind} nativeSubKind={subKind}", target.Id, target.Kind, runtimeTargetService.ActiveNativeSubKind)
- workspace state schema 加 string? RuntimeNativeSubKind 字段 · 启动时反序列化读 · SetActive 时写
- 老 workspace state(无该字段)向后兼容(默认 null)
Step 5 · API 端点 + 测试 + 全测试基线零回归 0.4d(子任务 ⑤)
- Routes/RuntimeRoutes.cs(若不存在则新建)
* GET /api/runtime/targets → [{ id, kind, nativeSubKind?, displayName }, ...]
* POST /api/runtime/active body { id: string, nativeSubKind?: string } → 200 OK + 切换持久化
- 新建 Services/Runtime/Tests/RuntimeTargetServiceTests.cs ≥ 8 case(T1-T8 见任务定义子任务 ⑤)
- dotnet build 0 errors
- dotnet test 全测试基线零回归(后端基线 217+12+8=237 + 8 新 case)
- 浏览器实测(可选 · 未派 F1-2 时 UI 暂无 · 主要看 API):curl -X GET http://localhost:5000/api/runtime/targets · 应返回 11 项(原 3 + 新 8)
Step 6 · commit
- git add . && git commit -m "feat(backend/runtime): P5.A26.F1 加 NativeSubKind enum + 8 native target 注册 + workspace 持久化
用户 2026-06-18 16:50 拍板 accept ADR-AIOS-26 + 16:55 三连 start(F1-1+F2-1+F3-1 文件正交 max=1.5d)。
F1-1 本 fork(ADR-26 §3.1 ① + §4.1):
① IRuntimeTargetService.cs L21-27 紧邻新增 NativeSubKind enum 8 值(Cpu0-3 + Vdsp0-3)
② 接口加 ActiveNativeSubKind 属性 + SetActive 重载(append-only 零回归)
③ RuntimeTargetRegistry 追加 8 个 PcNative 子目标(id=pc-native-cpu0~vdsp3 · DspHardware/PcNative0/PcNativeLegacy 零修改)
④ AudioEngineService.cs:120 DspHardware 分支零修改 · 仅加 nativeSubKind 日志元信息
⑤ workspace state 加 RuntimeNativeSubKind 字段(ADR-15 持久化复用 · 老数据兼容 default null)
⑥ Routes/RuntimeRoutes.cs GET/POST API + RuntimeTargetServiceTests.cs 8 case 全过
解锁 F1-2 P3.A26.F1-runtime-target-frontend-ui(ClaudeA 2.0d 消费 NativeSubKind enum)
ADR-23→25→25-R1 三连教训承接:用户原话名词 grep 找具体文件+行号(本 commit 涉及 5 处 backend 真值锚点)
VDSP source 路径切换非本 fork 范围 · NativeSubKind 仅作元信息透传(后续独立 fork 处理)
[step=6/6] [pid=P5] [uid=P5.A26.F1-runtime-target-backend-extension] [type=fork] [isolation=file]
[occupies=P5.K-shared-runtime-target+audio-engine] [files=5(3M+2N)] [ipc=rest]
[adr=ADR-AIOS-26 §3.1 ① + §4.1 F1-1 + §1.3 #1 grep 真值 + 用户 2026-06-18 12:30 第 1 轮 4.b/4.c verbatim + 16:50 accept]"
【验收】
☐ Step 0 文件注入真值核查通过(read 4 文件 + grep RuntimeKind 全 backend · commit log 留痕)
☐ Step 1 NativeSubKind enum 8 值定义 · RuntimeKind 4 值零修改
☐ Step 2 接口扩展 ActiveNativeSubKind 属性 + SetActive 重载 · 现有调用零回归
☐ Step 3 RuntimeTargetRegistry 追加 8 个 native 子目标 · 原 3 注册零修改
☐ Step 4 AudioEngineService.cs:120 分支零修改 + 日志加 nativeSubKind 元信息 + workspace state 持久化 round-trip
☐ Step 5 GET/POST API 端点工作 · RuntimeTargetServiceTests.cs 8 case 全过 · dotnet build/test 全绿(基线 237→245+ 零回归)
☐ Step 6 commit message 含 7 元组 trailer + ADR-26 §3.1 + §4.1 + 用户 verbatim 引用
【禁止】
❌ 禁止跳过 Step 0 文件注入真值核查(ADR-26 §9.2 三连教训 · 5 处真值锚点必须逐一对齐)
❌ 禁止动 RuntimeKind enum 4 枚举值(PcNative/PcSimulator/DspHardware/Remote)· 仅 append NativeSubKind enum
❌ 禁止动 AudioEngineService.cs:120 if 分支逻辑(仅加日志元信息)
❌ 禁止动 SourceSignalService.cs(VDSP source 路径切换是后续独立 fork · 非本 fork 范围)
❌ 禁止动 RuntimeTargetRegistry.cs L15/25/35 现有 3 注册(append-only 追加第 4-11 项)
❌ 禁止动 frontend_vue3 任何文件(F1-2 / F2-1 / F3-1 范围)
❌ 禁止破坏 IRuntimeTargetService 现有方法签名(SetActive 用默认参数 append · 不破坏老调用)
❌ 禁止跳过 RuntimeTargetServiceTests 8 case(T1-T8 验收硬门槛)
❌ 禁止 commit 缺七元组 trailer(.clinerules v3.0 铁律)
❌ 禁止嵌入完整 C# class > 10 行(.clinerules v3.0 · 用 diff 模式提交)
解锁链(本任务 zombie 后)
- ✅ NativeSubKind enum 8 值后端落地(CPU0-3 + VDSP0-3)· F1-2 ClaudeA 可消费
- ✅ RuntimeTargetRegistry 11 注册可枚举(原 3 + 新 8)
- ✅ workspace 持久化兼容老数据(default null 向后兼容)
- ✅ F1-2
P3.A26.F1-runtime-target-frontend-uiready(ClaudeA 2.0d · 资源监控 Dock 左移 + native 选项 + 8 target 下拉) - ⏳ F4-1
P_e2e.A26.F4-truth-e2e-meter-dual-link部分解锁(还需 F1-2/F2-1/F3-1/F3-2 全 zombie · 五齐后 ready · ClaudeC 1.5d → ADR-26 整体闭环 🏆)
风险评估
| 风险 | 缓解 |
|---|---|
| RuntimeKind enum 加新 NativeSubKind 触动 AudioEngineService.cs:120 分支(if Kind == DspHardware) | Step 0 强制 read AudioEngineService.cs L80-150 · NativeSubKind 仅作元信息透传 · 不破坏现有 if 分支逻辑(ADR-26 §5 风险表第 1 行) |
| RuntimeTargetRegistry 现有 3 注册被误改 | append-only 追加第 4-11 项 · L15/25/35 现有注册零修改(diff 仅在文件末尾或紧邻 L35) |
| SourceSignalService.cs VDSP 真实路径切换缺失 · 用户期望 native+VDSP 真切到 DSP 算法栈 | ADR-26 §3.1 ② "VDSP source 走 DSP 算法栈"是契约 · 但本 fork 范围仅 enum + 注册 + 元信息 · 实际路径切换由后续独立 fork 实施 · commit message + ADR-26 §7 状态流转明确说明 |
| workspace state 老数据无 RuntimeNativeSubKind 字段 · 反序列化失败 | C# JSON 反序列化默认可选字段 default null · 加单元测试 T8 覆盖老数据 round-trip |
| API 端点 POST /api/runtime/active 接受 nativeSubKind 字符串 → enum 转换异常 | 加 enum.TryParse 校验 · 失败返回 400 BadRequest + reason_code |
| dotnet test 全测试基线 237 case · 加 8 case 后 245+ · CI 误报 | commit message 明确说明 · CI 看通过率 + 加新 case 数 · 不看绝对数 |
| ClaudeB 排队膨胀(本 1.5d + F6 🚀task ADR-15 1.0d + A22.F1 1.5d 共 4.0d) | 本 fork 是关键路径 · F1-2 阻塞解锁 · 必须优先 · F6 🚀task 独立 worktree 不冲突 · A22.F1 已 dispatched 期间可串行接 |
| F1-1 与 F2-1/F3-1 三并行可能 git 锁冲突(同 04_development worktree) | isolation file · backend_csharp 范围内独占 · 与 F2-1(frontend xilink/drawers)+ F3-1(frontend xilink/nodes + backend Routes/LogModuleRoutes)文件 100% 正交 |
历史
| 时间 | 事件 | hash |
|---|---|---|
| 2026-06-18 17:00 | dispatched(用户 16:50 accept ADR-AIOS-26 + 16:55 三连 start · 关键路径起点 1.5d · 解锁 F1-2 前端 UI) | — |