SuperAPI AI 工具集

ha-config-migration

编程与开发

查看项目

更新于 10-15 23:48

技能介绍

用途:在 Home Assistant 集成的配置项(config entry)数据结构发生变化时,指导完成版本迁移。涵盖重命名键、新增必填字段、重构数据等场景,通过递增版本号并实现 async_migrate_entry 完成迁移。

主要能力:

  1. 版本递增规则。VERSION 用于破坏性 schema 变更,需要转换既有用户数据;MINOR_VERSION 用于非破坏性新增,可安全添加默认值。
  2. 提供 async_migrate_entry 模板,展示如何按 entry.version 与 entry.minor_version 逐级迁移数据,例如重命名 old_key 为 new_key、补默认字段,并调用 hass.config_entries.async_update_entry 写回新数据与版本。
  3. 降级防护:若 entry.version 大于当前代码支持的最高主版本,说明用户回滚了 HA 或集成,旧代码无法读取新 schema,应在函数开头返回 False,避免落到 return True 而静默加载损坏数据。

使用方式:在 config_flow.py 中设置 VERSION 与 MINOR_VERSION;在 init.py 中实现 async_migrate_entry,返回 True 表示成功,返回 False 表示迁移失败(配置项会被禁用)。由于 async_update_entry 会就地修改 entry,同一调用内的后续判断可看到已更新版本,因此 1→2→2.1 可级联迁移。应逐版本迁移(1→2→3),不要直接跳到最新版。始终记录日志便于排查。

限制:资料未提供安装命令、具体平台要求或价格信息;示例代码仅作模板,实际迁移逻辑需按具体 schema 变更自行实现。