Back to search
smart-home-voice-bridge
MCP serverGitHub
智能家居语音桥:小爱音箱 + 海尔 + 美的 + 极米 + 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
Markdown
[](/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
- # 智能家居语音桥(Xiaoai Smart Home Bridge)
- 把小爱音箱变成家里的语音入口:**能问的交给大模型,能控的本地直连**,小爱自己管不到的家电(海尔、美的)也接进来。
- 三个独立的桥,可以只用其中一个:
- | 桥 | 对象 | 走的通道 | 能做什么 | 延迟 |
- |---|---|---|---|---|
- | `xiaoai-bridge` | 小爱音箱 | 小米云 `micoapi`(非公开接口) | 文字/语音播报;读云端对话记录,把提问转给大模型再念回来 | 播报 <1s |
- | `haier-bridge` | 海尔家电 | 海尔 U+ 云平台 | 读状态、下发控制(开关/温度等) | 读 0.1~0.7s,写 1~3s |
- | `midea-bridge` | 美的家电 | 局域网直连(UDP 6445 发现 / TCP 6444 控制) | 读状态、下发控制,断网也能用 | 几十毫秒 |
- 三者都以 **MCP server** 形式暴露给 WorkBuddy,也都能单独当命令行工具用。
- ---
- ## 目录结构
- ```
- .
- ├── xiaoai-bridge/ 小爱音箱(小米云)
- │ ├── xiaoai_bridge.py 登录 / 播报 / 米家 API / MCP(外部入口,路径固定)
- │ ├── xiaoai_voice.py 语音对话桥入口(薄壳:实现拆进了 voice/ 包)
- │ ├── voice/ 语音桥实现
- │ │ ├── runtime.py 日志/心跳/单实例互斥/pid/--stop --status --bg
- │ │ ├── llm.py WorkBuddy 网关 + ask_workbuddy + 朗读化
- │ │ ├── intents.py 全部 parse_*_intent 纯函数 + 词表
- │ │ ├── answers.py 小爱回话判定:软拒绝/是否家电指令/跨音箱去重
- │ │ ├── projector.py 坚果投影仪执行 + 看片/睡觉场景
- │ │ ├── miot.py 米家:台灯/就近开灯/核查小爱的口头宣称
- │ │ ├── appliances/ 本地家电按设备与场景分包
- │ │ │ ├── common.py 共享路径、模式文案、不支持设备清单
- │ │ │ ├── bath.py 浴霸局域网直控
- │ │ │ ├── liangba.py 凉霸 BLE + ESP32 连接预热
- │ │ │ ├── heater.py 海尔热水器
- │ │ │ ├── washer.py 美的洗衣机状态与基础控制
- │ │ │ ├── scenes.py 洗澡组合场景
- │ │ │ ├── scheduling.py 定时登记/取消/查询
- │ │ │ └── dispatcher.py fast_home_action 总分发 + 超时播报
- │ │ ├── conversation.py 云端对话读取/凭证续期/播报
- │ │ └── main.py poll_once / 多音箱 worker / 主循环
- │ ├── xiaoai_schedule.py 定时任务(纯本地)
- │ ├── voice_watchdog.py 看门狗(Windows 计划任务每分钟拉起)
- │ ├── tests/ 离线自测,不碰真实设备
- │ ├── docs/ 语音场景与模块地图
- │ ├── tools/ 米家域解锁等运维工具
- │ └── *.cmd 双击即用的登录 / 自检 / 启动脚本
- ├── haier-bridge/ 海尔智家(U+ 云)
- │ ├── haier_bridge.py 登录 / 读状态 / 控制 / MCP(外部入口)
- │ └── tests/ 离线自测
- ├── midea-bridge/ 美的(局域网 + BLE)
- │ ├── midea_bridge.py 发现 / 登录换密钥 / 控制 / MCP(外部入口)
- │ ├── midea_ble.py 凉霸 BLE 广播遥控协议(按键语义/状态解析)
- │ ├── esp32_adv.py ESP32 板子的 UDP 命令通道
- │ ├── tools/ BLE 抓包、云端模块提取等开发工具
- │ └── experiments/ 协议逆向时的抓包取证(归档,无人引用)
- ├── jmgo-bridge/ 坚果投影仪(局域网 ADB)
- │ ├── jmgo_bridge.py 扫描 / 连接 / 控制 / MCP(外部入口)
- │ └── tests/ 离线自测
- ├── esp32-ble-bridge/ ESP32-C5 BLE/WiFi 桥(固件 + 板子运维)
- │ ├── main/ 固件源码(IDF v5.5.1)
- │ ├── tools/ 板子运维:远程盲发/重启、串口诊断等
- │ ├── hardware/ 官方原理图 + 充电电路局部图
- │ └── README.md 固件协议与硬件注意事项
- ├── tools/
- │ └── check_repo.py 提交前检查:换行策略 + 敏感信息
- └── requirements.txt
- ```
- 五个桥接根目录及各桥主入口是计划任务、MCP、CMD/VBS 和跨桥导入共同依赖的
- 外部契约,保持原路径;测试、开发工具和内部实现可以独立归档。
- ---
- ## 安装
- ```bash
- python -m venv .venv
- source .venv/bin/activate # Windows: .venv\Scripts\activate
- pip install -r requirements.txt
- ```
- 国内网络建议加镜像,否则装 `miservice_fork` 会挂很久甚至报「找不到版本」:
- ```bash
- pip install -r requirements.txt -i https://mirrors.aliyun.com/pypi/simple
- ```
- ---
- ## 一、小爱音箱桥
- ### 登录
- ```bash
- cd xiaoai-bridge
- python xiaomi_credential.py --save # 存账号密码(也可双击 save-credentials.cmd),之后自动续期
- python xiaoai_bridge.py --login # 账号密码登录一次,生成本地凭证
- python xiaoai_bridge.py --demo # 自测:让音箱念一句话
- ```
- **密码登录可能被拒(`securityStatus=16`)**,这是小米的异地登录风控,不是密码错 —— 需要打开返回里的 `notificationUrl` 收一条短信。验证信任**只绑当次登录会话**,所以必须在同一个浏览器进程里验完立刻换取凭证,Python 侧重放没用。这一步有专门脚本:`tools/unlock_xiaomiio.py`(详见该文件头注释)。
- `--pass-token`(手动从浏览器 F12 复制 passToken)**已废弃不要再用**:小米的 passToken 用一次就轮换,第二次必定 `70016`;而且网页 `serviceLogin` 的回包不带 `ssecurity`,算不出 `clientSign`,换票恒定 401。
- 凭证只写到本地的 `xiaoai_token.json` / `xiaoai_auth.json`,两个文件都在 `.gitignore` 里。
- ### 播报
- ```bash
- python xiaoai_bridge.py --speak "水烧好了"
- python xiaoai_bridge.py --probe # 检查录音/对话两条通道有没有数据
- python xiaoai_bridge.py --rooms # 按米家房间列出设备
- python xiaoai_bridge.py --refresh-rooms # 挪过设备后重新拉一次房间划分
- ```
- `--rooms` 用的是米家 App 里的分房:设备列表接口本身**不带**房间号,房间归属只在
- `/homeroom/gethome` 的 `roomlist[].dids` 里。语音桥的核查层靠这张表把「主卧的灯」
- 圈到具体几台,所以挪过设备记得 `--refresh-rooms`(缓存 7 天,启动时会自动续)。
- ### 语音对话桥
- ```bash
- python xiaoai_voice.py # 默认:问句转发,家电指令先看小爱办没办成
- python xiaoai_voice.py --all # 家电指令一律转发
- python xiaoai_voice.py --trigger 问电脑 # 只响应含触发词的话
- python xiaoai_voice.py --dry-run # 只打印听到的内容,不调大模型
- ```
- 工作方式:每 2.5 秒轮询一次小米云端的对话记录,发现新提问就交给大模型,再念回来。
- **关键设计:家电指令去重。** 每条提问在云端都带 `answers`(小爱自己的回复):
- - 有回复、且不是失败话术 → 小爱已经办了,桥**闭嘴**
- - 回复是失败话术 → 小爱没办成,交给本桥兜底
- - 还没有回复 → 再等 6 秒,等不到就转发
- 这里有个必须知道的细节:小爱对**它管不到的第三方设备**(海尔、美的)不会说「不支持」,而是甩一句引导语,比如「没有发现可以操作的热水器,先去米家绑定设备吧」。只按「不支持/找不到」这类硬失败词判断,会把这种**软拒绝**误判成"已执行"直接吞掉。所以判定必须同时覆盖硬失败词和句式正则。
- ### 家电指令快通道
- 问句要过一次网关对话轮次(固定 10~13 秒),但开关家电不需要。`voice/` 包里有一层纯规则解析:
- - 认得很准的「打开/关闭 XX」→ 本地直接调桥的接口,**3~4 秒**完成,不经过大模型
- - 认不准的说法(「调到 45 度」之类)→ 回落给大模型,不猜
- - 小爱压根没吭声时,**开关类不擅自执行**,只有只读查询才接管
- - 说了「关灯」但没说是哪个屋 → **就近执行**:按听见这句话的音箱所在房间办。
- 三台音箱分属主卧 / 客厅 / 门头沟,房间取自米家 App 的分房(见上面 `--rooms`)
- ### 改完代码怎么生效
- 语音桥是常驻进程,改完 `xiaoai_voice.py` 必须重启才会加载新代码。两种方式:
- ```bash
- # ① 直接重启(`--bg` 会脱离终端,关掉窗口也不影响)
- python xiaoai_voice.py --stop
- python xiaoai_voice.py --bg --interval 2.5 --timeout 180
- # ② 留个标记,让看门狗下一轮自己重启(沙箱/编辑器里起的进程容易被回收,这种最稳)
- python -c "open('xiaoai_voice_restart.flag','w').close()"
- python voice_watchdog.py # 想立刻生效就手动跑一轮;不然等计划任务
- ```
- **注意(2026-11-06 18:29 验证)**:在 WorkBuddy 的沙箱终端里手动跑 `voice_watchdog.py`
- 时,`launch()` 用的 `explorer.exe` 会被沙箱拦掉(命令返回 1,进程没起来,日志却已经写了
- 「正在重启」)。沙箱里也不要指望 `--bg`:命令一结束子进程就被回收,看上去还活着但心跳
- 不再刷新。正解是**只写 flag,然后等计划任务那一轮(每分钟)**——它在沙箱外跑,能正常拉起。
- 看门狗由 Windows 计划任务调起,通过 `explorer.exe` 启动进程,所以进程不会随启动它的
- 终端或会话被回收。**同一时刻只允许一个监听进程**(Windows 命名互斥体
- `Local\XiaoaiVoiceBridge`):重复启动的那个会打印一行「已经有一个语音桥在跑了」后自己
- 退出,否则同一句话会被两份进程各执行一遍(2026-11-06 09:08 撞过一次)。
- ---
- ## 二、海尔桥
- ```bash
- cd haier-bridge
- python haier_bridge.py --login # 手机号 + 密码,缓存 token
- python haier_bridge.py --list # 账号下的设备
- python haier_bridge.py --status # 当前状态(带中文描述和取值范围)
- python haier_bridge.py --attrs # 原始属性表,查属性名用
- python haier_bridge.py --set 热水器 onOffStatus=false
- python haier_bridge.py --doctor # 自检
- ```
- 账号也可以走环境变量,避免命令行留痕:`HAIER_USER` / `HAIER_PASS`。
- 三条链路:
- 1. **登录** `POST zj.haier.net/api-gw/oauthserver/account/v1/login`
- 2. **读状态** `POST uws.haier.net/shadow/v1/devdigitalmodels`(数字孪生属性表)
- 3. **控制** WSS `uws.haier.net/gmsWS` → `BatchCmdReq`,内容是 `{属性名: 值}`
- 所有请求要 sha256 签名:`path + body(去空白) + appId + appKey + timestamp`。
- `refreshToken` 与签发它的客户端绑定,换 `app_source` 会报 `43005`。
- ---
- ## 三、美的桥
- ```bash
- cd midea-bridge
- python midea_bridge.py --list # 扫描局域网,不需要账号
- python midea_bridge.py --login # 登录美居,换取并缓存 token/key
- python midea_bridge.py --status
- python midea_bridge.py --set 洗衣机 power=true
- ```
- 美的设备支持局域网直连,延迟几十毫秒,断网也能用。代价是 V3 协议的设备需要一对 token/key,只能从云端用账号换一次,换到后缓存在本地,之后不再联网。
- ---
- ## 接入 WorkBuddy(MCP)
- 三个桥都能以 MCP server 方式运行(不带参数就是 stdio 模式)。在 WorkBuddy 的 MCP 配置文件里加:
- ```jsonc
- {
- "mcpServers": {
- "xiaoai": {
- "command": "python",
- "args": ["/绝对路径/xiaoai-bridge/xiaoai_bridge.py"]
- },
- "haier": {
- "command": "python",
- "args": ["/绝对路径/haier-bridge/haier_bridge.py", "--mcp"]
- },
- "midea": {
- "command": "python",
- "args": ["/绝对路径/midea-bridge/midea_bridge.py", "--mcp"]
- }
- }
- }
- ```
- 配置写好后需要在连接器管理页点一次「信任」,MCP 不会自动启用。
- ---
- ## 已知坑(都是实测踩出来的)
- **TLS**:`account.xiaomi.com` 用默认 SSL 上下文会报 `CERTIFICATE_VERIFY_FAILED`(链里缺中间证书),其他站点正常。连小米账号域时统一用 `ssl.create_default_context(cafile=certifi.where())`。
- **HTTP 代理**:如果环境里有 `HTTP_PROXY`,登录会撞上异地登录风控(`securityStatus=16`)。所有 .cmd 启动脚本都先把代理变量清空。
- **小米返回码**:`code=0` + `securityStatus=16` 是「密码对但判定异地登录」,需要打开返回里的 `notificationUrl` 完成短信验证;`code=70016` 才是密码校验没过。两者完全不同。
- **云端对话记录读不到**:cookie 里的 `deviceId` 必须是**真实设备的 DID**(UUID 形式),不是 token 里那个登录客户端 ID。用错会返回 200 但 `records` 恒为空,从返回上完全看不出问题。另外 `hardware`(设备型号)也是必填。
- **小爱的失败反馈分两种**:硬失败(明确说「不支持」)和软拒绝(换个说法让你去米家绑定设备)。只判断硬失败词,第三方设备永远走不通,详见上文「家电指令去重」。
- **小爱的 serviceToken 只有几天寿命**:凭证文件里的 `micoapi` 一对是 serviceToken,过期后对话接口一律回 401。`xiaoai_voice.py` 里 `maybe_refresh_service_token()` 满 8 小时就用**账号密码**重新登录换一对(密码经 Windows DPAPI 加密存在 `.xiaomi_credential.dat`,改密码或换机器后跑一次 `save-credentials.cmd`)。这条链路实测可连续续期,不需要人工干预。
- > passToken 续期那条路**已废弃**:它用一次就轮换,只有 `Set-Cookie` 里才是新值,第二次必定 70016。所以 `renew_token.py` / `setup-pass-token.cmd` 已被删除,别再往回走。
- **别传 token_store 的字符串路径**:miservice 的 `MiTokenStore.save_token(None)` 会 `os.remove()` **删掉凭证文件**,而 `MiAccount.login()` 的异常分支正好这么调 —— 登录失败一次,`passToken` 就连文件一起没了。所以创建 `MiAccount` 一律用 `xiaoai_bridge.token_store()`(包了一层,空 token 直接忽略)。
- **别永久缓存 MiAccount**:进程若在凭证文件缺失时启动,缓存下来的 `account.token` 是 `None`,之后每次播报都抛 `Login failed`,哪怕凭证几秒后就恢复了。`XiaoaiClient._ensure` 现在按文件 mtime 判断要不要重建。
- **海尔写入后回读是旧值**:燃气热水器这类设备不主动上报,写完立刻查会读到旧值。要先发 `getAllProperty` 强制刷新再回读。
- **海尔类型必须对**:云端读回来的值全是字符串,下发时要按属性的 `dataType` 转成原生类型(`Integer` / `Double`),否则设备静默不执行。布尔比较也要小心 `"true"` 和 `"True"`。
- **WSS 关闭握手会硬等 10 秒**:`async with session.ws_connect()` 退出时要等服务器回 close 帧。命令早就发完了却为关连接多等十秒,这是延迟的主要来源。改成手动 close + `asyncio.wait_for(ws.close(), 0.8)`。
- **美的云端模块被杀毒删掉**:`site-packages/midealocal/cloud.py` 会被某些杀软按内容拦截删除。所以 `tools/make_cloud_blob.py` 把源码转成 base64 存成 blob,运行时还原并注入 `sys.modules`。升级 `midea-local` 之后要重新跑一次:
- ```bash
- python tools/make_cloud_blob.py
- ```
- **Windows 批处理**:`.cmd` 必须是 CRLF + 纯 ASCII,否则 cmd.exe 解析失败、脚本静默中断(表现为双击没反应)。路径里别用正斜杠,`if exist "C://..."` 会判成不存在。
- ---
- ## 安全与隐私
- **这个仓库里不含任何凭证。** 下列文件全部在 `.gitignore` 里,永远不会被提交:
- | 文件 | 里面有什么 |
- |---|---|
- | `xiaoai-bridge/xiaoai_token.json` | `passToken`、`userId`、登录客户端 ID |
- | `xiaoai-bridge/xiaoai_auth.json` | 设备 DID、音箱名称、型号 |
- | `haier-bridge/haier_auth.json` | 手机号、`accessToken`、`refreshToken` |
- | `haier-bridge/haier_devices.json` | 设备 ID、产品型号 |
- | `midea-bridge/midea_devices.json` | 局域网 token/key、设备 ID |
- | `*_log.txt` / `*.log` | 对话原文、设备状态、云端原始返回 |
- 如果你自己 fork 这个项目,**提交前务必确认这些文件没被 `git add -f` 强制加进去**。
- 仓库里带了一个检查脚本,提交前跑一次:
- ```bash
- git add -A
- python tools/check_repo.py # 返回 0 才干净
- ```
- 它会检查暂存区里有没有手机号、邮箱、`passToken`、设备 DID、本机路径、内网 IP,同时确认 `.cmd` 的换行属性是 `crlf`。用法见文件头注释,可以挂到 pre-commit 钩子上。
- 另外两点:
- - `haier-bridge` 里的 `appId` / `appKey` 是海尔官方 App 客户端自带的,不是任何人的私人凭证,但也不属于本项目。它们随时可能失效。
- - 小爱、海尔、美的用的都是各家的**非公开接口**,靠逆向 App 得到,没有任何官方支持。接口随时会变。
- ## 免责
- 仅供个人学习和自用。请只操作你自己账号下的设备。因使用本项目导致的设备异常、账号风控、数据丢失,作者不承担责任。
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.