把小米遥控器变成 Mac 无线麦:拆解 SayAll 背后的 ATVV 解码、USB 驱动伪装与 Fn 污染净化架构
在 Vibe Coding 流行起来之后,对着桌面麦克风或笔记本自带麦克风长时间口述 Prompt 成了常态——但一旦想靠在椅背上、或者离开工位两步继续用语音输入,笔记本的收音距离立刻变成瓶颈,而普通蓝牙耳机一开启通话麦克风就会切进低音质 HFP 模式,直接把正在播放的音乐压成“电话音质”。开源项目 HD838A/remote-mic-app(无线麦 SayAll App)给出了一个极其反直觉却又顺理成章的解法:拿一只几十块钱的小米蓝牙语音遥控器(RC001 / RC003),把它改造成随时拿在手里的 Mac 无线麦克风与全局快捷键控制器。
为了弄清这款常驻内存仅约 50 MB、CPU 占用低于 0.5% 的原生 Swift 应用究竟是如何绕过 macOS 蓝牙音频栈、第三方语音输入法挑食机制以及 WindowServer 底层按键拦截的,我完整克隆并精读了 HD838A/remote-mic-app 仓库源码(截至 2026 年 11 月 20 日最新合并提交 f1e5086 / PR #1155,GitHub Star 突破 3,060)。在逐一拆解完 Sources/RemoteMic/ 的 131 个 Swift 源文件、BlackHole 驱动补丁、私有 HCI 抓包守护进程与 SayAllMCPKit 之后,我发现它远不止是一个“BLE 转发麦克风”的玩具,而是一份教科书级的 macOS 系统编程避坑实录。
[!NOTE] 代码审计基线与开源边界说明
本文所有模块名称、协议 UUID、驱动补丁、键码与行为逻辑,均源自我在 2026 年 11 月 20 日对公开仓库 HD838A/remote-mic-app(GPL-3.0-only)及其源码和TECHNICAL.md的直接分析。需要说明的是,作者在Package.swift中通过环境变量(如SAYALL_ENABLE_PRIVATE_SWIFTPM)划分了公私有边界:小米 RC001/RC003 的 BLE/ATVV 引擎、CoreAudio 驱动、HID 抑止器、Siri Remote 私有 HCI 抓包管线以及SayAllMCP服务全部开源;而 iPhone/Apple Watch 直连(公开仓在PublicRemoteCompatibility提供协议占位)、组合动作扩展与多键位方案等商业/私有特性位于外部私有包中。
一、跳过系统默认麦切换:BLE ATVV 协议解码与 USB 驱动伪装
普通蓝牙麦克风在 macOS 上最恼人的地方在于:一旦切入语音通道,系统就可能自动变更默认音频输入/输出设备,打断原本正在听的音乐或会议流。SayAll 选择了一条完全绕开经典蓝牙 HFP 的底层路径——直接把遥控器当作纯 BLE GATT 外设,按 Android TV 语音服务(ATVV)规范手工拉流解码,再送入独立的虚拟音频输出端。
1. BLE GATT 白名单与 IMA/DVI ADPCM 实时解码
在 Sources/RemoteMic/XiaomiBluetoothBridge.swift 与 ATVVProtocol.swift 中,SayAll 对候选蓝牙设备做了非常克制的白名单过滤:只匹配去空白后名称精确等于 MI RC、Xiaomi Bluetooth Remote 2 Pro 或“小米蓝牙语音遥控器”,或者在广播包里显式携带 ATVV Service UUID(AB5E0001-5A21-4F05-BC7D-AF01F617B664)的设备,绝不对名称里带“小米”的蓝牙外设做模糊扫描。
建连后,桥接层必须在 8 秒初始化超时内完成四条 GATT 特征发现与 Audio(...0003)/ Control(...0004)通知订阅,并向 Transmit(...0002)下发能力查询指令 0x0A 0x01 0x00 0x00 0x03 0x03。根据 ATVVProtocol.swift 中的解析逻辑:
- 严格锁定 16 kHz 采样率:解析
0x0B能力回包后,若设备仅支持 8 kHz(selectedCodec != 0x02),SayAll 会直接判定失败并重连;小米 RC001/RC003 声明的frameSize为120字节(1 字节拆为 2 个 4-bit ADPCM 样本,即每帧 240 个 16 kHz 样本、恰好对应 15 ms 语音)。 - 区分固件字节序的 ADPCM 解码器:
IMAADPCMDecoder在注释里揭露了一个非常隐蔽的硬件差异——小米 RC001/RC003(固件 2671)采用 高半字节优先(high-nibble-first)编码,而部分 ARN9 固件采用低半字节优先,桥接层会读取设备信息特征2A24动态翻转lowNibbleFirst;当语音流中插入同步包时,同步重置predictor与stepIndex。 - 三点平滑与双层限幅:解码出的
Int16PCM 数据并不会直接丢给系统,而是先经过PCMPostprocessor的三点平滑滤波(([i-1] + 2*[i] + [i+1]) >> 2)与-24...24 dB安全限幅,再通过AudioOutput.swift里的AVAudioEngine+AVAudioPlayerNode写入虚拟设备;用户调节的0...1000%音量放大(1000%约+20 dB)被统一后置到写缓冲出口执行削顶,甚至还专门用了一小段 Objective-C 包装层AudioExceptionGuard.m捕获[player play]与installTapOnBus:抛出的NSException——因为 Swift 原生无法捕获 CoreAudio 底层抛出的 Objective-C 异常。
2. 只有 2 行代码却救了全队的补丁:kAudioDeviceTransportTypeUSB
刚开始看源码时,我很好奇为什么 SayAll 要在 third_party/blackhole/blackhole-device-usb.patch 里自己维护一份基于 BlackHole 改造的虚拟声卡驱动 MiRemoteV2ch.driver。点开那份只有 34 行的 diff 文件后,答案瞬间清晰:
// third_party/blackhole/blackhole-device-usb.patch
- *((UInt32*)outData) = kAudioDeviceTransportTypeVirtual;
+ *((UInt32*)outData) = kAudioDeviceTransportTypeUSB;
原来,以豆包输入法、微信输入法、飞书为代表的众多国产 macOS 语音输入工具,在枚举系统麦克风列表时存在一层隐式过滤——它们会直接忽略传输类型为 kAudioDeviceTransportTypeVirtual 的纯虚拟音频设备!作者给 BlackHole 换了一套独立的 CFPlugInFactories UUID(4a91361d-19af-4ba0-a87a-0a6242ed6ae4),并将 kAudioDevicePropertyTransportType 伪装成 kAudioDeviceTransportTypeUSB,成功让虚拟麦克风以“USB 声卡”的身份通过所有语音输入工具的设备校验。
同时,围绕不同输入工具“如何开始/结束收音”的分裂生态,SayAll 在 VoiceInputCapabilityMatrix.swift 和 remote/遥控器与输入工具能力矩阵.md 里沉淀了一套“单一事实源”矩阵:
- 小米 RC001/RC003 在硬件和固件上只支持长按语音键,不支持按一次切换;
- 豆包、微信输入法、Vokie 等既支持长按(默认 Fn)也支持免按;但 Typeless 只支持“按一次开始、再按一次结束”,且会被长期按住的物理
Fn键干扰; - 因此,当搭配 Typeless 时,
RemoteVoiceFunctionMapper会通过IOHID的UserKeyMapping把遥控器语音键(Usage0x0007_0000_003E,即F5)先映射为0x0彻底中和丢弃,再由VoiceFnTapSessionController在语音按下与松开的两个边沿分别用软件模拟一次干净的Fn点按;而在普通模式下,则将F5(0x3E)硬件级重映射为 Apple Top-CaseFn/Globe(0x00FF_0000_0003),同时顺手把遥控器上误触就会让 Mac 休眠的电源键(Usage0x66)重映射为无害的F20(0x6F)!
二、HID 兼容模式与 Fn 层污染:和 macOS WindowServer 抢时间差
如果遥控器只拿来按住说话,事情到这里就结束了。但 SayAll 还想让遥控器剩下的 11 颗按键(方向键、OK、返回、主页、菜单、TV、音量加减、电源)变成支持单击、双击、长按、组合动作与按 App 自动切换键位的全身遥控器。而一旦不想粗暴独占整个 HID 设备(兼容模式),或者在 macOS 27 与 Intel Mac 上跑起来,底层的坑立刻接踵而至。
1. macOS 27 双回调风暴与 mach_timebase 双击修复
在 Sources/RemoteMic/HIDRemoteMonitor.swift 的头部注释里,我读到了两条非常珍贵的实战踩坑记录:
- macOS 27 同时投递 Manager 与 Device 两条回调:在较新系统版本上,同时注册
IOHIDManager与IOHIDDevice的带时间戳输入报告回调后,同一份物理按键报告会被双通道同时投递;但某些环境下又可能只有一条通道活跃。SayAll 没有赌死单一回调,而是构建了HIDReportDeduplicationCache(按设备指针 +reportID+ 负载字节去重,去重窗口50_000_000 ns即 50 ms,保留250 ms),做到“谁先到听谁的,另一条直接丢弃”。 - 为什么双击间隔曾经出现 0 ms 或 1 ms:早期实现是在回调里读取
ProcessInfo.systemUptime,但报告在专用 RunLoop 队列上积压后批量派发,两次回调读到的systemUptime被压缩在同一毫秒!后来作者改用IOHIDManagerRegisterInputReportWithTimeStampCallback自带的内核mach绝对时间戳,再通过HIDReportClock乘以mach_timebase_info的分子分母换算为纳秒,彻底消除了队列抖动带来的假双击。
2. 滞后 300 ms 的原生按键幽灵,与 prearm 提前登记队列
在非独占的兼容模式下,用户按下遥控器 TV 键或 音量+ 时,SayAll 的 HID 回调先拿到原始报告准备执行自定义动作,但 macOS 系统底层的原生键值事件(CGEvent 或系统媒体键 NX_SYSDEFINED)也会在随后抵达 WindowServer——而且实测原生事件的投递可能比 HID 原始报告慢出超过 300 ms,甚至在手指松开之后才姗姗来迟!
更棘手的是 TV 键的物理键码乌龙:RemoteButtons.swift 第 115 行注明,初版假设小米遥控器 TV 键对应键码 50,结果真机实测它的共享键盘接口发出的其实是键码 10(ISO § 键,带 0x100 标志位),导致拦截器一度完全漏拦 TV 键原生事件,直到同时把 10 和 50 都纳管才修复。
为了防止 KeyboardEventSuppressor 的 CGSessionEventTap 在拦截遥控器原生键时误杀实体键盘的同类按键(比如遥控器刚按完音量键,紧接着手敲键盘调音量),作者设计了一套带 500 ms(nativeDeliveryWindow)TTL 窗口的 FIFO 认领账本:
- 当 HID 报告线程刚收到按下事件时,先通过线程安全的
prearm提前在KeyboardEventSuppressor登记; - 若原生事件抢在主线程处理之前先到 Tap 回调,它会消费一条
prearm记录并往prearmedDownsClaimed队列里压入带过期时间的认领凭证; - 主线程随后
arm时看到队列里有认领凭证,就知道“刚才那次已经拦截过了”,直接出队核销而不再追加新的待拦截项——注释里特别强调必须用队列不能用松键清空,因为快速连按时up 1与down 2会交错到达,“松键清空”会把第二次按下的认领抹掉,导致吞掉实体键盘按键。
3. Home 键为什么会把 Cmd+Shift+H 污染成 Fn+Cmd+Shift+H?
这是我在 MACOS_FUNCTION_LAYER.md 里看到的最硬核的一篇系统级排障笔记。小米遥控器的 主页(Home) 键对应 macOS 键码 115。在 Apple 键盘映射表里,Home(115)、PageUp(116)、Forward Delete(117)、End(119)、PageDown(121)全都属于 Fn 层键位!
当用户按下遥控器 Home 键触发一条自定义快捷键(比如 Cmd+Shift+H)时,ShortcutEventSequence.send 会调用 CGEventSource.flagsState(.hidSystemState) 读取当前硬件修饰键快照(原本是为了保留用户手按着的修饰键状态),结果硬件快照里凭空多出了 maskSecondaryFn(0x00800000)!方向键(123–126)因为同时带有 maskNumericPad(0x00A00000)比较好认,而 Home 115 只带了单独的 0x00800000,让旧版过滤器漏网,最终把 Cmd+Shift+H 注入成了 Fn+Cmd+Shift+H,导致目标应用完全匹配不到快捷键。
SayAll 最终确立的过滤原则极其漂亮——“只保留可证明的 Fn”:除非用户录制的快捷键本身显式包含 Fn,或者拦截器确实在事件流里观测到了物理键码 63(真 Fn 键)的按下边沿,否则硬件快照里上报的 maskSecondaryFn 一律剔除!
4. 不读文本内容、不抢焦点的半页滚动(ScrollRegionInjector)
就在 2026 年 11 月 20 日刚刚合并的 PR #1155 中,SayAll 新增了半页翻页(pageUpHalf / pageDownHalf)与滚动区域定向能力。查看 Sources/RemoteMic/ScrollRegionInjector.swift 可以看到,它的实现相当克制:
- 不读
AXValue、不截屏、不移动键盘焦点:仅通过 macOS Accessibility 树读取当前光标或学习坐标下的容器几何信息(考虑到 Chromium 内核网页嵌套常深达 20 层,先直取kAXWindowAttribute再向上找滚动容器,并把树扫描节点上限定死在5,000以防卡死); - 优先命中学习记录的归一化坐标中心点;如果当前前台刚好是 SayAll 自己,则直接绕过同进程 AX 查询(避免触发 SwiftUI View Graph 死锁),退回按窗口高度比例的像素滚轮事件。
三、把触角伸向苹果生态与 AI Agent:HCI 私有抓包与本地只读 MCP“回眸”
除了把小米遥控器打磨到极致,我在仓库源码里还发现了两条令人拍案叫绝的工程支线:一条面向 Apple Siri Remote(A2854 / A2540,VID 0x004C / PID 0x0315) 的私有蓝牙协议旁路采集,另一条则面向“说过有回眸”和 AI 代理生态的本地只读 MCP 服务。
1. Siri Remote 语音逆向:Root 租约守护进程 + 内存级 HCI 解析
与开放 GATT 协议的小米遥控器不同,苹果自家的 Siri Remote 并不走标准 CoreBluetooth ATVV 音频暴露。为了在非越狱 macOS 上拿到它的语音流与触控板手势,SayAll 在开源仓库中放出了完整的 AppleRemote* 四件套模块:
- 触控与语音激活(
AppleRemoteSupport.c&AppleRemoteVoiceController.swift):通过IOHIDDeviceSetReport向苹果设备管理接口(UsagePage0xFF00, Usage0x000B)下发 Feature Report0x98 0x01 / 0x00开关麦克风;同时通过dlopen动态加载系统私有框架接口(MTDeviceCreateList、MTRegisterContactFrameCallbackWithRefcon等)获取遥控器触摸面上的多指归一化坐标与接触面积。 - 受控租约式 Root LaunchDaemon(
AppleRemoteHCIService):要监听苹果私有 XPC 服务com.apple.bluetooth.BTPacketLogger,系统必须开启蓝牙调试标志位并授予com.apple.PacketLogger.HCI授权。SayAll 没有让用户手动在终端乱改系统配置,而是实现了一个按 TeamID(L3QHLDRPAY)和 Bundle ID 校验的 XPC 服务com.hd838a.SayAll.AppleRemoteHCIService。它在开启调试前,先把原生的/Library/Preferences/com.apple.MobileBluetooth.debug.plist与授权数据库原样持久化备份到state.plist(0600权限),随后写入HCITraces(含RawAudioTrace、HCILiveTraces等 6 个开关),等语音结束后或下次异常重启恢复时,通过引用计数租约(AppleRemoteHCILeaseState) 全量自动还原甚至把新建调试文件移入废纸篓。 - 零落盘内存态 ACL/Opus 解析(
AppleRemoteXPCVoiceParser.swift):SayAllBTPacketLoggerClient直连com.apple.bluetooth.BTPacketLogger(并设置了8 MB/s与20,000 pkt/s的熔断流控),所有原始 HCI 字节严禁写盘或打日志,直接在内存中完成 PacketLogger 帧重组、L2CAP CID0x0004分片拼接、ATT0x1B / 0x1D拆包;只有在同一(connectionHandle, attributeHandle)上连续命中 3 个序列号递增、且载荷头符合 Opus 特征(bytes[opusStart] & 0xFC == 0xB8)的语音帧时,才锁定音频流并剥离出纯净 Opus 数据包送去解码!
2. “说过有回眸”与 SayAllMCP:极度克制的本地上下文闭环
在 AI 编程与多 Agent 协同场景下,用户口述过的长段 Prompt 往往散落在微信、Cursor、终端、飞书等十几个不同的窗口里。SayAll 新近引入的“记录回眸”与 SayAllMCP 二进制工具(Sources/SayAllMCPKit + Sources/SayAllMCP),专门用来解决“我刚才在某个软件里说过的那段话去哪了”的问题:
- 只采增量出字、不录音频、不读上下文:在
TranscriptCaptureCoordinator.swift中,SayAll 并没有开启录音留档或全局录屏,而是在语音会话开始与结束后,通过kAXFocusedUIElementAttribute对比前台输入框的kAXValueAttribute与光标选区变化,等文本稳定后只提取本次由语音输入新增的那一段文字,按应用和本地日期写入分片存储(单条上限8,000字符)。 - 硬编码隐私熔断:只要焦点控件角色是
AXSecureTextField、带AXProtectedContent标志,或者控件的 Identifier / Title / Placeholder 中出现password、passcode、secret、api key、token、credit card、search、密码、口令、密钥等敏感词,采集器会直接拒绝读取。 - 可独立撤销的 stdio MCP 服务:
SayAllMCP实现了2025-11-25协议版本的 stdio MCP 服务器,仅暴露两个只读工具——list_transcript_apps和query_transcripts(支持按时间窗口、Bundle ID 和游标分页检索,单次上限 500 条)。每个接入的客户端(如 Claude、WorkBuddy 等)在SayAllMCPAuthorizationStore中拥有独立的clientId(UUID)、SHA-256 哈希后的 Access Token、固定transcripts.read.all只读权限以及独立的审计日志SayAllMCPAuditLog,用户可在 UI 中随时一键吊销某个 Agent 的访问权。
3. 连安装向导都面向 AI Agent 设计(--agent-configure)
在阅读 README.md 和 Sources/RemoteMic/AgentConfigurationCommand.swift 时,我还注意到一个非常具有 2026 年时代特征的设计:作者专门在 Resources/zh-Hans.lproj/OnboardingAIAssistantPrompt.txt 里写了一段给 AI 助手复制粘贴的配置提示词,并在主程序入口开放了受限无头子命令:
"/Applications/SayAll.app/Contents/MacOS/RemoteMic" --agent-configure --auto --json
这个命令专门用于配合用户桌面上的 AI Agent 自动完成遥控器档案与输入工具匹配,但代码把权限边界卡得极死:不能替用户建立蓝牙连接、不读取个人路径与敏感日志,只返回结构化状态码(configured、needs_choice、permission_required、not_found),真正做到让 AI 帮忙“配好环境”,却绝不越权碰隐私。
四、发布工程复盘:比业务代码更严格的“防翻车自检门禁”
把 TECHNICAL.md 和 packaging/doubao-driver/install/postinstall 读到最后,我甚至觉得作者在macOS 签名与 PKG 安装工程上交过的学费,对所有桌面端开发者都极具参考价值。TECHNICAL.md 里坦诚记录了两次真实的线上翻车事故:
v1.4.5PKG 触发 Xcode 命令行工具弹窗:作者曾在安装后脚本postinstall里调用/usr/bin/lipo和/usr/bin/vtool校验架构与最低系统版本,结果未装 Xcode 的普通用户一运行安装包就被系统弹窗逼着下载 Command Line Tools 并直接失败中止。如今仓库里的校验脚本verify-doubao-driver-pkg.sh会展开最终从 GitHub Release 回下载的 PKG,明文封杀任何lipo、vtool、xcrun、xcode-select、swift调用,并改用系统自带的/usr/sbin/sysctl与/usr/bin/file检测架构。v1.4.2 / v1.4.3权限改写抹掉 Sparkle 更新器:早期postinstall先把.app内部所有普通文件改成了0644,随后只恢复了主二进制Contents/MacOS/RemoteMic的0755,意外把Sparkle.framework内部的Autoupdate、Updater以及Installer.xpc/Downloader.xpc的可执行位全清掉了——更可怕的是原始 App、DMG 和 PKG 的公证与 Gatekeeper 验签全部能通过!于是现在的postinstall显式维护了一份 9 个核心可执行文件清单(含SayAllMCP、SayAllAppleRemoteAudioCapture、SayAllAppleRemoteHCIService与 Sparkle 全套组件)逐项强锁0755,而且两阶段预览版发布流水线甚至要求先用上一版公开稳定 App 跑通真实的 Sparkle UI 在线升级闭环后,才允许晋升为正式版。
五、客观测评与适用边界
把 HD838A/remote-mic-app 从蓝牙射频解码到 Sparkle 发布流水线全部拆解一遍后,我对这套工程的整体评价非常明确:它精准命中了“轻量级系统桥接工具”最难啃的那些操作系统缝隙——不依赖重型 Electron 壳,用纯 Swift 5 + CoreBluetooth + AudioServerPlugIn + IOKit HID 打出了极高的完成度。
当然,实际入手前也有四条客观边界必须看清:
- 硬件平台与架构分离:官方 Apple Silicon 版要求 macOS 14+,Intel 版要求 macOS 13+,两者发行线与 Sparkle
appcast完全独立不可混装;且主链路主力面向 小米蓝牙遥控器 2 / 2 Pro(RC001 / RC003),Siri Remote 与 Chromecast 遥控器部分能力仍依赖仓库演进或私有扩展包状态。 - 首次系统权限与驱动信任门槛:因为既要拦截非独占按键,又要跨进程注入快捷键与采集转录增量,应用必须拿到蓝牙、输入监控、辅助功能三项系统权限,并在安装阶段写入
/Library/Audio/Plug-Ins/HAL/MiRemoteV2ch.driver(升级 Sparkle 时只更新应用本体,驱动变更仍需重新运行.pkg安装包)。 - 第三方输入法仍需手工对齐:正如
VoiceInputCapabilityMatrix.swift所揭示的,SayAll 不会篡改其他输入法软件的内部私有数据库,用户仍需确保输入工具里的麦克风选为SayAll(或旧名MiRemoteV 2ch),且收音触发方式(长按 vs 按一次)与当前遥控器模式一致。 - “回眸”与局部特征仍处快速演进期:从仓库最新提交与
README.md标记来看,组合动作、按 App 自动切换方案以及“记录回眸”本地 MCP 仍在持续结合真实第三方应用做灰度验证;如果你看重最稳妥的开箱体验,建议优先跑通基础蓝牙语音输入与常用快捷键,再逐步启用高级自动化与 MCP 检索。
无论是想给自己的 Vibe Coding 工作流配一只随手拿起的“无线对讲机”,还是想学习如何在 macOS 上规范编写 CGEventTap 事件抑止器、CoreAudio 虚拟声卡补丁、XPC 权限租约与本地 stdio MCP 服务,HD838A/remote-mic-app 都是一座含金量极高的开源工程样本。