⚡

HomeAssistant助手Skill home-assistant

这个技能用于辅助Home Assistant的安装、自动化创建、仪表板修改、实体状态检查、自动化调试和智能家居配置管理。提供工具查询实体、生成YAML配置、执行服务调用和调试工具，帮助用户高效管理智能家居系统。关键词：智能家居，Home Assistant，自动化，YAML配置，调试工具，家庭自动化，物联网，DevOps。

DevOps 0 次安装 0 次浏览 更新于 3/20/2026

名称: home-assistant 描述: 此技能应用于帮助Home Assistant设置，包括创建自动化、修改仪表板、检查实体状态、调试自动化和管理智能家居配置。适用于查询HA实体、生成YAML自动化/仪表板配置或故障排除HA问题。

Home Assistant助手

概述

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

核心能力：

  • 从实时HA安装查询实体、状态和服务
  • 搜索类似实体作为示例使用
  • 检查自动化状态和执行历史
  • 生成YAML配置，可直接复制粘贴到HA
  • 从用户设置中查找真实示例以指导新配置

核心工作流程

在帮助处理Home Assistant任务时，遵循以下通用方法：

  1. 理解需求 - 用户试图完成什么？
  2. 发现现有实体 - 使用脚本查找相关实体
  3. 查找类似示例 - 搜索执行类似操作的现有自动化或实体
  4. 生成YAML - 创建格式良好的YAML，可直接复制到HA
  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           # 所有实体
uv run scripts/ha_get_entities.py light     # 仅灯光
uv run scripts/ha_get_entities.py sensor    # 仅传感器

何时使用： 发现可用实体，特别是在构建新自动化时。

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              # 所有自动化
uv run scripts/ha_get_automations.py motion       # 包含'motion'的自动化
uv run scripts/ha_get_automations.py light        # 包含'light'的自动化

何时使用： 查找与用户想创建内容类似的现有自动化。用作模板。

自动化跟踪分析

ha_list_traces.py [automation_id]

列出自动化执行跟踪，包含时间戳和状态。

用法：

uv run scripts/ha_list_traces.py                    # 所有跟踪
uv run scripts/ha_list_traces.py 1761430536701      # 特定自动化跟踪（使用数字ID）

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

何时使用： 查看最近自动化运行、状态和时序。用于识别需要进一步调查的运行ID。

输出包括：

  • 运行ID（用于ha_get_trace.py）
  • 时间戳
  • 执行状态（停止、运行等）
  • 脚本执行状态（完成、失败_单一、失败_条件等）
  • 最后执行的步骤
  • 任何错误

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              # 所有服务
uv run scripts/ha_get_services.py light        # 仅灯光服务
uv run scripts/ha_get_services.py climate      # 仅气候服务

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

配置

ha_get_config.py

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

用法：

uv run scripts/ha_get_config.py

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

ha_get_config_entries.py [domain]

获取Home Assistant配置条目，可选按域过滤。这对于需要config_entry_id的服务至关重要，例如telegram_bot.send_message。

用法：

uv run scripts/ha_get_config_entries.py              # 所有配置条目
uv run scripts/ha_get_config_entries.py telegram_bot # 仅Telegram机器人
uv run scripts/ha_get_config_entries.py mqtt         # 仅MQTT条目

何时使用： 当需要获取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：
    • 描述性别名
    • 清晰描述
    • 适当的触发器
    • 相关条件
    • 必要操作
    • 适当模式（单一、重启、排队、并行）
  6. 提供复制粘贴YAML - 格式化为易于复制到HA配置
  7. 解释 - 描述自动化作用以及如何添加到HA

调试自动化

  1. 检查自动化状态 - 使用uv run scripts/ha_get_state.py automation.automation_name检查：
    • 当前状态（开/关）
    • 最后触发时间
    • 当前执行计数
    • 自动化模式
  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或配置更改

基于跟踪的调试工作流程：

# 步骤1：获取自动化详情以找到数字ID
uv run scripts/ha_get_automations.py problem_automation

# 步骤2：检查自动化是否运行并获取统计（使用步骤1的数字ID）
uv run scripts/ha_trace_summary.py 1761430536701

# 步骤3：列出最近运行以查找失败者（使用数字ID）
uv run scripts/ha_list_traces.py 1761430536701

# 步骤4：获取特定失败运行的详细跟踪（使用数字ID）
uv run scripts/ha_get_trace.py 1761430536701 <run_id_from_step_3>

# 步骤5：检查跟踪以查看失败的确切位置和原因

修改仪表板

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

探索实体状态

  1. 使用搜索或域过滤 - 查找感兴趣的实体
  2. 检查特定状态 - 获取详细状态信息
  3. 报告发现 - 清晰呈现相关信息

发送Telegram通知

Telegram通知需要使用telegram_bot.send_message服务和config_entry_id参数（而非notify服务模式）。

工作流程：

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

带Telegram通知的自动化示例：

alias: 示例Telegram警报
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  # 从ha_get_config_entries.py获取此ID
mode: single

注意： config_entry_id特定于您的Telegram机器人配置。始终使用uv run scripts/ha_get_config_entries.py telegram_bot获取设置的正确ID。

重要注意事项

YAML输出格式

生成YAML配置时，始终：

  • 使用正确YAML格式，2空格缩进
  • 包含适当注释
  • 提供描述性别名和描述
  • 使用适当触发器平台（状态、时间、numeric_state等）
  • 包含模式设置（单一、重启、排队、并行）
  • 格式化为易于复制粘贴到HA

需要手动安装

用户必须手动复制粘贴生成的YAML到Home Assistant。明确说明并提供指令：

  • 对于自动化：配置 → 自动化与场景 → 添加自动化 → YAML编辑
  • 对于仪表板：仪表板 → 编辑仪表板 → 原始配置编辑器
  • 对于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 - 允许多个同时运行