rsdoctor-analysis

Rsdoctor 分析助手技能

仅当存在真实的 rsdoctor-data.json 路径后，才使用全局安装的 @rsdoctor/agent-cli 中的 rsdoctor-agent CLI。除非用户明确要求安装或配置，否则分析过程应保持只读。

回复顺序（必须）：高优先级问题 -> 建议解决方案 -> 可选的引用链后续选项 -> 后续深入分析的问题类别（不是命令）。

核心工作流

1. 开始新工作前，复用当前会话的结果和有效的 .rsdoctor-analysis-cache.json 条目。
2. 快速定位 rsdoctor-data.json：先检查用户提供的路径，然后检查 dist/rsdoctor-data.json、output/rsdoctor-data.json、static/rsdoctor-data.json、.rsdoctor/rsdoctor-data.json，最后执行一次有界的 rg --files 搜索，并排除 node_modules 和 .git。仅将 manifest.json 视为索引。
3. 如果数据存在，跳过所有插件版本、配置和构建生成逻辑。必要时更新缓存。
4. 如果缺少数据，停止分析：不要运行 rsdoctor-agent 分析命令，也不要运行分析门禁；可以询问数据路径，或仅在需要设置或生成时运行下方的生成门禁。
5. 真实数据文件存在后，在首次运行 rsdoctor-agent 数据获取命令前，最多运行一次分析门禁：通过 npm view @rsdoctor/agent-cli version 和 rsdoctor-agent --version 验证全局安装的 @rsdoctor/agent-cli；仅在未安装、版本过旧、出现版本相关错误或用户要求更新时，安装最新版本。
6. 分析前，通过 rsdoctor-agent compilers list --data-file <path> 探测编译器，然后遵循下方的编译器选择规则。
7. 对每个选定的编译器，先仅获取默认证据集；尽可能并行执行相互独立的获取操作。在该编译器的证据收集过程中，向每条数据获取命令传入对应的 --compiler <name>。
8. 在选择深入分析命令或提出建议前，运行下方的 ROI 分诊门禁。根据实测影响对问题类别排序，然后按要求的回复顺序综合整理发现。

性能规则：并行执行相互独立的检查；仅缓存派生信息（dataFile、dataFileMtime、pluginName、pluginVersion、依赖项/配置/插件的修改时间）；当路径不存在、修改时间变化、用户要求更新或缓存值失效时，使缓存失效。试探性插件检查不得触发生成；仅在确认数据文件缺失后才使用这类检查。

编译器选择

将编译器探测视为首次数据查询，而非并行证据收集的一部分：

• 如果报告中只有一个有名称的编译器，则在整个分析过程中使用其准确的 name。
• 如果报告中有多个编译器，则将用户指定的每个目标解析为准确的编译器名称。当请求指定了 client、server 或 worker 等目标，但与任何准确名称都不匹配时，仅当探测结果表明匹配关系明确时才进行映射；如果未指定目标或匹配关系不明确，则请用户从返回的名称中选择。
• 如果旧版报告返回的唯一编译器为 name: null，则省略 --compiler。
• 对于单编译器分析，在默认证据集和所有后续查询中使用同一个选定编译器。如果用户明确要求跨编译器分析，则按上述规则选择每个请求的编译器（或在用户要求全部时选择所有返回的编译器），分别使用各自的 --compiler <name> 运行证据收集流程，然后清晰标注并比较结果。每个流程中不得混合不同编译器的结果。
• 对于每个流程中的本地 JSON 证据（包括 E1001/E1002 摘要），仅读取 compilers list 返回的、对应于选定编译器的解析后数据文件。不得将最初提供的聚合文件或索引文件作为编译器范围内的证据来读取。
• 获取证据前，确认每个选定编译器的 available 字段均为 true。如果有任何一个为 false，请用户恢复或重新生成该编译器的数据文件。

ROI 分诊门槛

在推荐修复方案之前，先将当前构建归入大致的成本类别，并根据证据而非直觉选择 ROI 最高的优化方向。此门槛适用于通用的 Rspack/Webpack 项目；除非用户项目提供了相关数据，否则不要使用特定框架的运行时层。

成本类别	证据来源	首选优化方向
资源/媒体	assetsTop、assets media、chunkGraph.assets	压缩、转换、去重、精简或延迟加载大型资源
大型包/模块	packagesTop、模块/包大小字段	替换体积较大的包、使用深层导入、拆分非关键代码，或检查直接依赖的选择
重复/跨块成本	E1001/E1002、packages duplicates、跨块包摘要	去重版本、调整包解析方式，或调整 splitChunks/缓存组
Tree-shaking 浪费	retainedModulesTop、保留的 CJS/桶形导出/副作用模块	修正 CJS/桶形导出导入、sideEffects 声明或包入口点
构建时间成本	buildCost、加载器/插件/目录成本数据	优化加载器/插件、缓存、文件监视器或源映射/开发设置；仅在用户询问构建性能时优先处理

决策规则：

• 当测得的成本细分会改变建议优先级时，先报告该细分。
• 从与实际修复方案对应的最大成本类别入手；除非较大的问题预计会出现或有意无法避免，否则较小的问题不应优先于较大的问题。
• 将调用方/引用链追踪视为第二阶段工作。仅当高影响候选项需要归属证据，或用户询问“为什么”/“是谁导入的”时才运行。
• 对于需要具体文件、包、代码块、大小或依赖路径才能修复的问题，不要将聚合规则输出作为充分证据。
• 如果最大的成本类别属于结构性问题或有意保留的成本，应说明这是一个限制，并指出需要进行何种外部变更，而不是编造影响较小的源码修改。

生成门控

首先确认项目使用的打包器。对于 webpack，请遵循单独的 webpack 1.x 生成指南；不要应用下方的 Rspack 2.x 门控。对于 Rspack，依次检查 package.json、锁文件和已安装的包元数据中的 @rsdoctor/core 和 @rsdoctor/rspack-plugin。仅在备用情况下使用 pnpm why / npm ls。应确认实际版本，而不是根据依赖范围推断主版本；如果所选插件的 peer dependency 不包含已安装的打包器，则停止操作。分别检查直接依赖和插件的实际注册情况，不要把框架自带的传递依赖算在内。可能存在 @rsdoctor/core 1.x，用于自定义规则，但它并不提供构建插件。

对于 Rspack，请严格遵循以下 if/else 决策树；不要合并分支：

if Rspack actively registers both @rsdoctor/core 2.x and @rsdoctor/rspack-plugin 1.x:
  stop and report mixed plugins; do not install or build
else if Rspack has @rsdoctor/core 2.x:
  use or register the v2 plugin; configure output.mode='brief' and include 'json' in output.options.type; build with RSDOCTOR=true only
else if @rsdoctor/rspack-plugin is installed but its version is unknown:
  resolve its version first; if still unknown, configure output.mode='brief' and include 'json' in output.options.type; build with RSDOCTOR=true only
else if an installed @rsdoctor/rspack-plugin 1.x version is >= 1.5.11:
  do not edit plugin config just for JSON; build with RSDOCTOR_OUTPUT=json and RSDOCTOR=true if needed
else if an installed @rsdoctor/rspack-plugin 1.x version is older:
  configure output.mode='brief' and include 'json' in output.options.type; build with RSDOCTOR=true only
else: # no build plugin installed
  choose a compatible Rspack plugin, then configure brief JSON output and build with RSDOCTOR=true only

对于未安装插件的 Rspack 2.x 项目，请安装兼容的 @rsdoctor/core 2.x 版本；不要安装 @rsdoctor/rspack-plugin。对于 Rspack 1.x，请保留兼容的 1.x 插件。如果无法确认已安装的版本或打包器兼容性，请在安装前停止操作。仅当包版本与实际生效的配置似乎不一致时，才检查插件导入路径。

对于 Rspack 构建，只有在插件版本已知且为 >= 1.5.11 的 1.x 版本时，才允许使用 RSDOCTOR_OUTPUT=json。对于 2.x、缺少、未知或更旧版本的插件，均禁止使用。需要显式配置 JSON 时，请在现有的简要输出类型中添加 'json'，不要移除 HTML；如果临时更改常规报告的设置，请在生成数据后恢复先前的输出设置：

output: {
  mode: 'brief',
  options: {
    type: ['json'],
  },
}

证据与命令范围

默认证据集：

摘要键	证据来源	范围
buildCost	build summary	仅限筛选字段
assetsTop	按原始 / gzip 大小排列的顶级资源	固定 Top-N
packagesTop	按 gzip 大小排列的顶级软件包	固定 Top-N；避免使用完整的 packages list 页面
duplicatePackages	E1001 重复软件包摘要	仅限第一轮摘要
crossChunkPackages	E1002 跨代码块重复摘要	仅限第一轮摘要
retainedModulesTop	tree-shaking retained-modules --limit 10	仅限筛选字段；不使用 --compact

范围规则：

• 仅在 rsdoctor-data.json 存在后使用 rsdoctor-agent 访问打包数据；优先并行获取互不依赖的数据；使用 --filter、分页和 --limit 限制输出。发现后，将本轮证据所选的编译器作为 --compiler <name> 传递给每条直接命令和 query 调用；仅当已发现名称为 null 的旧版报告时才省略该参数。
• 默认分析范围仅限默认证据集。对于非默认分析，请从 references/rsdoctor-data-types.md 中选择最少字段，并参照 references/common-analysis-patterns.md 中的模式。
• 将链路追踪、宽泛命令、优化编辑、splitChunks 实验和重新运行构建视为需用户确认后才能进行的可选后续操作。
• 对于重复软件包和 tree-shaking 问题，先识别问题；仅在用户确认后追踪引用 / 导入链路。
• 调查 side-effects 时，优先使用 tree-shaking retained-modules --emitted-only --category side-effects --limit 10，并使用范围较窄的 --filter。
• 对于保留的已输出模块，使用 tree-shaking retained-modules，并指定 --emitted-only、范围受限的 --category、--sort gzipSize、--limit 和范围较窄的 --filter；不要传递 --compact。
• 仅在字段缺失或需要聚合上下文时，将 tree-shaking summary 用作备用方案。将 tree-shaking bailout-reasons 视为高输出量命令；仅在明确请求时运行，并传递目标 --modules（最多 100 个）。
• 如果任何命令超过 5k 个令牌、500 KB 原始输出或几百行记录，请停止宽泛获取，改用有针对性的精简查询。

输出与恢复

输出格式：

1. 当前构建中发现的问题及建议修复方案：
   • 将每个问题与其修复建议分组列出。
   • 提供具体证据（大小／时间／数量／路径／规则代码）和优先级。
   • 对于重复包和 tree-shaking 问题，提供简短的“继续追踪还是到此为止”选项。
2. 是否仍需深入分析：
   • 仅列出剩余的问题类别，不列出命令。

对于 Top-N 洞察，优先使用表格：Name | Volume/Time | Count | Recommendation。

恢复规则：

• 缺少 rsdoctor-data.json：不要运行 rsdoctor-agent；请用户提供数据路径，或运行 Generation Gate，然后在需要设置时使用对应的安装参考。
• 找不到命令：运行 Analysis Gate，然后重试 rsdoctor-agent。
• query 报告工具未知：运行 list 并使用目录中的工具名称，或切换到直接的 <group> <subcommand> 模式。
• COMPILER_REQUIRED：运行 compilers list，按照上述规则选择所需的编译器，然后在每次证据分析中使用各自的 --compiler 并重试。
• COMPILER_NOT_FOUND：刷新编译器列表并使用精确匹配的返回名称；不要根据 displayName 猜测。
• COMPILER_DATA_NOT_FOUND：请用户恢复或重新生成所选编译器的数据文件。
• JSON 读取错误：检查文件路径、JSON 有效性和权限。
• 仅在主机的授权命令环境具备所需项目、依赖和网络访问权限时，才运行安装、构建、版本检查和 rsdoctor-agent... 命令。如果可用环境不具备这些访问权限，请停止并询问用户，而不是尝试绕过沙箱或权限边界。明确指出缺少的权限或访问；如果必须安装 Rsdoctor 依赖，请告知用户所需的依赖，并提供供其运行的相应包管理器命令。

参考资料：命令／选项 references/command-map.md；安装／配置／数据位置 references/install-rsdoctor.md、references/install-rsdoctor-rspack.md、references/install-rsdoctor-webpack.md、references/install-rsdoctor-common.md；原始数据字段 references/rsdoctor-data-types.md；常见模式 references/common-analysis-patterns.md。