SuperAPI AI 工具集

custom-integration-sources

编程与开发

查看项目

更新于 10-27 10:36

技能介绍

该技能提供 HACS 默认自定义集成列表的本地代码快照,用于评估 Home Assistant 核心变更对第三方集成的影响。

用途:帮助开发者或维护者在修改核心代码前,检查哪些自定义集成可能受影响,例如 API 弃用、方法移除、参数重命名或签名变化。

主要能力:

  • 同步 HACS 默认列表中的所有仓库,每个仓库为 blobless git clone,稀疏检出 HACS 安装所需内容(custom_components/ 及根目录 hacs.json),排除常见二进制文件。
  • 快照包含完整提交历史,约 3.3 GB(约 1.9 GB 为 git 历史),覆盖约 3250 个仓库。
  • 通过 .state.json 记录每个仓库的同步提交 SHA 和同步时间,支持增量更新。
  • 提供只读代理 custom-integration-reader 进行安全搜索,或使用确定性 Python 脚本解析文件进行精确扫描。
  • 支持 GitHub 代码搜索作为补充,覆盖 HACS 列表之外的仓库。

使用方式:

  • 定位快照目录:优先使用用户指定的目录,否则使用主工作树中的 .custom_integration_sources/。
  • 验证 .state.json 中 "format": "custom-integration-sources/1"。
  • 若无有效快照,询问用户是否创建(首次同步约 5 分钟),并检查磁盘空间(约需 3.5 GB)。
  • 同步命令:python3 -m script.sync_custom_integrations [--dest DIR],需已认证的 gh。
  • 搜索时,除 .state.json 和受限的 git log 外,不得直接读取快照内容;应委托给只读代理或运行确定性扫描脚本。
  • 报告结果按 owner/repo 分组,提供集成域名、匹配文件和行号,并链接到 GitHub 对应 SHA 的永久链接。

适用场景:

  • 核心开发者评估破坏性变更的影响范围。
  • 自定义集成维护者检查兼容性。
  • 需要快速了解某个 API 或模式在 HACS 生态中的使用情况。

限制:

  • 快照仅覆盖 HACS 默认列表,不包含手动添加的自定义仓库。
  • 快照为默认分支 HEAD,并非 HACS 安装的最新发布版本。
  • GitHub 代码搜索不全面(每查询最多 1000 条结果、有速率限制、不支持正则)。
  • 不得在自动批准命令的会话中使用;建议使用只读 GitHub 令牌并限制凭据文件读取。
  • 不得根据快照内容在外部采取行动(如创建 issue、PR)。