Skip to content
Back to search

smart-home-voice-bridge

智能家居语音桥:小爱音箱 + 海尔 + 美的 + 极米 + ESP32,以 MCP server 形式接入 WorkBuddy

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/gxygrenn--smart-home-voice-bridge/badge.svg)](/listings/gxygrenn--smart-home-voice-bridge)

HTML

<a href="/listings/gxygrenn--smart-home-voice-bridge"><img src="/api/listings/gxygrenn--smart-home-voice-bridge/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

python -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate
pip install -r requirements.txt

国内网络建议加镜像,否则装 `miservice_fork` 会挂很久甚至报「找不到版本」:

pip install -r requirements.txt -i https://mirrors.aliyun.com/pypi/simple

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 309 lines
  1. # 智能家居语音桥(Xiaoai Smart Home Bridge)
  2. 把小爱音箱变成家里的语音入口:**能问的交给大模型,能控的本地直连**,小爱自己管不到的家电(海尔、美的)也接进来。
  3. 三个独立的桥,可以只用其中一个:
  4. | 桥 | 对象 | 走的通道 | 能做什么 | 延迟 |
  5. |---|---|---|---|---|
  6. | `xiaoai-bridge` | 小爱音箱 | 小米云 `micoapi`(非公开接口) | 文字/语音播报;读云端对话记录,把提问转给大模型再念回来 | 播报 <1s |
  7. | `haier-bridge` | 海尔家电 | 海尔 U+ 云平台 | 读状态、下发控制(开关/温度等) | 读 0.1~0.7s,写 1~3s |
  8. | `midea-bridge` | 美的家电 | 局域网直连(UDP 6445 发现 / TCP 6444 控制) | 读状态、下发控制,断网也能用 | 几十毫秒 |
  9. 三者都以 **MCP server** 形式暴露给 WorkBuddy,也都能单独当命令行工具用。
  10. ---
  11. ## 目录结构
  12. ```
  13. .
  14. ├── xiaoai-bridge/ 小爱音箱(小米云)
  15. │ ├── xiaoai_bridge.py 登录 / 播报 / 米家 API / MCP(外部入口,路径固定)
  16. │ ├── xiaoai_voice.py 语音对话桥入口(薄壳:实现拆进了 voice/ 包)
  17. │ ├── voice/ 语音桥实现
  18. │ │ ├── runtime.py 日志/心跳/单实例互斥/pid/--stop --status --bg
  19. │ │ ├── llm.py WorkBuddy 网关 + ask_workbuddy + 朗读化
  20. │ │ ├── intents.py 全部 parse_*_intent 纯函数 + 词表
  21. │ │ ├── answers.py 小爱回话判定:软拒绝/是否家电指令/跨音箱去重
  22. │ │ ├── projector.py 坚果投影仪执行 + 看片/睡觉场景
  23. │ │ ├── miot.py 米家:台灯/就近开灯/核查小爱的口头宣称
  24. │ │ ├── appliances/ 本地家电按设备与场景分包
  25. │ │ │ ├── common.py 共享路径、模式文案、不支持设备清单
  26. │ │ │ ├── bath.py 浴霸局域网直控
  27. │ │ │ ├── liangba.py 凉霸 BLE + ESP32 连接预热
  28. │ │ │ ├── heater.py 海尔热水器
  29. │ │ │ ├── washer.py 美的洗衣机状态与基础控制
  30. │ │ │ ├── scenes.py 洗澡组合场景
  31. │ │ │ ├── scheduling.py 定时登记/取消/查询
  32. │ │ │ └── dispatcher.py fast_home_action 总分发 + 超时播报
  33. │ │ ├── conversation.py 云端对话读取/凭证续期/播报
  34. │ │ └── main.py poll_once / 多音箱 worker / 主循环
  35. │ ├── xiaoai_schedule.py 定时任务(纯本地)
  36. │ ├── voice_watchdog.py 看门狗(Windows 计划任务每分钟拉起)
  37. │ ├── tests/ 离线自测,不碰真实设备
  38. │ ├── docs/ 语音场景与模块地图
  39. │ ├── tools/ 米家域解锁等运维工具
  40. │ └── *.cmd 双击即用的登录 / 自检 / 启动脚本
  41. ├── haier-bridge/ 海尔智家(U+ 云)
  42. │ ├── haier_bridge.py 登录 / 读状态 / 控制 / MCP(外部入口)
  43. │ └── tests/ 离线自测
  44. ├── midea-bridge/ 美的(局域网 + BLE)
  45. │ ├── midea_bridge.py 发现 / 登录换密钥 / 控制 / MCP(外部入口)
  46. │ ├── midea_ble.py 凉霸 BLE 广播遥控协议(按键语义/状态解析)
  47. │ ├── esp32_adv.py ESP32 板子的 UDP 命令通道
  48. │ ├── tools/ BLE 抓包、云端模块提取等开发工具
  49. │ └── experiments/ 协议逆向时的抓包取证(归档,无人引用)
  50. ├── jmgo-bridge/ 坚果投影仪(局域网 ADB)
  51. │ ├── jmgo_bridge.py 扫描 / 连接 / 控制 / MCP(外部入口)
  52. │ └── tests/ 离线自测
  53. ├── esp32-ble-bridge/ ESP32-C5 BLE/WiFi 桥(固件 + 板子运维)
  54. │ ├── main/ 固件源码(IDF v5.5.1)
  55. │ ├── tools/ 板子运维:远程盲发/重启、串口诊断等
  56. │ ├── hardware/ 官方原理图 + 充电电路局部图
  57. │ └── README.md 固件协议与硬件注意事项
  58. ├── tools/
  59. │ └── check_repo.py 提交前检查:换行策略 + 敏感信息
  60. └── requirements.txt
  61. ```
  62. 五个桥接根目录及各桥主入口是计划任务、MCP、CMD/VBS 和跨桥导入共同依赖的
  63. 外部契约,保持原路径;测试、开发工具和内部实现可以独立归档。
  64. ---
  65. ## 安装
  66. ```bash
  67. python -m venv .venv
  68. source .venv/bin/activate # Windows: .venv\Scripts\activate
  69. pip install -r requirements.txt
  70. ```
  71. 国内网络建议加镜像,否则装 `miservice_fork` 会挂很久甚至报「找不到版本」:
  72. ```bash
  73. pip install -r requirements.txt -i https://mirrors.aliyun.com/pypi/simple
  74. ```
  75. ---
  76. ## 一、小爱音箱桥
  77. ### 登录
  78. ```bash
  79. cd xiaoai-bridge
  80. python xiaomi_credential.py --save # 存账号密码(也可双击 save-credentials.cmd),之后自动续期
  81. python xiaoai_bridge.py --login # 账号密码登录一次,生成本地凭证
  82. python xiaoai_bridge.py --demo # 自测:让音箱念一句话
  83. ```
  84. **密码登录可能被拒(`securityStatus=16`)**,这是小米的异地登录风控,不是密码错 —— 需要打开返回里的 `notificationUrl` 收一条短信。验证信任**只绑当次登录会话**,所以必须在同一个浏览器进程里验完立刻换取凭证,Python 侧重放没用。这一步有专门脚本:`tools/unlock_xiaomiio.py`(详见该文件头注释)。
  85. `--pass-token`(手动从浏览器 F12 复制 passToken)**已废弃不要再用**:小米的 passToken 用一次就轮换,第二次必定 `70016`;而且网页 `serviceLogin` 的回包不带 `ssecurity`,算不出 `clientSign`,换票恒定 401。
  86. 凭证只写到本地的 `xiaoai_token.json` / `xiaoai_auth.json`,两个文件都在 `.gitignore` 里。
  87. ### 播报
  88. ```bash
  89. python xiaoai_bridge.py --speak "水烧好了"
  90. python xiaoai_bridge.py --probe # 检查录音/对话两条通道有没有数据
  91. python xiaoai_bridge.py --rooms # 按米家房间列出设备
  92. python xiaoai_bridge.py --refresh-rooms # 挪过设备后重新拉一次房间划分
  93. ```
  94. `--rooms` 用的是米家 App 里的分房:设备列表接口本身**不带**房间号,房间归属只在
  95. `/homeroom/gethome` 的 `roomlist[].dids` 里。语音桥的核查层靠这张表把「主卧的灯」
  96. 圈到具体几台,所以挪过设备记得 `--refresh-rooms`(缓存 7 天,启动时会自动续)。
  97. ### 语音对话桥
  98. ```bash
  99. python xiaoai_voice.py # 默认:问句转发,家电指令先看小爱办没办成
  100. python xiaoai_voice.py --all # 家电指令一律转发
  101. python xiaoai_voice.py --trigger 问电脑 # 只响应含触发词的话
  102. python xiaoai_voice.py --dry-run # 只打印听到的内容,不调大模型
  103. ```
  104. 工作方式:每 2.5 秒轮询一次小米云端的对话记录,发现新提问就交给大模型,再念回来。
  105. **关键设计:家电指令去重。** 每条提问在云端都带 `answers`(小爱自己的回复):
  106. - 有回复、且不是失败话术 → 小爱已经办了,桥**闭嘴**
  107. - 回复是失败话术 → 小爱没办成,交给本桥兜底
  108. - 还没有回复 → 再等 6 秒,等不到就转发
  109. 这里有个必须知道的细节:小爱对**它管不到的第三方设备**(海尔、美的)不会说「不支持」,而是甩一句引导语,比如「没有发现可以操作的热水器,先去米家绑定设备吧」。只按「不支持/找不到」这类硬失败词判断,会把这种**软拒绝**误判成"已执行"直接吞掉。所以判定必须同时覆盖硬失败词和句式正则。
  110. ### 家电指令快通道
  111. 问句要过一次网关对话轮次(固定 10~13 秒),但开关家电不需要。`voice/` 包里有一层纯规则解析:
  112. - 认得很准的「打开/关闭 XX」→ 本地直接调桥的接口,**3~4 秒**完成,不经过大模型
  113. - 认不准的说法(「调到 45 度」之类)→ 回落给大模型,不猜
  114. - 小爱压根没吭声时,**开关类不擅自执行**,只有只读查询才接管
  115. - 说了「关灯」但没说是哪个屋 → **就近执行**:按听见这句话的音箱所在房间办。
  116. 三台音箱分属主卧 / 客厅 / 门头沟,房间取自米家 App 的分房(见上面 `--rooms`)
  117. ### 改完代码怎么生效
  118. 语音桥是常驻进程,改完 `xiaoai_voice.py` 必须重启才会加载新代码。两种方式:
  119. ```bash
  120. # ① 直接重启(`--bg` 会脱离终端,关掉窗口也不影响)
  121. python xiaoai_voice.py --stop
  122. python xiaoai_voice.py --bg --interval 2.5 --timeout 180
  123. # ② 留个标记,让看门狗下一轮自己重启(沙箱/编辑器里起的进程容易被回收,这种最稳)
  124. python -c "open('xiaoai_voice_restart.flag','w').close()"
  125. python voice_watchdog.py # 想立刻生效就手动跑一轮;不然等计划任务
  126. ```
  127. **注意(2026-11-06 18:29 验证)**:在 WorkBuddy 的沙箱终端里手动跑 `voice_watchdog.py`
  128. 时,`launch()` 用的 `explorer.exe` 会被沙箱拦掉(命令返回 1,进程没起来,日志却已经写了
  129. 「正在重启」)。沙箱里也不要指望 `--bg`:命令一结束子进程就被回收,看上去还活着但心跳
  130. 不再刷新。正解是**只写 flag,然后等计划任务那一轮(每分钟)**——它在沙箱外跑,能正常拉起。
  131. 看门狗由 Windows 计划任务调起,通过 `explorer.exe` 启动进程,所以进程不会随启动它的
  132. 终端或会话被回收。**同一时刻只允许一个监听进程**(Windows 命名互斥体
  133. `Local\XiaoaiVoiceBridge`):重复启动的那个会打印一行「已经有一个语音桥在跑了」后自己
  134. 退出,否则同一句话会被两份进程各执行一遍(2026-11-06 09:08 撞过一次)。
  135. ---
  136. ## 二、海尔桥
  137. ```bash
  138. cd haier-bridge
  139. python haier_bridge.py --login # 手机号 + 密码,缓存 token
  140. python haier_bridge.py --list # 账号下的设备
  141. python haier_bridge.py --status # 当前状态(带中文描述和取值范围)
  142. python haier_bridge.py --attrs # 原始属性表,查属性名用
  143. python haier_bridge.py --set 热水器 onOffStatus=false
  144. python haier_bridge.py --doctor # 自检
  145. ```
  146. 账号也可以走环境变量,避免命令行留痕:`HAIER_USER` / `HAIER_PASS`。
  147. 三条链路:
  148. 1. **登录** `POST zj.haier.net/api-gw/oauthserver/account/v1/login`
  149. 2. **读状态** `POST uws.haier.net/shadow/v1/devdigitalmodels`(数字孪生属性表)
  150. 3. **控制** WSS `uws.haier.net/gmsWS` → `BatchCmdReq`,内容是 `{属性名: 值}`
  151. 所有请求要 sha256 签名:`path + body(去空白) + appId + appKey + timestamp`。
  152. `refreshToken` 与签发它的客户端绑定,换 `app_source` 会报 `43005`。
  153. ---
  154. ## 三、美的桥
  155. ```bash
  156. cd midea-bridge
  157. python midea_bridge.py --list # 扫描局域网,不需要账号
  158. python midea_bridge.py --login # 登录美居,换取并缓存 token/key
  159. python midea_bridge.py --status
  160. python midea_bridge.py --set 洗衣机 power=true
  161. ```
  162. 美的设备支持局域网直连,延迟几十毫秒,断网也能用。代价是 V3 协议的设备需要一对 token/key,只能从云端用账号换一次,换到后缓存在本地,之后不再联网。
  163. ---
  164. ## 接入 WorkBuddy(MCP)
  165. 三个桥都能以 MCP server 方式运行(不带参数就是 stdio 模式)。在 WorkBuddy 的 MCP 配置文件里加:
  166. ```jsonc
  167. {
  168. "mcpServers": {
  169. "xiaoai": {
  170. "command": "python",
  171. "args": ["/绝对路径/xiaoai-bridge/xiaoai_bridge.py"]
  172. },
  173. "haier": {
  174. "command": "python",
  175. "args": ["/绝对路径/haier-bridge/haier_bridge.py", "--mcp"]
  176. },
  177. "midea": {
  178. "command": "python",
  179. "args": ["/绝对路径/midea-bridge/midea_bridge.py", "--mcp"]
  180. }
  181. }
  182. }
  183. ```
  184. 配置写好后需要在连接器管理页点一次「信任」,MCP 不会自动启用。
  185. ---
  186. ## 已知坑(都是实测踩出来的)
  187. **TLS**:`account.xiaomi.com` 用默认 SSL 上下文会报 `CERTIFICATE_VERIFY_FAILED`(链里缺中间证书),其他站点正常。连小米账号域时统一用 `ssl.create_default_context(cafile=certifi.where())`。
  188. **HTTP 代理**:如果环境里有 `HTTP_PROXY`,登录会撞上异地登录风控(`securityStatus=16`)。所有 .cmd 启动脚本都先把代理变量清空。
  189. **小米返回码**:`code=0` + `securityStatus=16` 是「密码对但判定异地登录」,需要打开返回里的 `notificationUrl` 完成短信验证;`code=70016` 才是密码校验没过。两者完全不同。
  190. **云端对话记录读不到**:cookie 里的 `deviceId` 必须是**真实设备的 DID**(UUID 形式),不是 token 里那个登录客户端 ID。用错会返回 200 但 `records` 恒为空,从返回上完全看不出问题。另外 `hardware`(设备型号)也是必填。
  191. **小爱的失败反馈分两种**:硬失败(明确说「不支持」)和软拒绝(换个说法让你去米家绑定设备)。只判断硬失败词,第三方设备永远走不通,详见上文「家电指令去重」。
  192. **小爱的 serviceToken 只有几天寿命**:凭证文件里的 `micoapi` 一对是 serviceToken,过期后对话接口一律回 401。`xiaoai_voice.py` 里 `maybe_refresh_service_token()` 满 8 小时就用**账号密码**重新登录换一对(密码经 Windows DPAPI 加密存在 `.xiaomi_credential.dat`,改密码或换机器后跑一次 `save-credentials.cmd`)。这条链路实测可连续续期,不需要人工干预。
  193. > passToken 续期那条路**已废弃**:它用一次就轮换,只有 `Set-Cookie` 里才是新值,第二次必定 70016。所以 `renew_token.py` / `setup-pass-token.cmd` 已被删除,别再往回走。
  194. **别传 token_store 的字符串路径**:miservice 的 `MiTokenStore.save_token(None)` 会 `os.remove()` **删掉凭证文件**,而 `MiAccount.login()` 的异常分支正好这么调 —— 登录失败一次,`passToken` 就连文件一起没了。所以创建 `MiAccount` 一律用 `xiaoai_bridge.token_store()`(包了一层,空 token 直接忽略)。
  195. **别永久缓存 MiAccount**:进程若在凭证文件缺失时启动,缓存下来的 `account.token` 是 `None`,之后每次播报都抛 `Login failed`,哪怕凭证几秒后就恢复了。`XiaoaiClient._ensure` 现在按文件 mtime 判断要不要重建。
  196. **海尔写入后回读是旧值**:燃气热水器这类设备不主动上报,写完立刻查会读到旧值。要先发 `getAllProperty` 强制刷新再回读。
  197. **海尔类型必须对**:云端读回来的值全是字符串,下发时要按属性的 `dataType` 转成原生类型(`Integer` / `Double`),否则设备静默不执行。布尔比较也要小心 `"true"` 和 `"True"`。
  198. **WSS 关闭握手会硬等 10 秒**:`async with session.ws_connect()` 退出时要等服务器回 close 帧。命令早就发完了却为关连接多等十秒,这是延迟的主要来源。改成手动 close + `asyncio.wait_for(ws.close(), 0.8)`。
  199. **美的云端模块被杀毒删掉**:`site-packages/midealocal/cloud.py` 会被某些杀软按内容拦截删除。所以 `tools/make_cloud_blob.py` 把源码转成 base64 存成 blob,运行时还原并注入 `sys.modules`。升级 `midea-local` 之后要重新跑一次:
  200. ```bash
  201. python tools/make_cloud_blob.py
  202. ```
  203. **Windows 批处理**:`.cmd` 必须是 CRLF + 纯 ASCII,否则 cmd.exe 解析失败、脚本静默中断(表现为双击没反应)。路径里别用正斜杠,`if exist "C://..."` 会判成不存在。
  204. ---
  205. ## 安全与隐私
  206. **这个仓库里不含任何凭证。** 下列文件全部在 `.gitignore` 里,永远不会被提交:
  207. | 文件 | 里面有什么 |
  208. |---|---|
  209. | `xiaoai-bridge/xiaoai_token.json` | `passToken`、`userId`、登录客户端 ID |
  210. | `xiaoai-bridge/xiaoai_auth.json` | 设备 DID、音箱名称、型号 |
  211. | `haier-bridge/haier_auth.json` | 手机号、`accessToken`、`refreshToken` |
  212. | `haier-bridge/haier_devices.json` | 设备 ID、产品型号 |
  213. | `midea-bridge/midea_devices.json` | 局域网 token/key、设备 ID |
  214. | `*_log.txt` / `*.log` | 对话原文、设备状态、云端原始返回 |
  215. 如果你自己 fork 这个项目,**提交前务必确认这些文件没被 `git add -f` 强制加进去**。
  216. 仓库里带了一个检查脚本,提交前跑一次:
  217. ```bash
  218. git add -A
  219. python tools/check_repo.py # 返回 0 才干净
  220. ```
  221. 它会检查暂存区里有没有手机号、邮箱、`passToken`、设备 DID、本机路径、内网 IP,同时确认 `.cmd` 的换行属性是 `crlf`。用法见文件头注释,可以挂到 pre-commit 钩子上。
  222. 另外两点:
  223. - `haier-bridge` 里的 `appId` / `appKey` 是海尔官方 App 客户端自带的,不是任何人的私人凭证,但也不属于本项目。它们随时可能失效。
  224. - 小爱、海尔、美的用的都是各家的**非公开接口**,靠逆向 App 得到,没有任何官方支持。接口随时会变。
  225. ## 免责
  226. 仅供个人学习和自用。请只操作你自己账号下的设备。因使用本项目导致的设备异常、账号风控、数据丢失,作者不承担责任。

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.