| name | mpx-mode-migration |
| description | 审计存量 Mpx 项目迁移到“mode 只负责目标筛选、srcMode 只负责源码方言”的新版编译语义。只要用户提到升级 Mpx 后检查条件编译、排查 .ali/.swan 等条件文件、mode/src-mode 区块、@mode/@_mode、modeRules/srcModeRules 或外部模板迁移，就应使用本 Skill；不用于与该语义变更无关的普通 Mpx 升级。 |
| compatibility | 需要 Node.js 14+；扫描脚本只读取目标项目，不会自动修改业务文件。 |
Mpx mode/srcMode 升级迁移审计
目标
找出存量项目中依赖旧版隐式源码方言语义的位置，并把每一处候选项核实为：
必须修改：升级后会冲突或明确依赖旧语义；需要确认：编译路径改变，需结合源码或目标产物判断；兼容清理：旧写法仍兼容，但建议迁移到新名称或新语法；无需修改：命中扫描规则，但实际不依赖旧语义。
默认只输出审计报告。用户明确要求实施迁移时，才修改目标项目。
工作流
1. 确定项目和目标
- 将用户指定目录作为项目根目录；未指定时使用当前工作目录。
- 读取目标项目的
AGENTS.md、构建配置、package.json 和相关迁移约束。
- 确认项目
srcMode、实际构建 targets，以及是否使用 Web/RN。不要只根据文件名猜测构建目标。
2. 运行确定性扫描
使用本 Skill 自带脚本：
node <skill-root>/scripts/scan-project.js <project-root> --json
需要便于人工阅读时去掉 --json：
node <skill-root>/scripts/scan-project.js <project-root>
扫描器不会解析或执行 webpack 配置，也不会自动判断某个 include 是否覆盖具体资源。因此，扫描结果只是高召回候选集，必须继续执行下一步核实。
3. 按规则逐项核实
读取 迁移规则与判定矩阵，然后对每条候选项：
- 打开完整文件或 SFC 区块，不要只看命中行。
- 判断内容采用项目
srcMode 语法，还是目标平台原生语法。
- 检查资源是否已经被有效的
srcModeRules.<target> 覆盖；不要仅凭配置中出现了该 key 就判定已覆盖。
- 模板包含
<import> / <include> 时，继续解析相对路径并检查被引用资源；它们不继承引用方 srcMode。
- 显式
@mode 命中后会进入正常平台转换。逐项确认节点、属性名及属性值采用项目 srcMode 语法，还是目标平台原生语法，并以目标项目实际安装的 @mpxjs/webpack-plugin/lib/platform 实现核对是否命中转换规则。使用本 Skill 的 scripts/resolve-platform.js <project-root> 定位规则目录，不要直接解析包内 package.json 或依赖当前工作目录。读取 lib/platform/index.js 确定 type + srcMode 对应的规则集，再检查具体规则的 test 与目标 mode 处理器；两者同时存在才算实际命中。项目 srcMode 语法通常无需迁移；目标平台原生语法未实际命中规则时可安全直通并归入“无需修改”。只有规则会重命名、改值、删除或诊断该语法时，才优先建议改成项目 srcMode 的等价写法；没有等价写法时改用完整原生区块/资源。报告中记录插件安装版本、命中的规则文件及行号。
- RN 候选项涉及组件、事件或样式能力时，结合仓库的
mpx2rn Skill 核对支持范围，不要用 RN 原生能力替代 Mpx2RN 能力事实。
4. 给出最小迁移建议
按以下优先级选择方案：
- 优先把内容改成项目
srcMode 语法，让框架正常转换。
- 完整目标平台原生 SFC 区块增加
src-mode="<target>"。
- 完整目标平台原生文件或独立模板通过
srcModeRules.<target> 精确覆盖。
- 旧
modeRules 可兼容，但建议改名为 srcModeRules；两者不能同时配置。
@_mode 与 @mode 行为一致，替换属于兼容清理，不是阻塞升级的必改项。
不要为了消除报告而给整个 src/ 配置宽泛的 srcModeRules。规则过宽会让本应转换的 Mpx 源码被当成目标平台原生源码。
对 @mode 不要仅凭“目标平台原生写法”要求迁移，也不要根据其他版本的源码或记忆推断规则。以目标项目安装版本的 lib/platform 为准；没有实际命中时允许安全直通，不拦截也不建议改写。
5. 验证
若用户要求实际修改：
- 先为确认需要迁移的路径补核心回归用例。
- 分目标平台执行相关编译，重点检查模板事件/指令、JSON 转换和运行时选项转换。
- RN 页面或组件同时按
mpx2rn Skill 的编译校验流程验证。
- 执行目标项目要求的 ESLint 与 Jest。
- 对比迁移前预期和迁移后产物，不以“能编译”代替行为验证。
报告格式
使用以下结构，并给每条结论附可点击的文件与行号：
# Mpx mode/srcMode 迁移审计
## 摘要
- 必须修改：N
- 需要确认：N
- 兼容清理：N
- 无需修改：N
## 必须修改
### [规则码] path/to/file:line
- 旧语义依赖：
- 升级后行为：
- 迁移建议：
- 验证方式：
## 需要确认
...
## 兼容清理
...
## 无需修改
...
## 验证清单
...
如果没有必改项，明确写出“未发现确定需要修改的位置”，同时保留仍需确认的候选项和未执行的构建目标。
扫描器限制
- 正则扫描无法可靠理解通过变量、函数或多文件合并生成的 webpack 配置。
srcModeRules 的 include/exclude 最终覆盖范围需要按 webpack rule 语义人工核实。- 目标平台原生语法可能与项目
srcMode 语法同名，不能只凭一个属性名自动判定。
- 动态生成的模板、loader 虚拟模块和构建期代码生成结果不在静态扫描范围内。
