Back to Details

ha-integration-knowledge

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

File Locations

文件位置

  • Integration code: 
    ./homeassistant/components/<integration_domain>/
  • Integration tests: 
    ./tests/components/<integration_domain>/
  • 集成代码：
    ./homeassistant/components/<integration_domain>/
  • 集成测试：
    ./tests/components/<integration_domain>/

General guidelines

通用准则

  • When looking for examples, prefer integrations with the platinum or gold quality scale level first.
  • Polling intervals are NOT user-configurable. Never add scan_interval, update_interval, or polling frequency options to config flows or config entries.
  • Do NOT allow users to set config entry names in config flows. Names are automatically generated or can be customized later in UI. Exception: helper integrations may allow custom names.
  • For entity actions and entity services, avoid requesting redundant defensive checks for fields already enforced by Home Assistant validation schemas and entity filters; only request extra guards when values bypass validation or are transformed unsafely.
  • When validation guarantees a key is present, prefer direct dictionary indexing (
    data["key"]
    ) over 
    .get("key")
    so invalid assumptions fail fast.
  • Integrations should be thin wrappers. Protocol parsing, device state machines, or other domain logic belong in a separate PyPI library, not in the integration itself. If unsure, ask before inlining.
  • Integrations should not implement fixes or workarounds for limitations in libraries. Instead, the library should be updated to fix the issue.
The following platforms have extra guidelines:
  • Diagnostics: 
    platform-diagnostics.md
     for diagnostic data collection
  • Repairs: 
    platform-repairs.md
     for user-actionable repair issues
  • 查找示例时，优先选择达到铂金或黄金质量等级的集成。
  • 轮询间隔不可由用户配置。切勿在配置流程或配置项中添加scan_interval、update_interval或轮询频率选项。
  • 不允许用户在配置流程中设置配置项名称。名称会自动生成，或之后可在UI中自定义。例外情况：辅助集成可允许自定义名称。
  • 对于实体操作和实体服务，避免对Home Assistant验证模式和实体过滤器已强制要求的字段进行冗余的防御性检查；仅当值绕过验证或被不安全转换时，才需要额外的防护。
  • 当验证保证某个键存在时，优先使用直接字典索引（
    data["key"]
    ）而非
    .get("key")
    ，这样错误的假设会快速暴露。
  • 集成应作为轻量包装器。协议解析、设备状态机或其他领域逻辑应放在独立的PyPI库中，而非集成本身。若不确定，先咨询再内联实现。
  • 集成不应为库的局限性实现修复或变通方法。相反，应更新库来解决问题。
以下平台有额外准则：
  • 诊断：
    platform-diagnostics.md
     用于诊断数据收集
  • 修复：
    platform-repairs.md
     用于用户可执行的修复问题

Entity platforms

实体平台

  • Ensure 
    async_added_to_hass()
    and 
    async_will_remove_from_hass()
    have symmetrical behavior. For example, if a subscription is created in 
    async_added_to_hass()
    , it should be unsubscribed in 
    async_will_remove_from_hass()
    . Also, if something is torn down in 
    async_will_remove_from_hass()
    , it should be set up in 
    async_added_to_hass()
    .
  • 确保
    async_added_to_hass()
    和
    async_will_remove_from_hass()
    的行为对称。例如，若在
    async_added_to_hass()
    中创建了订阅，则应在
    async_will_remove_from_hass()
    中取消订阅。同样，若在
    async_will_remove_from_hass()
    中销毁了某些内容，则应在
    async_added_to_hass()
    中进行设置。

Integration Quality Scale

集成质量等级

Template scale file: 
./script/scaffold/templates/integration/integration/quality_scale.yaml
模板等级文件：
./script/scaffold/templates/integration/integration/quality_scale.yaml

How Rules Apply

规则应用方式

  1. Check 
    manifest.json
    : Look for 
    "quality_scale"
    key to determine integration level
  2. Bronze Rules: Always required for any integration with quality scale
  3. Higher Tier Rules: Only apply if integration targets that tier or higher
  4. Rule Status: Check 
    quality_scale.yaml
    in integration folder for: 
    • done
      : Rule implemented
    • exempt
      : Rule doesn't apply (with reason in comment)
    • todo
      : Rule needs implementation
  1. 检查
    manifest.json
    ：查找
    "quality_scale"
    键以确定集成等级
  2. 青铜规则：所有带有质量等级的集成都必须遵守
  3. 更高等级规则：仅当集成目标为该等级或更高时才适用
  4. 规则状态：查看集成文件夹中的
    quality_scale.yaml
    以了解： 
    • done
      ：规则已实现
    • exempt
      ：规则不适用（注释中需说明原因）
    • todo
      ：规则需要实现

Testing Requirements

测试要求