jkooe
aaf0175e94
feat(v17): 音频控制能力 system.audio.get / set（40 -> 41 项）
## 动机
「远程把那台机器静音」是接管场景里的高频小事，此前只能靠 exec 拼脚本，
容易踩本项目已记录的各种坑（C# 转义 / 编码 / 引号）。做成正式能力后一条命令即可。
## 实现
- **Windows**：Core Audio COM（IMMDeviceEnumerator → IAudioEndpointVolume）
—— 可**读回真实状态**，所以是确定性的「设为静音」而不是「切换」
（切换在未知状态下可能反而打开声音）。走项目既有的常驻助手基础设施（label=audio）。
- **macOS**：osascript 原生 `output muted` / `output volume`，零互操作。
## C# 互操作的两个硬约束（已写进文件头注释）
1. **槽位顺序即 vtable 顺序**：接口方法必须按 COM 定义顺序声明，不调用的也要占位。
顺序错了不报编译错，而是调用到错误的内存地址 → 进程崩溃。
（本次：m1..m4 → SetMasterVolumeLevelScalar(5) → m6 → GetMasterVolumeLevelScalar(7)
→ m8..m11 → SetMute(12) → GetMute(13)）
2. **C# 源码必须纯 ASCII**：Add-Type 按系统 ANSI(GBK) 落盘，非 ASCII 会乱码。
## 出口
- CLI：`nodeagent audio [get]` / `nodeagent audio set [--mute on|off] [--volume 0-100]`
- MCP：na_audio_get / na_audio_set
- 参数校验：mute 必须布尔、volume 必须 0-100 整数（越界由 schema 在协议层拒绝）
## 验证
- 单测 124 → 125（新增音频 schema 用例：范围/类型/未知参数）
- e2e 26 → 27：新增音频用例，**macOS 路径已实测**（读回真实 state、写回原值走通写入路径不产生可感知变化）
- ⚠️ **Windows 侧（Core Audio COM）尚未真机验证** —— 被控端重装系统后当前离线，上线后补验
- 顺带修正 e2e 一处断言：空参数属**能力层**失败（返回 failed），越界属**协议层**（抛异常）——
正好把本项目那条契约固化进用例
2026-10-02 19:53:46 +08:00
..
2026-10-02 19:53:46 +08:00
2026-10-02 19:53:46 +08:00