核心用法
Home Assistant Skill 通过 REST API 实现对开源智能家居平台 Home Assistant 的完整控制。用户需配置 HA_URL 和 HA_TOKEN 环境变量后，即可通过 curl + jq 组合查询设备状态、执行服务调用。
设备发现：支持按实体域（domain）检索全部设备，或通过模板 API 查询区域（area）、楼层（floor）、标签（label）等层级结构，实现"客厅所有灯光"这类语义化操作。
控制操作：涵盖开关、灯光调光调色、场景激活、脚本执行、自动化启停、恒温器设置、窗帘/车库门控制、门锁、风扇、媒体播放、扫地机器人、安防面板等 25+ 设备类型。支持批量操作（单次调用多设备）和带参调用（亮度、颜色、变量等）。
高级功能：模板求值（Jinja2）、历史数据查询、日志追踪、日历事件获取、TTS 语音播报、人员位置追踪、天气预报等。
显著优点
- 生态兼容性极强：对接 Home Assistant——全球最大开源智能家居平台，支持数千种第三方设备集成
- 功能覆盖全面：从基础开关到复杂自动化编排，从单一设备到全屋场景，API 设计完整
- 安全机制健全：内置显式确认规则，对门锁、安防、车库门等敏感操作强制用户二次确认
- 查询能力丰富：模板 API 支持复杂过滤和计算，jq 配合可实现灵活的数据处理
- 批量与高效：支持多设备单次调用，减少网络往返
潜在缺点与局限性
- 网络依赖：必须能访问 HA 实例，无法离线使用
- 令牌管理：长期访问令牌需安全存储，泄露风险高
- 无状态缓存：每次查询实时请求，高频调用可能增加 HA 负载
- 错误处理粗放：依赖 HTTP 状态码和 jq 过滤，复杂错误场景需自行封装
- 无内置重试：网络波动时需外部实现重试逻辑
适合人群
- 已部署 Home Assistant 的智能家居用户
- 需要将自然语言指令转为设备控制的技术爱好者
- 希望通过 API 批量管理或监控家庭环境的自动化工程师
常规风险
| 风险类型 | 说明 |
|---------|------|
| 令牌泄露 | 长期令牌一旦泄露，攻击者可完全控制家庭设备 |
| 误操作 | 灯光误关影响小，门锁/车库门误操作涉及物理安全 |
| 网络暴露 | 若 HA 暴露公网且无额外防护，API 面临暴力破解风险 |
| 依赖单点 | HA 服务宕机时全部控制失效，需考虑降级方案 |
| 隐私数据 | 位置追踪、摄像头等数据流经 API，存在隐私泄露隐患 |
建议搭配 VPN 或内网访问，定期轮换令牌，敏感操作启用 HA 的二次验证机制。