小爱同学：播报 & 执行
本 skill 只有两个动词。收到请求 → 判断一次 → 调一条命令 → 报一句 → 结束，单条约 3 秒。
把链路保持在这个长度，就是本 skill 的全部设计意图。
本 skill 只负责执行：不做场景编排、不做自动化规则、无 MCP server、无定时任务。
多设备诉求由 agent 自行拆成多次调用依次执行。
一、唯一需要的判断
| 用户想要 | 子命令 | 例 |
|---|---|---|
| 让音箱说话（传话 / 广播 / 通知 / 提醒 / 念一段） | speak |
speak "该做饭了" --speaker "卧室-小爱音箱" |
| 让设备动作（打开 / 关闭 / 调到 / 播放） | directive |
directive "打开客厅灯" --speaker "客厅-小爱音箱" |
判据只有一条：这句话是要"被说出来"，还是要"被做出来"？
> ⚠️ 最常见的误判：speak "打开客厅灯" —— 音箱会把「打开客厅灯」念出来，灯一动不动。
> speak 是嘴巴，从不执行。凡是「打开 / 关闭 / 调到 / 播放」这类祈使句，一律用 directive。
> （自 2026-09-13 起，speak 检测到像指令的文本时会在输出 JSON 里附 hint，看到就改 directive。）
二、命令
python "<skill_dir>/scripts/xiaoai_control.py" speak "文字" [--speaker "音箱名"]
python "<skill_dir>/scripts/xiaoai_control.py" directive "指令" [--speaker "音箱名"] [--loud]
<skill_dir>= 本 SKILL.md 所在目录，必须解析成绝对路径。--speaker可省略 → 用config.json的speakers.default。--loud仅directive可用：让小爱出声应答；默认静默执行。- 音箱名须与米家 App 里的中文名完全一致（如
卧室-小爱音箱），不是media_player.xxx。 - 输出是单行 JSON，中文以
\uXXXX转义（这是刻意设计，不是乱码），解析后再呈现给用户。
> 设备侧的调节无需本 skill 另做功能。 "调大音量 / 调到 30 / 切到制冷 / 风速最大"这类诉求，
> 直接原样交给 directive —— 小爱云端会自己解析成对应设备的动作。
> 本 skill 只提供「一张嘴（speak）+ 一双手（directive）」，功能面到此为止。
选音箱：唯一需要多想一秒的地方
控制哪个房间的设备，就用那个房间的音箱。 用错房间 → 指令返回成功、设备毫无动作。
| 房间 | 音箱 |
|---|---|
| 有音箱的房间 | 用该房间的音箱（如 卧室-小爱音箱） |
| 无音箱的房间 | 指令里写明确设备名（如「打开客厅灯」），可跨房间生效 |
音箱名须与米家 App 里的中文名完全一致。不确定就用 speakers.default。不要为了选音箱去扫描设备清单。
三、调完即结束（硬规则）
发一次 → 报一句 → 结束。
明确禁止（这些正是把 3 秒拖成数分钟的原因）：
- ❌ 换音箱重试 / 多台音箱扫描
- ❌ 为"验证是否可用"而真的下发一次指令
- ❌ 因猜疑失败而重复下发——音箱一出声收不回来。返回里只要出现过"已下发/已受理"
就视为已生效，哪怕同时报了错也不要重试
回报口径（不要拔高）
| 命令 | 只能说 | 不能说 |
|---|---|---|
speak |
"已下发" | "已经说话了" |
directive |
"已下发 / 云端已接受" | "已打开 / 已关闭 / 已完成" |
依据：speak 只返回 chars（连布尔都没有）；directive 返回的 result: true 仅代表
小爱云端收下了这句话，不代表设备真的执行了。
没有读回能力（2026-09-13 起）：本 skill 只有 speak 和 directive 两个命令，
不存在读取设备状态或精确控制的能力。设备是否真的动作，只能靠用户肉眼确认，agent 不下场排查。
四、硬约束（只有两条）
| 项 | 值 | 超限表现 |
|---|---|---|
| 长度 | 单条 200 字 | 超长须切段后逐条发（可多次调用） |
| 审计 | 全部控制类调用记入 state/audit.log |
— |
没有频控（2026-09-13 取消）：directive / speak 均不限次数，连发多条不必等待、
不必节流。不要为"避免触发频控"而改写措辞或拆分意图。
设备侧护栏已从代码中彻底移除（2026-09-13）：无设备白名单、无名称/类别/关键词黑名单。
本 skill 不做"某设备 / 某类设备 / 某句话不可操作"的判定——directive 是 agent 的手，
权限全开，风险判断交由 agent 侧。
五、出错怎么办
| 现象 | 处置 |
|---|---|
凭据未配置 |
告知用户填写 ~/.xiaoi/config.json，不要自行获取或猜测凭据 |
NOT_FOUND: 未能定位 xiaoii 包 |
提示 npm i -g xiaoii，或在 config.json 设 bridge.xiaoiiPath |
未找到设备 |
设备名写错了（须与米家 App 完全一致） |
| 返回成功但设备没动 | 小爱通道无回执，无法确认；如实告知用户即可，不要据此推断"此设备不能走 directive" |
