# 小米许愿棒：交给 AI 的 Mac 安装与配置指南

适用发行版：**0.2.0 / build 7**。安装包：`XiaomiWishWand-0.2.0-7-arm64.dmg`。下载入口：[wand.lowpower.me](https://wand.lowpower.me/)。本说明不假设接收者安装过 SayAll、音频驱动、豆包输入法或开发工具。

最终目标：小米蓝牙遥控器 2 Pro → 小米许愿棒 → MiRemoteV 2ch 虚拟麦克风 → 豆包输入法 → 用户选定的输入框。完成标准是接收者这台 Mac 的真实语音和按键测试通过。作者机器的历史测试、签名检查或设置保存都不能代替它。

## 先给协助安装的 AI

请先通读全文，再带用户逐步操作。每次只推进到下一个检查点；已经完成且可确认的步骤直接跳过。能够访问本机工具时可做只读检查和普通界面操作；只能聊天时，用同样的步骤引导用户，并让用户报告结果。不要假装已经点过按钮、取得权限或测试成功。

- 只针对用户确认的 Mac 和遥控器。开始前确认系统版本、芯片、管理员权限及是否有现用同类工具，避免争用遥控器。
- 管理员密码、Touch ID、隐私权限、输入法启用、登录及服务条款由用户本人处理。解释当前请求用途后停在该步骤，收到结果再继续。不要索取或记录密码。
- 不关闭 Gatekeeper（macOS 安全检查）、SIP（系统完整性保护），不删除 quarantine（下载隔离标记），不重新签名，不给应用额外添加完全磁盘访问。若发行包被阻止，核对来源和签名后反馈给提供者。
- 只用系统公开接口、应用自己的设置和用户可见界面。不得读取豆包、聊天应用或其他第三方软件的私有数据库、历史、沙盒、偏好文件或未公开协议来绕过设置。
- 不导入作者的偏好文件、设备标识、录音、回眸、日志或授权。使用接收者的干净配置；已有配置先说明差异并保留可恢复副本。
- 测试使用无价值的临时文本和未发送草稿。不得替用户发消息、执行终端输入、清空工作文档或录下真实对话。语音识别由豆包提供；按其当前官方条款和用户选择使用，不假定整条链路离线。
- 默认不打开“记录回眸”、原始录音或持续录音实验功能。需要诊断时只报告版本、权限状态、错误原因和通过/失败结果，不收集输入内容、普通键盘输入、音频正文或设备唯一标识。

## 1. 确认环境与文件

必备：Apple Silicon（M 系列芯片）Mac、macOS 14 或更新系统、小米蓝牙遥控器 2 Pro、电量充足、可用网络，以及能够确认驱动安装的管理员。**本包只有 arm64 架构，不支持 Intel Mac；不要通过 Rosetta 试图解决。**豆包自身要求以其当前官网为准。本次不承诺其他遥控器型号。

用户可在“苹果菜单 → 关于本机”查看芯片和系统。AI 有终端时可只读执行：

```sh
sw_vers -productVersion
sysctl -n hw.optional.arm64
```

第二条应为 `1`。如果没有管理员权限或公司管理策略禁止驱动/输入法，请联系管理员；不要绕过管理限制。

从上述下载页获取 DMG、本文和同版本校验信息。对应源码为 `XiaomiWishWand-0.2.0-7-source.zip`，用于查阅和 GPL 许可交付，普通安装无需解压编译，不需要 Xcode、Homebrew 或 Git。不要使用上游 `Install SayAll.pkg` 或上游卸载器代替本包。

**检查点：**确认芯片和系统符合要求，DMG 完整下载，文件名和版本匹配。核对文件 SHA-256（文件校验值）时，由 AI 使用已确认的实际下载路径运行 `shasum -a 256`，与下载页的同版本值逐字比较；不匹配即停止。

## 2. 安装应用并核对身份

1. 双击 DMG，把 `小米许愿棒.app` 拖到里面的 `Applications`（应用程序）入口。
2. 如果应用程序目录已有同名应用，先核对版本并保留原包；退出旧版后再更新。不要自动覆盖来源不明的同名 App。
3. 从 `/Applications/小米许愿棒.app` 启动。不要长期从 DMG 或下载文件夹运行。
4. 出现正常的首次下载打开提示时，由用户确认打开。如果提示已损坏、开发者无法验证或包含恶意内容，停止并反馈。不要用“移除隔离属性”等命令修复。

可选只读核对：

```sh
APP_PATH='/Applications/小米许愿棒.app'
/usr/libexec/PlistBuddy -c 'Print :CFBundleIdentifier' "$APP_PATH/Contents/Info.plist"
/usr/libexec/PlistBuddy -c 'Print :CFBundleShortVersionString' "$APP_PATH/Contents/Info.plist"
/usr/libexec/PlistBuddy -c 'Print :CFBundleVersion' "$APP_PATH/Contents/Info.plist"
codesign --verify --deep --strict "$APP_PATH"
codesign -dv --verbose=4 "$APP_PATH" 2>&1
spctl --assess --type execute --verbose=4 "$APP_PATH"
```

预期应用标识 `local.bluesky.XiaomiWishWand`，版本 `0.2.0`，build `7`，签名含 `Developer ID Application`，`TeamIdentifier=UP3X54L977`。安全评估应接受该应用，正式公证发行通常显示 `Notarized Developer ID`。命令失败或身份不符时先查清原因；证书存在不等于检查通过。

**检查点：**应用位于应用程序目录，可正常打开，版本身份匹配。应用常驻菜单栏；主窗口关闭后仍可从菜单栏或应用程序重新打开。

## 3. 准备虚拟麦克风

先在小米许愿棒“连接”页或系统“音频 MIDI 设置”查看设备，避免改动系统默认声音输出。

- 已看到可用的 `MiRemoteV 2ch`：保留它，无需安装。
- 已看到名为 `SayAll` 的兼容虚拟麦克风：可能是旧版安装，保留原名即可；两边选择同一个设备。
- 只有 `BlackHole 2ch`：本应用能识别它，但本指南的豆包标准链路使用 MiRemoteV 2ch。保留现有 BlackHole，另外安装本包驱动，不覆盖它。
- 没有兼容设备：按下面步骤安装。

打开 DMG 内的 **`安装语音驱动.app`**。核对其来源与本次 DMG 一致，点击安装，由用户在 macOS 系统弹窗中确认管理员授权。驱动目标路径为：

```text
/Library/Audio/Plug-Ins/HAL/MiRemoteV2ch.driver
```

助手保留该路径已存在的驱动，不强行覆盖，不重启系统音频服务。**新安装后必须先保存工作，再由用户重新启动 Mac。**重启后打开小米许愿棒，刷新音频设备，选择 `MiRemoteV 2ch`。无需在恢复模式降低安全性或安装内核扩展。

若助手提示已存在但设备仍不出现，不代表旧驱动健康；先重启、只读检查路径与签名，向提供者报告，不自动删除、替换或反复安装。此驱动可能被其他音频应用使用。

**检查点：**小米许愿棒的可选音频设备中出现目标虚拟麦克风，且已选中；不能选 Mac 扬声器当作语音输入路线。

## 4. 安装并启用豆包输入法

打开[豆包输入法官网](https://srf.doubao.com/)的 macOS 下载入口，按官方安装向导完成。需要登录、条款确认或系统输入法授权时让用户亲自处理。不要下载豆包聊天客户端或手机 App 来代替 Mac 输入法。

按豆包向导添加输入法；必要时在“系统设置 → 键盘 → 文本输入 → 编辑”查看输入源。菜单栏输入法菜单中应能选择豆包输入法。先在“文本编辑”的空白临时文档中，用 Mac 键盘直接触发豆包语音，确认豆包本身能够正常识别。此时临时用 Mac 自带麦克风也可以，完成后再按下一节改回虚拟麦克风。

**检查点：**豆包输入法可选择、可打开设置，本机语音功能没有账号、网络或服务错误。豆包不可用时先解决其自身问题，不反复调整遥控器。

## 5. 配对遥控器并授予权限

1. 暂时退出官方 SayAll、其他遥控语音桥接工具以及另一份小米许愿棒，保留一份正式 App。遇到键盘映射工具冲突时，只调整遥控器对应项目，先记录原状态。
2. 打开“系统设置 → 蓝牙”，确认蓝牙开启。按本型号说明唤醒遥控器；需要时长按 `TV` 约 2 秒，直到底部白灯闪烁。
3. 同时长按 `Home`（房子图标）和 `Menu`（菜单图标）进入配对状态；在 Mac 附近设备里连接对应的小米遥控器。显示名可能为“小米蓝牙语音遥控器”、`MI RC` 或 `Xiaomi Bluetooth Remote 2 Pro`。不要仅因名字相似连接他人设备。
4. 若遥控器曾连接电视或另一台电脑，先让原设备停止抢占，再重新配对。未找到设备时检查电池、距离和配对状态，不立即删除其他蓝牙设备。
5. 打开小米许愿棒的首次引导，选“已有遥控器”及小米实体遥控器。根据“设置 → 权限”提示为 **小米许愿棒** 开启蓝牙、输入监控、辅助功能。

| 权限 | 用途 | 检查位置 |
| --- | --- | --- |
| 蓝牙 | 接收遥控器连接与语音 | 系统设置 → 隐私与安全性 → 蓝牙 |
| 输入监控 | 接收遥控器按键 | 系统设置 → 隐私与安全性 → 输入监控 |
| 辅助功能 | 执行配置的按键、切换和输入框操作 | 系统设置 → 隐私与安全性 → 辅助功能 |
| 豆包请求的麦克风等权限 | 豆包接收所选麦克风并输入文字 | 由豆包官方引导发起，用户逐项确认 |

授权后按系统提示退出并重开小米许愿棒。若列表中没有应用，先从 App 发起请求；可手动加入已安装的 `/Applications/小米许愿棒.app`，不要选 DMG 内副本。系统显示开启而 App 仍报无权限时，先重启应用；从旧自签名版本升级的用户可在系统列表中移除旧条目再重新添加并授权，不重置所有应用权限。

**检查点：**系统蓝牙显示已连接；小米许愿棒也显示遥控器语音/按键连接正常；三个权限均在 App 内显示已启用。三项分别确认，不能相互替代。

## 6. 将两侧语音配置对齐

通过可见设置界面核对，界面文案随豆包版本可能变化，找不到时停在该项让用户展示当前设置，不猜坐标或偷偷读配置文件。

| 设置项 | 小米许愿棒 | 豆包输入法 |
| --- | --- | --- |
| 音频路线 | 连接页选择 `MiRemoteV 2ch` | 麦克风选择同一个 `MiRemoteV 2ch` |
| 触发键 | `Fn/地球键` | `Fn` |
| 手势 | 按住说话；“点按式语音工具”关闭 | 长按模式 / 按住说话 |
| 跨应用使用 | 当前输入框已获得光标 | “全局唤起语音”开启 |

已有驱动显示为 `SayAll` 时，上表两侧都改选那个实际设备。不要只在 macOS 声音设置中换设备，却漏掉豆包自己的麦克风设置；应用不会替豆包修改它。不要改变系统默认声音输出或将系统声音送入虚拟麦克风。

增益首次默认约为 `10 dB`，先保留；只有听到声音太小、噪声或失真时才小幅调整。Fn 与系统听写等快捷键冲突时，先记录用户当前设置，再由用户决定如何消除冲突。

**检查点：**界面逐项读回一致。首次引导中的“已确认”复选框只有在用户真实核对后才能勾选。

## 7. 设置日常键位

打开“按键”，选中这台遥控器，开启“启用映射”。**干净安装不会携带作者的个人键位**：默认左右为方向键、音量键控制系统音量、返回单击 Delete，长按清空未设置；主 README 中的使用方式需要按下表配置。

| 遥控器键 | 单击动作 | 双击动作 | 长按动作 |
| --- | --- | --- | --- |
| 左 | `Command-Tab` | 未设置 | 未设置 |
| 右 | `Command-Tab` | 未设置 | 未设置 |
| 确定 | `Return` | 未设置 | 未设置 |
| 返回 | `Delete`（退格） | 未设置 | `清空输入框`，持续按住 3 秒 |
| 音量 + | `向上滚动` | 未设置 | 未设置 |
| 音量 − | `向下滚动` | 未设置 | 未设置 |

左右两键的单击动作都选择内置 **`Command-Tab` 动作**，不要录制一个普通自定义快捷键来替代。打开系统切换面板后，左右负责选择、确定完成、返回取消。音量键不另设长按动作，应用会按住连续滚动、松手停止。语音键维持 Fn 按住说话，不添加双击/长按识别延时。其他键保留原设置。

启用返回长按清空前，向用户说明：它会清除当前可写非密码输入框；可写代码编辑区也属于输入框，不能承诺可撤销。用户不希望清空时，将长按保持“未设置”，并在完成报告中注明。只有持续按住同一次超过 3 秒才应清空；焦点变化、松手、断连或权限变化必须取消。

**检查点：**从按键页回读已保存动作。现用配置与上表不同且用户希望保留时，保留并记录；不要导入整份作者配置来省略这一步。

## 8. 完成真实验收

先在引导测试框或“文本编辑”的空白未保存文档中测试，再进入用户常用应用的未发送草稿。用户亲自操作遥控器和说话，AI 只记录通过/失败，不保存正文。

1. **说话上屏：**先单击临时输入框看到光标，按住语音键说一句，松开，确认收音结束且文字完整出现。连续两次，检查开头和尾字没有被截断。不得用键盘补字冒充语音成功。
2. **单字删除：**输入少量无价值文字，短按返回并松手，检查仅退格一次。若已开启长按清空，按约 2 秒后松手也只能退格一次。
3. **安全清空（已启用才测）：**新建测试文字，持续按住返回超过 3 秒，确认只清空一次；提前松手不得清空。再用两个临时输入框验证：按住期间换焦点后，两个框都不得被清空。
4. **滚动：**在可滚动测试页面按音量 +/-，检查方向正确、按住连续、松手停止。多栏界面可能滚到窗口中心对应区域，按实际应用记录。
5. **切换：**预先打开两个无敏感内容的应用窗口，按左右进入系统切换面板，继续选择，确定后检查已有窗口出现在前台；再测返回取消。面板外确定会发送 Return，只在本地文本编辑中确认换行。
6. **常用应用：**先手动点击其聊天框，复验语音上屏。随后单独测试切换后是否自动聚焦。没有明确聊天框、存在歧义或用户改变焦点时，自动聚焦应停止；手动聚焦是正常回退。不得自动新建聊天或发送消息。聊天应用的 Return 可能直接发送，检查文字后由用户决定是否发送。
7. **重开保持：**正常退出并重开小米许愿棒，确认映射保存、连接恢复，再说一句。不是每次都需要重装或重新配对。

**完成报告至少包含：**应用版本/芯片/系统；驱动是否出现；三项权限；豆包匹配设置；语音两次测试；删除与可选清空；滚动；切换；每个目标 App 的手动输入/自动聚焦分别结果；尚未验证的项目。未做的写“待验证”，不要以“应该可以”算通过。

## 9. 按症状排查

| 症状 | 下一步 |
| --- | --- |
| DMG 打不开或签名评估不通过 | 对比同版本校验值、重新从项目下载页获取；仍失败则记录错误给提供者，保留系统保护 |
| 驱动助手提示取消 | 用户取消授权是未安装；等待用户愿意安装时再做，不连点或代输密码 |
| 安装驱动后找不到设备 | 确认重启过 Mac、驱动路径存在，再刷新；已有路径但不能加载时保留现场，不覆盖旧驱动 |
| 系统蓝牙连接，App 未连接 | 核对蓝牙权限，唤醒遥控器，退出其他桥接 App，使用 App 重新连接；再检查设备型号 |
| 语音工作，普通键失效 | 检查输入监控、辅助功能、“启用映射”和当前设备；检查其他键盘映射工具是否接管遥控器 |
| 有语音动画或电平，没有文字 | 检查豆包当前输入法、长按 Fn、全局唤起、麦克风和输入框光标；先用 Mac 键盘验证豆包自身 |
| 按下就结束，或松手不结束 | 两侧长按/点按模式不一致；恢复本指南的长按 Fn，关闭“点按式语音工具”再测 |
| 文字来自 Mac 麦克风或环境声音 | 豆包未选同一个虚拟麦克风；按其设置界面重新选择，不仅更改系统默认输入 |
| 想确认音频是否送达 | QuickTime → 文件 → 新建音频录制，选目标虚拟麦克风，仅观察按住语音时电平；不点录制。其麦克风权限由用户决定 |
| 清空没发生 | 确认已配置长按、满 3 秒、权限有效且同一可写非密码框；不支持安全写入时不执行是预期，不降级成全局全选删除 |
| 切换了应用但没进入聊天框 | 先检查窗口和页面是否已有明确聊天框，手动点击再输入；记录具体 App/版本，不通过盲点、搜索框或新建聊天替代 |
| 旧本地包升级后权限看似开着仍失效 | 退出 App，在系统设置中重新添加正式 Applications 副本并由用户重新授权；不要清除所有 TCC（隐私权限）记录 |

## 给有终端工具的 AI：可选配置命令

界面流程已完成就不必运行。此命令只准备小米许愿棒自身的语音引导配置，不能安装驱动、修改豆包设置、授予权限或代替键位配置和真实测试。

前提：应用曾在这台 Mac 成功识别遥控器并建立设备档案，豆包已启用，虚拟音频设备已出现。为避免运行中的 App 覆写设置，先从应用菜单正常退出小米许愿棒，然后在当前普通用户会话运行，不使用 sudo：

```sh
APP_PATH='/Applications/小米许愿棒.app'
"$APP_PATH/Contents/MacOS/RemoteMic" --agent-configure --auto \
  --control-source xiaomi_remote --voice-tool doubao --json
"$APP_PATH/Contents/MacOS/RemoteMic" --agent-configure --verify --json
open "$APP_PATH"
```

逐项读取 JSON（结构化结果）中的 `status`、`reason`、`remaining`：`configured` 仅表示配置已准备，`permission_required` 仍需用户授权；两者退出码都可能是 0。`not_found / connected_remote` 时回到界面识别设备，`not_found / audio_device` 时检查驱动，`needs_choice` 时让用户选择，`failed` 时保留原因并停止重试。`remaining` 中的 `real_voice_test` 必须亲自完成。命令检测的是设备档案，不能证明此刻真的连着遥控器；`--verify` 也不是硬件测试。已完成引导后不再用此命令作为日常健康检查。

## 更新、保留与出处

本发行版不启用上游自动更新。新版本从 [小米许愿棒下载页](https://wand.lowpower.me/)取得。卸载应用前先退出，再由用户把 App 移到废纸篓；共享虚拟麦克风和现有设置先保留。确需移除驱动时先确认没有其他应用依赖，并准备可恢复副本，由管理员单独处理。

本项目基于 [SayAll 开源源码](https://github.com/HD838A/remote-mic-app)，不是小米或 SayAll 官方产品。应用采用 GPL-3.0-only，驱动基于 BlackHole；对应源码、补丁及许可随发行资料提供。豆包须由接收者从其官网取得，使用其自己的账号与授权。

本说明于 2026-10-12 对照本项目公开源码、首次引导与 [豆包输入法官网](https://srf.doubao.com/)核对。macOS 蓝牙操作可参考 [Apple 官方指南](https://support.apple.com/zh-cn/guide/mac-help/blth1004/mac)。第三方界面如有变化，以接收者当前可见设置及官方说明为准。