home-assistant

Home Assistant 助手

概述

此技能提供用于处理 Home Assistant 安装实例的工具和工作流。它支持查询实时 HA 实例中的实体、服务和配置数据，调试自动化，并为自动化和仪表盘生成 YAML 配置。

主要功能：

• 查询实时 HA 安装实例中的实体、状态和服务
• 搜索相似实体，以供参考
• 检查自动化的状态和执行历史
• 生成可复制并粘贴到 HA 中的 YAML 配置
• 查找用户设置中的真实示例，为新配置提供参考

核心工作流

处理 Home Assistant 相关任务时，请遵循以下通用流程：

1. 了解需求 —— 用户想要实现什么？
2. 发现现有实体 —— 使用脚本查找其设置中的相关实体
3. 查找相似示例 —— 搜索功能相似的现有自动化或实体
4. 生成 YAML —— 创建格式正确、可直接复制到 HA 中的 YAML
5. 说明配置 —— 描述 YAML 的作用以及安装方法

可用脚本

所有脚本都需要设置 HA_TOKEN 环境变量，其中包含 Home Assistant 长期有效的访问令牌。HA 实例可通过 http://homeassistant.local:8123 访问。

重要： 所有脚本现在都使用 uv，并采用内联 PEP 723 依赖声明和 homeassistant-api 库，以确保代码一致且易于维护。uv 会在首次运行时自动安装依赖项。

实体发现

ha_get_entities.py [domain]

获取所有实体，也可以按域筛选。

用法：

uv run scripts/ha_get_entities.py           # All entities
uv run scripts/ha_get_entities.py light     # Just lights
uv run scripts/ha_get_entities.py sensor    # Just sensors

适用场景： 发现有哪些实体可用，尤其是在构建新的自动化时。

ha_get_state.py <entity_id>

获取特定实体的当前状态和属性。

用法：

uv run scripts/ha_get_state.py light.living_room

适用场景： 检查当前状态、可用属性，或确认实体是否存在。

ha_search_similar_entities.py <pattern>

搜索 entity_id 或 friendly_name 中符合指定模式的实体。

用法：

uv run scripts/ha_search_similar_entities.py "bedroom"
uv run scripts/ha_search_similar_entities.py "motion"
uv run scripts/ha_search_similar_entities.py "temperature"

适用场景： 查找与用户想要自动化的内容相关的实体。在创建新的自动化之前查找示例时，这尤其有用。

自动化管理

ha_get_automations.py [search_term]

获取所有自动化，也可以按搜索词筛选。

用法：

uv run scripts/ha_get_automations.py              # All automations
uv run scripts/ha_get_automations.py motion       # Automations with 'motion'
uv run scripts/ha_get_automations.py light        # Automations with 'light'

适用场景： 查找与用户想要创建的自动化相似的现有自动化，并将其用作模板。

自动化跟踪分析

ha_list_traces.py [automation_id]

列出自动化执行跟踪记录，以及时间戳和状态。

用法：

uv run scripts/ha_list_traces.py                    # All traces
uv run scripts/ha_list_traces.py 1761430536701      # Specific automation traces (using numeric ID)

重要： 使用数字自动化 ID（例如 1761430536701），而非完整的 entity_id（例如 automation.bedroom_light）。可以在 ha_get_automations.py 的输出中查看自动化属性里的数字 ID。

适用场景： 查看自动化最近的运行记录、状态和时间信息。可据此确定需要进一步调查的运行 ID。

输出包括：

• 运行 ID（用于 ha_get_trace.py）
• 时间戳
• 执行状态（已停止、运行中等）
• 脚本执行状态（已完成、failed_single、failed_conditions 等）
• 上次执行的步骤
• 错误信息（如有）

ha_get_trace.py <automation_id> <run_id>

获取特定自动化运行记录的详细逐步跟踪信息。

用法：

uv run scripts/ha_get_trace.py 1761430536701 1ceef6b2b6f63a8745eb5dba3fe12f71

重要： 使用数字自动化 ID（例如 1761430536701），而非完整的 entity_id。

适用场景： 调试特定的自动化运行记录。显示完整的执行路径，包括：

• 触发器详情
• 条件评估（通过／未通过）
• 已执行的操作
• 各步骤中的变量
• 时间信息
• 失败时的错误详情

提示： 从 ha_list_traces.py 的输出中获取 run_id。

ha_trace_summary.py <automation_id>

获取某个自动化执行历史的汇总统计数据。

用法：

uv run scripts/ha_trace_summary.py 1761430536701

重要： 使用数字自动化 ID（例如 1761430536701），而非完整的 entity_id。

使用时机： 了解自动化长期运行的可靠性和性能。

输出包括：

• 运行总次数
• 成功/失败次数及比例
• 平均/最短/最长执行时间
• 常见错误模式
• 执行完成位置的分布

服务发现

ha_get_services.py [domain]

获取所有可用服务及其描述和字段信息。

用法：

uv run scripts/ha_get_services.py              # All services
uv run scripts/ha_get_services.py light        # Just light services
uv run scripts/ha_get_services.py climate      # Just climate services

使用时机： 发现可用的服务及其接受的参数。

配置

ha_get_config.py

获取 Home Assistant 配置，包括版本、位置和组件。

用法：

uv run scripts/ha_get_config.py

使用时机： 了解 HA 设置、可用集成或系统信息。

ha_get_config_entries.py [domain]

获取 Home Assistant 配置条目，可按 domain 筛选。对于需要 config_entry_id 的服务（例如 telegram_bot.send_message），这项操作至关重要。

用法：

uv run scripts/ha_get_config_entries.py              # All config entries
uv run scripts/ha_get_config_entries.py telegram_bot # Just Telegram bots
uv run scripts/ha_get_config_entries.py mqtt         # Just MQTT entries

使用时机： 需要获取 Telegram 通知等服务所需的 config_entry_id，或了解已配置哪些集成时。

服务调用

ha_call_service.py <domain> <service> <json_data>

调用 Home Assistant 服务（请谨慎使用）。

用法：

uv run scripts/ha_call_service.py light turn_on '{"entity_id": "light.living_room"}'

使用时机： 很少使用。通常仅用于测试，或用户明确要求控制某项内容时。

典型工作流

创建新的自动化

1. 了解目标 - 询问触发条件、条件和操作方面的细节
2. 查找相似实体 - 使用 ha_search_similar_entities.py 查找相关实体
3. 搜索相似自动化 - 使用 ha_get_automations.py 和搜索词查找示例
4. 查看现有自动化 - 如果存在相似自动化，检查其结构
5. 生成 YAML - 创建格式规范的 YAML，其中包含：
   • 描述性别名
   • 清晰的描述
   • 合适的触发条件
   • 相关条件
   • 必要操作
   • 恰当的模式（single、restart、queued、parallel）
6. 提供可直接复制粘贴的 YAML - 格式应便于复制到 HA 配置中
7. 说明 - 描述自动化的功能以及如何将其添加到 HA

调试自动化

1. 检查自动化状态 - 使用 uv run scripts/ha_get_state.py automation.automation_name 检查：
   • 当前状态（on/off）
   • 上次触发时间
   • 当前执行次数
   • 自动化模式
2. 查看执行历史 - 使用轨迹分析工具（使用属性中的数字自动化 ID）：
   • uv run scripts/ha_trace_summary.py <numeric_id> - 获取成功率和常见问题
   • uv run scripts/ha_list_traces.py <numeric_id> - 查看最近的运行记录
   • uv run scripts/ha_get_trace.py <numeric_id> <run_id> - 查看逐步的详细轨迹
3. 分析轨迹数据 - 检查：
   • 触发了哪个触发条件
   • 条件是否通过
   • 哪些操作成功执行
   • 自动化停止或出错的位置
   • 每个步骤中的变量值
4. 检查相关实体 - 使用 uv run scripts/ha_get_state.py 确认触发实体处于预期状态
5. 查看自动化配置 - 使用 uv run scripts/ha_get_automations.py 查看完整的自动化详情
6. 确定问题 - 根据轨迹数据、状态信息和配置检查结果定位问题
7. 提出修复方案 - 提供修正后的 YAML 或配置更改

基于轨迹的调试工作流：

# Step 1: Get the automation details to find the numeric ID
uv run scripts/ha_get_automations.py problem_automation

# Step 2: Check if automation has been running and get stats (use numeric ID from step 1)
uv run scripts/ha_trace_summary.py 1761430536701

# Step 3: List recent runs to find failing ones (use numeric ID)
uv run scripts/ha_list_traces.py 1761430536701

# Step 4: Get detailed trace for a specific failed run (use numeric ID)
uv run scripts/ha_get_trace.py 1761430536701 <run_id_from_step_3>

# Step 5: Examine the trace to see exactly where and why it failed

修改仪表盘

1. 了解预期更改 - 仪表盘应该显示什么？
2. 查找相关实体 - 使用实体发现脚本
3. 生成 Lovelace YAML - 创建仪表盘卡片配置
4. 提供可复制粘贴的 YAML - 用户将手动添加到自己的仪表盘
5. 说明卡片配置 - 描述选项和自定义方式

探索实体状态

1. 使用搜索或按域筛选 - 查找感兴趣的实体
2. 检查具体状态 - 获取详细的状态信息
3. 报告发现结果 - 清晰地呈现相关信息

发送 Telegram 通知

Telegram 通知需要使用 telegram_bot.send_message 服务，并附带 config_entry_id 参数（而不是 notify 服务模式）。

工作流程：

1. 获取 Telegram 机器人配置项 ID - 使用 uv run scripts/ha_get_config_entries.py telegram_bot 查找配置项 ID
2. 使用 telegram_bot.send_message 服务 - 在操作数据中包含 config_entry_id

Telegram 通知自动化示例：

alias: Example Telegram Alert
description: Send a Telegram notification when something happens
triggers:
  - entity_id: binary_sensor.front_door
    to: "on"
    trigger: state
conditions: []
actions:
  - action: telegram_bot.send_message
    data:
      message: "Front door opened at {{ now().strftime('%I:%M %p') }}"
      config_entry_id: 01JZE11D7Y6B7C3WCARWVZRYNH  # Get this from ha_get_config_entries.py
mode: single

注意：config_entry_id 是针对你的 Telegram 机器人配置的专属 ID。请始终使用 uv run scripts/ha_get_config_entries.py telegram_bot 获取适用于你设置的正确 ID。

重要说明

YAML 输出格式

生成 YAML 配置时，务必：

• 使用正确的 YAML 格式，并缩进 2 个空格
• 在适当位置添加有用的注释
• 提供描述性别名和说明
• 使用适当的触发平台（state、time、numeric_state 等）
• 包含模式设置（single、restart、queued、parallel）
• 设置格式，方便复制粘贴到 HA 中

需要手动安装

用户必须手动将生成的 YAML 复制/粘贴到 Home Assistant 中。请明确说明这一点并提供操作说明：

• 对于自动化：Configuration → Automations & Scenes → Add Automation → Edit in YAML
• 对于仪表盘：Dashboard → Edit Dashboard → Raw Configuration Editor
• 对于 configuration.yaml 的添加内容：编辑文件并重启 HA

用于截图的浏览器自动化

如果用户要求提供仪表盘截图或想查看当前 UI 状态，可以使用 Playwright 浏览器自动化工具导航到 HA 实例并截取屏幕截图。用户需要自行处理身份验证。

服务调用

调用会更改状态的服务时请谨慎。通常只有在用户明确要求或用于测试时才这样做。

实体命名

所有实体都遵循 domain.object_id 模式，常见域包括：

• light - 灯
• switch - 开关
• sensor - 传感器（只读）
• binary_sensor - 二进制传感器（开/关）
• climate - 恒温器
• automation - 自动化
• script - 脚本
• input_boolean、input_number、input_select、input_text、input_datetime - 辅助实体
• person - 人员
• device_tracker - 设备追踪器
• camera - 摄像头
• media_player - 媒体播放器
• cover - 窗帘（百叶窗、车库门）
• fan - 风扇
• lock - 锁

常见触发平台

• state - 实体状态变化
• numeric_state - 数值跨越阈值
• sun - 日出/日落
• time - 指定时间
• time_pattern - 时间模式（每 N 分钟）
• event - HA 事件触发
• webhook - Webhook 触发器
• zone - 进入/离开区域
• device - 特定设备的触发器

常见条件平台

• state - 实体状态等于某个值
• numeric_state - 数值比较
• time - 时间范围
• sun - 日出/日落之前或之后
• zone - 人员位于区域内
• template - 模板求值

自动化模式

• single - 如果自动化已在运行，则不启动新的运行
• restart - 如果自动化在运行时被触发，则重新启动
• queued - 如果自动化已在运行，则将运行排入队列
• parallel - 允许多个运行同时进行