技能使用指南

home-assistant（HomeAssistant助手）Skill 是什么？智能家居能靠它吗？

HomeAssistant助手Skill 能读取你真实的 Home Assistant 实例，查询实体与服务、生成可粘贴的自动化与仪表板 YAML，并借助执行跟踪快速定位自动化不触发的原因。本文详解安装前提、HA_TOKEN 配置、常用脚本用法、竞品对比与典型场景，助你少走弯路。

HomeAssistant助手Skillhome-assistant
8 个章节 约 16 分钟阅读 AI 智能生成

HomeAssistant助手Skill：让 AI 帮你写 YAML、查实体、调自动化

  • 一句话定位：这是一款面向 Home Assistant（以下简称 HA）的智能家居配置助手技能，通过实时查询 HA 实例的真实数据，帮你生成可直接粘贴使用的自动化与仪表板 YAML，并支持自动化运行跟踪与故障排查。
  • 三个核心动作：先“查真实数据”（实体、状态、服务、配置条目），再“找相似示例”（现有自动化），最后“生成可复制的 YAML”。
  • 强项在调试：内置执行跟踪分析能力，可以看到某次自动化运行到哪一步、条件是否通过、错在哪里。
  • 使用门槛低：所有脚本通过 uv 自动安装依赖，只需准备一个 HA 长寿命访问令牌（HA_TOKEN）。
  • 需要注意：生成的 YAML 需要你手动复制粘贴到 HA 中保存，技能不会自行写入你的配置。

1. 该技能叫什么？如何一键安装 AI 技能提升开发效率？

技能基本信息

项目 内容
中文名 HomeAssistant助手Skill
英文名 home-assistant
技能ID 11960
适用对象 Home Assistant 用户、智能家居爱好者、自建家庭自动化的开发者

它解决什么问题？

Home Assistant 功能强大，但配置体验对普通用户并不友好：实体 ID 记不住、YAML 缩进写错就整段失效、自动化不触发时只能靠“猜”、仪表板卡片配置项复杂。传统做法是在官方文档、社区论坛和浏览器标签页之间反复切换，一边抄示例一边改实体名。

这个技能把流程反过来：先读取你家里真实的 HA 实例数据（有哪些实体、当前状态如何、有哪些可用服务），再基于真实数据生成配置，避免“示例里的实体名在你家根本不存在”的尴尬。

一键安装的思路与步骤

  1. 确认安装前提：你需要有一个可访问的 Home Assistant 实例（技能默认面向 http://homeassistant.local:8123），并在 HA 中生成一个长寿命访问令牌（Long-Lived Access Token）。
  2. 在技能入口中安装：在支持 AI 技能（Skill）的客户端或平台中，通过技能库/技能市场搜索英文名 home-assistant 或技能ID 11960 完成安装。具体安装入口、命令与版本要求以官方说明为准。
  3. 配置访问凭证：技能的所有脚本都依赖环境变量 HA_TOKEN，其值为你的 HA 长寿命访问令牌。令牌属于敏感信息，建议仅在可信环境中配置，不要提交到代码仓库。
  4. 准备运行环境：脚本使用 uv 运行，并采用内联 PEP 723 依赖声明与 homeassistant-api 库，依赖项在首次运行时由 uv 自动安装，无需手动 pip install。
  5. 验证是否生效：安装并配置完成后，运行配置查询脚本，如果能返回 HA 的版本、安装位置与已加载组件信息，说明技能已成功连通你的实例：
uv run scripts/ha_get_config.py

如果返回认证失败，优先检查 HA_TOKEN 是否正确、令牌是否被撤销、HA 地址是否可达。任何与具体安装命令、账号或计费相关的细节，请以官方说明为准。

2. 该技能的主要功能和特点

技能的可用能力围绕一组脚本展开，可分为四大类：

（1）实体与状态发现

  • ha_get_entities.py [domain]：按域（如 light、sensor）检索全部实体，快速摸清家里到底有哪些设备。
  • ha_get_state.py <entity_id>：获取单个实体的当前状态与全部属性，例如确认 light.living_room 此刻是开是关、亮度多少。
  • ha_search_similar_entities.py <pattern>：按 entity_id 或友好名称模糊搜索，比如搜 bedroom、motion、temperature，用来定位“卧室那个传感器到底叫什么”。

（2）自动化管理与执行跟踪

  • ha_get_automations.py [search_term]：列出全部自动化，可按关键词过滤，用于找“和我想要的类似的现成自动化”当模板。
  • ha_list_traces.py [automation_id]：列出自动化执行跟踪，包含运行ID、时间戳、执行状态、脚本执行状态、最后执行的步骤与错误信息。
  • ha_get_trace.py <automation_id> <run_id>：查看某一次运行的逐步详情，包括触发器、条件评估（通过/失败）、执行的动作、每一步的变量与耗时。
  • ha_trace_summary.py <automation_id>：输出聚合统计，包含总运行次数、成功/失败计数与成功率、平均/最小/最大执行时间、常见错误模式。

（3）服务与配置查询

  • ha_get_services.py [domain]：查询可用服务及其字段定义，避免写错服务名或参数。
  • ha_get_config.py：读取 HA 版本、位置和组件信息。
  • ha_get_config_entries.py [domain]：查询配置条目，对需要 config_entry_id 的服务（如 telegram_bot.send_message）尤其关键。

（4）服务调用与界面查看

  • ha_call_service.py <domain> <service> <json_data>：调用 HA 服务，用于测试或用户明确要求控制设备时。
  • 当用户需要仪表板截图或查看当前界面状态时，可借助 Playwright 浏览器自动化导航到 HA 实例截图，身份验证需用户自行处理。

和“普通 AI 写 YAML”相比强在哪？

普通 AI 只能凭记忆生成一段“看起来对”的 YAML，实体名往往是编的；这个技能的差异在于数据闭环：实体来自你的实例、示例来自你已有的自动化、调试依据来自真实的执行跟踪。同时它严格遵循 YAML 输出规范——2 空格缩进、描述性别名与 description、合适的触发平台（state、numeric_state、sun、time、time_pattern、event、webhook、zone、device）、明确的运行模式（single、restart、queued、parallel），并格式化为方便复制粘贴的形态。

3. 如何使用该技能？

步骤一：明确需求

先想清楚触发器、条件、动作三件事。例如：“前门被打开时，如果家里没人，就开客厅灯并发送 Telegram 通知。”

步骤二：发现相关实体

不要凭记忆写实体名，先查：

uv run scripts/ha_search_similar_entities.py "front_door"
uv run scripts/ha_get_state.py binary_sensor.front_door

输出会告诉你实体的真实状态与属性，确认它是否是你要的那个门磁。

步骤三：找同类示例

uv run scripts/ha_get_automations.py door

如果存在相似自动化，可以参照它的结构和命名习惯，减少风格不一致。

步骤四：生成 YAML

技能会输出带注释、缩进规范、可直接复制的配置。例如（含 Telegram 通知的自动化示例）：

alias: 前门开启提醒
description: 当某事发生时发送Telegram通知
triggers:
  - entity_id: binary_sensor.front_door
    to: "on"
    trigger: state
conditions: []
actions:
  - action: telegram_bot.send_message
    data:
      message: "前门在{{ now().strftime('%I:%M %p') }}打开"
      config_entry_id: 01JZE11D7Y6B7C3WCARWVZRYNH
mode: single

其中 config_entry_id 必须来自你自己的环境：

uv run scripts/ha_get_config_entries.py telegram_bot

步骤五：手动安装到 HA

技能不会替你写入配置，需要你复制粘贴：

  • 自动化：配置 → 自动化与场景 → 添加自动化 → YAML 编辑
  • 仪表板：仪表板 → 编辑仪表板 → 原始配置编辑器
  • configuration.yaml 相关：编辑文件后重启 HA

步骤六：出问题时调试

uv run scripts/ha_get_automations.py problem_automation
uv run scripts/ha_trace_summary.py 1761430536701
uv run scripts/ha_list_traces.py 1761430536701
uv run scripts/ha_get_trace.py 1761430536701 <run_id>

注意：跟踪相关脚本必须使用数字自动化ID（如 1761430536701），而不是 automation.bedroom_light 这类实体ID；数字ID可从 ha_get_automations.py 的输出属性中找到。

4. 同类型竞品对比分析

方案名称 定位 核心功能 安装/使用门槛 适用场景 优势与不足
HomeAssistant助手Skill（home-assistant） AI 驱动的 HA 配置与调试助手 实时查询实体/服务/配置条目、生成 YAML、执行跟踪分析、服务调用 需 HA 实例 + 长寿命令牌 + uv 环境，安装入口以官方说明为准 写自动化、改仪表板、排查不触发的自动化 优势：基于真实数据生成、有调试闭环；不足：YAML 需手动粘贴，依赖令牌配置
HA 内置自动化编辑器 官方图形化配置界面 可视化添加触发器/条件/动作 无需额外安装，HA 自带 简单自动化、可视化调整 优势：无需外部工具、即时生效；不足：复杂逻辑表达受限，无 AI 辅助与跟踪解读
Node-RED 可视化流程编排 拖拽节点、复杂流程与逻辑分支 需额外安装加载项并学习节点概念 复杂多分支联动、数据处理 优势：逻辑表达强；不足：学习成本高，与纯 YAML 自动化生态不同
通用 AI 对话工具直接写 YAML 通用大模型 生成 YAML 文本 零配置 简单脚本草稿 优势：上手快；不足：实体名易编造，无法读取你的实例数据，也难以解读执行跟踪

选择建议：如果你只是想快速拼一个简单自动化，内置编辑器足够；如果你需要复杂流程编排，可考虑 Node-RED；而当你面对的是“实体名记不住 + 自动化不触发 + 想把调试过程说清楚”的组合问题，这个技能的价值最明显。

5. 该技能的典型应用场景与实际体验情况

场景一：新手第一次写自动化

角色：刚装好 HA 的家庭用户。痛点：不知道实体叫什么、YAML 缩进总是错。使用方式：先用 ha_search_similar_entities.py 搜出真实实体，再让技能生成带注释的 YAML，复制到 YAML 编辑器保存。体验：上手难度低，最大价值是把“猜实体名”这一步彻底消除；注意生成的 YAML 仍需手动粘贴，技能不会自动写入。

场景二：老手排查“自动化不触发”

角色：已有几十条自动化的进阶用户。痛点：日志看不出条件在哪一步失败。使用方式：按“取数字ID → 看统计 → 列最近跟踪 → 拉取失败运行的详细跟踪”的顺序操作，直接定位是哪一步条件评估失败。体验：这是该技能区别于普通 AI 写 YAML 的核心体验，ha_trace_summary.py 的成功率与常见错误模式对判断“偶发失败还是配置错误”很有帮助。

场景三：改造仪表板

角色：想让首页更直观的用户。痛点：Lovelace 卡片配置项繁杂。使用方式：先查相关实体与当前状态，再生成卡片 YAML，粘贴到“原始配置编辑器”。体验：生成的配置带注释便于二次修改；如需看当前界面效果，可借助浏览器自动化截图，但需用户自行完成登录验证。

场景四：配置 Telegram 通知

角色：想让 HA 主动推送消息的用户。痛点：telegram_bot.send_message 需要 config_entry_id，且不能套用旧版 notify 写法。使用方式：先用 ha_get_config_entries.py telegram_bot 取到条目ID，再写进动作数据。体验：这一步如果没有工具辅助很容易卡住，脚本查询把不确定性降到了最低。

注意事项：调用会改变状态的服务（ha_call_service.py）要谨慎，通常只在测试或用户明确要求时使用；令牌属于高敏感凭证，注意保管。

6. 该技能能为用户带来的价值

  • 效率提升：把“翻文档 → 抄示例 → 改名 → 试错”的循环压缩为“查真实实体 → 生成 → 粘贴”三步，写一条中等复杂度自动化的时间通常从反复试错降到一次成型。
  • 门槛降低：不熟悉 YAML 语法、触发器平台和运行模式含义的用户，也能拿到结构规范、带注释的配置，边用边学。
  • 调试可量化：ha_trace_summary.py 提供成功率、执行耗时区间与常见错误模式，让“偶尔不灵”的自动化从玄学问题变成可度量的问题。
  • 长期价值：技能鼓励“先找相似示例再改造”的工作方式，你的历史自动化会成为新配置的模板库，配置风格逐渐统一，后续维护成本持续下降。

7. 常见问题 FAQ

Q1：这个技能怎么安装？需要准备什么？ 在支持 AI 技能的客户端或平台中搜索英文名 home-assistant 或技能ID 11960 安装，具体入口与命令以官方说明为准。使用前需准备可访问的 HA 实例和长寿命访问令牌，并配置环境变量 HA_TOKEN，脚本通过 uv 运行并自动安装依赖。

Q2：它会自动帮我修改 Home Assistant 里的配置吗？ 不会。技能生成 YAML 后需要你手动复制粘贴：自动化在“配置 → 自动化与场景 → 添加自动化 → YAML 编辑”中粘贴，仪表板在“原始配置编辑器”中粘贴，涉及 configuration.yaml 的改动需编辑文件并重启 HA。

Q3：为什么调试时必须用数字ID？ ha_list_traces.py、ha_get_trace.py、ha_trace_summary.py 都要求数字自动化ID（如 1761430536701），不能使用 automation.xxx 形式的实体ID。数字ID可以从 ha_get_automations.py 输出的自动化属性中找到，运行ID则从 ha_list_traces.py 的结果中获取。

Q4：它会直接控制我的设备吗？ 技能提供 ha_call_service.py 用于调用服务，但设计上是“谨慎使用”，通常仅在测试或你明确要求控制时才调用，不会随意改变设备状态。

Q5：和直接用通用 AI 写 YAML 相比，该怎么选？ 如果你只需要一段示例代码，通用 AI 也能给；但如果你希望配置里的实体名、服务参数、config_entry_id 都来自你自己的 HA 实例，并且出问题时有执行跟踪可以分析，那么这个技能更合适。是否收费及具体权益以官方说明为准。