| name | xiaoai-ha-control |
| description | 通过 Home Assistant + Xiaomi Miot 控制小爱音箱，并可选支持“小爱语音 → OpenClaw”的桥接。适用于两类场景：1) 用户要求“让小爱说一句… / 播报… / 通知…”、“告诉小爱… / 让小爱执行…”、“让小爱播放音频 / mp3 / 链接”时，使用本 skill 进行下行控制；2) 已接入小爱语音桥时，处理带有 `【来自小爱】` / `【来自小爱语音】` 标识的上行消息。只要任务涉及小爱音箱控制、通过小爱执行命令、通过小爱播报结果，或小爱来源消息的桥接与分流，就应使用此 skill。 |
xiaoai-ha-control
这个 skill 提供两层能力：
- OpenClaw → 小爱音箱（核心能力）
say：让小爱播报文本exec：让小爱执行文本指令play：让小爱播放 URL 音频
- 小爱音箱 → OpenClaw（可选桥接能力）
- 通过 Home Assistant conversation sensor +
bridge_server.py 把小爱语音文本转给 OpenClaw
优先把它理解为一个 小爱控制 skill；语音桥接是可选增强，不是所有用户都必须启用。
何时使用
A. 普通聊天中，用户想让 OpenClaw 控制小爱
当消息不带 【来自小爱】 / 【来自小爱语音】 标识，并且文本中出现：
优先按 OpenClaw 控制小爱 处理。
推荐映射：
- 明确“说 / 播报 / 通知” →
say
- 明确“播放音频 / 链接 / mp3” →
play
- 其他默认 →
exec
示例：
告诉小爱同学，5分钟后该我洗碗 → exec让小爱播报一句：开会啦 → say让小爱播放这个 mp3 → play
B. 消息带有小爱来源标识
当消息中明确带有：
说明这是 小爱控制 OpenClaw 的上行请求。
此时：
- 不要把它当普通聊天消息理解
- 若环境已接入 bridge，应按桥接规则处理
- 若桥接环境未配置，则只说明当前未接入该能力，不要假装已经收到真实小爱入口事件
前置条件
使用本 skill 前，通常需要：
- 已安装并启动 Home Assistant
- 已安装 HACS
- 已安装 Xiaomi Miot
- 已将小爱音箱接入 HA
- 已找到以下实体：
play_textexecute_text_directivemedia_player（可选但推荐）
- 已配置
.env：
HA_URLHA_TOKENXIAOAI_PLAY_TEXT_ENTITY_IDXIAOAI_EXECUTE_TEXT_ENTITY_IDXIAOAI_MEDIA_PLAYER_ENTITY_ID
详细搭建步骤见 README.md。
推荐调用
say
bash scripts/xiaoai.sh say "你好，我是小叮当。"
exec
bash scripts/xiaoai.sh exec "关闭客厅灯"
play
bash scripts/xiaoai.sh play "http://example.com/test.mp3"
语音桥接规则（启用 bridge 时）
如果已启用 bridge_server.py：
- HA 只做入口转发
bridge_server.py 负责白名单放行- 命中白名单才继续交给 OpenClaw
- 未命中则终止，让小爱原生处理
若带小爱来源标识的文本中明确点名了某个子 agent（如研究员、邮差、码农、产品、运维、教练、运营等），推荐规则是：
main 必须将任务分配给对应子 agent- 子 agent 完成后先回
main
- 再由
main 统一决定聊天回复与小爱口播
不要让 bridge 直接跳过 main 去找子 agent。
重要注意事项
say 用于播报，不负责设备控制exec 用于让小爱理解一条文本命令，能否成功取决于小爱本身是否能理解该命令play 用于播放 URL 音频，要求小爱音箱能访问该 URL- 不同设备型号、不同 Xiaomi Miot 接入方式，暴露的实体可能不同
- 如果要对外分享，请提醒使用者：先跑通
say / exec / play，再考虑语音桥接
文档导航
README.md：从零搭建、完整架构、桥接说明NOTES.md：兼容性边界、分享注意事项STATUS.md：当前架构定位与已知限制
