迁移到 Rsdoctor 2.0

Rsdoctor 2.0 围绕 Rspack 收敛了包结构。大多数项目只需要安装 @rsdoctor/core。此版本移除了多个独立包。请同时更新依赖和导入路径，避免在 2.0 代码中解析到 1.x 包。

检查构建工具

Rsdoctor 2.0 要求使用 Node.js 22.18 及以上版本和 Rspack 2.0 及以上版本，不再支持 Rspack 1.x。此外，Rsdoctor 2.0 不再支持 webpack，并移除了 @rsdoctor/webpack-plugin。

Rspack 项目可以继续按照本文档迁移。
webpack 项目应继续使用 Rsdoctor 1.x，或先迁移到 Rspack，再升级 Rsdoctor。

更新 Rspack 插件

使用 @rsdoctor/core 替换 @rsdoctor/rspack-plugin：

pnpm remove @rsdoctor/rspack-plugin
pnpm add -D @rsdoctor/core

Rsdoctor 2.0 的包仅提供 ESM 产物。请在现有 ESM 导入中更新包路径：

迁移前

import { RsdoctorRspackPlugin } from '@rsdoctor/rspack-plugin';

迁移后

import { RsdoctorRspackPlugin } from '@rsdoctor/core';

如果 1.x 配置使用 CommonJS require()，请改为上面的 ESM 导入方式。

@rspack/core 仍是 @rsdoctor/core 的可选 peer dependency，最低支持版本为 2.0。基于 Rspack 的构建工具通常已经提供该依赖；直接使用 Rspack 的项目需要安装 @rspack/core。

Rsdoctor 2.0 要求使用 Rspack 内置的 Rsdoctor 原生插件来收集模块图和 chunk 图。请移除原有的 experiments.enableNativePlugin 配置，因为原生链路现在始终启用。如果构建提示 experiments.RsdoctorPlugin 不可用，请升级项目或框架提供的 Rspack 依赖。

CLI 迁移

@rsdoctor/cli 仍是 rsdoctor 命令对应的包。请为 @rsdoctor/cli 和 @rsdoctor/core 使用相同版本：

pnpm add -D @rsdoctor/core @rsdoctor/cli

原有命令和 Node.js API 继续保留，当前用法请参考 CLI 使用教程。

AI 工作流迁移

Rsdoctor 2.0 已移除 @rsdoctor/mcp-server，不再提供 MCP Server。所有基于 Rsdoctor 的 AI 辅助分析工作流都需要迁移到 @rsdoctor/agent-cli：

pnpm remove @rsdoctor/mcp-server
pnpm add -D @rsdoctor/agent-cli

Agent CLI 是新的替代工作流，但不兼容 MCP 协议，也不是旧 API 的直接替代品。不能只替换包名，还需要完成以下调整：

从 .cursor/mcp.json、.vscode/mcp.json 等配置中删除 Rsdoctor MCP 项。
删除启动 npx @rsdoctor/mcp-server 的脚本或自动化配置。

生成 rsdoctor-data.json，然后使用 Agent CLI 直接读取该文件：

rsdoctor-agent bundle optimize --data-file ./dist/rsdoctor-data.json
rsdoctor-agent query packages_duplicates --data-file ./dist/rsdoctor-data.json

调整 AI Agent 和自动化流程，通过 rsdoctor-agent 执行分析并消费其结构化 JSON 输出。支持 Skill 的 Coding Agent 可以使用 Rsdoctor analysis skill 管理此流程。

Agent CLI 直接读取数据文件，因此不再需要 MCP Server 端口、compiler 等 MCP 专用配置。安装、数据生成和更多命令示例请参考 AI。

配置迁移

包迁移不会自动更新已移除或废弃的配置项。mode、brief、output.compressData 以及相关输出选项的迁移方法，请参考配置迁移说明。

验证升级结果

更新依赖和导入路径后：

搜索项目中是否仍存在已移除的包名：

rg '@rsdoctor/(rspack-plugin|webpack-plugin|sdk|graph|types|utils|components|mcp-server)'

使用项目的包管理器重新安装依赖。
执行生产环境构建，确认 Rsdoctor 能够生成报告。
打开报告，检查项目使用的概览、编译分析和产物分析页面。
如果项目使用 @rsdoctor/cli 或 @rsdoctor/agent-cli，请使用新生成的 Rsdoctor 数据执行对应命令。

#迁移到 Rsdoctor 2.0

#检查构建工具

#更新 Rspack 插件

#CLI 迁移

#AI 工作流迁移

#配置迁移