Hermes 版本号更新接线设计¶

日期： 2026-08-05 修订： 2026-08-06 状态： 已批准

目标¶

通过将 .hermes-plugin/plugin.yaml 注册到 .version-bump.json 中，并让 scripts/bump-version.sh 在不实现 Bash YAML 解析器的情况下处理 YAML，使其与 仓库版本保持同步。

设计¶

• 将 { "path": ".hermes-plugin/plugin.yaml", "field": "version" } 添加到 .version-bump.json 中。
• 将 .json 路由到现有的 jq 辅助工具，将 .yaml 路由到 Mike Farah yq v4。YAML 键和值作为数据传递，而不会插值到表达式中。
• 仅支持存在且位于顶层的 YAML 字符串字段。嵌套字段和 .yml 不在支持范围内。
• 将 --check、--audit 和版本更新操作路由到同一个小型 读/写分发器。
• 在版本更新写入任何清单文件之前，运行一次只读预检： 验证所需工具，并通过分发器读取每个存在且已声明的清单。这样可避免在较早的 JSON 文件已被更新之后， 再发生确定性的 YAML 失败。缺失文件的行为保持不变，且 --help 在没有 jq 或 yq 时仍然可用。

预检是唯一新增的可靠性措施。它不会让脚本具备事务性， 也不会重新设计现有的审计和错误状态行为。

测试¶

三个有针对性的行为测试在隔离的临时测试夹具上运行真实脚本，并证明：

• 对齐的 JSON 和 YAML 通过 --check 和 --audit，且一次版本更新会同时更新两种 格式；
• 当 JSON 声明在前、后续 YAML 清单的顶层 version 不是字符串时，一次实际的版本更新会以非零状态退出， 并让所有清单文件逐字节保持不变；以及
• 真实的 .version-bump.json 注册了 Hermes 清单。

验证还会针对仓库运行 shell lint 和 scripts/bump-version.sh --check。

非目标¶

• 不编写手写的 YAML 解析器。
• 不支持 .yml 或嵌套 YAML。
• 不改变 Hermes 运行时。
• 不引入回滚框架、通用配置结构层、审计/状态重构，或 穷举式失败矩阵。
• 对审查期间发现的独立版本校验与 JSON 表达式问题不做修改。