Music Island插件体系完整解析：Better Voice从Sidecar到进程内引擎的设计演进

Music Island 是一款贴在 Windows 桌面顶边的轻量音乐控制与本地语音工具，其主打的语音降噪功能Better Voice经历了一次值得研究的架构演进：从由manifest.json+ TCP 通信管理的 Sidecar 外部插件进程，到直接运行在主进程内的 in-process 音频引擎。本文结合仓库源码与变更记录，带你完整看懂这套 Music Island 插件体系是如何设计、取舍并落地为进程内引擎的。

一、先分清两个概念：Modules 与 Plugins

Music Island 官方文档 docs/PLUGINS.md 对项目扩展能力做了清晰的切分：

Better Voice 最初就是按第二种方式设计的——一个独立的meowmic.exe进程，由主程序负责拉起、监控、通信。

二、Sidecar 时代：插件宿主如何管理一个外部进程

Sidecar 机制的完整实现集中在 src-tauri/src/plugins/mod.rs，可以拆成五个环节：

1. 三级插件发现顺序

discover_plugins（src-tauri/src/plugins/mod.rs#L191-L225）按以下优先级扫描：

1. %APPDATA%\Music Island\plugins\*\manifest.json（主安装位置）
2. 可执行文件同目录plugins\*\manifest.json（便携/U盘场景）
3. 开发覆盖：环境变量MUSIC_ISLAND_PLUGIN_VOICE直接指向某个插件目录

2. manifest.json 契约（v0）

一个插件只需一份清单文件即可被识别，示例见 docs/plugins/better-voice.manifest.example.json：

{ "id": "better-voice", "entryExe": "meowmic.exe", "entryArgs": ["--island-sidecar", "--hidden"], "ipc": { "kind": "tcp", "host": "127.0.0.1", "port": 38472 }, "island": { "railActions": ["toggle", "open-settings"] }, "settings": { "panel": "voice" } }

• entryExe永远相对插件目录解析；
• railActions决定左侧栏图标点击后是「切换引擎」还是「打开设置」；
• settings.panel把插件接入主设置的哪个面板。

3. 进程生命周期状态机

宿主用PluginRuntimeState枚举描述每个插件：Stopped/Starting/Running/Unhealthy/Missing/Error。每次刷新时（refresh_runtime_locked）会同时检查进程是否存活（try_wait）和IPC 是否健康（发一次ping），两者都通过才算Running。

4. TCP JSON-lines 通信

ipc_call（src-tauri/src/plugins/mod.rs#L468-L506）协议非常克制：连接127.0.0.1:38472，写入一行 JSON 请求{ "id": 1, "method": "...", "params": {} }，读回一行响应{ "ok": true, "result": ... }，全程 3 秒超时。Better Voice 当时暴露的方法只有六个：ping、get_status、start_denoising、stop_denoising、update_denoise_config、get_audio_stats。

5. 日志与清理

子进程的 stdout/stderr 被逐行 tee 到%APPDATA%\Music Island\logs\plugins\<id>.log；禁用插件时直接kill + wait，并写入事件日志。

三、转折点在 CHANGELOG 里：从 0.9.10 到 1.3.0

演进时间线记录在 CHANGELOG.md 中，非常耐人寻味：

从 Sidecar 转向进程内引擎，背后有几层清晰的动机：

• 单文件便携分发：Music Island 坚持「永远只有一个music-island.exe」。语音运行时与降噪模型直接嵌入 EXE，首次使用时解压到%APPDATA%\Music Island\voice\，不需要在插件目录里再维护第二个可执行文件；
• 音频链路对时延敏感：Sidecar 方案要经过「进程启动 → TCP 握手 → 序列化往返」，进程内方案让前端命令直接落到AudioEngine，少一跳；
• 接口契约可以原样保留：方法名、参数名全部不变，前端 UI 代码几乎零改动（下文详述）；
• Sidecar 宿主不删，只闲置：为未来的可选伴侣插件保留通道。

四、进程内引擎：voice_invoke 接管一切

现在打开 src-tauri/src/voice/mod.rs，文件开头的注释就是这次演进的宣言：

In-process Better Voice engine (WASAPI + denoise + EQ + FX). No sidecar / TCP — commands talk to AudioEngine directly.

核心结构很简洁：

• VoiceEngineState用Mutex<AudioEngine>持有唯一音频引擎实例，注册为 Tauri 全局状态；
• 对前端只暴露一个入口voice_invoke（src-tauri/src/voice/mod.rs#L148-L314），内部按method字符串分发。

与 Sidecar 时代相比，方法表从 6 个扩展到二十多个：新增switch_model、list_input_devices/list_output_devices、list_denoise_models、监听点控制（set_monitor_mode/set_monitor_point）、EQ 全套（update_eq_config/get_eq_presets/get_eq_frequencies）、Explode特效、VB-Cable 安装检测与安装、设置读写等——这些在 Sidecar 方案里都要各自跨 TCP 序列化，现在只是一次函数调用。

音频管线为：WASAPI 采集 → 降噪（DeepFilter / RNNoise）→ DSP 链（增益 / AGC / EQ / 音效）→ WASAPI 渲染到 VB-Cable 虚拟麦克风。引擎内部用 8 帧环形缓冲预留约 80ms 余量来抗抖动（src-tauri/src/voice/audio_engine.rs#L20-L21）。

最妙的设计：前端契约完全没变

看 src/features/plugins/voice/pluginApi.ts，前端仍然调用startDenoising、stopDenoising、updateDenoiseConfig这些方法名——源码注释写得很直白：“same method names as the old IPC”。变的只是传输层：从「TCP + JSON lines」换成 Tauri commandvoice_invoke，方法名与参数结构原样保留。这意味着 Better Voice 的全部 UI（设置面板、效果卡片、狐狸吉祥物状态机）在架构切换时一行没改，是“先定契约、后换实现”的教科书式案例。

五、插件宿主没有死，只是“待机”

演进之后，Sidecar 机制并没有被删除。看bootstrap函数（src-tauri/src/plugins/mod.rs#L523-L526），整个函数体只剩一行：

logging::append_event("plugin host idle (in-process voice)");

这行日志说明了现状：Better Voice 内嵌在进程内（voice模块），Sidecar 插件保持禁用但机制保留。前端侧的 src/features/plugins/usePlugins.ts 与 src/features/plugins/PluginRail.tsx 也完整保留——只要将来某个目录里出现合法的manifest.json，左侧栏图标、启用/禁用开关、状态轮询就会自动工作。文档也明确：Handy STT 与未来的自定义插件可以复用同一套 manifest + IPC 契约。

六、关键文件速查表

七、总结：一次教科书式的架构收敛

Better Voice 的演进可以概括为一句话：先用 Sidecar 验证插件契约，再把同一个契约收敛进进程。Sidecar 方案留下了完整的发现机制、清单格式与 JSON-lines 协议，作为面向未来伴侣插件的“保留通道”；而音频这条低时延、强耦合的链路则回归进程内，由voice_invoke直接对话AudioEngine。方法名不变、UI 不变、用户体验不变——变的只是方法背后那一层传输。对任何想把“外挂组件”演进为“内建引擎”的团队，这个仓库都提供了一个干净、可追溯的参考样本。🎙️