Renovate Home Assistant Manifest Manager 深度解析自动维护集成依赖 requirements 字段【免费下载链接】renovateHome of the Renovate CLI: Cross-platform Dependency Automation by Mend.io项目地址: https://gitcode.com/GitHub_Trending/re/renovate本篇指南聚焦 Renovate 中负责处理 Home Assistant 集成清单文件的homeassistant-manifest管理器说明它如何识别manifest.json、解析requirements中的 Python 依赖并驱动版本更新。读完本文你将掌握该管理器的匹配规则、依赖解析逻辑、支持的依赖来源与版本约束写法并能结合实际配置让 Renovate 持续维护自定义组件的依赖清单。概述这个管理器解决什么问题Home Assistant 的自定义集成custom integration通过manifest.json描述自身元数据其中requirements字段声明该集成运行所需的 Python 包及版本约束。手写这些版本号很容易过时而 Renovate 的homeassistant-manifest管理器正是为此而生它会解析requirements数组中的每一条依赖交给对应的 datasource 查询最新版本从而为你的集成自动生成依赖更新 PR。该管理器的官方说明位于 readme.md核心职责一句话概括更新 Home Assistant 集成manifest.json文件中的requirements字段。其最小示例形态如下{ domain: my_integration, name: My Integration, requirements: [aiohttp3.9.1, pydantic2.5.0] }管理器注册信息与适用场景在 index.ts 中该管理器暴露了完整的注册元数据从中可以提炼出它的关键特性属性值说明displayNameHome Assistant Manifest在 Renovate 日志与报告中显示的名称defaultConfig.managerFilePatterns[/(^|/)manifest\\.json$/]默认匹配任何名为manifest.json的文件categories[python]归类为 Python 生态管理器supportedDatasources[pypi, git-tags]支持 PyPI 与 Git 标签两种依赖来源需要特别注意的是managerFilePatterns默认值它匹配任意层级下名为manifest.json的文件。这意味着如果你的仓库中同时存在 Chrome 扩展、VS Code 插件等也命名为manifest.json的文件该管理器会尝试解析它们。不过源码对此有防御性设计——extract.ts 中通过严格的 schema 校验区分JSON 解析失败与不是 Home Assistant manifest并分别记录 debug 日志随后返回null跳过该文件详见后文文件识别与容错一节。如果你想自定义匹配范围可以参照 Managers 配置文档 中的managerFilePatterns配置方式对homeassistant-manifest进行覆盖或扩展也可以使用enabledManagers数组只保留本管理器{ enabledManagers: [homeassistant-manifest] }文件识别与容错如何判定这是 Home Assistant 清单该管理器的提取入口是extractPackageFile(content, packageFile)其完整流程定义在 extract.ts对文件内容执行HomeAssistantManifest.safeParse(content)schema 定义见 schema.ts。解析失败时检查错误信息中是否包含Invalid JSON若是说明该文件是非法 JSON记录Failed to parse manifest.json否则说明 JSON 合法但结构不符记录Not a Home Assistant manifest。解析成功但requirements为空或缺失时同样返回null不产出任何依赖。否则返回{ deps }即解析出的依赖列表。schema 本身通过Json.pipe(...)组合而成Json解码器定义于 lib/util/schema-utils/index.ts 依赖的 schema-utils 中负责把字符串内容解析为 JSON 对象失败时抛出Invalid JSON错误随后用z.object校验三个字段domain: z.string()—— 必须存在且为字符串name: z.string()—— 必须存在且为字符串requirements: LooseArray(Requirement).optional()—— 可选的字符串数组。其中LooseArray的语义是宽容数组数组中的非字符串元素如数字、null会被静默丢弃而不是让整个文件解析失败——这正是测试用例handles invalid requirement types in array所验证的行为[aiohue1.9.1, 123, null, valid2.0.0]最终只提取出两个合法依赖。从 extract.spec.ts 的测试用例可以完整还原判定矩阵输入文件特征结果非法 JSON如not valid json返回null日志提示 JSON 解析失败缺domain或缺name返回null日志提示非 Home Assistant manifestChrome 扩展式manifest_version清单返回nullrequirements为空数组或不含该字段返回nullrequirements不是数组如字符串返回null结构合法且含有效requirements返回提取出的depsrequirements 的逐条解析从字符串到依赖对象每条requirements条目都是一个字符串schema 通过Requirement转换器定义于 schema.ts将其解析为标准的PackageDependency对象。关键实现细节复用 pip_requirements 解析器每条 requirement 字符串会被直接传给 pip_requirements 管理器的 extractPackageFile该解析器基于 PEP 508 包名规则与renovatebot/pep440的RANGE_PATTERN实现版本区间匹配。无版本声明的处理如果解析出的依赖既没有currentValue也没有skipReason会被标记为skipReason: unspecified-version即未指定版本Renovate 将跳过它而不会报错。对应测试handles requirements without version[package, aiohue1.9.1]中package被跳过。完全无法解析的处理若连包名都解析不出来则退化为把原始字符串当作depName标记skipReason: invalid-dependency-specification并默认使用pypidatasource。对应测试handles unparseable requirement strings!!!invalid!!!被标记跳过而aiohue1.9.1正常提取。精确版本号提取当currentValue以开头时会额外生成currentVersion字段去掉前缀后的纯版本号便于 Renovate 直接进行版本比较。支持的依赖来源与版本约束写法homeassistant-manifest声明支持两种 datasource分别对应requirements中两种依赖写法1. PyPI 包pypidatasource最常见的形态即标准的 PEP 508 风格约束。从 extract.spec.ts 的supports requirements with other operators测试可以看到支持多种版本运算符{ requirements: [ package1.0.0, another2.0.0, exact1.5.0, tilde~1.2.3 ] }对应的解析结果分别产出currentValue: 1.0.0、2.0.0、1.5.0带currentVersion: 1.5.0与~1.2.3。这些依赖统一使用 PypiDatasource 查询版本其默认版本策略为pep440默认注册源为https://pypi.org/pypi/也支持通过PIP_INDEX_URL环境变量切换私有源。带 extras 的写法同样被支持测试handles requirements with extras验证了package[extra1,extra2]1.0.0会被正确解析为depName: package、currentValue: 1.0.0。2. Git 引用git-tagsdatasourcerequirements中还可以直接引用 Git 仓库源码写法形如pycoolmastergithttps://github.com/issacg/pycoolmaster.gitv1.0.0对应测试extracts githttps requirements验证了其解析结果datasource: git-tagsdepName: pycoolmasterpackageName: https://github.com/issacg/pycoolmaster.gitcurrentValue: v1.0.0、currentVersion: v1.0.0这种形态的解析能力同样源自 pip_requirements/extract.ts 中的packageGitRegex支持githttps、gitgit、gitssh等协议因此 Renovate 会基于该 Git 仓库的标签版本为这类依赖提出更新。真实世界示例一个完整的 Home Assistant 集成清单测试用例extracts from real-world ASUSWRT manifest使用了一个接近真实的自定义集成manifest.json可以直观看到该管理器的处理对象{ domain: asuswrt, name: ASUSWRT, codeowners: [kennedyshead, ollo69, Vaskivskyi], config_flow: true, documentation: https://www.home-assistant.io/integrations/asuswrt, integration_type: hub, iot_class: local_polling, loggers: [aioasuswrt, asusrouter, asyncssh], requirements: [aioasuswrt1.5.1, asusrouter1.21.3] }注意schema 只关心domain、name、requirements三个字段其余如codeowners、config_flow、iot_class等字段都会被忽略但不会导致解析失败最终提取出aioasuswrt1.5.1与asusrouter1.21.3两条 PyPI 依赖。常见问题排查指引仓库中同名manifest.json被误判该管理器默认匹配所有名为manifest.json的文件。若某些非 Home Assistant 文件被错误匹配可通过 ignorePaths 配置选项 排除反之若文件未被匹配请检查managerFilePatterns是否被预设覆盖相关说明见 Managers 文档。依赖未生成更新检查requirements中的写法。无版本声明如aiohttp会被标记为unspecified-version跳过无法解析的写法会被标记为invalid-dependency-specification跳过。建议统一使用精确锁定版本这也是 Home Assistant 官方推荐的做法。如何观察解析行为在 DEBUG 级别日志中搜索Failed to parse manifest.json与Not a Home Assistant manifest可以快速定位文件未被提取的原因。小结homeassistant-manifest是 Renovate 中一个小而专的 Python 生态管理器它用严格的 schema 识别 Home Assistant 集成清单复用 pip_requirements 的解析能力处理requirements数组同时支持 PyPI 与 Git 标签两种依赖来源。核心实现横跨 index.ts注册与匹配、schema.ts解析规则、extract.ts提取入口并有 extract.spec.ts 覆盖了从非法 JSON、结构不符到各类版本运算符的完整行为矩阵。对于维护 Home Assistant 自定义集成的开发者而言只需确保requirements采用规范的包名版本号写法即可让 Renovate 持续、自动地跟进依赖升级。【免费下载链接】renovateHome of the Renovate CLI: Cross-platform Dependency Automation by Mend.io项目地址: https://gitcode.com/GitHub_Trending/re/renovate创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考