Rails Upgrade 是一个面向 Rails 应用版本升级的系统化工作流技能，覆盖 Rails 5.2 到最新发布版本，帮助在动手改动代码前完成评估、检测与规划。
主要能力
- 版本评估：读取 Gemfile、Gemfile.lock、config/application.rb 与 .ruby-version，确认当前 Rails、Ruby 版本、load_defaults 值，并将目标版本解析为具体补丁号（如 8.1.3.1），而非仅指定次版本。
- 多跳升级规划：当跨度超过一个次版本时，拆分为顺序升级路径（例如 6.1 → 7.0 → 7.1 → 7.2 → 8.0），逐跳执行且每跳测试通过后才进入下一跳。
- 配置差异获取：通过 GitHub API 从 railsdiff.org 的数据源获取当前版本与目标版本之间的实时配置差异，并归类为配置文件、基础设施文件、资源管线、新增与删除文件；获取失败时改用内置静态参考数据。
- 代码级检测：使用 Grep、Glob、Read 在代码库中按版本对检索需要修改的写法，结合 gem 兼容性数据交叉检查 Gemfile.lock 中已知有问题的 gem。
- 安全门禁：针对使用 Active Storage 与 vips 变体处理器的应用，检查 variant_processor 配置、libvips 版本与 ruby-vips 版本，并提示相关上传类型限制与密钥轮换建议。
- 测试基线：在任何升级工作前运行测试套件并记录通过、失败、待定数量，基线不通过则停止。
- load_defaults 迁移：检查是否残留上一次升级未完成的 new_framework_defaults 文件，并生成各配置项的启用顺序与风险分级。
- 升级报告与执行：汇总环境、配置变更、升级前与升级后必须修复的问题、废弃警告、gem 更新表、load_defaults 计划与工作量估计；用户确认后创建升级分支，更新 Gemfile、执行 bundle update、应用配置变更、运行 app:update 并逐项审查，最后再次运行测试。
使用方式 在开始时会声明正在使用该技能引导升级。整个流程分为版本评估、安全门禁、测试基线、配置差异、代码检测、load_defaults 校验、生成报告、执行升级等步骤，其中测试基线、安全门禁、load_defaults 校验和报告确认被设为硬性关卡，未通过或未获批准时不修改文件。
适用场景
- 升级前评估应用是否就绪
- 规划跨多个次版本的升级路径
- 排查特定版本对之间的破坏性变更
- 判断是否需要采用 next_rails 双启动方案
限制与注意事项
- Rails 8.2 尚未发布（8.2.0.alpha），不建议将生产应用升级到该版本；相关资料仅用于在 8.1 上提前清理 8.2 将移除的用法，且内容可能变化，使用前需重新核对 main 分支。
- 7.2 以前的版本已不再获得上游安全补丁支持。
- 部分检查依赖外部 API 与本地工具（如 vips --version），API 获取失败时只能使用静态参考数据。
- 技能的参考数据最后核对时间为 2026-08-13，实际升级前应重新确认最新补丁版本。