把小米遥控器变成 Mac 无线麦:拆解 SayAll 背后的 ATVV 解码、USB 驱动伪装与 Fn 污染净化架构

把小米遥控器变成 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)规范手工拉流解码,再送入独立的虚拟音频输出端。

SayAll 无线麦 ATVV 语音解码与 USB 驱动伪装数据流

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。
  • 三点平滑与双层限幅:解码出的 Int16 PCM 数据并不会直接丢给系统,而是先经过 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 把遥控器语音键(Usage 0x0007_0000_003E,即 F5)先映射为 0x0 彻底中和丢弃,再由 VoiceFnTapSessionController 在语音按下与松开的两个边沿分别用软件模拟一次干净的 Fn 点按;而在普通模式下,则将 F5(0x3E)硬件级重映射为 Apple Top-Case Fn/Globe(0x00FF_0000_0003),同时顺手把遥控器上误触就会让 Mac 休眠的电源键(Usage 0x66)重映射为无害的 F20(0x6F)!

二、HID 兼容模式与 Fn 层污染:和 macOS WindowServer 抢时间差

如果遥控器只拿来按住说话,事情到这里就结束了。但 SayAll 还想让遥控器剩下的 11 颗按键(方向键、OK、返回、主页、菜单、TV、音量加减、电源)变成支持单击、双击、长按、组合动作与按 App 自动切换键位的全身遥控器。而一旦不想粗暴独占整个 HID 设备(兼容模式),或者在 macOS 27 与 Intel Mac 上跑起来,底层的坑立刻接踵而至。

SayAll HID 回调去重、事件抑制与 Fn 层标志位净化泳道图

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 服务。

SayAll 私有 HCI 抓包租约与本地只读 MCP 回眸双信任域架构

1. Siri Remote 语音逆向:Root 租约守护进程 + 内存级 HCI 解析

与开放 GATT 协议的小米遥控器不同,苹果自家的 Siri Remote 并不走标准 CoreBluetooth ATVV 音频暴露。为了在非越狱 macOS 上拿到它的语音流与触控板手势,SayAll 在开源仓库中放出了完整的 AppleRemote* 四件套模块:

  1. 触控与语音激活(AppleRemoteSupport.c & AppleRemoteVoiceController.swift):通过 IOHIDDeviceSetReport 向苹果设备管理接口(UsagePage 0xFF00, Usage 0x000B)下发 Feature Report 0x98 0x01 / 0x00 开关麦克风;同时通过 dlopen 动态加载系统私有框架接口(MTDeviceCreateList、MTRegisterContactFrameCallbackWithRefcon 等)获取遥控器触摸面上的多指归一化坐标与接触面积。
  2. 受控租约式 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) 全量自动还原甚至把新建调试文件移入废纸篓。
  3. 零落盘内存态 ACL/Opus 解析(AppleRemoteXPCVoiceParser.swift):SayAllBTPacketLoggerClient 直连 com.apple.bluetooth.BTPacketLogger(并设置了 8 MB/s 与 20,000 pkt/s 的熔断流控),所有原始 HCI 字节严禁写盘或打日志,直接在内存中完成 PacketLogger 帧重组、L2CAP CID 0x0004 分片拼接、ATT 0x1B / 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 里坦诚记录了两次真实的线上翻车事故:

  1. v1.4.5 PKG 触发 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 检测架构。
  2. 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 打出了极高的完成度。

当然,实际入手前也有四条客观边界必须看清:

  1. 硬件平台与架构分离:官方 Apple Silicon 版要求 macOS 14+,Intel 版要求 macOS 13+,两者发行线与 Sparkle appcast 完全独立不可混装;且主链路主力面向 小米蓝牙遥控器 2 / 2 Pro(RC001 / RC003),Siri Remote 与 Chromecast 遥控器部分能力仍依赖仓库演进或私有扩展包状态。
  2. 首次系统权限与驱动信任门槛:因为既要拦截非独占按键,又要跨进程注入快捷键与采集转录增量,应用必须拿到蓝牙、输入监控、辅助功能三项系统权限,并在安装阶段写入 /Library/Audio/Plug-Ins/HAL/MiRemoteV2ch.driver(升级 Sparkle 时只更新应用本体,驱动变更仍需重新运行 .pkg 安装包)。
  3. 第三方输入法仍需手工对齐:正如 VoiceInputCapabilityMatrix.swift 所揭示的,SayAll 不会篡改其他输入法软件的内部私有数据库,用户仍需确保输入工具里的麦克风选为 SayAll(或旧名 MiRemoteV 2ch),且收音触发方式(长按 vs 按一次)与当前遥控器模式一致。
  4. “回眸”与局部特征仍处快速演进期:从仓库最新提交与 README.md 标记来看,组合动作、按 App 自动切换方案以及“记录回眸”本地 MCP 仍在持续结合真实第三方应用做灰度验证;如果你看重最稳妥的开箱体验,建议优先跑通基础蓝牙语音输入与常用快捷键,再逐步启用高级自动化与 MCP 检索。

无论是想给自己的 Vibe Coding 工作流配一只随手拿起的“无线对讲机”,还是想学习如何在 macOS 上规范编写 CGEventTap 事件抑止器、CoreAudio 虚拟声卡补丁、XPC 权限租约与本地 stdio MCP 服务,HD838A/remote-mic-app 都是一座含金量极高的开源工程样本。


原文链接与参考资料