用途:通过 Home Assistant 的 WebSocket API 以编程方式创建和更新 Lovelace 仪表板,适合将仪表板作为代码管理、批量生成多环境仪表板、部署前校验实体,以及动态生成卡片配置。
主要能力:连接并认证 WebSocket;用 lovelace/dashboards/list 查询现有仪表板;用 lovelace/dashboards/create 创建;用 lovelace/config/save 保存配置;用 lovelace/config 读取配置;用 system_log/list 检查 lovelace 错误;用 get_states 校验实体 ID 是否存在。
关键规则:仪表板的 url_path 必须包含连字符(kebab-case),例如 climate-control、mobile-app、energy-monitor;climate、mobile、energy 这类无连字符的写法是错误的。
使用方式:需 Python 的 websocket-client 与长期访问令牌。基本流程为:连接 WebSocket 并认证;查询仪表板是否已存在;不存在则创建(url_path 含连字符);保存配置;在 HA UI 与系统日志中验证。示例中通过 HA_URL 将 http 替换为 ws 并拼接 /api/websocket,发送 {"type": "auth", "access_token": HA_TOKEN} 完成认证。
适用场景:自动化创建与更新仪表板、构建仪表板生成器、部署前实体校验、以版本控制管理仪表板配置。
限制:若可用 HA UI 编辑器手动修改、或只需简单静态仪表板,则不必使用本技能;未创建长期访问令牌时无法使用。常见错误包括 url_path 缺少连字符、实体不存在、自定义卡片未通过 HACS 安装、JavaScript 配置错误。仪表板未出现在侧边栏时,检查 show_in_sidebar 是否为 True、url_path 是否含连字符并刷新浏览器。配置未保存时,检查认证是否成功、url_path 是否匹配、JSON 结构是否正确。实体校验可先获取全部实体再与仪表板中使用的实体比对。官方文档为 Home Assistant 的 Lovelace Dashboards 与 WebSocket API。