homeassistant-config

Home Assistant 配置技能

创建并管理 Home Assistant YAML 配置文件，包括自动化、脚本、模板、蓝图以及文件组织。

斜杠命令

命令	描述
/ha-find-duplicates [path]	查找配置中重复的自动化和脚本

/ha-find-duplicates

扫描 Home Assistant 配置文件以查找：

• 完全重复项：触发器和操作完全相同的自动化/脚本
• 相似项：相似度达到 80% 以上的项（名称、实体、结构）
• 触发器冲突：多个自动化响应同一个触发器

用法：/ha-find-duplicates /path/to/config 或 /ha-find-duplicates 表示当前目录。

子 Agent

Agent	描述
ha-suggestions	针对自动化、场景和设备推荐的智能家居改进顾问

ha-suggestions

一个主动的智能家居顾问，会分析你的 Home Assistant 配置，并针对以下方面提供个性化建议：

• 新自动化：运动照明、存在检测、基于时间的例程、节能
• 新场景：电影之夜、早晨活力、晚餐时间、居家办公、派对模式
• 脚本改进：可复用的序列和参数化例程
• 设备推荐：用于增强你设置的传感器、开关和集成
• 优化：整合、触发器效率、模式使用、蓝图转换

该 Agent 会自动发现你的配置文件，按域（灯、传感器、气候等）清点实体，并生成带有完整、可直接使用的 YAML 代码的按优先级排序的建议。

验证脚本

本技能包含用于验证和分析 Home Assistant 配置的脚本。

YAML 验证器

验证 YAML 语法并检查常见的 HA 问题（制表符、未加引号的布尔值、已弃用的语法）：

python3 {baseDir}/scripts/validate_yaml.py /path/to/config.yaml
python3 {baseDir}/scripts/validate_yaml.py /path/to/config.yaml --strict

配置检查器

分析 HA 配置结构，查找实体，跟踪 include 和 secret：

python3 {baseDir}/scripts/check_config.py /path/to/config/directory
python3 {baseDir}/scripts/check_config.py /path/to/config.yaml --verbose

Lovelace 验证器

验证 Lovelace 仪表盘配置（YAML 和 JSON .storage 格式）：

python3 {baseDir}/scripts/lovelace_validator.py /path/to/ui-lovelace.yaml
python3 {baseDir}/scripts/lovelace_validator.py /path/to/.storage/lovelace --strict

功能：

• 验证卡片类型（内置和自定义）
• 检查实体 ID 格式
• 验证操作（tap_action、hold_action）
• 检测自定义卡片（HACS）
• 同时支持 YAML 和 JSON 存储格式

重复项查找器

在配置文件中查找重复和相似的自动化/脚本：

python3 {baseDir}/scripts/find_duplicates.py /path/to/config/directory
python3 {baseDir}/scripts/find_duplicates.py /path/to/automations.yaml --verbose

功能：

• 完全重复项检测（触发器和操作完全相同）
• 相似项检测（名称、实体、结构的 80% 阈值）
• 触发器冲突检测（多个自动化使用同一触发器）
• 自动化之间的实体重叠分析
• 带详细发现的 JSON 输出

保存前验证钩子

本插件包含一个保存前钩子，可在保存前自动验证 YAML 文件。它会检查：

• 制表符（HA 要求使用空格）
• 基本的 YAML 语法错误

该钩子会在对 .yaml 和 .yml 文件执行 Write/Edit 操作时自动运行。

YAML 要求

• 缩进：每级 2 个空格（绝不使用制表符）
• 字符串：为类似布尔值的值加引号（"on"、"off"、"yes"、"no"）
• 列表：使用 - 前缀并正确缩进
• 注释：使用 # 进行行内文档说明
• 关键术语：使用 action:（而非 service:）、triggers:（而非 trigger:）、actions:（序列中而非 action:）

文件组织

基本 Include

# configuration.yaml
automation: !include automations.yaml
script: !include scripts.yaml
sensor: !include sensors.yaml

目录 Include

# Merge all files in directory
automation: !include_dir_merge_list automations/
sensor: !include_dir_merge_list sensors/

Secrets 管理

# secrets.yaml
mqtt_password: "super_secret_password"
api_key: "your-api-key-here"

# configuration.yaml
mqtt:
  password: !secret mqtt_password

自动化（2024+ 语法）

基本结构

automation:
  - alias: "Descriptive Name"
    id: unique_automation_id
    description: "What this automation does"
    mode: single  # single, restart, queued, parallel
    triggers:
      - trigger: state
        entity_id: binary_sensor.motion
        to: "on"
    conditions:
      - condition: time
        after: "sunset"
    actions:
      - action: light.turn_on
        target:
          entity_id: light.living_room

常见触发器

状态触发器

triggers:
  - trigger: state
    entity_id: sensor.temperature
    from: "off"
    to: "on"
    for:
      minutes: 5

时间触发器

triggers:
  - trigger: time
    at: "07:00:00"

数值状态触发器

triggers:
  - trigger: numeric_state
    entity_id: sensor.temperature
    above: 25
    below: 30

太阳触发器

triggers:
  - trigger: sun
    event: sunset
    offset: "-00:30:00"

模板触发器

triggers:
  - trigger: template
    value_template: "{{ states('sensor.power') | float > 1000 }}"

日历触发器

triggers:
  - trigger: calendar
    entity_id: calendar.work
    event: start
    offset: "-00:15:00"  # 15 min before event

设备触发器

triggers:
  - trigger: device
    device_id: abc123
    domain: zwave_js
    type: event.value_notification.entry_control

事件触发器

triggers:
  - trigger: event
    event_type: mobile_app_notification_action
    event_data:
      action: "CONFIRM_ACTION"

触发器 ID（用于多触发器自动化）

triggers:
  - trigger: state
    id: "motion_detected"
    entity_id: binary_sensor.motion
    to: "on"
  - trigger: state
    id: "door_opened"
    entity_id: binary_sensor.door
    to: "on"
actions:
  - choose:
      - conditions:
          - condition: trigger
            id: "motion_detected"
        sequence:
          - action: light.turn_on
            target:
              entity_id: light.hallway

常见操作

服务调用

actions:
  - action: light.turn_on
    target:
      entity_id: light.bedroom
    data:
      brightness_pct: 50
      color_temp: 350

延迟

actions:
  - delay:
      seconds: 30

条件（选择）

actions:
  - choose:
      - conditions:
          - condition: state
            entity_id: sun.sun
            state: "below_horizon"
        sequence:
          - action: light.turn_on
            target:
              entity_id: light.porch
    default:
      - action: light.turn_off
        target:
          entity_id: light.porch

重复

actions:
  - repeat:
      count: 3
      sequence:
        - action: notify.mobile_app
          data:
            message: "Alert!"
        - delay:
            minutes: 1

If-Then-Else

actions:
  - if:
      - condition: state
        entity_id: sun.sun
        state: "below_horizon"
    then:
      - action: light.turn_on
        target:
          entity_id: light.porch
    else:
      - action: light.turn_off
        target:
          entity_id: light.porch

并行操作

actions:
  - parallel:
      - action: notify.person1
        data:
          message: "Alert sent simultaneously!"
      - action: notify.person2
        data:
          message: "Alert sent simultaneously!"
      - sequence:
          - action: light.turn_on
            target:
              entity_id: light.alarm
          - delay:
              seconds: 5
          - action: light.turn_off
            target:
              entity_id: light.alarm

等待触发

actions:
  - action: light.turn_on
    target:
      entity_id: light.porch
  - wait_for_trigger:
      - trigger: state
        entity_id: binary_sensor.motion
        to: "off"
    timeout:
      minutes: 10
    continue_on_timeout: true
  - action: light.turn_off
    target:
      entity_id: light.porch

响应变量（从操作中获取数据）

actions:
  - action: calendar.get_events
    target:
      entity_id: calendar.work
    data:
      duration:
        hours: 24
    response_variable: agenda
  - action: notify.mobile_app
    data:
      message: "You have {{ agenda['calendar.work'].events | count }} events today"

出错时继续

actions:
  - action: notify.unreliable_service
    data:
      message: "This might fail"
    continue_on_error: true
  - action: light.turn_on
    target:
      entity_id: light.bedroom

带响应停止

actions:
  - if:
      - condition: state
        entity_id: input_boolean.enabled
        state: "off"
    then:
      - stop: "Feature is disabled"
        error: true
  - action: script.do_something

脚本

script:
  morning_routine:
    alias: "Morning Routine"
    description: "Start the day"
    fields:
      brightness:
        description: "Light brightness"
        example: 80
        default: 100
        selector:
          number:
            min: 0
            max: 100
    sequence:
      - action: light.turn_on
        target:
          area_id: bedroom
        data:
          brightness_pct: "{{ brightness }}"
      - action: media_player.play_media
        target:
          entity_id: media_player.speaker
        data:
          media_content_id: "morning_news"
          media_content_type: "music"

Jinja2 模板

状态函数

# Get state
{{ states('sensor.temperature') }}

# Get attribute
{{ state_attr('climate.thermostat', 'current_temperature') }}

# Check if entity exists
{{ states.sensor.temperature is defined }}

过滤器与测试

# Convert types
{{ states('sensor.temp') | float(0) }}
{{ states('sensor.count') | int(0) }}

# Math operations
{{ states('sensor.power') | float * 0.15 | round(2) }}

# Date/time
{{ now().strftime('%H:%M') }}
{{ as_timestamp(now()) }}

模板传感器

template:
  - sensor:
      - name: "Total Power Usage"
        unit_of_measurement: "W"
        state: >
          {{ states('sensor.plug_1_power') | float(0) +
             states('sensor.plug_2_power') | float(0) }}
        availability: >
          {{ states('sensor.plug_1_power') not in ['unknown', 'unavailable'] }}

Lovelace 仪表板

启用 YAML 模式

# configuration.yaml
lovelace:
  mode: yaml

基本仪表板结构

# ui-lovelace.yaml
title: My Home
views:
  - title: Home
    path: home
    icon: mdi:home
    cards:
      - type: entities
        title: Living Room
        entities:
          - light.living_room
          - switch.fan

常见卡片类型

实体卡片

type: entities
title: Room Controls
state_color: true
entities:
  - entity: light.ceiling
    name: Ceiling Light
  - type: divider
  - entity: climate.thermostat

按钮卡片

type: button
entity: light.bedroom
name: Bedroom
icon: mdi:lightbulb
tap_action:
  action: toggle
hold_action:
  action: more-info

网格布局

type: grid
columns: 3
square: true
cards:
  - type: button
    entity: light.1
  - type: button
    entity: light.2
  - type: button
    entity: light.3

区域卡片

type: area
area: living_room
display_type: compact
navigation_path: /lovelace/living-room
sensor_classes:
  - temperature
  - humidity

条件卡片

type: conditional
conditions:
  - condition: state
    entity: person.john
    state: home
card:
  type: entities
  entities:
    - light.johns_room

卡片操作

tap_action:
  action: toggle           # Toggle entity
  # action: more-info      # Show details
  # action: navigate       # Go to view
  #   navigation_path: /lovelace/lights
  # action: call-service   # Call action
  #   service: light.turn_on
  #   target:
  #     entity_id: light.all

热门自定义卡片（通过 HACS）

Mushroom 卡片

type: custom:mushroom-light-card
entity: light.bedroom
show_brightness_control: true
use_light_color: true

按钮卡片（自定义）

type: custom:button-card
entity: light.bedroom
name: Bedroom
styles:
  card:
    - border-radius: 12px
state:
  - value: "on"
    styles:
      icon:
        - color: amber

验证工具

1. 开发者工具 > YAML：检查配置语法
2. 开发者工具 > 模板：测试 Jinja2 模板
3. 开发者工具 > 状态：验证实体状态
4. 日志：启用调试日志以进行故障排查

logger:
  default: info
  logs:
    homeassistant.components.automation: debug

常见问题

问题	解决方案
制表符	替换为 2 个空格
未加引号的布尔值	为 "on"、"off"、"yes"、"no" 加引号
模板错误	先在开发者工具中测试
找不到实体	检查 entity_id 拼写
自动化未触发	在跟踪中验证触发条件

蓝图

可复用、带有可配置输入的自动化模板：

blueprint:
  name: Motion-activated Light
  description: Turn on a light when motion is detected
  domain: automation
  input:
    motion_sensor:
      name: Motion Sensor
      selector:
        entity:
          filter:
            - domain: binary_sensor
              device_class: motion
    target_light:
      name: Light
      selector:
        target:
          entity:
            - domain: light
    delay_time:
      name: Delay
      default: 120
      selector:
        number:
          min: 0
          max: 3600
          unit_of_measurement: seconds

triggers:
  - trigger: state
    entity_id: !input motion_sensor
    to: "on"

actions:
  - action: light.turn_on
    target: !input target_light
  - wait_for_trigger:
      - trigger: state
        entity_id: !input motion_sensor
        to: "off"
        for:
          seconds: !input delay_time
  - action: light.turn_off
    target: !input target_light

参考文件

有关详细的模式和示例，请参阅：

• references/patterns.md - 常见自动化模式
• references/templates.md - 模板传感器示例
• references/lovelace.md - 仪表板卡片和布局
• references/troubleshooting.md - 错误解决方案
• references/best-practices.md - 优化技巧
• references/blueprints.md - 蓝图创建指南
• examples/ - 完整可用的配置