ha-validate

/ha:validate

验证 Home Assistant 配置文件中的 YAML 语法错误和常见问题。

何时使用此技能

在以下情况下使用此技能……	在以下情况下改用 ha-configuration……
检查 configuration.yaml 或 automations.yaml 中的 YAML 语法	编辑 configuration.yaml 以添加或更改集成
检查 secrets.yaml 中未定义的 !secret 引用	在 secrets.yaml 中添加新条目
查找 scripts.yaml 或 scenes.yaml 中的重复键	将配置重新整理到 packages 中
通过 Docker 或 HA OS 运行 hass --script check_config	编写模板传感器以及 recorder/logger 配置

上下文

• 配置路径：{{ path or '.' }}
• YAML 文件：!find . -name "*.yaml" -type f

验证步骤

1. YAML 语法验证

验证所有 YAML 文件的语法是否正确：

find {{ path or '.' }} -name "*.yaml" -type f -exec python3 -c "
import yaml
import sys
try:
    with open('{}', 'r') as f:
        yaml.safe_load(f)
    print('OK: {}')
except yaml.YAMLError as e:
    print('ERROR: {}')
    print(str(e)[:200])
    sys.exit(1)
" \; 2>&1 | head -50

2. 检查常见问题

检查未定义的密钥：

# Find secret references
grep -rh "!secret [a-z_]*" {{ path or '.' }} --include="*.yaml" 2>/dev/null | \
  sed 's/.*!secret //' | sort -u > /tmp/used_secrets.txt

# Check if secrets.yaml exists
if [ -f "{{ path or '.' }}/secrets.yaml" ]; then
  echo "secrets.yaml found"
  # List defined secrets
  grep "^[a-z_]*:" {{ path or '.' }}/secrets.yaml | sed 's/:.*//' | sort -u > /tmp/defined_secrets.txt
  echo "Undefined secrets:"
  comm -23 /tmp/used_secrets.txt /tmp/defined_secrets.txt
else
  echo "WARNING: secrets.yaml not found"
fi

检查重复键：

python3 -c "
import yaml
import sys
from collections import Counter

class DuplicateKeyChecker(yaml.SafeLoader):
    def construct_mapping(self, node, deep=False):
        keys = [k.value for k, v in node.value if isinstance(k, yaml.ScalarNode)]
        duplicates = [k for k, count in Counter(keys).items() if count > 1]
        if duplicates:
            print(f'Duplicate keys in {node.start_mark}: {duplicates}')
        return super().construct_mapping(node, deep)

for f in ['configuration.yaml', 'automations.yaml', 'scripts.yaml', 'scenes.yaml']:
    path = '{{ path or '.' }}/' + f
    try:
        with open(path) as file:
            yaml.load(file, Loader=DuplicateKeyChecker)
            print(f'OK: {f}')
    except FileNotFoundError:
        pass
    except yaml.YAMLError as e:
        print(f'ERROR in {f}: {e}')
" 2>&1

3. 基于 Docker 的完整验证（如果可用）

如果 Home Assistant 正在 Docker 中运行：

docker exec homeassistant hass --script check_config 2>&1 | head -100 || echo "Docker validation not available"

4. Home Assistant OS 验证（如果可用）

ha core check 2>&1 || echo "HA OS validation not available"

验证后

报告验证结果：

• 列出所有 YAML 语法错误及其文件和行号
• 列出所有未定义的密钥引用
• 列出所有重复键
• 为常见问题提供修复建议

常见修复方法

问题	修复方法
found undefined alias	在 secrets.yaml 中添加缺失的条目
could not determine a constructor	检查 YAML 缩进
duplicate key	删除或重命名重复键
expected <block end>	修正缩进对齐
mapping values are not allowed	在冒号后添加空格