用途
provider-upgrade 用于将任意 Pulumi provider 升级到较新版本，并协调升级后产生的 diff。它适用于用户希望升级或更新 provider 的场景。
该技能的核心原则是：provider 升级是一次翻译，而不是变更请求。用户的基础设施意图没有改变——仍然是同一个 bucket、同一个 function、同一个 cluster。改变的是 provider API 表达该意图的方式。任务是把现有代码翻译到新 API，使 Pulumi 看不出代码所述与已存在资源之间的差异。
技能将问题分为四层：用户意图（升级期间不变）、代码（可能需更新）、Pulumi 状态（可能需协调）、真实云资源（升级期间不应改变）。升级期间第 2、3 层可能需要改动，以继续正确表示不变的第 1、4 层。正确的翻译产生零 diff；如果出现 diff，要么翻译有误，要么需要代码改动之外的操作（import、alias、手动步骤）。
主要能力
- 升级 provider 依赖版本（支持 TypeScript/JavaScript、Python、Go、.NET、Java、YAML）。
- 使用必需 CLI 参数运行 preview：
pulumi preview --refresh --run-program。 - 执行 Diff Checkpoint：对每个非 same 资源分类。
- 处理 Category A：自己改动的代码未产生 same，需修正翻译。
- 处理 Category B：未改代码但出现 diff，需借助诊断工具箱调查。
- 处理 Category C：provider 版本变更这一预期 diff。
- 生成升级摘要并创建 PR。
使用方式
核心循环：升级 provider 依赖 → 带必需参数运行 preview → Diff Checkpoint 分类每个非 same 资源 → 修复 Category A → 调查 Category B → 重复直到干净或剩余 diff 已充分调查 → 创建 PR 并附升级摘要。
Diff Checkpoint 是最重要的环节，每次 preview 后都要运行。对每个非 same 资源回答：我的代码改动是否直接或间接影响了该资源？直接指编辑了资源块本身；间接指改动了喂给该资源的共享变量、其他资源的输出、辅助函数、默认值或它依赖的资源。
Category A 中，若修改的现有资源显示 update，说明重命名、重构或值调整改变了语义而非仅语法；常见原因包括新属性名映射到不同底层字段、值形状变化导致信息丢失或增加、新版本默认值变化需显式设置旧值、新 provider 版本追踪了以前不追踪的字段。若新增资源块显示 create，通常表示云上已存在该基础设施，正确做法是 import 而非 create。若移除资源块显示 delete，意味着 pulumi up 会调用 provider 的 Delete API 真实销毁资源，正确做法是使用 pulumi state delete '<urn>' 仅从跟踪中移除，再用 import 采纳替代资源。
Category B 的 diff 来自 provider 版本变化本身，可能是可用代码修复、有文档记载的 no-op（需引用升级指南或 provider 文档）、需要手动步骤，或未知需询问用户。
Category C 是 pulumi:providers:{name} 上仅显示版本变化的 update，这是唯一预期的 diff。
分类后需做完整性检查：preview 中所有非 same 资源都必须出现在检查点中，包括带 [diff: ...] 标注的资源。接受任何 diff 为“OK”都需要证据，如升级指南、GitHub issue 或 provider 文档。应先修复所有 Category A 再调查 Category B。最终 preview 中不允许残留 delete 或 replace。
适用场景
- 用户希望升级或更新 Pulumi provider 版本。
- 需要协调升级后产生的 diff，确保不改变真实云基础设施。
- 需要判断 diff 是代码翻译错误还是 provider 行为变化。
限制与硬性规则
- preview 必须使用
--refresh --run-program，否则可能显示虚假 diff。 - 不追逐已弃用但仍可用的写法，迁移会引入无收益的风险。
- 改动尽量最小，每一行改动都可能引入回归。
- 不运行
pulumi up，provider 升级修改源代码，需经代码评审后由 CI/CD 部署。 - 最终 preview 中不允许残留 delete 或 replace，必须通过代码修复、alias 或文档化手动步骤解决。
- 接受 diff 需要权威来源，个人判断不足以作为证据。
参考文件
- references/diagnostic-toolbox.md：升级指南、schema-tools、堆栈状态检查、SDK 类型、GitHub issue，调查 Category B diff 时阅读。
- references/gcp-v10.md：pulumi-gcp v10 的每个破坏性变更及状态扫描、grep 模式、修复顺序与风险，升级 pulumi-gcp 到 10.x 前阅读。
暂未提供
该技能的收费、价格、平台支持范围等具体信息暂未提供。