modernjs-migrate-to-v3

name	modernjs-migrate-to-v3
description	将一个 Modern.js 2.0 应用迁移到 3.0，优先做可安全自动化的依赖/配置/入口/import 改写，剩余复杂项收敛为人工清单。在「升级 Modern.js 大版本、modern.config 报废弃、要从 webpack/pages 迁到 Rspack/routes、自定义 server 报错」时使用。

Migrate Modern.js 2.0 to 3.0

本 skill 用于单个 Modern.js 应用的 v2→v3 迁移。目标：完成可安全改写的部分，剩余风险收敛成明确人工清单。规则与示例以仓库 guides/upgrade/* 的真实文档为准。

使用原则

• 调用方先确定 projectDir，所有修改仅限 projectDir
• 不在开始时读取全部 references/；仅在命中人工项时按需加载
• 每个成功步骤结束后提交一次（见 references/commit-changes.md）

输出要求

• 进度简短：[X/6] 开始/完成/跳过/失败
• 非阻断问题记录后继续；阻断问题立即停止并说明步骤、原因、恢复方式

前置检查

git -C <projectDir> status --porcelain

工作区非空时停止，提示先 git commit/git stash。建议在干净分支或 worktree 上迁移，便于回滚。

执行步骤

步骤 1：扫描项目，生成迁移上下文

node scripts/scan-project.mjs <projectDir>

产出 <projectDir>/.agents/runs/modernjs-migrate/context.json：判定 v2/v3、Node 版本、入口类型、命中的 features 与 v2Signals。脚本失败（非 v2/v3、Node 过低）时直接停止并展示原因。migrationState=v3 按续迁移处理。

monorepo / workspace 项目：@modern-js/app-tools 用 workspace:* / link: / catalog: 等协议时无法从版本号判定大版本。此时只有命中v2-only 结构信号（顶层 runtime、appTools({ bundler })、applyBaseConfig、@modern-js/plugin-tailwindcss、@modern-js/runtime/bff|server import、App.config/init、src/pages、自定义 server/index）才判为 v2；无任何信号则视为 ambiguous 并阻断（非 0 退出、不写 context），避免把已是 v3 的 workspace 应用误迁。routes / src/modern.runtime.ts / appTools() 不算 v2 信号（v3 也有）。

约定式路由红线：entryType=routes 时，src/routes/page.* 和 src/routes/layout.* 是 v3 标准结构，必须保留。不要把 page.tsx 改名为 index.tsx，不要把 layout.tsx 挪到 legacy-*，不要凭空生成 src/entry.* 或 src/legacy-app / src/legacy-routes。如需处理 routes/layout 的 config/init 导出，只迁运行时配置逻辑，不改路由文件命名。

步骤 2：执行可安全自动化的改写

node scripts/migrate.mjs <projectDir>

自动完成（依据 guides/upgrade/*）：

• 前置自保护：workspace/link/catalog 协议 + 无任何 v2-only 信号 → 直接中止（exit 1，不改任何文件），不依赖 scan
• 目标版本：未传 --to 时会通过 npm 检测 @modern-js/app-tools@3 的最新稳定 v3 版本作为目标版本；只有需要锁定版本时才显式传 --to=<version>。如果当前环境无法访问 npm registry，脚本会中止并提示显式传入目标版本，不会回退到 3.0.0。
• 依赖：固定版本（^2.x）的 @modern-js/* 升到检测到的最新 v3 目标版本；workspace/link/catalog 协议依赖保留不改（随 monorepo 整体升级，进人工清单）；移除 @modern-js/plugin-tailwindcss
• 配置入口形态：defineConfig({}) / defineConfig<'rspack'>({}) / export default {} / module.exports = {}（JS 静态配置）均按主路径处理；函数式/动态 defineConfig(() => ({})) 含 runtime 时进人工清单
• import 路径：@modern-js/runtime/bff→@modern-js/plugin-bff/client、@modern-js/runtime/server→@modern-js/server-runtime，并补充对应依赖（@modern-js/plugin-bff / @modern-js/server-runtime；版本协议：普通 semver 用目标版本；workspace: / catalog:（名称无关）沿用现有 app-tools/runtime 的 spec；link: / file: / portal: / npm:（指向具体包路径/别名）不照搬、进人工清单）；命中 BFF 时给 modern.config 顶层 plugins 末尾追加 bffPlugin()（保持 [appTools(), bffPlugin()] 顺序；必要时在 @modern-js/app-tools import 上补 appTools；无法补则进人工清单，不写半成品）
• 健壮性（注释/字符串）：import 的检测与改写共用同一套真实 specifier 扫描器（eachModuleSpecifier，覆盖 import/export-from/side-effect import/import()/require()，含 import(/* magic */ '...') 这类带注释的动态 import）；dev/server 只在配置对象顶层迁移（嵌套 不动）；tailwind 仅删真实 import 行与真实 调用（按真实 specifier offset，不伤普通字符串/注释示例，移除后清理悬挂逗号）；注释/普通字符串里的 ///// 都不会被误当真实配置、v2 信号或 import；需要字符串「值」的判断（如 ）才保留字符串

applyBaseConfig(...) 包装的配置（仓库 integration 测试 helper / 非标准用户配置）：runtime / plugins / dev.port / appTools bundler 等结构性迁移一律进人工清单（报告标注「结构迁移未完成」），只做依赖升级 / import 路径 / tailwind 移除等文件级安全改写，不在包装内半自动改坏配置。package.json 的 modernConfig.runtime 同样进人工清单。

完成后查看 .agents/runs/modernjs-migrate/report.json 的 changed / manual。本步骤成功后执行 references/commit-changes.md。

步骤 3：按人工清单逐项处理（按需读 references）

依据 report 的 manual 列表，命中哪项读哪份：

人工项	参考
App.init / routes/layout 的 config/init 导出、modernConfig.runtime、非空/函数式 runtime	references/migrate-entry.md
自定义 Web Server（unstableMiddleware / afterRender）	references/migrate-custom-server.md
html.appIcon 字符串、server.ssr.mode、webpack 自定义配置、applyBaseConfig(...) 结构性迁移	references/migrate-config.md
useRuntimeContext as 别名 调用	references/migrate-entry.md

每处理完一项执行 references/commit-changes.md。

步骤 4：安装依赖

bash scripts/install-deps.sh <projectDir>

锁文件变更后执行 references/commit-changes.md（带 --include-lockfiles）。

步骤 5：Lint 自动修复

bash scripts/run-lint.sh <projectDir>

失败记录后继续，不视为迁移失败。

步骤 6：构建验证 + 最终报告

跑 modern build（必要时关键路由 smoke）。最终报告：成功步骤、跳过项、失败项、人工处理项、后续建议。

安全红线

• 改写优先结构化；纯文本替换仅用于无歧义项（import 路径）。
• 不手改 pnpm-lock.yaml / dist / CHANGELOG / node_modules / secret。
• 复杂、不确定项一律进人工清单，不盲目改。