技能介绍

要解决什么问题

Rails 大版本或次版本升级时，rails app:update 会批量覆盖生成文件，很容易抹掉你在 config/application.rb、bin/dev、mailer/i18n 等处的本地定制。升级前还需要对照官方指南、发布说明和框架默认文件的差异，并同步 Hotwire、importmap 等前端依赖——这些工作分散在多个站点，手工整理成本高。

技能如何工作

本技能把升级流程拆成可执行的检查与分析步骤：

确认是 Rails 项目：检查 Gemfile（含 rails）、config/application.rb、config/environment.rb；不符合则停止。
锁定版本：从 Gemfile.lock 或 Gemfile 读取当前 Rails 版本；用 GitHub CLI 查最新稳定 tag（去掉 v 前缀），并区分补丁 / 次版本 / 主版本升级。
拉取官方与 diff 资料：用 WebFetch 读 Rails 升级指南中与你的跳转路径相关的章节；再从 railsdiff.org/{current}/{target} 汇总默认配置、新文件、initializer、bin/ 脚本与依赖变更。
JavaScript 侧：识别 npm/yarn 或 importmap；核对 @hotwired/turbo-rails、@rails/actioncable、config/importmap.rb 等是否与目标 Rails 时代对齐。
输出升级总结：给出复杂度（小/中/大）、关键破坏性变更、弃用项、推荐步骤，并明确不建议直接跑 rails app:update。
选择性合并：按 railsdiff 把变更分为新文件、可安全覆盖、需手动合并、仅注释变更；对自定义文件展示本地版、Rails 新版与建议合并结果；迁移与测试验证后再逐步启用 new_framework_defaults_*。

适用边界与注意点

依赖 GitHub CLI（查 release/tag）与 WebFetch（指南、railsdiff）；gh 未认证时需先 gh auth login。
railsdiff 若无精确 patch 版本，可退到 x.y.0 近似对比。
原则：不检查就不覆盖、保留本地意图、变更最小化；任何可能丢失自定义的操作前先展示将被覆盖的内容，便于用 git 回滚。