rsdoctor-v2-upgrade

rsdoctor-v2-upgrade

用途

该技能用于把 Rspack 项目从 Rsdoctor 1.x 升级到 Rsdoctor 2.0。升级目标是以最小的、保持行为不变的差异完成迁移，并以官方迁移指南与已安装包的导出内容作为事实来源：

• https://rsdoctor.rs/guide/start/migration-v2
• https://rsdoctor.rs/config/options/options-v2

工作流程

1. 审计当前集成

• 读取 package.json、lockfile、Node.js 版本文件和构建脚本。
• 从 lockfile 或包元数据判断已安装的 Rsdoctor 包版本，并确认由哪个包提供当前生效的 RsdoctorRspackPlugin。
• 需要迁移的是 1.x 的 @rsdoctor/rspack-plugin 集成，包括那些仍导入它、处于部分迁移状态的配置。
• 如果 @rsdoctor/core 2.x 已经提供当前生效的插件，则应验证集成，而不是再次迁移。仅有 @rsdoctor/core 并不能证明这是 2.x 集成，因为 1.x 项目也可能用它来实现自定义规则。
• 区分直接集成与框架自带的传递性 1.x 依赖。
• 定位 Rspack、Rsbuild、Rsdoctor 的配置文件，保留仅在特定构建中启用 Rsdoctor 的环境条件。
• 在源码、脚本和编辑器配置中搜索 @rsdoctor/、RsdoctorRspackPlugin、旧版选项、MCP 配置和报告输出相关假设。
• 在修改前记录当前的构建命令与预期报告格式。

2. 通过兼容性门禁

• 要求 Node.js 为 ^20.19.0 || >=22.12.0，并确认已安装的 Rspack 版本满足所选 @rsdoctor/core 的 peer dependency；若所选包自身的 engines 与 peer dependencies 不同，也要检查。
• 对于 webpack 项目，停止 Rsdoctor 升级，保留 Rsdoctor 1.x，或先把项目迁移到 Rspack 作为单独任务。
• 只更新 Rsdoctor 相关依赖，保留现有的 Rspack 与框架版本。如果框架已提供 Rspack，不要直接添加 @rspack/core。仅当已安装版本不满足 Rsdoctor 的 peer dependency 时，才单独报告兼容性问题。

3. 只规划适用的变更

• 阅读 references/migration-map.md。
• 列出对本项目适用的包、导入、模块格式、配置与 AI 工作流变更。
• 选择一个 Rsdoctor 2.x 目标版本。@rsdoctor/core 与 @rsdoctor/cli 保持同一版本；@rsdoctor/agent-cli 单独定版。

4. 迁移包与导入

• 用 @rsdoctor/core 替换 @rsdoctor/rspack-plugin，并从 @rsdoctor/core 导入 RsdoctorRspackPlugin。
• 把 Rsdoctor 的 require() 调用改为 ESM 导入。如果项目仍是 CommonJS，只把受影响的构建配置改为受支持的 ESM 扩展名（如 .mjs），而不是无必要地更改整个包的模块类型。
• 不要机械地重命名来自已移除底层包的导入。每个导入符号都要对照 2.x 的公开导出进行核对，并做类型检查。
• 使用项目现有的包管理器，避免无关的依赖或 lockfile 更新。
• 不要仅仅因为框架自带的传递性 1.x 依赖仍留在 lockfile 中就删除它；要确认框架是否仍会激活其旧插件。

5. 在不改变报告意图的前提下迁移配置

• 使用映射参考逐个替换被移除或废弃的字段。
• 保留项目需要 HTML、JSON 或两者兼有的设置，并保留 lite 报告中有意省略代码源的配置。
• 删除 experiments.enableNativePlugin 与 supports.banner；这两个选项在 2.0 中已被移除，且 Rspack 原生插件始终启用。
• 如果 Rspack 报告 experiments.RsdoctorPlugin 不可用，应报告兼容性问题，而不是在本次升级中更改 Rspack 或框架依赖。

6. 迁移 AI 工作流（如存在）

• 移除 @rsdoctor/mcp-server、其编辑器 MCP 条目以及启动它的脚本。
• 添加 @rsdoctor/agent-cli，重新生成 rsdoctor-data.json，并针对该文件调用 rsdoctor-agent。
• 重写自动化逻辑以消费结构化 CLI 输出。Agent CLI 不是兼容 MCP 的 API，也不能作为其直接替代。不要沿用 MCP 端口，也不要假设其编译器选择语法仍然适用；对于多编译器数据，使用 Agent CLI 的 --compiler <name> 选择编译器。

7. 验证迁移

• 重新安装依赖，并在项目支持的 Node.js 版本下运行生产构建。
• 确认生成了预期的 Rsdoctor 报告，并打开项目使用的 overview、compilation 与 bundle-analysis 页面。
• 如果使用 JSON 输出或 Agent CLI，用一个代表性命令验证新生成的数据文件。
• 运行相关测试与类型检查，然后再次搜索被移除的包与旧版选项。
• 报告变更内容、运行的命令以及未能完成的验证。不要仅凭依赖安装成功就宣称迁移完成。

输出语言

• 面向用户的说明、计划、进度更新和迁移总结，使用用户要求的语言；若未指定，则跟随用户请求的语言。
• 包名、API 名、配置字段、命令、文件路径和错误信息保持原样；必要时在回复语言中解释其含义。

限制与禁令

• 不要把 Rsdoctor 2.x 安装到仅使用 webpack 的项目中。
• 不要为了绕过迁移错误而同时启用 1.x 与 2.x 插件；应单独排查框架自带的传递性 1.x 包。
• 不要悄悄更改报告格式、文件名、服务器端口或源码可见性。
• 不要用虚构的 Agent CLI 服务配置替换 MCP 配置。
• 在替代构建与报告得到验证之前，不要移除兼容性代码。

适用场景

适用于需要对 Rspack 项目中的 Rsdoctor 进行 1.x 到 2.0 升级的开发或迁移场景，包括包替换、导入改为 ESM、配置项迁移以及 AI 工作流从 MCP 切换到 Agent CLI。webpack 项目不适用。