SoundSwitch Model 领域架构解析：状态边界、事件语义与应用生命周期

• 桌面应用

SoundSwitch 是一款用于切换 Windows 默认音频播放/录制设备的 C# 桌面应用。本文聚焦其SoundSwitch/Model领域（由 Model 领域指南 定义），系统讲解该层如何作为「框架代码与 UI 之间的状态与事件边界」运转：从组合接口设计、partial class 拆分、事件 DTO 语义，到热键注册、设置持久化与验证流程。读完本文，你将掌握 SoundSwitch 模型层的职责划分、新增一项设置时必须接线的四个环节，以及如何在修改模型代码后正确验证。

Model 领域涵盖的范围

按 Model/AGENTS.md 的定义，SoundSwitch/Model领域负责以下四类构件：

其核心边界思想是：框架层（音频枚举、设备切换、通知、托盘）只负责"怎么做"，模型层负责"何时做什么、状态如何变化、如何持久化"，UI 层只负责"展示与触发"。三者通过模型暴露的事件与稳定属性解耦。

三个核心职责：状态边界、事件暴露、持久化协调

AGENTS.md 明确了模型层的三条职责，逐条对照源码说明其落地方式。

1. 作为框架代码与 UI 之间的状态与事件边界

模型层是唯一被 UI 直接持有的状态入口。例如 AppModel.cs 通过单例Instance暴露给整个应用：

public static IAppModel Instance { get; } = new AppModel();

UI 组件（如托盘菜单、设置窗体）只与IAppModel.Instance交互，而音频设备枚举与切换则委托给SoundSwitch.Audio.Manager、DeviceCyclerManager、MicrophoneMuteToggler等框架组件。从 AppModel.cs 的构造函数可见，模型在内部组装这些依赖，UI 无须感知其实现细节：

private AppModel() { _notificationManager = new NotificationManager(this, this, this); _deviceCyclerManager = new DeviceCyclerManager(); _selectedDevices = null; _microphoneMuteToggler = new MicrophoneMuteToggler(AudioSwitcher.Instance); _updateScheduler = new LimitedConcurrencyLevelTaskScheduler(1); }

2. 通过事件与稳定属性暴露状态变化

模型不要求 UI 轮询状态，而是通过事件主动通知。例如切换默认设备成功后触发DefaultDeviceChanged，设备列表变更后触发SelectedDeviceChanged（见 AppModel.DeviceService.cs）。UI 订阅这些事件刷新界面，而模型自身对"事件如何被消费"一无所知，从而保持单向依赖。

3. 协调设置持久化，但不嵌入表单逻辑

所有设置属性的 setter 都遵循同一模式：写配置 → 保存 → 广播事件。以 AppModel.NotificationSettings.cs 中的SwitchDeviceNotification为例：

public NotificationType SwitchDeviceNotification { get => AppConfigs.Configuration.SwitchDeviceNotification; set { var previousSwitchDeviceNotification = AppConfigs.Configuration.SwitchDeviceNotification; var previousSwitchProfileNotification = AppConfigs.Configuration.SwitchProfileNotification; var previousMicrophoneMuteNotification = AppConfigs.Configuration.MicrophoneMuteNotification; AppConfigs.Configuration.SwitchDeviceNotification = value; if (!AppConfigs.Configuration.NotificationAdvancedMode) { AppConfigs.Configuration.SwitchProfileNotification = value; AppConfigs.Configuration.MicrophoneMuteNotification = value; } AppConfigs.Configuration.Save(); NotificationSettingsChanged?.Invoke(this, new NotificationSettingsUpdatedEvent(previousSwitchDeviceNotification, AppConfigs.Configuration.SwitchDeviceNotification, previousSwitchProfileNotification, AppConfigs.Configuration.SwitchProfileNotification, previousMicrophoneMuteNotification, AppConfigs.Configuration.MicrophoneMuteNotification)); } }

设置窗体（Settings.cs）只需绑定这些属性并订阅NotificationSettingsChanged等事件即可，保存、校验、级联逻辑全部收敛在模型内部。这正是"不嵌入表单逻辑"的含义：模型是配置层AppConfigs与 UI 之间的唯一代理。

组合接口 + 分部类：IAppModel 与 AppModel 的对齐设计

AGENTS.md 特别强调"保持IAppModel与AppModel对齐"。二者的对齐方式非常清晰：

接口侧：组合而非巨型接口

IAppModel.cs 只做一件事——把四个聚焦子接口组合起来：

public interface IAppModel : IDeviceService, INotificationSettings, IAppSettings, IAppInfrastructure, IDisposable { }

四个子接口各自负责一个关注点：

• IDeviceService.cs：设备选择、默认设备切换、麦克风静音控制；
• INotificationSettings.cs：通知类型、横幅（Banner）位置/时长/透明度、自定义提示音、并发通知数量；
• IAppSettings.cs：开机自启、语言、更新通道、热键组合、遥测开关；
• IAppInfrastructure.cs：托盘图标、设备监听器、Profile 管理、App Sound Lock 管理、初始化入口。

这种"组合接口"模式让调用方既可以通过IAppModel一次性访问全部能力，也可以按需依赖某个子接口（例如只关心设备服务的消费者仅依赖IDeviceService），同时保持接口声明内聚。

实现侧：partial class 按关注点拆分

AppModel.cs 声明为public partial class AppModel : IAppModel，各关注点分散在独立分部类文件中，与子接口一一对应：

这一组织方式使得"接口按关注点拆分、实现按关注点拆文件"，两者天然对齐——新增一个设置时，接口声明与分部类实现的位置都能被快速定位。

事件系统：序列化无关、逻辑最小的事件 DTO

AGENTS.md 要求"事件 DTO 保持最小逻辑、与序列化无关"。事件定义集中在 Events.cs，全部继承EventArgs，只携带「变更前/变更后」的数据快照，不做任何处理。

典型如设备默认角色变化事件 Events.cs：

public class DeviceDefaultChangedEvent(DeviceFullInfo device, ERole role) { public string DeviceId => Device.Id; public ERole Role { get; } = role; public DeviceFullInfo Device { get; } = device; }

以及横幅设置变更事件BannerDataChangedEvent（Events.cs），它一次性携带 8 组 prev/new 快照：横幅位置、显示时长、透明度、显示内容、静音/取消静音横幅。消费者（如BannerManager）只读这些属性渲染 UI，事件 DTO 本身不含任何业务方法，也不依赖具体序列化框架，因此可以在 UI 线程与后台线程之间安全传递。

变更规则：新增设置的「四要素接线」

AGENTS.md 给出了最关键的工程约束：新增设置时，必须同时接通四个环节——模型属性、持久化、迁移、运行时消费方。以真实存在的设置项逐一映射：

值得注意的是 AppModel.cs 展示了一个完整的迁移范例：当检测到旧的SwitchForegroundProgram_force_off迁移标记存在且用户已关闭该功能时，模型会执行清理（重置进程级设备配置）并追加SwitchForegroundProgram_cleanup标记，最后统一Save()。这验证了"设置变更必须验证迁移路径"的规则。

热键的接线范例

热键是「运行时消费方」最典型的一环。设置侧由SetHotkeyCombination统一处理（AppModel.AppSettings.cs）：先注销旧组合、注册新组合，再按HotKeyAction（Playback / Recording / Mute，见 HotKeyAction.cs）写入对应配置并保存。运行时侧，HandleHotkeyPress根据命中的热键分派到CycleActiveDevice或ToggleMicrophoneMute，并记录遥测。启动时若某个热键注册失败（如被其他程序占用），模型会自动禁用该热键并保存配置（AppModel.cs），保证应用不会因注册失败而崩溃。

应用上下文：模型与生命周期、IPC 的衔接点

SoundSwitchApplicationContext.cs 是模型进入运行时的装配点，继承 WinForms 的ApplicationContext，负责：

1. 初始化基础设施：设置横幅管理器、麦克风静音横幅、快捷菜单；创建CachedAudioDeviceLister并刷新设备；注册MMNotificationClient；
2. 启动模型：调用AppModel.Instance.InitializeMain(deviceActiveLister, Program.SkipUpdate)（见 AppModel.cs），内部完成热键注册、通知管理器初始化、Profile 管理器与 App Sound Lock 管理器启动、更新检查器装配；
3. 注册 IPC 消息处理器：通过NamedPipe.RegisterMessageHandler处理来自 CLI/其他实例的请求，包括麦克风状态查询与静音设置、打开设置、触发 Profile、切换设备、查询活动设备与可切换设备列表等；
4. 首次运行引导：若FirstRun为真，自动弹出设置窗口。

模型在这里充当 IPC 请求与实际操作的桥接层：SoundSwitchApplicationContext收到TriggerSwitchRequest后调用AppModel.Instance.CycleActiveDevice(...)，收到MuteRequest后调用AppModel.Instance.SetMicrophoneMuteState(...)。这也解释了为何模型必须提供"稳定属性"——IPC 的响应数据（如设备名NameClean、活动 Profile 名）均来自模型暴露的稳定查询接口。

验证：构建与设置变更的回归检查

AGENTS.md 的 Validation 部分要求两条验证路径：

1. 构建整个解决方案：在仓库根目录执行dotnet build（解决方案文件为 SoundSwitch.sln，依赖版本由 Directory.Build.props 与 Directory.Packages.props 统一管理）。模型层改动若破坏接口对齐，编译期即可暴露。
2. 针对设置变更的专项验证：改动任一设置项后，至少验证三条路径——初始化读取（首次启动时SelectedDevices从配置懒加载，见 AppModel.DeviceService.cs）、保存行为（setter 内Save()被触发）、迁移路径（MigratedFields标记与迁移分支按旧配置组合正确执行）。

仓库中的测试套件（SoundSwitch.Tests）覆盖了模型相关行为，例如 AppSoundRuleMigrationTests.cs 验证设置迁移逻辑、SettingsFormTests.cs 验证设置界面与模型的交互，可作为修改模型后的回归参考。

小结

SoundSwitch 的Model领域是一个典型的"状态与事件边界"层：组合接口定义契约、分部类按关注点实现、事件 DTO 只携带数据快照、所有设置走"写配置→保存→广播事件"的统一通道。对贡献者而言，遵循 AGENTS.md 的规则意味着：新增功能优先问"状态应该由谁持有、变化如何广播、持久化与迁移在哪完成"，而这三问的答案都能在AppModel的分部类与Events.cs中直接落地验证。

• 桌面应用