mpx-mode-migration

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. 确定项目和目标

1. 将用户指定目录作为项目根目录；未指定时使用当前工作目录。
2. 读取目标项目的 AGENTS.md、构建配置、package.json 和相关迁移约束。
3. 确认项目 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. 按规则逐项核实

读取 迁移规则与判定矩阵，然后对每条候选项：

1. 打开完整文件或 SFC 区块，不要只看命中行。
2. 判断内容采用项目 srcMode 语法，还是目标平台原生语法。
3. 检查资源是否已经被有效的 srcModeRules.<target> 覆盖；不要仅凭配置中出现了该 key 就判定已覆盖。
4. 模板包含 <import> / <include> 时，继续解析相对路径并检查被引用资源；它们不继承引用方 srcMode。
5. 显式 @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 的等价写法；没有等价写法时改用完整原生区块/资源。报告中记录插件安装版本、命中的规则文件及行号。
6. RN 候选项涉及组件、事件或样式能力时，结合仓库的 mpx2rn Skill 核对支持范围，不要用 RN 原生能力替代 Mpx2RN 能力事实。

4. 给出最小迁移建议

按以下优先级选择方案：

1. 优先把内容改成项目 srcMode 语法，让框架正常转换。
2. 完整目标平台原生 SFC 区块增加 src-mode="<target>"。
3. 完整目标平台原生文件或独立模板通过 srcModeRules.<target> 精确覆盖。
4. 旧 modeRules 可兼容，但建议改名为 srcModeRules；两者不能同时配置。
5. @_mode 与 @mode 行为一致，替换属于兼容清理，不是阻塞升级的必改项。

不要为了消除报告而给整个 src/ 配置宽泛的 srcModeRules。规则过宽会让本应转换的 Mpx 源码被当成目标平台原生源码。

对 @mode 不要仅凭“目标平台原生写法”要求迁移，也不要根据其他版本的源码或记忆推断规则。以目标项目安装版本的 lib/platform 为准；没有实际命中时允许安全直通，不拦截也不建议改写。

5. 验证

若用户要求实际修改：

1. 先为确认需要迁移的路径补核心回归用例。
2. 分目标平台执行相关编译，重点检查模板事件/指令、JSON 转换和运行时选项转换。
3. RN 页面或组件同时按 mpx2rn Skill 的编译校验流程验证。
4. 执行目标项目要求的 ESLint 与 Jest。
5. 对比迁移前预期和迁移后产物，不以“能编译”代替行为验证。

报告格式

使用以下结构，并给每条结论附可点击的文件与行号：

# Mpx mode/srcMode 迁移审计

## 摘要
- 必须修改：N
- 需要确认：N
- 兼容清理：N
- 无需修改：N

## 必须修改
### [规则码] path/to/file:line
- 旧语义依赖：
- 升级后行为：
- 迁移建议：
- 验证方式：

## 需要确认
...

## 兼容清理
...

## 无需修改
...

## 验证清单
...

如果没有必改项，明确写出“未发现确定需要修改的位置”，同时保留仍需确认的候选项和未执行的构建目标。

扫描器限制

• 正则扫描无法可靠理解通过变量、函数或多文件合并生成的 webpack 配置。
• srcModeRules 的 include/exclude 最终覆盖范围需要按 webpack rule 语义人工核实。
• 目标平台原生语法可能与项目 srcMode 语法同名，不能只凭一个属性名自动判定。
• 动态生成的模板、loader 虚拟模块和构建期代码生成结果不在静态扫描范围内。