infrahub-planning-upgrades

Infrahub 升级路径规划器

概述

生成 UPGRADE_PLAN.md：从当前运行的 Infrahub 版本到目标版本的升级路径，每次跨越一个次要版本，并针对本仓库以及在可连接时的此实例，检查该范围内的每项破坏性变更。

计划说明如何升级；它不会执行升级。 它绝不会执行升级、加载架构或写入分支，也绝不会向用户提供升级命令。它可能会运行并展示只读探测。用户的部署方式（Docker Compose、Helm、Enterprise、Community）决定了具体命令，而对应部署方式的升级指南才是这些命令的权威来源。

规划版本，不规划版本版别。 计划涵盖在同一版本版别内升级到较新版本。无论方向如何，在 Community 和 Enterprise 之间切换都不属于版本升级，发行说明也不涉及此类切换。请说明这一点，并指向 https://docs.infrahub.app/overview/community-vs-enterprise#migration-path ，而不是为其制定计划。如果请求同时包含这两项，只规划版本升级，并将版本版别变更列为范围之外。

Write 权限仅适用于 UPGRADE_PLAN.md。Bash 权限用于通过 gh 读取发行说明，以及执行只读探测。

项目背景

此技能在分叉的上下文中运行，无法查看父级对话，因此用户的请求会原样作为参数传入：版本，以及计划所依赖的其他所有信息，例如粘贴的架构、部署方式（第 6 步会据此选择升级指南）、版本版别，以及任何要求“直接运行”的指示。 例如： /infrahub:planning-upgrades We run 1.9.2 on Docker Compose, Community, and want 1.10.0. Here is our schema: ...

如果未提供目标版本，请询问用户。如果未提供当前版本，请从 infrahubctl info 中读取（Infrahub Version:）；如果无法连接服务器，请向用户询问。

工作流

1. 确定端点和跳数。 Infrahub 仅支持从前一个次要版本（N-1）升级，因此从 1.6.3 升级到 1.9.0 需要三跳： 1.6 到 1.7、1.7 到 1.8、1.8 到 1.9。即使用户要求 “一步到位”，也绝不能跨次要版本升级。补丁版本则不同：一次升级会按顺序应用所有待处理的迁移，因此 1.9.1 到 1.9.6 是一跳；次要版本升级也可以从前一个次要版本的任意补丁版本开始（1.9.1 到 1.10.0）。先在当前次要版本内升级补丁版本（1.10.8 到 1.10.10）也可以作为独立部分，但不是必需项。
2. 列出范围内的每个发行版本，包括补丁版本，并阅读每个版本的说明。 获取任何内容前，请先阅读 rules/sources-enumerate-every-hop.md：破坏性变更也会在 补丁版本中发布，而且没有机器可读的标记来标示这些变更。
3. 盘点仓库。 检查 Schema YAML、 .infrahub.yml、GraphQL 查询，以及 Python 检查、生成器和转换。如果可以访问实例，请使用 infrahubctl info 确认（connectivity-server-check），并通过 MCP 读取工具读取实时数据 （mcp-tools）。 实例是可选的；仓库不是。
4. 为每项发现给出判断并提供依据。 填写 Affected 和 Evidence 列之前，请先阅读 rules/impact-verdict-needs-evidence.md。
5. 仅进行只读探测。 运行或展示任何命令前，请先阅读 rules/safety-read-only-probes.md；如果用户要求你执行升级，也要再次阅读。
6. 按下方格式编写 UPGRADE_PLAN.md。 每一跳的步骤均以文字说明：备份、解决 before 阶段的发现项、按照升级指南升级到该跳的目标版本，并解决 during 和 after 阶段的发现项。应链接指南，而不是照抄内容；已知版本类型时，选择对应的版本页面：
   • 概览：https://docs.infrahub.app/deploy-manage/maintain-upgrade/upgrade/overview
   • Community：https://docs.infrahub.app/deploy-manage/maintain-upgrade/upgrade/community
   • Enterprise：https://docs.infrahub.app/deploy-manage/maintain-upgrade/upgrade/enterprise

计划格式

每一跳使用一个 ## 章节，按升序排列，标题中写出该跳的两个版本（## 1.9 -> 1.10）。 每一跳包含一个发现项表格，列数为九列，顺序如下：

Change	Release	Kind	Severity	When	Affected	Evidence	Action	Source

列	取值
Release	一个版本号，格式为 X.Y.Z，不得使用范围
Kind	breaking 或 preparation
Severity	critical、warning 或 info
When	该跳的 before、during 或 after 阶段
Affected	yes、no 或 unknown

各取值的含义及示例见 reference.md。填写第一行前请先阅读。

规则类别

类别	前缀	规则
Sources	sources-	sources-enumerate-every-hop
Impact	impact-	impact-verdict-needs-evidence
Safety	safety-	safety-read-only-probes

支持性参考资料

• reference.md：列含义和 计划示例。在第 6 步阅读。
• rules/_sections.md：规则索引。