智能家居控制
让 agent 通过 Home Assistant 本地网关查询设备，并在明确授权后执行控制。
何时使用
- 用户要「开灯/关灯/调亮度/开空调/拉窗帘」等语音/自然语言控制家居
- 用户要查询家里设备状态（温度、开关、电量）
- 用户要把 HA 接成 MCP server 供 agent 调用
- 用户要建「回家/离家/晚安」等一键场景
前置条件
- 已运行 Home Assistant（本地网关，默认端口 8123）
- 已生成 长期访问令牌（HA 页面 → 个人资料 → 安全 → 长期访问令牌）
- 凭据走环境变量，不落盘：
export HA_URL="http://homeassistant.local:8123"
export HA_TOKEN="你的长期访问令牌"
> 若通过反向代理访问 HA（如 https://ha.example.com），注意 2026.10 起 http: 段已弃用，代理与外部 URL 配置改到 设置 → 系统 → 网络 → HTTP 服务器；只在本机直连 :8123 的用户无需处理。
工作流
1. 列出/查询设备
python3 bin/ha_cli.py states # 所有实体
python3 bin/ha_cli.py states light # 只看灯
python3 bin/ha_cli.py get light.living_room # 单设备状态
2. 控制设备（自然语言 → 服务调用）
python3 bin/ha_cli.py call light turn_on --entity light.living_room # 仅预演
python3 bin/ha_cli.py call light turn_on --entity light.living_room --execute # 实际执行
python3 bin/ha_cli.py call automation trigger --entity automation.wakeup --execute --confirm-dangerous
3. 激活场景
python3 bin/ha_cli.py scene 回家 # 仅预演
python3 bin/ha_cli.py scene 回家 --execute # 实际执行；含高风险域时还需 --confirm-dangerous
中文场景模板（examples/scenes.json）
| 场景 | 动作 |
|---|---|
| 回家 | 开客厅灯 + 开空调 26° + 开窗帘 |
| 离家 | 关所有灯 + 关空调 + 关窗帘 |
| 晚安 | 只留夜灯 + 关电视 + 锁门 |
| 早安 | 开卧室灯 + 开窗帘 + 开热水器 |
> 场景里的 entity_id 需按你家的实际实体改（先 states 查名字）。
MCP 化接入（可选）
本目录没有实现 MCP server。需要 MCP 时，可使用 Home Assistant 官方支持的集成，或另行把 call/states/get 封装成工具，并保留本脚本的 dry-run 与确认策略。
Home Assistant 版本校准（2026.9 ~ 2026.10 核对）
本 skill 依赖的 REST 核心接口（GET /api/states、POST /api/services/<domain>/<service>、GET /api/states/<entity_id>）在 2026.9 / 2026.10 中均未变更，脚本可继续使用。但以下变化会影响周边集成、反向代理配置与自动化，使用前需知悉：
2026.9 变化
| 变化 | 影响 | 应对 |
|---|---|---|
| LLM API 工具名加域前缀 | GetLiveContext → homeassistant__GetLiveContext；HassTurnOn → intent__HassTurnOn |
若你在自定义 prompt 里直接点名工具，须改用带前缀的新名称 |
| 敏感操作收紧为管理员 | 安装/跳过更新、清除已跳过更新、Z-Wave 锁用户与凭证操作（set_user/delete_user/set_credential 等）需管理员账户 |
非管理员发起的脚本会失败；改由自动化触发或以管理员身份运行 |
| Persistent Notification 语义变更 | 更新已存在的通知，update_type 由 added 变为 updated |
依赖 added 捕获所有通知的自动化，需把 updated 一并加入触发类型 |
| InfluxDB YAML 配置移除 | 2026.9 起 configuration.yaml 里的 influxdb 连接/认证键完全失效（已自动迁移到 UI） |
从 YAML 中删除相关键，避免启动告警 |
| Modbus 配置从 YAML 移到 UI | 逆变器/电表/热泵类寄存器映射改由集成托管 | 在 UI 中重新配置，配置项由集成维护而非手写 YAML |
| Configurator 集成弃用；VLC 集成移除 | 相关集成不再可用（VLC via Telnet 不受影响） | 迁移到替代方案 |
2026.10 变化
> 状态更新（2026-10-05 核对）：2026.10 beta 已于 2026-09-30 发布，稳定版定于 2026-10-07 20:00 GMT 发布（截至本次核对尚未 GA）。以下条目依据 HA 开发者博客与 beta 发布说明整理；REST 核心接口未受影响。
| 变化 | 影响 | 应对 |
|---|---|---|
http: YAML 配置弃用 ⚠️ |
反向代理、use_x_forwarded_for、trusted_proxies、外部 URL 等原写在 configuration.yaml 的 http: 段已弃用，改到 设置 → 系统 → 网络 → HTTP 服务器（UI） |
对本 skill 影响最直接：若你靠反向代理把 HA 暴露给内网其他机器/容器来调 REST API，需把配置迁到 UI，否则代理头识别与外部 URL 可能失效（长期访问令牌本身不变） |
| 旧版认证模式（legacy auth）移除 ⚠️ | 2026.10 起彻底移除 legacy API 密码认证；用户名统一规范化为小写且去空格 | 对本 skill 有影响：① 若仍用 api_password 旧式认证，升级后将无法登录，须改用长期访问令牌（本 skill 本就只支持 /api/ + Bearer token，不受影响）；② 若你的自动化/脚本按旧用户名大小写做匹配，需同步更新 |
| 一键启用 MCP Server（新功能） | 新增 AI 设置页，一键开启 Model Context Protocol server 访问并生成可复制 URL，可直接粘进 Claude / ChatGPT / Cursor 等外部客户端 | 对本 skill 有正面意义：想接 LLM 对话时，可优先用官方 MCP server 而非自建封装（自建封装见下文「MCP 化接入」仍可用） |
| OAuth2 错误处理移入 helper | OAuth2 异常改为继承 config entry 异常（OAuth2TokenRequestReauthError → ConfigEntryAuthFailed 等），集成不再自行翻译；ImplementationUnavailableError 不再需要手动包成 ConfigEntryNotReady |
仅影响自研自定义集成；调用 REST API 不受影响 |
modbus.get_hub 弃用 |
2026.10 起弃用，2027.10 移除；改用 async_get_unit |
自研 Modbus 集成需迁移；仅用 UI 配置的用户无需处理 |
LLM 工具返回 llm.ToolResult |
工具不再返回裸 JSON，改返回带 data 与 error 标志的 ToolResult；ToolResultContent.tool_result → .result；工具须声明 title / annotations（read_only/destructive/idempotent/open_world）与 integration |
仅影响自研 LLM 工具；免费版 REST 调用不受影响。⚠️ 若你按本 skill 的通用 MCP 模板自建 HA MCP server 并注册 LLM 工具，需按新签名迁移（旧写法告警可用至 2027.11；不声明 integration 的 core 集成直接报错，自定义集成宽限至 2027.10） |
DeviceEntry.config_entries 弃用转为强制 |
config_entries / config_entries_subentries / primary_config_entry 读取即报错（core 抛 RuntimeError，自定义集成记警告）；改用 config_entry_id / config_subentry_id |
仅影响自研集成；REST API 无关（自定义集成宽限至 2027.10） |
割草机新增 stop 动作与 IDLE 活动 |
LawnMowerEntity 支持 stop（取消当前任务但不返航）与 IDLE；原先映射为 PAUSED/ERROR 的集成应改 IDLE |
用到割草机实体/服务的自动化可关注；lawn_mower.stop 服务可经 REST 调用 |
async_migrate_entry 可用 config entry 异常 |
迁移方法可抛 ConfigEntryNotReady 以自动重试（原仅能返回 False） |
仅影响自研集成 |
其他 2026.10 变更（集成级，不影响 REST）：新增 15 个集成（SolarEdge Modbus / Sunsynk / KACO Modbus / my-PV / Threema / Gree Infrared / OSRAM Infrared / Axle Energy 等），移除 8 个（Melnor RainCloud、Zestimate、SolarEdge Local 等，因上游服务停止）；Matter 漏水传感器支持声/光警报分开配置、能源设备可报市电频率与功率因数；自动化「Triggered by」条件不再需手动管理 trigger ID；地图迁移到 OpenStreetMap 矢量瓦片。
> 提示：HA 每月发布都会收紧 API 契约。本 skill 只依赖稳定的 REST 核心接口，因此不受集成级 breaking change 影响；但如果你把本脚本包装成 MCP server、接入 LLM 对话，或通过反向代理访问 HA，请每季度对照一次 Home Assistant 发布说明。
边界与红线
- 安全：HA_TOKEN 是完整控制权凭证，只走环境变量、绝不写入文件/提交仓库；只在局域网/可信网络使用，勿暴露公网。
- 谨慎控制：涉及门锁、安防、大功率电器的操作，先确认再执行，避免误触发。
- 国产家电需先接入 HA（米家/涂鸦等有官方或社区集成），未接入的设备无法直接控制。
参考
- Home Assistant REST API: https://developers.home-assistant.io/docs/api/rest/
- 场景模板见
examples/scenes.json。
