System Capabilities Roadmap · v1.0

系统能力路线图 v1.0

Phase 9+ 十议题 A-J · ThreadChange 详细设计 · 格式转换模块规范 · 长期演进

作者：Cline · 日期：2026-05-08 · 版本：v1.0 · 基于 review v7.0

10

系统级议题 A-J

3

Phase 9 格式转换模块（resampler / channel_remap / format_convert）

3

未来 Phase（9 / 10 / 10+）

系统能力路线图 v1.0

文档目的

给出 Phase 8 之后的系统级能力演进路线图：ThreadChange 多核切换的完整设计（Phase 9 启用）、三个格式转换模块的规范（Phase 9 按需实施）、十议题 A-J（延时账本 / 状态机 / 多链路 / 错误恢复 / 测试框架 / 版本兼容 / mode 一致性 / 日志回流 / 格式转换 / i18n）的 Phase 8 vs Phase 9+ 归属、以及长期战略规划。

本文档与兄弟文档的关系

架构决策与 DQ 清单：Source/Sink 架构 Review v7.0
Phase 8 落地计划：Phase 8 实施计划 v1.0
本文档：Phase 9+ 长期路线图（未来做什么 / 怎么做 / 什么时候做）

本文档的"规划性"定位

本文档属于 D3 架构级文档的前瞻设计（未固化为代码）。随着 Phase 8 实测结果产出（特别是 §9 监控数据），本路线图可能调整——ThreadChange Go/No-Go 决策、多链路优先级、资源需求等均取决于实测负载。

1. 路线图总览

1.1 Phase 时间轴

gantt
    title Xisound DSP 系统能力演进（基于 review v7.0）
    dateFormat  YYYY-MM-DD
    section Phase 8
    Core Loop · 音频流打通 (16d)       :done,  p8, 2026-05-08, 16d
    section Phase 9
    ThreadChange 多核切换            :       p9a, after p8, 14d
    错误恢复 · DSP crash 自愈       :       p9b, after p8, 5d
    日志回流实时 WS                  :       p9c, after p8, 3d
    格式转换三模块（按需）           :       p9d, after p9a, 10d
    mode DSP 侧校验                 :       p9e, after p9b, 2d
    SaveProject UI 完善              :       p9f, after p9b, 4d
    section Phase 10
    多链路 · multi-session          :       p10a, after p9d, 12d
    版本兼容迁移 API                :       p10b, after p9d, 5d
    多路径延时对齐                   :       p10c, after p9d, 4d
    section Phase 10+
    i18n · 多语言                    :       p11a, after p10a, 8d
    离线模式                         :       p11b, after p10a, 6d
    插件扩展 .so/.dll                :       p11c, after p10a, 20d

1.2 议题 A-J 的 Phase 归属（DQ13-DQ22 approved）

议题	Phase 8	Phase 9	Phase 10+
A · 延时账本（totalLatency 累计）	✅	—	多路径对齐
B · 处理状态生命周期（link state machine）	简单徽章	完整	—
C · 多链路 / multi-instance	❌	❌	✅ Phase 10
D · 错误 / 故障恢复	underrun/overrun + fatal 广播	DSP crash 自恢复	—
E · 测试 / 验证自动化	≥3 单测/模块	CI 回归	—
F · 版本兼容性	schemaVersion 头	—	迁移 API Phase 10
G · mode 三端一致性	前端 readonly + 后端校验	DSP 侧校验	—
H · 日志 / 诊断回流	文件 log	实时 WS 回流	—
I · 格式转换（resampler 等）	只预留 ID	按需实施	—
J · i18n / 离线 / 插件	❌	❌	✅ Phase 10+

2. 议题 A-J 详细盘点

用户 v6.0 反馈（verbatim）

这些是有 source 和 sink 印出来的整个系统框架设计的一部分内容，你可以再从整个产品系统的维度看一下，还有哪些是没有的需要设计的，以及当前功能框架上不满足的，我们当前的第一步是这个框架从前端到后端到 DSP 能打通音频流，后续就是围绕这个主题进行外围的其他功能开发。

基于子代理从产品维度（对标 AWE / Dolby / Qualcomm Audio Designer / Cadence HiFi）的盘点，v6.0 识别出 10 个 v5.0 未覆盖但框架级必须考虑的主题。本章逐条展开。

2.1 议题 A · 端到端延时账本（Latency Accounting）

现状：DSP ModuleInstance / ModuleFuncTable 无 getLatency。无端到端累积。

期望：Framework 按拓扑序累加每模块 latencySamples，输出 chain.totalLatencyMs；多路径（mixer）各分支延时不一致时告警。

Gap：需要 Manifest 的 latencySamples + getLatencySamples hook 支撑。

Phase 8 落地（DQ13 approved）：✅ MetricsAggregator 顺便算 totalLatency（几乎零成本）。单路径累加 latencySamples，多路径场景暂取最长分支。

Phase 10+ 延伸：多路径延时对齐——mixer 输入各分支延时不一致时，自动插入 delay_align 模块补齐，防止相位抵消。

2.2 议题 B · 处理状态生命周期（Link State Machine）

现状：DynamicChain 已有 RebuildState { IDLE / FADEOUT / PENDING / FADEIN }（用于 SetLink 淡入淡出），但前端看不到。

期望：link 状态机广播到前端：CREATED → PROPAGATING → ALLOCATING → INIT → RUNNING → FADEOUT → DESTROYING。

Gap：WS 协议无 link_state_change 消息。

Phase 8 落地（DQ14 approved）：✅ 简单状态徽章——前端只显示 RUNNING / FADEOUT 两态（足够让用户知道"当前链路在跑还是在切换"）。

Phase 9 延伸：完整状态机 UI——显示所有 7 态 + 每态耗时；对调试 SetLink 慢的场景有用。

2.3 议题 C · 多链路 / Multi-Instance

现状：后端 DSPSessionService 全局单例，只支持一条活跃 link。

期望：同一后端进程支持 N 条并行 link（多房间 / 多会话场景）；前端同时打开多工程。

Gap：后端需 DSPSessionManager 管理多个 session，link.json 加 sessionId。

Phase 8 落地（DQ15 approved）：❌ 单链路，只确保"换工程时干净 tear-down"。

Phase 10 延伸：完整多链路 / multi-session。核心改动：

后端 DSPSessionManager：按 sessionId 分配独立的 paramStore + WasapiDrivenEngine
DSP framework 多实例：每个 session 对应一个 DynamicChain + 独立 link_graph
link.json 顶层加 sessionId 字段
WS 协议所有消息加 sessionId 路由
资源配额：每 session 最大模块数 / CPU 配额 / 内存上限

2.4 议题 D · 错误 / 故障恢复

现状：DSP underrun 只打 log，不恢复；DSP crash 前端无感知。

期望：分级错误（warning / error / fatal）+ 自动恢复（underrun → 填零继续 / fatal → 重载 DSP）+ 前端告警弹窗。

Gap：WS 协议无 error_event 分级消息；无 DSP crash 监控。

Phase 8 落地（DQ16 approved）：✅ underrun/overrun 计数上报 + fatal 错误广播。

Phase 9 延伸：DSP crash 自恢复—— - 后端 DspHealthMonitor 服务：看门狗 ping DSP，1s 无响应判 crash - 自动重启 DSP：重建 link + 重展开 profile + 重启 WasapiDrivenEngine - 前端弹告警："DSP 已重启，请检查链路" - 恢复策略分级：WARNING（显示告警，不中断） / ERROR（暂停 Process） / FATAL（重启 DSP）

2.5 议题 E · 测试 / 验证自动化

现状：UnitTest_Mixer 是 e2e 集成测试，覆盖有限；无单元测试；无回归基线。

期望：DSP 模块 pytest 风格单测 + 集成测试套件（覆盖 10 种 source × 2 种 sink 矩阵）+ CI 回归。

Gap：dsp_algo/test/ 无测试框架。

Phase 8 落地（DQ17 approved）：✅ 新 10 source 模块每模块 ≥ 3 个测试（详见 phase8-implementation-plan.md §6）。

Phase 9 延伸： - DSP 侧测试框架（C Unity / CMocka） - GitHub Actions CI：PR 触发 DSP + 后端 + 前端全套回归 - 回归基线：WAV 文件 + metrics JSON，每次 PR 比对 - 性能基线：Process 耗时 EWMA 不得比上一版慢 10%

2.6 议题 F · 版本兼容性

现状：模块 moduleId 含版本号（source_sine_v1），link.json 直接引用；v1→v2 升级无迁移路径。

期望：ModuleRegistryEntry 支持版本别名（source_sine_v1 → auto-upgrade to v2）；link.json 加 schemaVersion 字段。

Gap：无迁移 API，无 schema 版本头。

Phase 8 落地（DQ18 approved）：✅ link.json 头部加 "schemaVersion": "8.0"。

Phase 10 延伸： - 迁移 API：LinkMigrator.Migrate(oldLink, targetVersion) - 模块版本别名：source_sine_v1 废弃但保留 alias，加载时自动改写为 source_sine_v2 + 参数映射 - Migration 规则登记：migrations/8.0-to-9.0.json 声明旧→新字段映射

2.7 议题 G · mode 约束三端一致性

现状：review §11.3 提到三种 mode（chain_builder / tuning / test_verify），但约束只在后端校验，前端不知道 / DSP 不知道。

期望：mode 变更时前端 UI 锁定结构性控件 + DSP 拒绝 role=system 参数（tuning 模式）。

Gap：前端 modeStore.ts 需暴露当前 mode，UI 按 mode 条件渲染。

Phase 8 落地（DQ19 approved）：✅ 前端 readonly 标记 + 后端校验（已有）。

Phase 9 延伸：DSP 侧也做最终校验——防止前端被绕过（例如 API 直接发 WS）导致 tuning 模式改了 role=system 参数。

2.8 议题 H · 日志 / 诊断回流

现状：DSP 侧只有 printf 打印（不进日志系统）；后端日志不回流前端。

期望：DSP 统一 log API（DSP_LOGI/W/E）+ 后端 logger + 前端"诊断面板"显示。

Gap：DSP 侧 log API 不存在；WS 协议无 log_event。

Phase 8 落地（DQ20 approved）：❌ 只做文件 log + 前端"打开日志"按钮（实时 WS 回流复杂度太高）。

Phase 9 延伸： - DSP 侧 DSP_LOGI/W/E API + 环形日志 buffer（避免在 Process 线程打印） - 后端 LogAggregator 每秒拉 DSP log buffer → 写文件 + 广播 WS - 前端"诊断面板"：滚动显示 log，支持级别过滤 / 搜索

2.9 议题 I · 音频格式转换模块

见本文档 §4 格式转换三模块详细规范。

Phase 8 落地（DQ21 approved）：❌ 只预留 TypeNumId + stub（0x100D0001 resampler_v1 / 0x100D0002 channel_remap_v1 / 0x100D0003 format_convert_v1）。

Phase 9 延伸：按实测需求实现三模块（某些链路格式不一致时，LinkPropagator 自动插入）。

2.10 议题 J · 国际化 / 离线模式 / 插件扩展

国际化：当前前端写死中文，未来多语言支持（vue-i18n）
离线模式：当前必须连后端，未来支持"前端单独打开 link.json 预览"
插件扩展：当前 DSP 模块写在库内，未来支持动态加载 .so/.dll

Phase 8 落地（DQ22 approved）：❌ 全部推到 Phase 10+（现阶段核心是音频流打通）。

Phase 10+ 延伸： - i18n：vue-i18n + zh/en/ja 三语言 + 所有模块 displayName 国际化（后端 manifest 加 displayName_zh / displayName_en 字段） - 离线模式：前端嵌入只读 DSP WebAssembly 版本，link.json 可本地预览（不下发实机） - 插件扩展：DSP framework 支持 dlopen / LoadLibrary 动态加载 .so / .dll 模块；引入插件签名 / 沙箱机制防止恶意代码

3. ThreadChange 多核切换详细设计（Phase 9 启用）

用户 v5.0 反馈（verbatim）

在竞品中是支持 threadchange 这个功能的，也就是说在 CPU 上可以根据硬件分出多个 CPU 核心，每一个作为一个独立的资源，同理 DSP 上也是支持多 DSP 多核工作的，那这个 ThreadChange 的意义就是同一条链路中可以实现不同模块的多个 thread 之间进行切换，比如 gain 在 cpu1 上运行，后面会接上一个 threadchange 选择 cpu2，那后面的算法 eq 就在 cpu2 上运行，再加一个 changethread change 到 cpu3 最后 change 到 cpu1，这种操作，来实现多 thread 在一个硬件上同时运行，当然这种跨线程的操作会增加整体的延时，消耗内存等。

3.1 ThreadChange-Ready 框架兼容性清单（Phase 8 已落地 · Phase 9 启用）

Phase 8 的关键任务是让实现里 1 个 core 在跑，但设计里支持 N 个 core。Phase 9 开发 ThreadChange 时只是"启用更多线程 + 注册 thread_change_v1 模块"，不推翻 Phase 8 任何代码。

3.1.1 DSP 侧（dsp_algo）· Phase 8 必须改的接口

改动项	旧（Phase 8 前）	Phase 8 框架	Phase 9 启用
`DSPAlgo_Process` 签名	`void DSPAlgo_Process(buf_in, buf_out, n)`	`void DSPAlgo_Process(int coreId, buf_in, buf_out, n)`	`coreId=0..N-1` 由后端调度器分配
`ModuleInstance` 结构	无 coreId / processOrder	加 `int coreId`（默认 0）+ `int processOrder`（按拓扑序）	框架按 coreId 分组调用
`LinkFrame` 二进制格式	ConnEntry 无 coreId	ConnEntry 扩展 `uint8_t srcCoreId + dstCoreId`	Phase 9 判断是否需要跨核 ring buffer
`module_type_id.h`	—	预留 `0x100C0001 thread_change_v1` + `0x100D0001-3` 格式转换	逐个实现
framework scheduler	硬编码 `for(each module) module.Process()`	抽象 `Scheduler_Run(coreId)`，分核调度	多线程并行调用

3.1.2 后端 C# 侧 · Phase 8 必须改的服务

改动项	旧	Phase 8 框架	Phase 9 启用
`WasapiDrivenEngine`	单 Process 线程	抽象 `ICoreExecutor` 接口，默认 1 个实例	启动 N 个 ICoreExecutor，各自 MMCSS + affinity
`LinkFrameBuilder`	无 coreId 输出	为每个 module 填 `coreId=0`，ConnEntry 填 `srcCoreId=dstCoreId=0`	Phase 9 按 link_graph 分段决定 coreId
`LinkGraph` 数据结构	`List<Module>` + `List<Connection>`	`List<CoreSegment> { coreId, List<Module>, List<Connection> }`	Phase 9 按 coreId 分段
WS 协议 `metrics_update`	整体 + per-module	按 `core.{coreId}.` + `module.{instanceId}.`（core 字段 Phase 8 全 0）	Phase 9 多核各自上报

3.1.3 前端 TS 侧 · Phase 8 必须改的类型

改动项	旧	Phase 8 框架	Phase 9 启用
`ModuleInstance` type	无 coreId	加 `coreId?: number`（可选，默认 0）	Phase 9 用户拖 thread_change 模块时分配
`LinkGraph` 可视化	单色背景	按 coreId 分区着色（Phase 8 全绿，不显示分区）	Phase 9 多核不同背景色
`moduleLibrary`	无 thread_change	注册 stub `thread_change_v1`（category=system，disabled）	Phase 9 enable

3.1.4 不会推翻的部分（v7.0 承诺）

✅ review §12.3 SetParam lock-free MPSC 队列机制不变（Phase 9 每 core 一个独立队列）
✅ review §12.4 Device capture 独立线程 + ring buffer 机制不变
✅ review §12.5 Wav 预读入内存机制不变
✅ review §14 / 本文档 §2.1 / phase8-implementation-plan §9 监控指标体系不变（仅扩展 per-core 维度）
✅ review §10 参数生命周期四层模型不变
✅ review §4.6 10 模块参数 schema 不变
✅ link.json 结构不变（仅新增可选字段 coreId / processOrder）

3.2 竞品参考（AWE · Cadence）

AWE 的 ThreadChange 模块本质是链路分段点：

上游模块在线程 A 完成 Process
ThreadChange 把输出 buffer 写入跨线程 ring buffer（或共享内存区）
下游模块在线程 B 的下一个 block 边界读取
引入 1 个 block 的延时（例如 ~1.33ms @ 48k/64）每经过一次 change
各线程有独立 block 节拍器（通常共享系统时钟但各自调度）

3.3 `thread_change_v1` 模块设计

3.3.1 参数

Param	类型	默认	role	说明
enable	bool	true	system	启用
targetCoreId	int	0	structural	目标核/线程 ID（变更需 SetLink）
bufferFrames	int	128	structural	跨线程 ring buffer 大小（DQ12 approved）
mode	enum	async	system	`async`（延时 1 block）\| `sync`（强制同 block，不推荐）

3.3.2 DSP 侧内部状态

typedef struct {
    // 跨线程 lock-free SPSC ring buffer（上游写、下游读）
    float*      crossRing;        // 容量 = bufferFrames × channels
    uint32_t    ringCapacity;
    _Atomic uint64_t writePos;    // 上游线程写
    _Atomic uint64_t readPos;     // 目标线程读

    uint32_t    numChannels;
    uint32_t    targetCoreId;

    // 监控
    _Atomic uint64_t underrunCount;  // 下游读空
    _Atomic uint64_t overrunCount;   // 上游写满
} thread_change_state_t;

3.3.3 Process 行为

上游线程调 Process()：将输入 block 写入 crossRing（lock-free SPSC write），输出自己的 port 为零/静音（这是"出口"）
下游线程调 Process()：读 crossRing（lock-free SPSC read），作为"入口"向后传递
两端都不阻塞等待：上游写满 → 丢弃 + overrunCount++；下游读空 → 补零 + underrunCount++

3.4 调度模型（后端）

flowchart TB
    subgraph C1["Core 1 线程 (MMCSS Pro Audio)"]
        P1["Process 线程 C1<br/>drain param queue<br/>Process 上半段链路"]
        M1["module: source / gain"]
        TC1_OUT["thread_change_v1 (出口 #1)"]
    end

    subgraph C2["Core 2 线程 (MMCSS Pro Audio)"]
        P2["Process 线程 C2"]
        TC1_IN["thread_change_v1 (入口 #1)"]
        M2["module: eq"]
        TC2_OUT["thread_change_v1 (出口 #2)"]
    end

    subgraph C3["Core 3 线程 (MMCSS Pro Audio)"]
        P3["Process 线程 C3"]
        TC2_IN["thread_change_v1 (入口 #2)"]
        M3["module: compressor"]
        TC3_OUT["thread_change_v1 (出口 #3)"]
    end

    subgraph C1B["Core 1 线程（回到 C1 合并 sink）"]
        TC3_IN["thread_change_v1 (入口 #3)"]
        M4["module: sink"]
    end

    M1 --> TC1_OUT
    TC1_OUT -.->|lock-free SPSC| TC1_IN
    TC1_IN --> M2 --> TC2_OUT
    TC2_OUT -.->|lock-free SPSC| TC2_IN
    TC2_IN --> M3 --> TC3_OUT
    TC3_OUT -.->|lock-free SPSC| TC3_IN
    TC3_IN --> M4

关键点：

每个 core 一个独立的 Process 线程（MMCSS Pro Audio，绑定到对应 CPU 核心 / SetThreadAffinityMask）
Process 线程只跑自己 core 上的模块
跨核由 thread_change_v1 的 ring buffer 串联
仅 Core 1 线程由 WASAPI render callback 驱动（sink 所在核），其他 core 线程以相同节拍自驱（或由 Core 1 发信号触发）
必须采用 "各 core 线程节拍严格 1:1 对齐" 策略，否则 cumulative drift

3.5 延时 / 内存代价分析

3.5.1 延时代价

链路	延时
无 ThreadChange（单核）	0（同 block 完成）
1 个 ThreadChange（跨 2 核）	+1 block（典型 +1.33ms @ 48k/64）
2 个 ThreadChange（跨 3 核）	+2 block
N 个 ThreadChange	+N × block 时长

典型用例：source → gain (C1) → TC → eq (C2) → TC → comp (C3) → TC → sink (C1)，三个 TC = +3.99ms 总延时（@ 48k/64）。调音场景可接受（<10ms），严格实时场景（live monitoring）需谨慎。

3.5.2 内存代价

每个 thread_change_v1 实例：

crossRing 容量：bufferFrames × numChannels × sizeof(float)
典型 bufferFrames=128, channels=2, float32 = 1024 字节 / 实例
N 个 ThreadChange 总内存 = N × 1024 字节（可忽略）

但额外消耗：

每个新增 Process 线程有 ~1MB 栈 + MMCSS scheduling 开销
线程间 cache line 竞争（即使 lock-free）也会拖慢
CPU 核数不足时，新增线程反而降低吞吐（OS scheduler 抢占）

3.6 Phase 9 启用时的 Go/No-Go 评估

维度	Go（启用 ThreadChange）	No-Go（继续单核）
单核 CPU 负载实测（Phase 8 监控）	> 70% 持续	< 50% 宽松
硬件	目标部署机 ≥ 4 核	低端机只有 2 核
业务需求	某条链路需要 EQ + Dynamics + Reverb + Spatial 极限组合	典型链路 < 10 模块
团队经验	已有多线程 DSP 调试经验	新团队不熟 lock-free

Phase 9 实施建议

先跑 Phase 8 监控，收集 1-2 周实测 CPU 负载数据
识别"负载 > 70% 的链路" / "需要 4+ 模块并行的客户场景"
如果负载稳定 < 50%，Phase 9 不启用 ThreadChange，节省工程力投入其他功能
如果负载持续 > 70%，启动 Phase 9a（ThreadChange 实施，见 §3.7）

3.7 Phase 9 实施工作量

thread_change_v1 模块实现：~300 LOC C + lock-free SPSC 工具库（~200 LOC）
后端 ICoreExecutor 多实例启动：~100 LOC C#
Link propagate 拆段（按 coreId 分 CoreSegment）：~200 LOC
前端按 coreId 分区着色 + thread_change enable：~100 LOC
测试（跨核信号连续性 + drift 累积 + 极限负载 overrun/underrun）：~5 天
总人天：~14 天

4. 格式转换三模块详细规范（Phase 9）

4.1 背景

当前链路中音频格式（blockSize / sampleRate / pcmFormat / numChannels）默认均匀（全链路单一格式）。review §16 已给出 PortInfo propagation 的 pass-through 协议（Phase 8 落地）；当链路出现格式不匹配时（例如 source 48k → sink 96k），需要格式转换模块自动介入。

4.2 格式转换三模块

模块	作用	参数	延时代价
`resampler_v1`	改变采样率（48k → 96k 等）	`targetSampleRate`（structural）+ `quality` (low/medium/high)	高质量 ~20ms（64 tap sinc）
`channel_remap_v1`	改通道数 + 重排映射	`remapMatrix[in][out]`（structural）	0（无延时）
`format_convert_v1`	改 dataType（float32 ↔ int32 / int16 等）	`targetDataType`（structural）	0（纯类型转换）

4.3 LinkPropagator 自动插入逻辑（Phase 9 扩展）

Phase 8 的 pass-through propagate 遇到格式不一致时报 format_mismatch 错误。Phase 9 扩展为"自动插入格式转换模块"：

flowchart TB
    A["propagate 阶段 2"]
    B{"outSpec != inSpec<br/>of next module?"}
    C["检查差异类型"]
    D1["仅 sampleRate 不同<br/>→ 插入 resampler_v1"]
    D2["仅 numChannels 不同<br/>→ 插入 channel_remap_v1"]
    D3["仅 dataType 不同<br/>→ 插入 format_convert_v1"]
    D4["多维度不同<br/>→ 插入组合（按 SR → Channel → Format 顺序）"]
    E["更新 link_graph + 重新 propagate"]
    F["postPropagate 校验"]

    A --> B
    B -->|是| C
    B -->|否| F
    C --> D1 & D2 & D3 & D4
    D1 & D2 & D3 & D4 --> E --> B

重要：自动插入需要用户显式授权（前端弹确认框 "链路 A→B 格式不匹配，是否自动插入 resampler？会增加 ~20ms 延时"），不应默默改变链路拓扑。

4.4 `resampler_v1` 详细设计

4.4.1 参数

Param	类型	默认	role	说明
enable	bool	true	system	启用
targetSampleRate	int	48000	structural	目标采样率
quality	enum	medium	tunable	`low`（16-tap linear）/ `medium`（32-tap windowed sinc）/ `high`（64-tap + polyphase）

4.4.2 算法选型

low：线性插值（最低延时但频谱混叠严重，不推荐生产用）
medium：Hann 窗 sinc（32 tap）+ polyphase 结构，延时 ~15 samples @ target SR
high：Kaiser 窗 sinc（64 tap）+ polyphase，延时 ~30 samples，SNR > 100 dB

4.4.3 特殊情况

sourceSR == targetSR：自动 bypass（不做任何处理）
非整数倍比率（例如 44100 → 48000）：用 LCM 展开 + 抽取（polyphase）
极端比率（> 10:1）：分段 cascade（例如 192k → 8k 用 2 级 resampler）

4.5 `channel_remap_v1` 详细设计

4.5.1 参数

Param	类型	默认	role	说明
enable	bool	true	system	启用
inputChannels	int	2	structural	输入通道数
outputChannels	int	2	structural	输出通道数
remapMatrix	float[in][out]	identity	structural	通道混合矩阵

4.5.2 典型场景

Stereo → Mono：remapMatrix = [[0.5, 0.5]]（左右各 50% → 单 mono）
Mono → Stereo：remapMatrix = [[1.0], [1.0]]（mono 复制到左右）
5.1 → Stereo（downmix ITU-R BS.775-1）：[[1, 0, 0.707, 0.707, 0, 0], [0, 1, 0.707, 0, 0.707, 0]]
任意 channel mask 映射：用户在 UI 上用矩阵拖拽设置权重

4.6 `format_convert_v1` 详细设计

4.6.1 参数

Param	类型	默认	role	说明
enable	bool	true	system	启用
targetDataType	enum	float32	structural	`int16` / `int32` / `float32` / `float64`
dither	enum	none	tunable	`none` / `tpdf`（仅向下转换时需要）

4.6.2 转换规则

源	目标	行为
float32	int16	`× 32767 → clip → int16`（可选 TPDF dither）
float32	int32	`× 2147483647 → clip → int32`（dither 可选）
int16	float32	`/ 32768`
int32	float32	`/ 2147483648`
float32	float64	隐式扩展（零损失）
float64	float32	截断（无损，除非 > ±3.4e38）

4.7 Phase 9 实施工作量

resampler_v1 实现（medium 质量）：~500 LOC C + 测试 ~2 天
channel_remap_v1：~150 LOC C + 测试 ~1 天
format_convert_v1：~100 LOC C + 测试 ~0.5 天
LinkPropagator 自动插入逻辑 + 用户授权对话框：~400 LOC C# / TS
总人天：~10 天

5. Phase 10+ 长期规划

5.1 多链路 · multi-session（议题 C）

详见 §2.3。预估工作量 ~12 天（Phase 10）。

5.2 版本兼容迁移 API（议题 F）

详见 §2.6。预估工作量 ~5 天（Phase 10）。

5.3 多路径延时对齐（议题 A 延伸）

详见 §2.1。预估工作量 ~4 天（Phase 10）——实现 delay_align 模块 + LinkPropagator 多路径分析。

5.4 国际化 i18n（议题 J）

vue-i18n 集成
所有前端文本抽取
模块 displayName 国际化（manifest 扩展 displayName_zh / displayName_en / displayName_ja）
预估 ~8 天

5.5 离线模式（议题 J）

DSP WebAssembly 只读版本
前端嵌入 WASM 可本地 Process（性能受限，仅用于预览）
link.json 可离线加载 / 编辑 / 导出
预估 ~6 天

5.6 插件扩展 .so/.dll（议题 J）

DSP framework 支持 dlopen / LoadLibrary 动态加载
插件签名机制（防止恶意代码）
插件 sandbox（限制内存 / CPU 配额）
插件 SDK（公开 API 头 + 示例）
预估 ~20 天（含安全审计）

6. 路线图更新节奏

本路线图是 D3 架构级文档，按 doc-code-sync-policy v1.0 §3.5 季度评审更新节奏：

每季度末：根据 Phase 实施结果更新 §1.1 Gantt + §2 议题状态
每个 Phase 启动前：对应议题的 §3-§5 章节精化为实施计划（拆出独立的 phaseN-implementation-plan.md）
Phase 9 Go/No-Go 触发点：Phase 8 监控数据收集 1-2 周后（§3.6 条件）
v2.0 触发条件：Phase 9 完成或重大议题调整（例如多链路改为 Phase 9 优先）

7. 附录 · 相关文档

架构决策与 DQ 清单：Source/Sink 架构 Review v7.0
Phase 8 落地计划：Phase 8 实施计划 v1.0
格式规范：D0-company/05-standards/md-style-guide.md v1.1
命名规范：D0-company/05-standards/doc-numbering.md v1.0
分层规范：D0-company/05-standards/doc-code-sync-policy.md v1.0

版本历史

版本	日期	状态	变更
v1.0	2026-05-08	published	从 review v6.0 §15.1-§15.7（ThreadChange 详细设计） + §16.2.3（格式转换三模块） + §18（系统级能力盘点 A-J）拆分独立成文。整合：Phase 时间轴 Gantt + 议题 A-J 逐条盘点（Phase 归属） + ThreadChange 完整设计（含 ready 清单、竞品对标、模块设计、调度模型、代价分析、Go/No-Go 评估、Phase 9 实施工作量） + resampler/channel_remap/format_convert 三模块详细规范 + Phase 10+ 长期规划（多链路/版本兼容/i18n/离线/插件） + 季度评审节奏

反馈

对本路线图有意见？请提 PR 或联系 algo-team@xisound.com。

系统能力路线图 v1.0

系统能力路线图 v1.0

1. 路线图总览

1.1 Phase 时间轴

1.2 议题 A-J 的 Phase 归属（DQ13-DQ22 approved）

2. 议题 A-J 详细盘点

2.1 议题 A · 端到端延时账本（Latency Accounting）

2.2 议题 B · 处理状态生命周期（Link State Machine）

2.3 议题 C · 多链路 / Multi-Instance

2.4 议题 D · 错误 / 故障恢复

2.5 议题 E · 测试 / 验证自动化

2.6 议题 F · 版本兼容性

2.7 议题 G · mode 约束三端一致性

2.8 议题 H · 日志 / 诊断回流

2.9 议题 I · 音频格式转换模块

2.10 议题 J · 国际化 / 离线模式 / 插件扩展

3. ThreadChange 多核切换详细设计（Phase 9 启用）

3.1 ThreadChange-Ready 框架兼容性清单（Phase 8 已落地 · Phase 9 启用）

3.1.1 DSP 侧（dsp_algo）· Phase 8 必须改的接口

3.1.2 后端 C# 侧 · Phase 8 必须改的服务

3.1.3 前端 TS 侧 · Phase 8 必须改的类型

3.1.4 不会推翻的部分（v7.0 承诺）

3.2 竞品参考（AWE · Cadence）

3.3 thread_change_v1 模块设计

3.3.1 参数

3.3.2 DSP 侧内部状态

3.3.3 Process 行为

3.4 调度模型（后端）

3.5 延时 / 内存代价分析

3.5.1 延时代价

3.5.2 内存代价

3.6 Phase 9 启用时的 Go/No-Go 评估

3.7 Phase 9 实施工作量

4. 格式转换三模块详细规范（Phase 9）

4.1 背景

4.2 格式转换三模块

4.3 LinkPropagator 自动插入逻辑（Phase 9 扩展）

4.4 resampler_v1 详细设计

4.4.1 参数

4.4.2 算法选型

4.4.3 特殊情况

4.5 channel_remap_v1 详细设计

4.5.1 参数

4.5.2 典型场景

4.6 format_convert_v1 详细设计

4.6.1 参数

4.6.2 转换规则

4.7 Phase 9 实施工作量

5. Phase 10+ 长期规划

5.1 多链路 · multi-session（议题 C）

5.2 版本兼容迁移 API（议题 F）

5.3 多路径延时对齐（议题 A 延伸）

5.4 国际化 i18n（议题 J）

5.5 离线模式（议题 J）

5.6 插件扩展 .so/.dll（议题 J）

6. 路线图更新节奏

7. 附录 · 相关文档

版本历史

3.3 `thread_change_v1` 模块设计

4.4 `resampler_v1` 详细设计

4.5 `channel_remap_v1` 详细设计

4.6 `format_convert_v1` 详细设计