DRAFT

Source 模块 · XiStudio

摘要

Source 是 XiStudio 画布中的输入起点模块。当前前端一方面保留 source_v1 作为默认兼容入口，另一方面已经在模块库中引入 source_sine_v1、source_wav_v1、source_device_v1 等拆分模块定义。因此，Source 的产品定义必须同时描述现行可用的 legacy 入口与正在落地的拆分态能力。

1. 当前实现快照

维度	当前实现
默认入口	`source_v1`
模块模式	`builtin_normal`
分类	`source`
端口形态	无输入端口，1 个动态输出端口
默认调参入口	`src/components/SourceTuningDialog.vue`
默认画布行为	新建/清空工程时自动放置一个 `source_v1`
运行模式	`pc` / `dsp`

当前代码对应关系

模块定义：src/stores/moduleLibrary.ts
默认加点与端口传播：src/stores/linkStore.ts
调参界面：src/components/SourceTuningDialog.vue
输入设备枚举：src/stores/deviceStore.ts

2. 产品定位

Source 模块承担链路的信号注入职责，当前前端实现覆盖 4 类入口：

类型	前端模式值	当前交互方式	典型用途
Tone	`tone`	调音面板选择波形与频率参数	正弦/扫频/方波等测试信号
Noise	`noise`	调音面板选择噪声类型与分布	白噪/粉噪/棕噪测试
File	`file`	直接填写文件路径	本地音频文件回放
Device	`device`	枚举输入声卡并选择设备	麦克风/声卡输入采集

与旧文档的关键差异

当前 source_v1 的真实实现是 tone / noise / file / device，不是旧联合文档中的 tone / wav / device / noise。现阶段“文件源”采用路径输入，而非拖拽上传与加载进度条方案。

3. 前端已落地的能力边界

3.1 legacy `source_v1`

source_v1 仍是当前产品面的主入口，具备以下特征：

通过 sourceType 在单个调参窗内切换 4 类输入形态。
输出端口的 channels / blockSize / sampleRate 由参数与链路传播共同决定。
运行中切换参数时，按类型选择热更新或重启音频引擎。
设备模式支持驱动类型切换与输入设备刷新。

3.2 拆分态 `source_*_v1`

模块库已经包含以下拆分 Source 模块定义：

分组	模块
Tone	`source_sine_v1` / `source_sweep_v1` / `source_triangle_v1` / `source_square_v1` / `source_saw_v1`
Noise	`source_noise_white_v1` / `source_noise_pink_v1` / `source_noise_brown_v1`
File / Device	`source_wav_v1` / `source_device_v1`

这些模块已经出现在 moduleLibrary.ts 与模块库面板中，但默认工程初始化仍优先使用 source_v1。这说明当前产品处于“兼容入口保留 + 拆分模型并行存在”的阶段，而不是完全切换到拆分态。

4. Source 的交互定义

4.1 调参窗口结构

当前 SourceTuningDialog.vue 采用固定结构：

启用/禁用开关
Preset 面板
Source 类型切换栏
当前激活状态栏
对应子类型参数区
运行模式切换（pc / dsp）

4.2 Tone / Noise / File / Device 差异

子类型	关键参数	当前实现特征
Tone	`toneWaveform`、`toneStartFreq`、`toneEndFreq`、`toneAmplitude`、`toneDurationSec`	支持 `sweep / sine / triangle / sawtooth / square`
Noise	`noiseType`、`noiseDist`、`noiseChannelMode`、`noiseAmplitude`	支持 `black / white / pink / brown`
File	`filePath`、`playMode`、`fileGain`	文本路径输入，适合本地文件回放
Device	`inputDeviceId`、驱动类型、设备列表	通过 WebSocket 拉取输入设备列表

4.3 设备输入行为

设备输入模式的当前前端行为如下：

调参窗内可在 DirectX / ASIO 之间切换驱动类型。
点击“刷新”会重新请求输入设备列表。
设备列表为空时显示空状态提示。
选择 inputDeviceId 后，如引擎正在运行，会额外发送专用切换消息。

5. 运行时与链路行为

5.1 默认布点

linkStore.clearLink() 与 addDefaultModules() 会默认向画布加入：

source_v1
sink_v1

因此，从产品体验上，Source 仍是“开箱即用的默认入口”。

5.2 运行中修改的处理策略

操作	当前行为
非 `device` 模式下修改 Tone/Noise/File 参数	调用热更新同步
运行中切换到 `device` 或从 `device` 切回其他类型	重启音频引擎
运行中切换输入设备	发送专用输入设备切换消息

5.3 端口属性

Source 的输出端口是动态端口：

属性	说明
`numChannels`	决定输出通道数
`blockSize`	决定输出块长
`sampleRate`	决定输出采样率
`signalType / dataType / isComplex`	作为输出端口属性参与链路传播

6. 文档索引

类型	文件	说明
架构 review	00-architecture.md	Source/Sink 联合架构与历史决议
前端实现说明	20-frontend.md	基于当前 Vue3 前端代码的实现说明
ADR 决策记录	adr/	待补
Phase 计划	phases/	待补
测试报告	tests/	待补
Bug 复盘	postmortems/	待补

7. 当前结论

一句话结论

Source 当前不是“纯 legacy”，也不是“已完全拆分完成”；它处在source_v1 继续承担默认入口，而拆分模块定义已经进入模块库的双轨阶段。产品文档、测试用例和后续 IA 设计都应以这个现实为准。