该技能提供 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)。