homeassistant-config（家庭助理配置）

Home Assistant Configuration Skill

Create and manage Home Assistant YAML configuration files including automations, scripts, templates, blueprints, and file organization.

Slash Commands

/ha-find-duplicates

Scans Home Assistant configuration files to find:

• Exact duplicates: Automations/scripts with identical triggers and actions
• Similar items: Items with 80%+ similarity (name, entities, structure)
• Trigger conflicts: Multiple automations responding to the same trigger

Usage: /ha-find-duplicates /path/to/config or /ha-find-duplicates for current directory.

Subagents

ha-suggestions

A proactive smart home consultant that analyzes your Home Assistant configuration and provides personalized suggestions for:

• New Automations: Motion lighting, presence detection, time-based routines, energy saving
• New Scenes: Movie night, morning energy, dinner time, work from home, party mode
• Script Improvements: Reusable sequences and parameterized routines
• Device Recommendations: Sensors, switches, and integrations to enhance your setup
• Optimization: Consolidation, trigger efficiency, mode usage, blueprint conversion

The agent automatically discovers your configuration files, inventories entities by domain (lights, sensors, climate, etc.), and generates prioritized suggestions with complete, ready-to-use YAML code.

Validation Scripts

This skill includes scripts to validate and analyze Home Assistant configurations.

YAML Validator

Validates YAML syntax and checks for common HA issues (tabs, unquoted booleans, deprecated syntax):

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

Configuration Checker

Analyzes HA configuration structure, finds entities, tracks includes and secrets:

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

Lovelace Validator

Validates Lovelace dashboard configurations (YAML and JSON.storage format):

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

Features:

• Validates card types (built-in and custom)
• Checks entity ID formats
• Validates actions (tap_action, hold_action)
• Detects custom cards (HACS)
• Supports both YAML and JSON storage formats

Duplicate Finder

Finds duplicate and similar automations/scripts across configuration files:

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

Features:

• Exact duplicate detection (identical triggers + actions)
• Similar item detection (80% threshold for names, entities, structure)
• Trigger conflict detection (multiple automations on same trigger)
• Entity overlap analysis between automations
• JSON output with detailed findings

Pre-Save Validation Hook

This plugin includes a pre-save hook that automatically validates YAML files before saving. It checks for:

• Tab characters (HA requires spaces)
• Basic YAML syntax errors

The hook runs automatically on Write/Edit operations for .yaml and .yml files.

YAML Requirements

• Indentation: 2 spaces per level (never tabs)
• Strings: Quote boolean-like values ("on", "off", "yes", "no")
• Lists: Use - prefix with proper indentation
• Comments: Use # for inline documentation
• Key Terms: Use action: (not service:), triggers: (not trigger:), actions: (not action: for sequences)

File Organization

Basic Includes

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

Directory Includes

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

Secrets Management

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

# configuration.yaml
mqtt:
  password: !secret mqtt_password

Automations (2024+ Syntax)

Basic Structure

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

Common Triggers

State Trigger

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

Time Trigger

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

Numeric State Trigger

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

Sun Trigger

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

Template Trigger

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

Calendar Trigger

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

Device Trigger

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

Event Trigger

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

Trigger IDs (for multi-trigger automations)

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

Common Actions

Service Call

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

Delay

actions:
  - delay:
      seconds: 30

Conditional (Choose)

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

Repeat

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

Parallel Actions

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

Wait for Trigger

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

Response Variables (get data from actions)

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"

Continue on Error

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

Stop with Response

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

Scripts

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 Templates

State Functions

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

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

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

Filters and Tests

# 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 Sensors

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 Dashboards

Enable YAML Mode

# configuration.yaml
lovelace:
  mode: yaml

Basic Dashboard Structure

# 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

Common Card Types

Entities Card

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

Button Card

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

Grid Layout

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

Area Card

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

Conditional Card

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

Card Actions

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

Popular Custom Cards (via HACS)

Mushroom Cards

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

Button Card (Custom)

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

Validation Tools

1. Developer Tools > YAML: Check configuration syntax
2. Developer Tools > Template: Test Jinja2 templates
3. Developer Tools > States: Verify entity states
4. Logs: Enable debug logging for troubleshooting

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

Common Issues

Blueprints

Reusable automation templates with configurable inputs:

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

Reference Files

For detailed patterns and examples, see:

• references/patterns.md - Common automation patterns
• references/templates.md - Template sensor examples
• references/lovelace.md - Dashboard cards and layouts
• references/troubleshooting.md - Error solutions
• references/best-practices.md - Optimization tips
• references/blueprints.md - Blueprint creation guide
• examples/ - Complete working configurations