SuperAPI AI 工具集

rails-upgrade-assistant

编程与开发

查看项目

更新于 10-16 06:39

技能介绍

Rails Upgrade Assistant 是一个面向 Rails 应用升级的技能工具,版本为 v1.0。它的核心目标是帮助开发者分析 Rails 应用并生成全面的升级报告,报告内容涵盖破坏性变更、弃用项以及分步迁移指南。

用途

该工具用于 Rails 应用的版本升级辅助。它通过扫描代码库识别与目标 Rails 版本相关的破坏性变更,并基于实际发现生成升级报告和 app:update 预览,而不是基于假设。

主要能力

工具采用三步流程:

  1. 检测脚本:生成一个 bash 脚本,扫描代码库中的破坏性变更,并给出 file:line 引用。
  2. 用户运行脚本:用户执行脚本后,得到 rails_{version}_upgrade_findings.txt 文件。
  3. 生成报告:基于实际发现生成升级报告和 app:update 预览。

工具强调顺序升级策略,明确禁止跳版本。Rails 升级必须遵循以下顺序:7.0.x → 7.1.x → 7.2.x → 8.0.x → 8.1.x。例如,7.0 → 7.2(跳过 7.1)和 7.0 → 8.0(跳过 7.1 和 7.2)都是不允许的;7.0 → 7.1 和 7.1 → 7.2 是正确的。如果用户请求多跳升级(如 7.0 → 8.1),工具会解释顺序要求,将其拆分为单个跳转,为每个跳转生成单独报告,并建议在进入下一跳之前完整完成每一跳。

使用方式

工具的工作流分为三个阶段:

阶段 1:生成检测脚本

  • 从 Gemfile.lock 检测当前 Rails 版本
  • 读取 detection-scripts/patterns/rails-{VERSION}-patterns.yml
  • 读取 detection-scripts/templates/detection-script-template.sh
  • 读取 workflows/detection-script-workflow.md
  • 生成版本特定的 bash 脚本并交付给用户

阶段 2:用户运行脚本

  • 用户运行脚本,获得发现结果。等待用户分享 rails_{version}_upgrade_findings.txt。

阶段 3:生成报告

  • 解析 findings.txt,提取破坏性变更和受影响文件
  • 读取 version-guides/upgrade-{FROM}-to-{TO}.md
  • 读取 workflows/upgrade-report-workflow.md 和 workflows/app-update-preview-workflow.md
  • 使用用户项目中的真实代码生成综合升级报告
  • 使用实际配置文件差异生成 app:update 预览

工具提供多种资源,按需加载:核心文档(docs/README.md、docs/QUICK-REFERENCE.md、docs/USAGE-GUIDE.md)、版本特定指南(upgrade-7.0-to-7.1.md、upgrade-7.1-to-7.2.md、upgrade-7.2-to-8.0.md、upgrade-8.0-to-8.1.md)、工作流指南(upgrade-report-workflow.md、detection-script-workflow.md、app-update-preview-workflow.md)、示例(simple-upgrade.md、multi-hop-upgrade.md、detection-script-only.md、preview-only.md)、参考资料(breaking-changes-by-version.md、multi-hop-strategy.md、deprecations-timeline.md、testing-checklist.md、pattern-file-guide.md、quality-checklist.md、troubleshooting.md)、检测脚本资源(rails-72-patterns.yml、rails-80-patterns.yml、rails-81-patterns.yml、detection-script-template.sh)以及报告模板(upgrade-report-template.md、app-update-preview-template.md)。

适用场景

适用于需要将 Rails 应用从 7.0 升级到 8.1 范围内版本的开发者,尤其是希望获得基于实际代码扫描结果的破坏性变更清单、弃用项跟踪和分步迁移指南的场景。也适用于需要生成 app:update 配置预览的情况。

限制

工具明确要求不能跳过版本,必须按 7.0 → 7.1 → 7.2 → 8.0 → 8.1 的顺序逐版本升级。多跳升级需要拆分为单个跳转并分别生成报告。质量要求方面,交付前需对照 reference/quality-checklist.md 验证,关键规则包括:替换所有 {PLACEHOLDERS} 为实际值、使用脚本的实际发现而非通用示例、包含真实的 file:line 引用和用户项目中的真实代码、对自定义代码标记警告。资源应按需加载,不要一次性读取全部内容。