企业官网建设流程全解析

• 桌面应用

SoundSwitch 附带了一个命令行接口（SoundSwitch.CLI），面向希望从脚本、快捷方式或自动化工具中控制音频设备的高级用户。借助它，你可以随时切换默认播放/录制设备、管理音频配置文件（Profile）、控制麦克风静音状态、查询当前设备状态，所有命令均支持--json机器可读输出，便于在 PowerShell、批处理、任务计划等场景中进一步编排。本文将以仓库中的官方 CLI 文档（website/src/usage/cli.md）为骨架，并结合SoundSwitch.CLI项目的真实源码，从命令语法、JSON 输出格式、错误处理到 IPC 通信原理做一次完整的实战讲解。

一、SoundSwitch.CLI 是什么

SoundSwitch.CLI是 SoundSwitch 主程序自带的一个独立可执行命令行工具，位于仓库的 SoundSwitch.CLI 目录（项目文件：SoundSwitch.CLI.csproj）。它本身不做音频切换的底层工作，而是通过命名管道（Named Pipe）与正在运行的主进程通信，把用户意图转交给主程序执行。因此：

• 使用前请确保主程序 SoundSwitch 正在运行，否则 CLI 无法连接管道并会报错；
• 命令行返回的结果（如切换是否成功、当前状态）实际来自主程序对管道请求的处理结果。

从源码结构看，CLI 使用了 Spectre.Console.Cli 构建命令体系，入口文件 Program.cs 注册了 6 个子命令，每个命令同时提供人类可读输出（默认）与--json机器可读输出两种模式。

二、快速开始：帮助与版本

直接运行可执行文件即可查看全部命令与语法：

SoundSwitch.CLI.exe --help SoundSwitch.CLI.exe --version

--help会列出所有已注册命令及示例（这些示例来自 Program.cs 中的WithExample配置），--version输出版本信息。每个子命令也都支持--help，例如SoundSwitch.CLI.exe switch --help可查看该命令的专属参数说明。

提示：在 Windows 上，你可以将SoundSwitch.CLI.exe的完整路径加入PATH，之后即可在任意终端、.bat脚本或 PowerShell 中直接调用SoundSwitch.CLI。

三、可用命令总览

CLI 提供以下六类能力（对应 Program.cs 中的六个命令注册）：

四、命令详解与实战示例

4.1 switch：切换播放/录制设备

切换设备是最常用的能力，语法为：

SoundSwitch.CLI.exe switch --type Playback SoundSwitch.CLI.exe switch --type Recording SoundSwitch.CLI.exe switch --type Playback --json

• --type（或-t）取值：Playback/Recording，分别对应循环切换下一个播放设备或下一个录制设备；
• 不加--json时，终端会显示一个临时的状态提示，成功时输出Successfully switched ... device；
• 加--json时输出机器可读 JSON。

从实现看（SwitchCommand.cs），命令会向主进程发送TriggerSwitchRequest，成功后输出：

{ "success": true, "type": "Playback" }

失败则输出{ "error": "..." }并以退出码 1 结束。

4.2 mute：麦克风静音控制

mute命令既可以查询当前状态，也可以静音/取消静音：

SoundSwitch.CLI.exe mute # 查询当前静音状态 SoundSwitch.CLI.exe mute --state true # 静音 SoundSwitch.CLI.exe mute -s false # 取消静音（-s 是 --state 的简写） SoundSwitch.CLI.exe mute --toggle # 切换静音状态（-t 为简写） SoundSwitch.CLI.exe mute --json # 以 JSON 查询当前状态

关键行为（见 MuteCommand.cs）：

• 不带任何动作参数时，仅查询并展示当前默认麦克风的静音状态；
• 指定--state或--toggle时，会先查询当前状态，若目标状态与当前状态一致则不做多余操作（幂等设计）；
• 加--json时，无论查询还是执行，输出格式统一为：

{ "deviceName": "Microphone (USB Audio Device)", "isMuted": false }

• 失败时输出{ "error": "..." }并以退出码 1 结束。若系统未设置默认麦克风，该命令会报错。

4.3 profile：配置档管理与激活

音频配置档是 SoundSwitch 的核心概念之一（保存了播放、录制、通信设备的一组绑定关系）。profile命令提供两个操作：

列出全部配置档：

SoundSwitch.CLI.exe profile --list SoundSwitch.CLI.exe profile --list --json

--json变体输出一个配置档对象的数组，每个对象包含name、playbackDevice、playbackCommunicationDevice、recordingDevice、recordingCommunicationDevice五个字段（字段映射见 ProfileCommand.cs）：

[ { "name": "Gaming", "playbackDevice": "Speakers (Realtek(R) Audio)", "playbackCommunicationDevice": "Headset Earphone (HyperX Cloud II)", "recordingDevice": "Microphone (USB Audio Device)", "recordingCommunicationDevice": "Headset Microphone (HyperX Cloud II)" } ]

激活指定配置档：

SoundSwitch.CLI.exe profile --name "Gaming" SoundSwitch.CLI.exe profile --name "Gaming" --json

• -n/--name用于指定配置档名称，名称需与设置窗口中保存的完全一致；
• 成功时 JSON 输出：

{ "success": true, "profile": "Gaming" }

• 若既没有--list也没有--name，命令会直接报错 "Profile name is required unless --list is specified"（见 ProfileCommand.cs）；配置档名称无效时同样返回错误并以退出码 1 结束。

4.4 settings：打开设置窗口

SoundSwitch.CLI.exe settings SoundSwitch.CLI.exe settings --json

该命令请求主程序打开设置窗口（见 SettingsCommand.cs），JSON 模式成功时输出：

{ "success": true }

失败时输出{ "error": "..." }并以退出码 1 结束。

4.5 status：查询当前状态

status一次性返回当前激活的配置档和四个默认音频端点：

SoundSwitch.CLI.exe status # 人类可读的表格输出 SoundSwitch.CLI.exe status --json # 机器可读 JSON

默认（表格）模式下会以美观的圆角边框表格展示Active Profile、Playback、Recording、Playback Comm、Recording Comm五行（见 StatusCommand.cs）。JSON 模式输出（字段名与 StatusCommand.cs 一一对应）：

{ "activeProfile": "Gaming", "playbackDevice": "Speakers (Realtek(R) Audio)", "recordingDevice": "Microphone (USB Audio Device)", "playbackCommunicationDevice": "Headset Earphone (HyperX Cloud II)", "recordingCommunicationDevice": "Headset Microphone (HyperX Cloud II)" }

两个重要的语义约定：

• activeProfile为null：表示自程序启动以来尚未触发过任何配置档；
• 设备字段为空字符串""：表示当前不存在匹配的设备。

另外需要特别说明：activeProfile只反映最近一次由用户操作或触发器显式激活的配置档，它不会追踪 SoundSwitch 之外的变化（例如直接在 Windows 声音设置中手动改动的设备），请勿把它当作系统级实时状态。

4.6 devices：列出可切换设备

devices用于查询"SoundSwitch 将会循环切换的设备"——即当前已激活（在线）且已在设置中被勾选参与切换的设备：

SoundSwitch.CLI.exe devices SoundSwitch.CLI.exe devices --json

JSON 输出按播放/录制分组（字段与 DevicesCommand.cs 对应）：

{ "playbackDevices": [ "Speakers (Realtek(R) Audio)", "Headset Earphone (HyperX Cloud II)" ], "recordingDevices": [ "Microphone (USB Audio Device)" ] }

注意它与status的差异：status返回的是系统当前的默认端点，而devices返回的是被勾选参与切换的候选设备列表（可能多于当前默认设备）。失败时同样输出{ "error": "..." }并以退出码 1 结束。

五、--json输出约定与错误处理

所有命令都继承自JsonCommandSettings（见 JsonCommandSettings.cs），因此统一支持--json选项，无需额外记忆。这一约定的核心目的是脚本友好：

• 输出通道：JSON 一律通过Console.Out写入标准输出（见 JsonOutput.cs），可直接用管道交给jq等工具解析，或捕获到变量；
• 无 ANSI 污染：JSON 路径下禁止使用 Spectre.Console 的标记与转义序列，避免破坏管道输出（这是 JsonOutput.cs 注释中明确的设计约束）；
• 格式化：使用System.Text.Json并以缩进格式输出（WriteIndented = true），可读性好；
• 退出码：成功返回 0，失败返回 1；失败时 stdout 输出统一格式的 JSON 错误对象：

{ "error": "Failed to retrieve status" }

动作类命令（switch、mute、settings、profile --name）的成功响应形态如下：

常见错误场景（完整清单见 SoundSwitch.CLI/README.md）：

• SoundSwitch 主程序未运行（管道连接失败）；
• 配置档名称无效（profile --name指定了不存在的名称）；
• 管道连接问题（主程序繁忙、超时等）；
• 提供了无效的命令或选项；
• 系统未设置默认麦克风（执行mute命令时）。

六、底层原理：CLI 如何与主程序通信

理解 CLI 的价值，有必要看一眼它的 IPC 实现。所有命令最终都调用NamedPipe.SendRequestAsync<TResponse>（见 SoundSwitch.IPC/Pipe/NamedPipe.cs）：

1. 管道命名：管道名由PipeConstants.GetUserPipeName()生成，格式为SoundSwitch + 当前 Windows 用户名（见 PipeConstants.cs），即SoundSwitchJohnDoe这种形式，保证同一台机器上不同用户互不干扰；
2. 连接：客户端以异步方式连接，连接超时 5 秒；建立连接后以"4 字节长度前缀 + 消息体"的帧格式收发数据；
3. 序列化：请求与响应使用MessagePack高效二进制序列化（而非 JSON），既减小了体积也提升速度；
4. 响应超时：客户端等待服务端响应的超时时间为 15 秒，超时后抛出TimeoutException并清理连接，最终由 CLI 以{ "error": "..." }+ 退出码 1 呈现给用户；
5. 服务端：主程序一侧通过StartListening启动管道服务，将收到的请求分发给注册的消息处理器（ProcessRequestAsync，见 NamedPipe.cs），并在连接空闲 10 秒后主动断开闲置客户端。

正是这种"薄客户端 + 厚主程序"的架构，让 CLI 命令与主程序托盘/热键触发的切换走的是同一条设备管理链路，行为一致、无需重复实现音频 API 逻辑。

七、自动化实战场景

场景 1：PowerShell 一键切换并读取结果

$result = & SoundSwitch.CLI.exe switch --type Playback --json | ConvertFrom-Json if ($result.success) { Write-Host "已切换到下一个播放设备" } else { Write-Host "失败：$($result.error)" }

场景 2：按应用场景切换整套配置

SoundSwitch.CLI.exe profile --name "Gaming" SoundSwitch.CLI.exe profile --name "Headphones + Mic"

适合放进游戏启动器、Steam 启动选项或 AHK 脚本中，实现"开游戏自动切耳机、关游戏自动切音箱"。

场景 3：会议开始前静音麦克风

SoundSwitch.CLI.exe mute -s true # 静音 SoundSwitch.CLI.exe mute -t # 会议中想说话时再切换 SoundSwitch.CLI.exe mute -s false # 会议结束取消静音

场景 4：结合任务计划程序定时巡检设备状态

SoundSwitch.CLI.exe status --json SoundSwitch.CLI.exe devices --json

可将两者输出写入日志文件，用于排障或监控设备插拔后的切换候选是否齐全。

八、总结

SoundSwitch.CLI把主程序的核心能力完整暴露给了命令行：switch（设备切换）、mute（麦克风静音）、profile（配置档管理）、settings（打开设置）、status（状态查询）、devices（可切换设备列表），并通过统一的--json约定与"错误对象 + 退出码 1"的错误协议，让脚本集成变得可靠。底层基于命名管道与 MessagePack 与主程序通信，因此务必保证主程序正在运行。更多源码级细节可继续阅读 SoundSwitch.CLI/README.md 以及本仓库的 SoundSwitch.CLI/Program.cs 与各命令实现文件。

• 桌面应用