在已有 rsdoctor-data.json 时分析…

适用于需要基于本地 rsdoctor-data.json 对 Rspack/Webpack 产物做只读、证据优先的包体积与构建性能分析与优化建议。

适用场景

解决思路

1. 仅在真实 `rsdoctor-data.json` 路径存在后，使用全局安装的 `rsdoctor-agent` CLI（来自 `@rsdoctor/agent-cli`）。除非用户明确要求安装/配置，否则保持分析只读。
2. 响应必须按规定顺序输出：高优先级问题 -> 建议解决方案 -> 可选的引用链后续选择 -> 下一步深入分析的问题类别（不是命令）。
3. 在新分析前，先复用当前会话结果和有效的 `.rsdoctor-analysis-cache.json` 条目。
4. 快速定位 `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` 当作索引。
5. 若数据存在，跳过所有插件版本/配置/构建生成逻辑；必要时更新缓存。
6. 若数据缺失，停止分析：不运行 `rsdoctor-agent` 分析命令，不运行 Analysis Gate；要么询问数据路径，要么仅在需要安装/生成时运行 Generation Gate。
7. 真实数据文件存在后，在第一个 `rsdoctor-agent` 数据获取命令前最多运行一次 Analysis Gate：用 `npm view @rsdoctor/agent-cli version` 和 `rsdoctor-agent --version` 验证全局 `@rsdoctor/agent-cli`；仅在缺失/过旧、出现版本相关错误或用户要求刷新时安装最新版。
8. 先只获取 Default Evidence Set；能并行时并行运行独立获取。
9. 选择深入命令或建议前运行 ROI Triage Gate；用它按可测量影响给问题类别排序，然后按规定响应顺序综合发现。
10. 性能规则：并行执行独立检查；只缓存派生事实（`dataFile`、`dataFileMtime`、`pluginName`、`pluginVersion`、依赖/配置/插件修改时间）；当路径消失、修改时间变化、用户要求刷新或缓存值失效时使缓存失效。
11. 推测性插件检查不得触发构建生成；仅在确认数据文件缺失后使用。
12. 在推荐修复前，把当前构建按成本桶分类，并从证据而非直觉选择最高 ROI 杠杆；该 gate 适用于 Rspack/Webpack 项目；除非用户项目数据暴露框架特定运行时层，不要使用框架特定运行时层。
13. Assets/media 成本桶：证据来自 `assetsTop`、`assets media`、`chunkGraph.assets`；首选杠杆：压缩、转换、去重、子集化或懒加载大资源。
14. Large packages/modules 成本桶：证据来自 `packagesTop`、模块/包大小字段；首选杠杆：替换重包、使用 deep imports、拆分非关键代码或审查直接依赖选择。
15. Duplicate/cross-chunk cost 成本桶：证据来自 E1001/E1002、`packages duplicates`、跨 chunk 包汇总；首选杠杆：去重版本、调整包解析或调整 `splitChunks`/cache groups。
16. Tree-shaking waste 成本桶：证据来自 `retainedModulesTop`、保留的 CJS/barrel/side-effects 模块；首选杠杆：修复 CJS/barrel imports、sideEffects 声明或包入口点。
17. Build-time cost 成本桶：证据来自 `buildCost`、loaders/plugins/directories cost data；首选杠杆：优化 loaders/plugins、缓存、watcher 或 source-map/dev 设置；仅当用户询问构建性能时优先处理。
18. ROI 决策规则：当测得的分解会改变推荐优先级时，先报告该分解。
19. 从映射到可实践修复的最大成本桶开始；较小问题不应排在较大问题之前，除非较大问题是预期内或有意不可避免的。
20. 将 issuer/reference-chain tracing 视为第二轮工作：仅在需要所有权证据的高影响候选，或用户问“why”/“who imported this”时运行。
21. 不要将聚合规则输出作为需要具体文件、包、chunk、大小或依赖路径的修复的充分证据。
22. 如果最大成本桶是结构性的或有意要求的，说明它是墙，并指出需要的外部变更，而不是发明低影响的源码编辑。
23. 确定 `pluginName`（`@rsdoctor/rspack-plugin` 或 `@rsdoctor/webpack-plugin`），并先从本地文件确定 `pluginVersion`：`package.json`、lockfile，再到 `node_modules/<plugin>/package.json`；仅将 `pnpm why` / `npm ls` 作为 fallback。
24. 使用精确 if/else 决策树且不要合并分支：如果 `pluginName` 缺失：安装/注册匹配的 Rsdoctor 插件，然后配置 `output.mode='brief'` 和 `output.options.type=['json']`；仅用 `RSDOCTOR=true` 构建。
25. 否则如果 `pluginVersion` 未知：先解析 `pluginVersion`；若仍未知，配置 `output.mode='brief'` 和 `output.options.type=['json']`；仅用 `RSDOCTOR=true` 构建。
26. 否则如果 `pluginVersion >= 1.5.11`：不要仅为 JSON 编辑插件配置；如有需要，用 `RSDOCTOR_OUTPUT=json` 和 `RSDOCTOR=true` 构建。
27. 否则（`pluginVersion < 1.5.11`）：必须配置 `output.mode='brief'` 和 `output.options.type=['json']`；仅用 `RSDOCTOR=true` 构建。
28. 对每个构建命令做预检：`RSDOCTOR_OUTPUT=json` 只允许在 `pluginVersion >= 1.5.11` 分支中使用；对于缺失、未知或 `< 1.5.11`，禁止使用。
29. 对于 `< 1.5.11`，生成 `rsdoctor-data.json` 需要插件配置：`output: { mode: 'brief', options: { type: ['json'] } }`。
30. Default Evidence Set：`buildCost` 来自 `build summary`，仅过滤字段。
31. `assetsTop` 来自按 raw/gzip 大小的 top assets，固定 Top-N。
32. `packagesTop` 来自按 gzip 大小的 top packages，固定 Top-N；避免完整 `packages list` 分页。
33. `duplicatePackages` 来自 E1001 duplicate package summary，仅首轮摘要。
34. `crossChunkPackages` 来自 E1002 cross-chunk duplication summary，仅首轮摘要。
35. `retainedModulesTop` 来自 `tree-shaking retained-modules --limit 10`，仅过滤字段；不要用 `--compact`。
36. Scope rules：仅在 `rsdoctor-data.json` 存在后，用 `rsdoctor-agent` 访问 bundle 数据；优先并行独立获取；用 `--filter`、分页和 `--limit` 限制输出。
37. 默认分析保持在 Default Evidence Set 内。非默认分析从 `references/rsdoctor-data-types.md` 选择最小字段，从 `references/common-analysis-patterns.md` 选择模式。
38. 将链追踪、宽泛命令、优化编辑、splitChunks 实验和重新构建视为需要用户确认的 opt-in follow-ups。
39. 对于重复包和 tree-shaking 问题，先识别问题；仅在用户确认后追踪 reference/import 链。
40. 对 side-effects 调查，优先用 `tree-shaking retained-modules --emitted-only --category side-effects --limit 10` 并配合窄 `--filter`。
41. 对保留的 emitted modules，使用 `tree-shaking retained-modules` 并带 `--emitted-only`、有界 `--category`、`--sort gzipSize`、`--limit` 和窄 `--filter`；不要传 `--compact`。
42. 仅当字段缺失或需要聚合上下文时，将 `tree-shaking summary` 作为 fallback。将 `tree-shaking bailout-reasons` 视为高产出量；仅在明确要求时运行，并传入目标 `--modules`（最多 100）。
43. 如果任何命令超过 `5k` tokens、`500 KB` 原始输出或几百行 transcript，停止宽泛获取，切换为目标明确的紧凑查询。
44. 输出格式第 1 部分：当前构建中发现的问题和推荐修复；将每个问题和其修复建议分组；包含具体证据（大小/时间/计数/路径/规则码）和优先级；对重复包和 tree-shaking 问题，包含简短的“继续追踪还是停在这里”选择。
45. 输出格式第 2 部分：是否仍需更深分析；只列剩余问题类别，不列命令。
46. 对 Top-N 洞察，优先用表格：`Name | Volume/Time | Count | Recommendation`。
47. 恢复规则：`rsdoctor-data.json` 缺失：不运行 `rsdoctor-agent`；询问数据路径或运行 Generation Gate，然后若需要设置则使用匹配的安装参考。
48. 恢复规则：命令未找到：运行 Analysis Gate，然后用 `rsdoctor-agent` 重试。
49. 恢复规则：`query` 报告未知 tool：运行 `list` 并使用目录中的 tool 名称，或切换到直接 `<group> <subcommand>` 模式。
50. 恢复规则：JSON 读取错误：验证文件路径、JSON 有效性和权限。
51. 仅在宿主授权且具备所需项目、依赖和网络访问的命令环境中运行安装、构建、版本检查和 `rsdoctor-agent...` 命令。如果可用环境缺少该访问权限，停止并询问用户，而不是尝试绕过沙箱或权限边界。清楚说明缺少的权限或访问；如果必须安装 Rsdoctor 依赖，告诉用户需要哪个依赖，并提供合适的包管理器命令让其运行。
52. 参考查询：命令/选项见 `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`。

适用边界 · 注意事项

• 没有任何真实 `rsdoctor-data.json` 时，不要运行 `rsdoctor-agent` 分析命令或 Analysis Gate；应先找路径或走 Generation Gate。
• 不要将链追踪、宽泛命令、优化编辑、splitChunks 实验、重新构建当作默认动作；需要用户确认才做。
• 不要将聚合规则输出当作需要具体文件/包/chunk/大小/依赖路径的修复证据；也不要绕过沙箱或权限边界。