聊天机器人接入智能家居后，最重要的设计点是权限边界。自然语言控制虽然方便，但设备状态、服务调用和会话来源都需要被明确记录。
项目概览
结构上，main.py 处理 /ha 与 /ha_ping，home_assistant_control 下拆分客户端、配置、权限、实体目录、别名解析、自然语言路由、服务路由、审计和 trace。用途是让 AstrBot 通过 Home Assistant API 查询状态并控制受限设备。
应用场景包括私聊中查询设备状态、群聊中控制低危设备、为智能家居操作加上角色权限和审计记录。
实例与设备目录
插件支持配置 Home Assistant 实例，启动时拉取实体列表并构建设备目录。目录中保存实体 ID、显示名、域、可用服务和别名。用户输入自然语言时，解析层先匹配设备，再匹配动作，最后生成服务调用。
目录缓存让大部分查询可以在本地完成。实体刷新由命令或定时任务触发，避免每次消息都访问 Home Assistant。
权限与审计
权限模型按角色和会话来源控制。低危操作可以开放给普通角色，高危服务需要更高权限。每次服务调用都会记录目标实体、动作类型、结果状态和调用来源，便于后续追踪。
插件还提供运行期自检，包括实例连接、令牌状态、实体目录数量和最近一次调用结果。
实现原理是先把 Home Assistant 实体缓存成本地目录，再通过别名匹配和规则路由生成服务调用。规则无法覆盖时再进入 LLM 解释层，输出仍要经过权限 profile 和服务白名单检查。