https://github.com/Yonsm/ZhiBot

Uniform Bot Platform for HomeAssistant

通用交互式机器人平台，目前支持天猫精灵、小爱同学、钉钉群机器人。

安装：把 zhibot 放入 custom_components；也支持在 HACS 中添加自定义库的方式安装。

提示：如果只用了单个平台，可以把未使用的平台文件删除，如只用了天猫精灵，可以删除掉 ding.py 和 miai.py。

配置：参见下文。也可以参考 我的 Home Assistant 配置 中 configuration.yaml

零、天猫精灵个人技能机器人（强烈推荐） genie2bot

1. Home Assistant 配置

zhibot:
  - platform: genie2
    token: XXXXXXXX
    file: !secret zhibot_file（天猫精灵-个人技能-后端服务-编辑-下载认证文件，文件名，不包含.txt）
    text: !secret zhibot_text（认证文件文件内容）

配置后，可以进行对话测试：https://xxx.xxx.xxx:8123/genie2bot?q=打开客厅灯&token=XXXXXXXX；也可以在浏览器通过以下链接获取相应的预料库和词汇表：

• 对话表达语料库：https://xxx.xxx.xxx:8123/genie2bot?q=corpus
• 动作实体词汇表：https://xxx.xxx.xxx:8123/genie2bot?q=action
• 位置实体词汇表：https://xxx.xxx.xxx:8123/genie2bot?q=place
• 设备实体词汇表：https://xxx.xxx.xxx:8123/genie2bot?q=device
• 名称实体词汇表（不用）：https://xxx.xxx.xxx:8123/genie2bot

语料库和实体词汇表，在后续的配置后批量导入。

2. 天猫精灵技能应用平台配置

登录 天猫精灵技能应用平台， 创建新技能 → 个人技能（私域分享） ，然后按照下面的示意图配置。

一、天猫精灵机器人 geniebot

一次性接入 Home Assistant 的大部分设备到天猫精灵，通过天猫精灵语音控制开关设备、查询传感器。无需第三方服务器，直接使用 Home Assistant 作为服务器和 OAuth，链路高效。

1. Home Assistant 配置

zhibot:
  - platform: genie

无需配置 token，会修正 HA 的 OAuth 认证方式延长认证有效期（借鉴来的套路，参见 oauthbot，我也没搞明白）。建议配置 token，这样不用重写 HA 的 OAuth 认证有效期，此时下文中的 网关 URL 将变成 https://xxx.xxx.xxx:8123//geniebot?token=******。

2. 天猫精灵开放平台设置

1). 添加技能

登录 天猫精灵开放平台，进入 设备开发与接入 → 生活物联网平台 → 云云接入 → 技能开发 → 添加新技能。

2). 服务设置

• 网关 URL：https://xxx.xxx.xxx:8123/geniebot
• Client ID：https://open.bot.tmall.com
• Client Secret：NA
• Authorization URL：https://xxx.xxx.xxx:8123/auth/authorize
• Access Token URL：https://xxx.xxx.xxx:8123/auth/token

3). 授权调试

内容设置 → 技能发布 → 发布前验证 → 授权调试 → 账户配置→ 输入 HA 账户密码 → 可看到你的设备列表。

4). 设备解绑

天猫精灵开放平台已升级为 2.0，但新版竟然没有 设备解绑 的功能。虽然旧版已无法新增 智能家居 技能，但可以解绑设备：控制台 → 技能应用平台 → 内容&IOT 技能 → 服务设置 → 测试验证 → 测试已开启 → 设备解绑。

另外，这里有 旧版本配置图示，仅供参考。

3. 使用方式

直接通过天猫精灵语音控制 HA 设备，如“天猫精灵，打开客厅灯”，也可以查询传感器，如“天猫精灵，阳台传感器 PM2.5”。

4. 名称规范

天猫精灵查询 HA 时，重要的三个参数需符合规范，否则天猫精灵理解不了：

• zone：区域名称，如客厅、餐厅等，须符合 placelist 规范：

门口,客厅,卧室,客房,主卧,次卧,书房,餐厅,厨房,洗手间,浴室,阳台,宠物房,老人房,儿童房,婴儿房,保姆房,玄关,一楼,二楼,三楼,四楼,楼梯,走廊,过道,楼上,楼下,影音室,娱乐室,工作间,杂物间,衣帽间,吧台,花园,温室,车库,休息室,办公室,起居室

• deviceName：设备名称，须符合 支持品类 或 aliaslist 规范：

灯,房灯,吸顶灯,床头灯,床灯,电灯,吊灯,台灯,落地灯,壁灯,挂灯,射灯,筒灯,灯带,灯条,暗藏灯,背景灯,阅读灯,柜灯,衣柜灯,天花灯,路灯,彩灯;空调,空气调节器,挂式空调;风扇,电风扇,落地扇,电扇,台扇,壁扇,顶扇,驱蚊风扇,暖风扇,净化暖风扇,冷风扇,塔扇;空气净化器,空净,空气清洁器;扫地机器人,扫地机,打扫机,自动打扫机;窗帘,窗纱,布帘,纱帘,百叶帘,卷帘;加湿器,空气加湿器,加湿机,空气加湿机;插座,插头,排插单孔单控;暖奶器,热奶器,牛奶,调奶器,温奶器,冲奶机;电热水壶,养生水壶,水壶,养生壶,热水壶,电水壶;豆浆机;烤箱,嵌入式烤箱;电视;净水器,净水器箱型;冰箱,双开门冰箱,冰柜;开关;机顶盒;传感器;热水器,电热水器,燃气热水器;饮水机;摄像头,摄像,摄像机;路由器,路由,智能路由器;电饭煲,电饭锅,饭煲,饭锅;水族箱控制器,智能鱼缸,鱼缸;蒸脸器;取暖器,加热器;料理机;洗衣机,顶开式洗衣机,滚筒洗衣机;微波炉;空气检测仪;除湿机,除湿器;智能床;万能遥控器;香薰机;窗;抽油烟机,抽烟机,烟机;指纹锁;洗碗机,洗碗器;车;浴霸;晾衣机;新风机;壁挂炉;干衣机,干衣器;驱蚊器;跑步机;智能门控,智能门锁,门锁,电子锁;破壁机,超跑;网关;秤;智能手环;电压力锅,压力锅,高压锅;晾衣架,衣架,晒衣架;电热毯;按摩仪;按摩椅;无线按钮;电视盒子,盒子,小米盒子,荣耀盒子,乐视盒子,智能盒子;投影仪,投影机,投影,背投;风扇灯;门磁传感器;人体传感器;灯带;智能猫眼;燃气热水器;面包机;消毒柜;磁炉,电磁炉;补水仪;电动牙刷;灭蚊器;双键开关;三键开关;单火开关;单火双键开关;单火三键开关;榨汁机;调奶器;酒柜;吸奶器;消毒锅;擦窗机;动感单车;走步机;多功能料理锅;吸尘器;电脑;温湿度传感器;四键开关;垃圾处理器;血糖仪;血压仪;智能垃圾桶;取暖桌;划船机;点读笔;猫砂盆;制冰机;电炸锅;按摩贴;烟雾传感器;燃气传感器;水浸传感器;光线传感器;暖菜板;艾灸仪;辅食机;足浴盆;暖宫带

• deviceType：设备类型，须符合 支持品类 规范。

会尝试从 HA 配置信息中，根据规则尝试自动转换成天猫精灵匹配的名称和类型。但有些可能匹配不成功，此时可以在 customize.yaml 中，定制天猫精灵能识别的区域、名称和类型，如：

genie_zone: 客厅
genie_name: 吸顶灯
genie_type: outlet

其中 genie_zone 可以配置给单个设备，也可以配置给分组（将应用到分组下的所有设备）。

建议：把设备按上述区域名称分组（如“客厅”），或以上述区域前导设备名称（如“客厅灯”）；设备名符合上述名称规范。这样会自动推测搞定，不用手动配置。

二、小爱同学机器人 miaibot

类似天猫精灵，但小爱同学的智能设备使用控制方式需要唤醒词语，实际体验远远没有天猫精灵好。且需进入测试模式，有效时间短，要频繁重新进入测试模式，不建议使用。

三、钉钉群机器人 dingbot 之 Home Assistant ⇋ 钉钉群机器人 双向互动

钉钉群设置：在钉钉群里添加自定义机器人，勾选“是否开启 Outgoing 机制”。据称此功能在内测，部分用户可能没有没有此选项，佛系或自行解决。

1. Home Assistant 配置

zhimsg:
  - platform: ding
    name: 钉钉信使
    token: !secret dingbot_token
    secret: !secret dingbot_secret

zhibot:
  - platform: ding
    token: !secret zhibot_token

依赖：需依赖 ZhiMsg，请一并安装好。 注意：zhibot 的 - platform: ding 没有配置 name 。

2. 钉钉群机器人设置

3. 使用方式

Home Assistant 可以给钉钉群机器人发送消息。也可以在钉钉群里面 @机器人 控制 Home Assistant，输入 ? 查询使用样例，如下：

打开/关闭（设备或群组名）；查询（设备或群组名，可省略“查询”）；触发（自动化，可省略“触发”）

四、钉钉群机器人 dingbot 之 钉钉群机器人 → Home Assistant → 小爱音箱 单向控制

钉钉群设置：在钉钉群里添加自定义机器人，勾选“是否开启 Outgoing 机制”。据称此功能在内测，部分用户可能没有没有此选项，佛系或自行解决。

1. Home Assistant 配置

zhimi:
  username: !secret zhimi_username
  password: !secret zhimi_password

zhimsg:
  - platform: miai
    name: 客厅音箱
    did: 380205692
    model: x08c
  - platform: miai
    name: 过道音箱
    did: 89463074
    model: lx01

zhibot:
  - platform: ding
    name: 客厅音箱
    token: !secret zhibot_token
  - platform: ding
    name: 过道音箱
    token: !secret zhibot_token

依赖：需依赖 ZhiMi 和 ZhiMsg，请一并安装好。 注意：必须配置 name，并和 ZhiMsg 的小爱音箱同名。

2. 钉钉群机器人设置

3. 使用方式

在钉钉群里面 @小爱音箱 来播报或执行文本。输入 ? 查询使用样例，如下：

您好，我是小爱同学
查询天气
执行关灯
静默关灯
音量40
音量70%大声说您好

还可以 ?? 查询更多 MIoT 命令，如下：

Get Props: ?<siid[-piid]>[,...]
           ?1,1-2,1-3,1-4,2-1,2-2,3
Set Props: ?<siid[-piid]=[#]value>[,...]
           ?2=#60,2-2=#false,3=test
Do Action: ?<siid[-piid]> <arg1> [...]
           ?5 Hello
           ?5-4 Hello #1

Call MIoT: ?<cmd=prop/get|/prop/set|action> <params>
           ?action {"did":"380205692","siid":5,"aiid":1,"in":["Hello"]}

Call MiIO: ?/<uri> <data>
           ?/home/device_list {"getVirtualModel":false,"getHuamiDevices":1}

Devs List: ?list [name=full|name_keyword] [getVirtualModel=false|true] [getHuamiDevices=0|1]
           ?list Light true 0

MiIO Spec: ?spec [model_keyword|type_urn]
           ?spec
           ?spec speaker
           ?spec xiaomi.wifispeaker.lx04
           ?spec urn:miot-spec-v2:device:speaker:0000A015:xiaomi-lx04:1

五、参考

• ZhiMsg
• Yonsm.NET
• Hassbian geniebot
• Hassbian miaibot
• Hassbian dingbot
• Hassbian ding2msgbot
• Yonsm's .homeassistant