用途：对单个 Modern.js 应用执行 v2→v3 迁移，先自动完成可安全改写的部分，再把剩余风险收敛为人工清单。规则以仓库 guides/upgrade/* 文档为准。
前置检查：先执行 git -C <projectDir> status --porcelain，工作区非空时停止，要求先 commit/stash；建议在干净分支或 worktree 上迁移。
主要能力（六步）：1）扫描项目生成迁移上下文：node scripts/scan-project.mjs <projectDir>，产出 .agents/runs/modernjs-migrate/context.json，判定 v2/v3、Node 版本、入口类型等；monorepo 无 v2-only 信号时视为 ambiguous 阻断。2）执行自动改写：node scripts/migrate.mjs <projectDir>，含依赖升级（未传 --to 时检测 @modern-js/app-tools@3 最新稳定版）、配置入口形态、import 路径改写、appTools({ bundler })→appTools()、modern.config 顶层 runtime 合并进 src/modern.runtime.ts、dev.port→server.port、v3 配置项改名、移除 @modern-js/plugin-server、src/index.→src/entry.、src/pages→src/routes、useRuntimeContext 迁移、删除 modern new/upgrade 脚本等。产物见 report.json 的 changed/manual。3）按人工清单逐项处理并参考对应 references。4）安装依赖：bash scripts/install-deps.sh <projectDir>。5）Lint 修复：bash scripts/run-lint.sh <projectDir>，失败记录后继续。6）跑 modern build 构建验证并输出最终报告。
约定式路由红线：entryType=routes 时 src/routes/page.* 与 layout.* 必须保留，不得改名或凭空生成 src/entry.*。
限制：不手改 pnpm-lock.yaml、dist、CHANGELOG、node_modules、secret；复杂或不确定项一律进人工清单，不盲目改；无法访问 npm registry 时脚本中止并要求显式传入目标版本。