核心用法
homeassistant-skill 是一款基于 Home Assistant REST API 的智能设备控制工具，提供对 25 种以上实体域（entity domains）的完整操作能力。用户需配置 HA_URL 和 HA_TOKEN 环境变量后，即可通过 curl + jq 组合查询设备状态、执行开关控制、触发场景与自动化等操作。
核心能力覆盖六大类别：
- 基础控制：灯光（亮度/颜色/色温）、开关、风扇、媒体的开关与调节
- 环境控制：恒温器模式与温度设定、窗帘/车库门开合百分比控制
- 安全设备：智能门锁、报警面板的加解锁与布防/撤防（强制确认机制）
- 自动化引擎：场景激活、脚本执行（支持变量传递）、自动化的启停与触发
- 信息查询：人员在场状态、设备位置追踪、天气预报、日历事件、传感器数据
- 系统功能：TTS 语音播报、移动推送通知、历史数据查询、模板计算
高级特性包括批量操作（单次调用控制多设备）、区域/楼层/标签维度的设备发现、Jinja2 模板服务端计算，以及完整的错误码处理机制。
显著优点
1. 生态完整性：原生支持 Home Assistant 的全部核心服务域，无需额外插件
2. 安全设计规范：明确区分高敏感操作（门锁、报警、车库门），强制要求用户二次确认
3. 查询能力强大：模板 API 支持复杂查询（如"找出厨房所有开启的灯光"）
4. 批量效率：单条命令可同时操控多设备，优于逐条调用的方案
5. 开源透明：MIT 许可证，代码完全可审计
潜在局限
- 网络依赖：要求 AI 运行环境与 Home Assistant 实例网络互通，无法离线使用
- 令牌安全风险：长期访问令牌（long-lived token）一旦泄露，权限等同于管理员
- 无内置状态缓存：频繁查询可能增加 HA 服务器负载
- 命令复杂度：复杂场景需手动拼接 JSON，对非技术用户门槛较高
- 无自动发现：实体 ID 需预先查询确认，不支持语音模糊匹配设备名称
适合人群
- 已部署 Home Assistant 的智能家居用户
- 需要通过 AI 助手实现语音/文本控制自动化工作流的技术用户
- 希望将智能家居操作集成到脚本或定时任务中的开发者
常规风险
| 风险类型 | 说明 | 缓释措施 |
|---------|------|---------|
| 未授权访问 | Token 泄露导致全屋设备被控 | 使用受限权限的专用令牌，定期轮换 |
| 误操作执行 | AI 错误解析意图导致设备异常状态 | 高敏感操作强制确认机制已内置 |
| 网络中间人 | HTTP 明文传输被窃听 | 建议使用 HTTPS + 证书验证 |
| 服务可用性 | HA 实例离线导致命令失败 | 调用前检查 HTTP 200 状态码 |
| 隐私泄露 | 人员位置、日历等敏感数据被查询 | 控制查询权限范围，避免日志留存敏感信息 |