---
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 自带脚本：

```bash
node <skill-root>/scripts/scan-project.js <project-root> --json
```

需要便于人工阅读时去掉 `--json`：

```bash
node <skill-root>/scripts/scan-project.js <project-root>
```

扫描器不会解析或执行 webpack 配置，也不会自动判断某个 `include` 是否覆盖具体资源。因此，扫描结果只是高召回候选集，必须继续执行下一步核实。

### 3. 按规则逐项核实

读取 [迁移规则与判定矩阵](references/migration-rules.md)，然后对每条候选项：

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. 对比迁移前预期和迁移后产物，不以“能编译”代替行为验证。

## 报告格式

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

```markdown
# Mpx mode/srcMode 迁移审计

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

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

## 需要确认
...

## 兼容清理
...

## 无需修改
...

## 验证清单
...
```

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

## 扫描器限制

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