核心用法
Home Assistant Control 是一套基于 REST API 的智能家居控制工具，专为 Claude 等大语言模型设计。其核心工作流包含五步：解析用户请求 → 查询命名别名 → 验证实体存在 → 执行服务调用 → 确认并报告结果。
主要功能覆盖六大领域：
- 设备控制：开关灯、调节亮度/色温、温控设置
- 场景触发：激活预设场景、执行脚本、启动自动化
- 状态查询：读取传感器数据、查看设备当前状态
- 实体管理：通过
fill_entities_md.sh生成设备清单，ha_entity_find.sh模糊搜索实体 - 安全操作：
ha_safe_action.sh对高影响操作（门锁、警报、车库门）强制确认 - 环境适配：支持本地/公网双URL自动切换，HTTPS优先
技术实现依赖标准 Unix 工具链（bash/curl/jq），通过 Bearer Token 认证，所有脚本遵循"不打印令牌"的安全原则。
显著优点
1. 架构清晰：分层设计（env加载 → 通用调用 → 安全封装 → 自检测试），便于维护和扩展
2. 用户友好：naming-context.md 支持自然语言别名，降低语音/文本交互门槛
3. 安全设计：高影响域强制确认、--dry-run 模式、--yes 覆盖标志，平衡安全与自动化需求
4. 部署灵活：支持本地内网、公网HTTPS、环境变量文件三种配置模式
5. 可维护性：self_check.sh 前置验证依赖与连通性，减少运行时故障
潜在局限
- 依赖 Home Assistant 实例：无官方云服务，需用户自行部署并暴露API端点
- 网络可达性要求高：本地URL优先策略在混合网络环境下可能产生延迟
- 令牌管理负担：长期访问令牌一旦泄露风险较高，需外部文件隔离但增加了配置复杂度
- 无状态持久化：实体引用文件需手动刷新，实时性取决于用户更新频率
适合人群
- 已部署 Home Assistant 的智能家居用户
- 需要语音/自然语言控制家庭设备的场景
- 偏好本地优先、注重数据隐私的技术爱好者
- 愿意承担令牌安全配置责任的进阶用户
常规风险
- 令牌泄露风险：若
HA_ENV_FILE权限设置不当或意外提交至版本控制，可能导致未授权访问 - 误操作风险：自然语言解析可能产生歧义（如"打开灯"对应多个实体），虽有多重确认但仍需用户警觉
- 网络暴露风险：公网部署需配合HTTPS+反向代理，HTTP明文传输或端口暴露面过大可能招致攻击
- 服务中断影响：HA实例离线时所有控制失效，缺乏降级机制