集成质量量表#

import RuleOverview from './_includes/rule_overview.jsx'

集成质量等级是 Home Assistant 的一个框架，用于根据用户体验、功能、代码质量和开发人员经验对集成进行分级。 为了对此进行评分，该项目提出了一组等级，它们都有自己的含义。

#缩放层级

有 4 个等级:青铜、白银、黄金和白金。 要达到某一层，集成必须满足该层及以下层的所有规则。

这些层的定义如下。

#🥉 铜牌

青铜级是所有新集成的基准标准和要求。它满足代码质量、功能和用户体验的最低要求。它符合基本期望，并为用户与其设备和服务交互提供可靠的基础。

该文档提供了直接来自 Home Assistant 用户界面设置集成的指南。

从技术角度来看，此集成已经过审核，符合我们对所有新集成所要求的所有基线标准，包括用于设置集成的自动化测试。

青铜级具有以下特点:

• 可通过UI轻松设置。
• 源代码遵循基本编码标准和开发指南。
• 可以正确配置保护此集成的自动化测试。
• 提供基本的最终用户文档，足以让用户轻松逐步入门。

#🥈 银

银牌层建立在“铜牌”级别的基础上，通过提高集成的可靠性和稳健性，确保可靠的运行时体验。它确保集成正确处理错误，例如设备或服务身份验证失败时、处理离线设备以及其他错误。

这些集成的文档提供了有关使用此集成时 Home Assistant 中可用内容的信息，以及出现问题时的故障排除信息。

此集成有一个或多个活跃的代码所有者来帮助维护它，以确保这一级别的体验在现在和将来持续。

银级具有以下特点:

• 提供“青铜”所拥有的一切。
• 在各种条件下提供稳定的用户体验。
• 拥有一名或多名活跃的代码所有者来帮助维护集成。
• 正确、自动地从连接错误或离线设备中恢复，无需填充日志文件，也不会出现不必要的消息。
• 如果设备或服务认证失败，自动触发重新认证。
• 提供有关集成提供的内容的详细文档以及故障排除问题的说明。

#🥇 黄金

集成用户体验的黄金标准，为集成设备和服务提供广泛而全面的支持。黄金级集成旨在用户友好、功能齐全且可供更广泛的受众使用。

如果可能，系统会自动发现设备，以实现轻松的安装，并且可以直接从 Home Assistant 更新其硬件/软件。

所有提供的设备和实体均经过逻辑命名且完全可翻译，并且已正确分类并启用以供长期统计使用。

这些集成的文档非常广泛，主要针对最终用户，并且提供非技术消费者理解。除了提供有关集成的一般信息之外，该文档还提供了可能的示例示例、兼容设备列表、集成提供的描述实体列表以及集成集成提供的可用操作的描述广泛和使用示例。我们还强烈鼓励使用示例自动化、仪表板、可用的 Blueprints 以及其他外部资源的链接。

该集成提供了调试问题的方法，包括下载诊断信息和记录故障排除说明。如果需要，可以通过 UI 重新配置集成。

从技术角度来看，集成需要对其代码库进行完全自动化的测试覆盖，以确保现在和将来保持设定的集成质量。

所有在与 Home Assistant 一起工作的计划中拥有设备的集成至少都需要具有此层。

黄金级具有以下特点:

• 提供“银”所拥有的一切。
• 拥有集成所能提供的最佳最终用户体验；精简且直观。
• 可以自动发现，简化集成设置。
• 集成可以重新配置和调整。
• 支持翻译。
• 广泛的文档，针对非技术用户。
• 在可能的情况下，它支持通过Home Assistant更新设备的软件/固件。
• 该集成具有覆盖整个集成的自动化测试。
• 在与 Home Assistant 计划合作中提供设备的集成所需的级别。

#🏆 白金

白金级是集成可以达到的最高级别，是Home Assistant质量的缩影。它不仅提供最佳的用户体验，而且通过坚持最高标准、最高的代码质量以及良好优化的性能和效率来实现卓越的技术。

白金级具有以下特点:

• 提供“黄金”所拥有的一切。
• 所有源代码都遵循所有编码和 Home Assistant 集成标准和最佳实践，并且完全标注类型注释和标注的代码注释，以代码增量和维护性。
• 完全异步集成代码库确保高效运行。
• 实现高效的数据处理，减少网络和CPU使用率。

#跟踪实施的规则

致力于更高层或具有集成层的必须将 quality_scale.yaml 文件添加到其集成中。 该文件的目的是跟踪已实施的规则的进度，并跟踪豁免的规则和豁免的原因。 该文件的示例如下所示:

rules:
  config_flow: done
  docs_high_level_description:
    status: exempt
    comment: This integration does not connect to any device or service.

#调整集成层

Home Assistant 鼓励我们体验的贡献者将其集成提升到更高的级别，为我们的贡献者提供出色的编码体验，并为我们的用户提供最佳体验。

当集成达到特定层的最低要求时，贡献者可以打开拉取请求来调整集成的规模。 此请求需要附有每个规模规则（包括所有较低级别规则）的完整清单，以证明其已满足这些要求。 该清单可在 here 中找到。

一旦 Home Assistant 核心团队审核并批准，集成将在 Home Assistant 的下一个主要版本中显示新的级别。

除了将集成升级到更高的级别之外，还可以将集成降级到较低的级别。 例如，当不再有活动的集成代码所有者时，就会发生这种情况。 在此特定示例中，即使集成完全符合“白金”级别，集成也将降级为“铜级”。

#对各层规则的调整

IoT世界和Home Assistant使用的所有技术正在快速变化；不仅涉及Home Assistant可以支持或执行的功能，还涉及构建Home Assistant的软件。Home Assistant正在快速引领行业技术。

这也意味着随着时间的推移，将会出现新的见解以及新开发和采用的最佳实践，从而对各个集成质量规模规则进行新的添加和改进。

如果调整某个层，则该层中的所有集成都需要重新评估并进行相应调整。

#特殊等级

还有 4 个用于集成的特殊层，这些层在扩展层列表中没有位置。 这是因为它们要么是核心的内部部分，要么根本不在核心中，或者不满足根据缩放级别进行分级的最低要求。

特殊层定义如下。

#❓ 没有分数

这些集成可以通过 Home Assistant 用户界面进行设置。“无分”提示并不意味着它们是坏的或有缺陷的，相反，它表明没有根据质量等级进行评估，或者它们需要一些维护才能现在考虑的最低“铜牌”标准。

“无分”等级不能分配新的集成，因为它们在最新时至少需要具有“铜牌”级别。 Home Assistant 项目鼓励社区帮助更新这些集成，而获得评分至少满足“铜牌”级别的要求。

特征:

• 尚未评分或缺乏足够的评分信息。
• 可以通过UI设置，但可能需要增强连接更好的体验。
• 可能可以正常工作，但尚未根据当前标准进行验证。
• 文档通常仅提供基本的设置步骤。

#🏠 内部

该层分配给 Home Assistant 内部使用的集成。这些集成为 Home Assistant 的核心程序或在其之上构建的其他集成提供了基本组件和构建块。

内部集成由 Home Assistant 项目维护，并遵循严格的架构设计程序。

特征:

• Home Assistant核心程序的内部内置构建块。
• 为其他集成提供构建块以供使用和构建。
• 由 Home Assistant 项目维护。

#💾 遗产

旧版本集成是较旧的集成，多年来（可能自 Home Assistant 成立以来）一直是 Home Assistant 的一部分。它们只能通过 YAML 文件进行配置，并且通常缺乏活跃的维护者（代码所有者）。这些集成的设置可能很复杂，并且不符合当前/现代最终用户其使用和功能的期望。

Home Assistant 项目鼓励社区帮助将这些集成迁移到 UI 并更新它们成为现代标准，使每个人都可以访问这些集成。

特征:

• 设置过程复杂；仅可通过 YAML 进行配置，基于 UI 的设置。
• 可能缺乏积极的代码所有权和维护。
• 可能缺少最近的更新或错误修复。
• 文档可能仍然针对开发人员。

#📦 定制

自定义集成由社区开发和分发，并为 Home Assistant 的设备和服务提供附加功能和支持。这些集成不包含在官方 Home Assistant 版本中，可以手动安装或通过 HACS（Home Assistant 社区商店）等第三方工具安装。

Home Assistant 项目不审查、安全审核、或支持第三方自定义集成。我们鼓励用户在安装前进行额外维护并查看自定义集成的源代码和社区反馈。

我们鼓励并邀请开发人员将他们的集成集成贡献给 Home Assistant 项目，方法使其与集成质量等级保持一致并提交以供引入。

特征:

• 不包含在官方 Home Assistant 版本中。
• 可以手动安装或通过社区工具（例如HACS）安装。
• 由个人开发者或社区成员维护。
• 用户体验可能差异很大。
• 功能、安全性和稳定性可能存在很大差异。
• 文档可能有限。