diff --git a/.agents/skills/mpx2web/SKILL.md b/.agents/skills/mpx2web/SKILL.md
new file mode 100644
index 0000000000..42e56ae6d9
--- /dev/null
+++ b/.agents/skills/mpx2web/SKILL.md
@@ -0,0 +1,305 @@
+---
+name: mpx2web
+description: Mpx 跨端输出 Web（简称 Mpx2Web）的开发适配指南，覆盖模板、脚本、样式、JSON 配置四大维度，以及路由部署、SEO/SSR、H5 生态混合开发等 Web 专属能力。当用户要求对已有 Mpx 组件进行 Web 跨端适配改造、创建符合 Web 跨端兼容规范的 Mpx 组件、排查 Mpx2Web 编译报错或查询某项能力（模板指令、基础组件、样式属性、生命周期、环境 API、JSON 字段、路由/部署等）在 Web 平台的支持情况时强制调用。当用户问题不涉及 Mpx 跨端输出 Web 时不应调用，如小程序原生开发问题、纯前端 Vue 开发问题、RN 端适配问题等。
+metadata:
+  version: "1.0.0"
+  author: wangcuijuan
+---
+
+# Mpx 跨端输出 Web 开发与适配指南
+
+## 背景介绍
+
+Mpx 是一个以微信小程序语法为基础、进行了类 Vue 语法拓展支持的跨端开发框架，支持将同一套代码输出到小程序（微信、支付宝、百度等）、Web 和 React Native 平台。其中 **Web（`mode === 'web'`）是 Mpx 起步最早、能力最完整、与小程序原平台语义最接近的输出端**：编译产物基于 **Vue 2.7**，经 webpack / vue-loader 生成真实 DOM 应用，绝大多数小程序模板、样式、逻辑写法可直接等效运行。
+
+正因为 Web 兼容度高，本 SKILL 的核心**不是**罗列"Web 不支持什么"的长清单，而是聚焦三类真正需要处理的问题：
+
+1. **小程序专属能力在 Web 的降级 / 缺失**（如 `onShareAppMessage`、`open-data`、部分依赖原生硬件的 API/组件）。
+2. **Web 独有且必须正确配置的能力**（路由模式与部署路径、`rpx` 单位换算、SEO/SSR、移动端适配）。
+3. **跨平台兼容约束**：产物须在原平台与 Web 平台均能正常运行，避免引入只在 Web 生效、却破坏小程序原平台的写法。
+
+本 SKILL 面向以下两类任务：
+
+1. **任务一**：对已有的 Mpx 组件进行 Web 跨端适配改造（已基于小程序规范编写、需补齐 Web 兼容性）。
+2. **任务二**：从零创建一个符合 Web 跨端兼容规范的 Mpx 组件。
+
+## Mpx 单文件组件（SFC）结构
+
+Mpx 页面/组件以 `.mpx` 为扩展名，将视图、逻辑、样式、配置封装在一个文件中，由以下区块组成（对应小程序的 wxml/js/wxss/json 四个文件）：
+
+- `<template>`：视图模板，微信小程序基础模板语法 + Mpx 的类 Vue 指令（如 `wx:if`、`wx:for`、`wx:model` 等）。
+- `<script>`：组件逻辑，支持选项式与组合式 API（`@mpxjs/core` 的 `createComponent` / `createPage` / `ref` / `computed` 等）。
+- `<style>`：样式，支持 Stylus / Sass / Less 等预处理器。
+- `<script type="application/json">`：JSON 配置，如 `usingComponents` 组件注册等。
+
+最小示例：
+
+```html
+<template>
+  <view class="container">{{ title }}</view>
+</template>
+
+<script>
+  import { createComponent, ref } from '@mpxjs/core'
+  createComponent({
+    setup () {
+      const title = ref('hello world')
+      return { title }
+    }
+  })
+</script>
+
+<script type="application/json">
+  { "usingComponents": {} }
+</script>
+
+<style lang="stylus">
+  .container
+    flex 1
+</style>
+```
+
+上述四个区块在 Web 输出下的具体跨端能力与差异，分别见下方知识库索引中的模板 / 脚本 / 样式 / JSON 能力参考。
+
+## 知识库索引
+
+| 知识库 | 说明 |
+| --- | --- |
+| [条件编译](./references/conditional-compile.md) | 模板、脚本、样式、JSON 等不同部分的条件编译语法，遇到无法跨端等效实现需分平台处理时读取 |
+| [跨端输出 Web 模板能力参考](./references/web-template-reference.md) | 模板部分跨端能力详情：数据绑定、模板指令、事件、Slot、WXML 模板、i18n、无障碍访问、基础组件清单及其属性/事件在 Web 的支持与降级情况 |
+| [跨端输出 Web 脚本能力参考](./references/web-script-reference.md) | 脚本部分跨端能力详情：构造选项、生命周期、实例方法/属性、组合式 API、运行时导出、状态管理 |
+| [跨端输出 Web 样式实践](./references/web-style-practice.md) | Web 样式差异与实践：`rpx` 换算、移动端适配、安全区域、固定定位、Web 专属 CSS 隔离 |
+| [跨端输出 Web 环境 API 参考](./references/web-api-reference.md) | `@mpxjs/api-proxy` 提供的环境 API 在 Web（H5 实现）的支持情况，涉及网络、存储、界面、设备、媒体、位置等及其浏览器限制 |
+| [跨端输出 Web JSON 配置参考](./references/web-json-reference.md) | 应用、页面、组件三层 JSON 配置在 Web 平台的支持范围与差异（含 `tabBar`、分包、路由与 SSR 相关配置） |
+| [Mpx 与 H5 生态混合开发](./references/web-hybrid-dev.md) | 在 `.mpx` 内使用原生 DOM、第三方 H5 SDK / Vue 组件的方式与跨端隔离方案 |
+
+### 知识库使用建议
+
+参考文档体量较大，**不要一次性预读全部参考**，按需取用即可：
+
+1. **入口只读本 SKILL.md**：完整读完本文档（含下方通用约束与任务流程）足以覆盖大多数常见场景的判断；不要在动笔前预读 references 目录。
+2. **触发式读取**：只在任务流程或通用约束中**明确指向**某份参考时读取，且仅读取与当前问题相关的小节（参考文档均含目录与章节锚点，使用 grep / 锚点跳读，不要整文件 Read）。
+3. **典型任务的最小阅读集**（仅当本 SKILL.md 已无法判断时再补充）：
+   - 已有组件 Web 跨端适配改造：Web 兼容度高，多数情况无需改动模板/样式主体；识别问题维度后再读对应能力参考的相关小节（如 API 降级查 `web-api-reference.md`、单位/适配查 `web-style-practice.md`）。
+   - 新建 Web 跨端兼容组件：先按本 SKILL.md 的通用约束起手，遇到能力存疑（某 API 是否存在、某组件是否降级）时再点查对应参考。
+   - 排查特定编译报错：直接定位到报错维度的能力参考相关小节。
+
+## 通用约束与适配原则
+
+无论是适配改造还是新建组件，跨端兼容均需严格遵循以下通用约束。**Web 输出与小程序原平台语义高度一致，几乎不需要为兼容而改写小程序原有写法，约束主要集中在"小程序专属能力在 Web 的降级"与"Web 专属能力的正确配置"两侧。**
+
+### 跨平台兼容约束
+
+产物代码须在原平台（小程序）与 Web 平台均能正常运行。引入「Web 支持但小程序不支持」的写法（如直接使用 DOM API、`window` 对象、第三方 H5 SDK 等）时，**不要替换小程序已有写法**，而应：
+
+- 用条件编译将该 Web 写法限定在 Web 平台输出（模板属性后缀 `@web`、样式与脚本 `@mpx-if` 包裹等）；
+- 同步用条件编译保留小程序原有写法，避免改造引入小程序行为退化。
+
+该原则贯穿模板 / 脚本 / 样式 / JSON 四个维度。
+
+### 模板（template）约束
+
+1. **基础组件优先**：使用 [模板能力参考 · 基础组件](./references/web-template-reference.md#基础组件) 中标注 Web 支持的基础组件与其支持属性/事件。多数小程序基础组件在 Web 有等效实现，但少数**依赖原生硬件或小程序开放能力**的组件（如 `camera` / `live-player` / `live-pusher` / `open-data` / `official-account` / `ad` 等）在 Web 不支持或仅部分降级，需查参考确认；`web-view` 在 Web 渲染为 `iframe`，行为与小程序有差异。
+2. **页面滚动**：Web 页面默认可滚动，`onPageScroll` / `onReachBottom` / `onPullDownRefresh` 等页面滚动相关生命周期在 Web **支持**（由 Mpx Web 运行时实现，行为与小程序对齐）；具体差异见 [脚本能力参考 · 生命周期](./references/web-script-reference.md#生命周期)。
+3. **模板内方法调用**：跨端通用约束下，模板 Mustache 表达式应避免普通方法调用，需通过 `computed` / `wxs` 实现（i18n 翻译函数除外），以保持与其他平台一致。
+4. **i18n**：组合式 API 中 `useI18n()` 解构出的翻译函数须以原名 `t` / `tc` / `te` / `tm` 暴露至模板的 `return`，禁止重命名。
+5. **事件传参**：传递自定义参数给事件处理器时，优先使用事件内联传参语法（如 `bindtap="handleTap('param')"`），而不是通过 `data-` dataset 属性传参，以保持跨端一致。
+6. **对象字面量 key 禁止加引号**：在模板插值（`wx:style` / `wx:class` 等）中使用对象字面量时，key **不允许**使用单引号或双引号包裹，否则会导致微信小程序模板编译报错。应使用 camelCase 形式的无引号 key。
+   - **Bad Example**: `wx:style="{{{'background-image': '...'}}}"`
+   - **Good Example**: `wx:style="{{{backgroundImage: '...'}}}"`
+7. **文字使用 `text` 包裹**：保持与小程序及其他端一致，文字内容优先使用 `text` 组件显式包裹，避免依赖平台隐式行为。
+
+### 脚本（script）约束
+
+1. **生命周期 / 构造选项**：仅使用 [脚本能力参考](./references/web-script-reference.md) 中标注 Web 支持的生命周期与构造选项；小程序专属的分享与 tab 相关生命周期（`onShareAppMessage` / `onShareTimeline` / `onAddToFavorites` / `onTabItemTap` 等）在 Web 无等效，须用条件编译隔离或确认可降级。
+2. **环境 API**：通过 `@mpxjs/api-proxy` 提供的统一 `mpx.xxx` API 调用环境能力，避免直接使用 `wx.xxx` / `my.xxx`；Web 端由 api-proxy 映射为 H5 实现，部分依赖原生硬件的能力（蓝牙、NFC、部分传感器等）受浏览器限制不可用或需降级，具体支持范围见 [环境 API 参考](./references/web-api-reference.md)；如用户通过 `custom` 配置扩充拓展了环境 API 能力，以用户说明为准。
+3. **路由跳转统一使用 Mpx 导航 API**：Mpx 自带一套与微信小程序对齐的跨端路由逻辑，页面跳转统一使用 `mpx.navigateTo` / `mpx.redirectTo` / `mpx.switchTab` / `mpx.navigateBack` / `mpx.reLaunch`（编译到 Web 时由 Mpx 内部映射到 Web 路由）。**禁止在 `.mpx` 中直接引入 `vue-router` 或手写 Web 路由跳转**，以免破坏跨端一致性。详见 [环境 API 参考](./references/web-api-reference.md)。
+4. **直接使用浏览器能力须隔离**：直接访问 `window` / `document` / DOM、第三方 H5 SDK 等仅 Web 可用的能力时，必须用条件编译限定在 Web 平台，并保留小程序侧等效逻辑，详见 [H5 生态混合开发](./references/web-hybrid-dev.md)。
+4. **selector API**：`selectComponent` / `createSelectorQuery` 等在 Web 的 selector 语法与微信小程序保持一致（ID、class、子元素 `>`、后代、跨组件后代 `>>>`、并集 `,` 等），直接基于真实 DOM 查询即可。详见 [脚本能力参考 · 实例方法与属性](./references/web-script-reference.md#页面--组件实例方法与属性)。
+
+### 样式（style）约束
+
+> **样式兼容度**：Web 基于真实 CSS 引擎，小程序中使用的复合选择器、伪类、伪元素、`grid` / `float`、媒体查询等 CSS 写法在 Web 均可直接使用，**无需为兼容而改写**。Web 样式约束主要集中在 `rpx` 单位换算与移动端适配。
+
+1. **样式能力判断口径**：Web 基于真实 CSS 引擎，绝大多数 CSS 属性与选择器可直接使用，无需逐项兼容改造；差异点见 [Web 样式实践](./references/web-style-practice.md)。
+2. **`rpx` 单位换算**：Web 端 `rpx` 默认会换算为视口单位 `vw`（以 750rpx 对应 100vw 为基准），详见 [Web 样式实践 · 单位与适配](./references/web-style-practice.md#单位与适配)。
+3. **优先使用模板指令进行动态样式绑定**：使用 `wx:class` / `wx:style` 指令，避免在 `class` / `style` 属性内拼接 `{{}}` 插值表达式（跨端通用约束）。
+   - **Bad Example**: `<view class="item {{isActive ? 'active' : ''}}">`
+   - **Good Example**: `<view class="item" wx:class="{{ {active: isActive} }}">`
+4. **保留单位注释**：保留原始样式中的 `/*use rpx*/` 与 `/*use px*/` 注释，编译期会据此批量切换样式单位。
+5. **Web 专属写法须隔离**：若使用仅 Web 生效、小程序不支持的 CSS（如 `::-webkit-scrollbar` 伪元素、`vh`/`vw` 视口单位等），按需用样式条件编译隔离，并保留小程序侧等效写法，避免破坏原平台。常见兼容方案见 [Web 样式实践](./references/web-style-practice.md)。
+
+### JSON 配置约束
+
+1. **支持范围**：应用、页面、组件三级 JSON 配置在 Web 平台的字段支持详情见 [JSON 配置参考](./references/web-json-reference.md)。小程序中常用的 `tabBar` 在 Web **支持**（Mpx 渲染等效 tabbar）；但部分小程序专属字段（如 `workers`、`plugins`、云开发相关）在 Web 不支持，须通过条件编译隔离。
+2. **路由与 SSR 相关配置**：`pages`、`subPackages`、页面 `navigationBar*`、`webConfig.routeConfig`、`webConfig.useSSR` 等在 Web 有对应行为，详见 [JSON 配置参考](./references/web-json-reference.md)。
+3. **动态生成配置**：当需要分平台或分环境定义 JSON 配置时，使用 `<script name="json">` 形式访问 `__mpx_mode__` / `__mpx_env__` 变量动态生成。
+
+### 条件编译约束
+
+当某项能力无法在 Web 平台等效实现，或需引入 Web 专属能力时，使用条件编译进行分平台处理：
+
+- 小程序原平台条件：`__mpx_mode__ === 'wx' || __mpx_mode__ === 'ali'`（按项目实际目标小程序补充 `swan`/`qq`/`tt`/`jd`）
+- Web 平台条件：`__mpx_mode__ === 'web'`
+- 如同时维护 RN，请额外覆盖 `ios` / `android` / `harmony`
+
+需遵循以下约束：
+
+1. **最小化使用**：条件编译是处理跨端不兼容的**最后手段**，不是首选方案。Web 兼容度高，多数能力无需条件编译；使用前应先确认是否存在无需条件编译的跨端兼容写法。需要时仅最小包裹真正不兼容的片段，不要整段代码都用条件编译分叉。
+2. **避免空选择器**：样式条件编译产物中不得留下空选择器（无样式内容的选择器），整条规则（含选择器与花括号内容）须一并被条件编译包裹。详见 [条件编译 · 避免产物中出现空选择器](./references/conditional-compile.md#避免产物中出现空选择器)。
+3. **缩进敏感预处理器（stylus / sass 等）中条件编译注释须与所在块体同级缩进**：mpx 会将指令注释和未命中分支替换为等长占位注释，占位注释保留原缩进。指令注释若顶格写在缩进块内部，会截断块上下文，触发 `expected "indent", got "outdent"` 等解析错误。
+4. **各区块使用对应的条件编译语法**：样式条件编译使用 `/* @mpx-if (__mpx_mode__ === ...) */` 注释语法；模板条件编译使用 `wx:if="{{__mpx_mode__ === ...}}"` 指令或 `@mode` / `@_mode` 属性后缀；脚本和 JSON 配置条件编译使用 `if (__mpx_mode__ === ...)` 条件语句，**避免误用**，详情参考 [条件编译](./references/conditional-compile.md)。
+
+## 任务一：对已有 Mpx 组件进行 Web 跨端适配改造
+
+### 输入
+
+基于小程序技术规范编写的 `{name}.mpx` 组件（已在小程序平台运行，但未适配 Web）。
+
+### 输出
+
+以用户指示为准；若无特殊指示则默认在原文件 `{name}.mpx` 中进行修改。输出修改后代码时应输出完整组件代码，避免使用省略号，确保用户可以直接复制或应用修改。
+
+> **提示**：Web 兼容度高，大量小程序组件无需任何改动即可输出 Web。改造前先快速判断是否真的存在不兼容点（多为小程序专属 API / 组件、或需要 Web 专属能力），避免无谓改写。
+
+### 任务流程
+
+#### 1. 模板（template）适配改造
+
+- 读取 [模板能力参考](./references/web-template-reference.md)，重点核对是否使用了在 Web **不支持或降级**的基础组件（`camera` / `live-*` / `open-data` 等）及其属性/事件；常规组件无需改动。
+- 检查动态 `class` / `style` 是否使用了 `{{}}` 拼接字符串，统一改造为 `wx:class` / `wx:style` 指令绑定（跨端通用规范）。
+- 对于无法等效实现的部分使用 [模板条件编译](./references/conditional-compile.md#模板条件编译)（`@mode` / `@_mode` / `mpxTagName@mode`）进行平台隔离，并添加 `todo` 注释记录差异原因。
+
+#### 2. 脚本（script）适配改造
+
+- 读取 [脚本能力参考](./references/web-script-reference.md) 与 [环境 API 参考](./references/web-api-reference.md)，核对生命周期、构造选项、实例方法与环境 API 在 Web 的支持情况，重点关注小程序专属能力（分享、tab、原生硬件 API）。
+- 平台直连 API（如 `wx.xxx` / `my.xxx`）统一替换为 `mpx.xxx` 接入 `@mpxjs/api-proxy` 抹平的实现。
+- 路由跳转保持使用 `mpx.navigateTo` 等统一导航 API，不要替换为 `vue-router`；若存在直接引入 `vue-router` 的写法，改回 Mpx 导航 API。
+- 直接使用 `window` / `document` / 第三方 H5 SDK 的 Web 专属逻辑，用 [脚本条件编译](./references/conditional-compile.md#脚本条件编译) 限定在 Web 平台，并保留小程序侧等效逻辑，添加 `todo` 注释记录差异原因。
+
+#### 3. 样式（style）适配改造
+
+- Web 支持完整 CSS，**通常无需对选择器或常规样式属性进行兼容改造**。
+- 读取 [Web 样式实践](./references/web-style-practice.md) 确认 `rpx` 换算与移动端适配口径符合工程配置。
+- 仅对"Web 专属、小程序不支持"或"小程序专属、Web 无等效"的样式片段，用 [样式条件编译](./references/conditional-compile.md#样式条件编译) 对**整条规则**进行最小包裹，添加 `todo` 注释记录差异原因。
+
+#### 4. JSON 配置适配改造
+
+- 读取 [JSON 配置参考](./references/web-json-reference.md)，检查所用字段在 Web 的支持情况，重点关注小程序专属字段（`workers` / `plugins` / 云开发等）。
+- 对于平台差异较大的配置项，将 JSON 区块改写为 `<script name="json">` 形式，借助 `__mpx_mode__` 进行 [配置条件编译](./references/conditional-compile.md#配置条件编译)。
+
+#### 5. 编译校验
+
+完成上述改造后，使用本 skill 自带的编译校验脚本对修改后的 `.mpx` 文件进行真实编译校验（位于 skill 目录下的 `scripts/compile-validate.js`，**不在宿主项目根目录下**），参见下文 [编译校验脚本](#编译校验脚本)。该脚本依赖业务项目内安装的 Mpx CLI 与构建配置，不能在 Mpx 核心仓库根目录直接校验业务组件。若校验失败，按错误分类回到对应步骤进行修正。
+
+#### 6. 检查与确认
+
+按 SFC 各区块逐项核对，并确认条件编译与编译校验已收尾：
+
+**跨平台兼容**
+- [ ] 引入的「Web 支持但小程序不支持」的写法均已通过条件编译限定在 Web 输出；小程序原有写法已用条件编译保留，未因 Web 适配而被替换或删除。
+
+**模板（template）**
+- [ ] `<template>` 中使用的基础组件、属性、事件均在 [模板能力参考](./references/web-template-reference.md) 标注为 Web 支持，或已通过模板条件编译进行平台隔离。
+- [ ] 动态 `class` / `style` 已改造为 `wx:class` / `wx:style` 指令，未在属性值内使用 `{{}}` 拼接。
+- [ ] `wx:class` / `wx:style` 等模板插值中的对象字面量 key 均未使用引号包裹，使用 camelCase 无引号形式。
+
+**脚本（script）**
+- [ ] `<script>` 中使用的生命周期、构造选项、实例方法与环境 API 均在 [脚本能力参考](./references/web-script-reference.md) 与 [环境 API 参考](./references/web-api-reference.md) 标注为 Web 支持，或已通过脚本条件编译进行平台隔离。
+- [ ] 平台直连 API（`wx.xxx` / `my.xxx`）已统一替换为 `mpx.xxx`；路由跳转使用 `mpx.navigateTo` 等统一导航 API，未直接引入 `vue-router`；直接访问 `window` / `document` / 第三方 H5 SDK 的逻辑已用条件编译限定在 Web 平台。
+
+**样式（style）**
+- [ ] `<style>`、`<template>`、`<script>` 中的样式写法符合 [Web 样式实践](./references/web-style-practice.md)，Web 专属且小程序不支持的样式已通过样式条件编译隔离。
+- [ ] `/*use rpx*/` / `/*use px*/` 单位注释已保留；`rpx` 换算与移动端适配符合工程配置。
+
+**JSON 配置**
+- [ ] `<script type="application/json">` / `<script name="json">` 中使用的字段均在 [JSON 配置参考](./references/web-json-reference.md) 标注为 Web 支持，或已通过配置条件编译进行平台隔离。
+
+**条件编译**
+- [ ] 不存在大面积连续条件编译，仅最小包裹不兼容片段。
+- [ ] 样式条件编译处理后产物中不存在空选择器。
+- [ ] 各个区块内的条件编译语法都符合规范，不存在误用（如在模板区块中使用 `/* @mpx-if */` 注释语法等）。
+
+**本地校验**
+- [ ] 通过 [编译校验脚本](#编译校验脚本) 或业务项目已有构建命令完成 Web 目标真实编译校验（建议 `--target=web` 与小程序目标一并校验，确保跨端兼容）。
+- [ ] 通过本地环境 ESLint 校验（如 `npx eslint path/to/component.mpx`），无 lint 错误与警告。
+
+## 任务二：创建符合 Web 跨端兼容规范的 Mpx 组件
+
+### 输入
+
+用户描述的组件需求，包括视图结构、交互、数据来源、目标平台范围、是否需要复用 H5 原生能力 / 第三方 SDK 等。
+
+### 输出
+
+完整的 `{name}.mpx` 组件文件，结构包含 `<template>`、`<script>`、`<style>` 与 JSON 配置区块。代码须直接满足 [通用约束与适配原则](#通用约束与适配原则)，避免新建后再走一轮适配改造。
+
+### 任务流程
+
+#### 1. 设计阶段
+
+- 与用户对齐需求要点：组件视图结构、props / 事件、数据流、目标平台、是否需要 Web 专属能力（路由、SEO/SSR、第三方 H5 SDK）。
+- 若需要复用 H5 原生能力或第三方库，读取 [H5 生态混合开发](./references/web-hybrid-dev.md)，对差异片段用局部条件编译（`@mode` / `@_mode` / `mpxTagName@mode` 或脚本 `__mpx_mode__`）隔离 Web 专属属性或少量节点即可。
+
+#### 2. 实施阶段
+
+按 SFC 四个区块依次实现，全程遵循 [通用约束与适配原则](#通用约束与适配原则)：
+
+- **`<template>`**：读取 [模板能力参考](./references/web-template-reference.md)，避开 Web 不支持/降级的基础组件；动态样式类名绑定使用 `wx:class` / `wx:style`。
+- **`<script>`**：读取 [脚本能力参考](./references/web-script-reference.md) 与 [环境 API 参考](./references/web-api-reference.md)，统一通过 `mpx.xxx` 调用环境能力。
+  - **优先使用组合式 API**：新建组件优先使用 `<script setup>` 风格的组合式 API 编写逻辑，生命周期须在 `<script setup>` 顶层同步注册，详见 [脚本能力参考 · 组合式 API](./references/web-script-reference.md#组合式-api)。
+  - **状态管理优先使用 `@mpxjs/pinia`**：新项目、新状态域或与组合式 API 协同时，使用 `@mpxjs/pinia`（Pinia 风格）；仅当工程已深度使用 `@mpxjs/store`（Vuex 风格）时继续维护沿用。详见 [脚本能力参考 · 状态管理](./references/web-script-reference.md#状态管理)。
+- **`<style>`**：读取 [Web 样式实践](./references/web-style-practice.md)，可直接使用完整 CSS 能力，注意 `rpx` 换算与移动端适配口径。
+- **JSON 配置**：读取 [JSON 配置参考](./references/web-json-reference.md)，仅使用 Web 支持的字段；当需要分平台注册组件或差异化配置时，使用 `<script name="json">` 形式动态生成。
+
+#### 3. 编译校验
+
+使用本 skill 自带的编译校验脚本（位于 skill 目录下的 `scripts/compile-validate.js`，**不在宿主项目根目录下**）校验新建组件，参见下文 [编译校验脚本](#编译校验脚本)。该脚本需要在安装了 Mpx CLI 的业务项目中运行。建议同时校验所有目标平台（如 `--target=wx,web`），确保跨端兼容。
+
+#### 4. 检查与确认
+
+复用 [任务一 · 检查与确认](#6-检查与确认) 的清单，确认新建组件不引入任何 Web 不兼容写法，且 Web 专属能力均已正确隔离。
+
+## 编译校验脚本
+
+> **脚本位置**：编译校验脚本随本 skill 一同分发，位于 **skill 目录下** 的 `scripts/compile-validate.js`（即 `<skill-root>/scripts/compile-validate.js`），下文所有命令示例均使用 **指向 skill 目录的路径**调用该脚本，不要尝试在宿主项目根目录或 `node_modules` 中查找它。
+
+该脚本基于业务项目内安装的 `@mpxjs/mpx-cli-service`、`@mpxjs/cli-shared-utils` 与 `@mpxjs/vue-cli-plugin-mpx` 进行真实编译校验：会自动从输入 `.mpx` 文件向上探测业务项目根目录、加载工程编译配置、按指定 `target` 进行编译，并按 `style / template / script / json / dependency / other` 分类聚合错误与警告。
+
+> 注意：Mpx 核心仓库本身不包含上述 CLI 包时，不能在核心仓库根目录直接运行该脚本校验业务组件；需在安装了 Mpx CLI 的业务项目中执行，或使用业务项目已有构建命令校验。
+
+### 命令行参数
+
+| 参数 | 默认 | 说明 |
+| --- | --- | --- |
+| `<file.mpx>...` | - | 一个或多个待校验的 `.mpx` 绝对/相对路径 |
+| `--target=<mode>` | `web` | 编译目标，多个用逗号分隔（如 `wx,web`）|
+| `--type=<page\|component>` | `component` | 入口类型，决定使用 `getPageEntry` 还是 `getComponentEntry`，并影响 `partialCompileRules` 形态 |
+| `--project-root=<path>` | 自动探测 | 显式指定业务项目根目录 |
+| `--no-ignore-sub-components` | 关闭 | 关闭默认子组件占位策略，递归编译所有子组件 |
+| `--json` | 关闭 | 输出结构化 JSON 结果 |
+
+退出码：`0` 校验通过；`1` 存在编译错误；`2` 运行期异常（如未找到 `@mpxjs/mpx-cli-service`）。
+
+### 使用示例
+
+> 下方示例中的 `<skill-root>` 表示本 skill 在宿主环境中的实际安装路径（例如 `.agents/skills/mpx2web`、`.claude/skills/mpx2web` 或 `~/.claude/skills/mpx2web` 等，以实际安装位置为准）；调用时使用该绝对路径，不要在宿主项目根目录下查找 `scripts/compile-validate.js`。
+
+```bash
+# 单组件、校验 Web 目标
+node <skill-root>/scripts/compile-validate.js src/components/foo.mpx --target=web
+
+# 显式指定为页面（影响 entry 与 partialCompileRules 形态）
+node <skill-root>/scripts/compile-validate.js src/pages/index.mpx --type=page --target=web
+
+# 跨端多目标校验（确保 Web 改造未破坏小程序原平台）
+node <skill-root>/scripts/compile-validate.js src/components/foo.mpx --target=wx,web
+
+# 输出结构化 JSON 便于二次处理
+node <skill-root>/scripts/compile-validate.js src/components/foo.mpx --target=web --json
+
+# 同时递归校验子组件（默认行为是仅校验目标自身）
+node <skill-root>/scripts/compile-validate.js src/components/foo.mpx --target=web --no-ignore-sub-components
+```
+
+校验失败时按错误的 `category` 字段回到对应任务步骤定位与修正问题，再次运行直至通过。
diff --git a/.agents/skills/mpx2web/references/conditional-compile.md b/.agents/skills/mpx2web/references/conditional-compile.md
new file mode 100644
index 0000000000..1e94fcd1be
--- /dev/null
+++ b/.agents/skills/mpx2web/references/conditional-compile.md
@@ -0,0 +1,159 @@
+# 条件编译
+
+对于跨平台无法兼容的部分，局部使用条件编译进行分平台定义是可以接受的。跨平台输出 Web 时，通常 **Web 平台**使用 `__mpx_mode__ === 'web'` 作为条件，**小程序原平台**使用 `__mpx_mode__ === 'wx' || __mpx_mode__ === 'ali'`（按项目实际目标补充 `swan` / `qq` / `tt` / `jd`）作为条件。若工程同时维护 RN，请额外覆盖 `ios` / `android` / `harmony`。
+
+## 目录
+
+- [样式条件编译](#样式条件编译)
+  - [避免产物中出现空选择器](#避免产物中出现空选择器)
+- [模板条件编译](#模板条件编译)
+  - [wx:if 条件编译](#wxif-条件编译)
+  - [节点/属性维度条件编译](#节点属性维度条件编译)
+- [脚本条件编译](#脚本条件编译)
+- [配置条件编译](#配置条件编译)
+
+---
+
+## 样式条件编译
+
+> **⚠️ `@mpx-if` 注释语法条件编译仅限在 `<style>` 区块内使用**，**严禁**在 `<style>` 区块以外的位置使用，不会生效。
+
+```html
+<style>
+.container {
+  /* @mpx-if (__mpx_mode__ === 'web') */
+  position: sticky; /* Web 支持 sticky 定位 */
+  /* @mpx-else */
+  position: relative; /* 小程序侧等效处理 */
+  /* @mpx-endif */
+}
+</style>
+```
+
+### 避免产物中出现空选择器
+
+样式条件编译后的产物中**不能留下空选择器（无样式内容的选择器）**。后续链路中的 CSS 预编译、PostCSS 插件等常会解析并遍历规则，空选择器容易触发解析错误或构建失败。
+
+若仅在声明块内做条件编译，某一平台分支可能把块内全部规则裁掉，从而留下「有选择器、无声明」的非法片段。此时应把**整条规则（含选择器与花括号内的内容）**一并纳入条件编译，保证每个平台产物里要么输出完整规则，要么完全不输出该规则。
+
+**❌ 避免（仅 Web 需要样式时，若只包在声明块内，小程序产物会得到空块 `.web-only { }`）：**
+
+```html
+<style>
+.web-only {
+  /* @mpx-if (__mpx_mode__ === 'web') */
+  position: fixed;
+  z-index: 999;
+  /* @mpx-endif */
+}
+</style>
+```
+
+**✅ 推荐（将选择器与整条规则一并条件编译，小程序不输出该规则，避免空选择器）：**
+
+```html
+<style>
+/* @mpx-if (__mpx_mode__ === 'web') */
+.web-only {
+  position: fixed;
+  z-index: 999;
+}
+/* @mpx-endif */
+</style>
+```
+
+---
+
+## 模板条件编译
+
+模板条件编译提供了两种，常用的有 `wx:if` 条件编译和 `@mode` / `@_mode` 节点/属性维度的条件编译。
+
+### wx:if 条件编译
+
+直接使用 `wx:if` 和 `__mpx_mode__` 变量进行条件渲染，逻辑直观但灵活性较低。
+
+```html
+<template>
+  <!-- 此处的 __mpx_mode__ 不需要声明数据，编译时会基于当前编译 mode 进行替换 -->
+  <view wx:if="{{__mpx_mode__ === 'web'}}">
+    仅 Web 平台可见
+  </view>
+  <view wx:else>
+    小程序平台可见
+  </view>
+</template>
+```
+
+### 节点/属性维度条件编译
+
+使用 `@` 和 `|` 符号来指定某个节点或属性只在某些平台下有效。这种方式更加灵活简洁。
+
+- **显式声明 (`@mode`)**：节点或属性仅在目标平台下输出，节点或属性为目标平台原生支持，**框架会跳过对该节点或属性的跨平台语法转换**。
+- **隐式声明 (`@_mode`)**：节点或属性仅在目标平台下输出，节点或属性为 Mpx 转换支持，**框架仍然会对其进行正常的跨平台语法转换**。
+- **标签名动态替换 (`mpxTagName@mode`)**：结合 `@mode` 属性，可以对模板组件的 `tagName` 进行分平台条件编译。当节点存在该属性时，在输出到对应平台时会将节点标签修改为该属性的值。
+
+**示例：**
+
+```html
+<template>
+  <!-- 属性维度条件编译，仅在 Web 平台注入 data-web 属性，使用 @mode 显式声明，输出 Web 时跳过属性跨平台语法转换 -->
+  <view
+    class="title"
+    some-web-attr@web="value"
+  >
+    {{title}}
+  </view>
+  <!-- 节点维度条件编译，使用 @_mode 隐式声明，仅在 Web 平台输出，并保留节点与属性的跨平台语法转换 -->
+  <view @_web bindtap="handleTap" class="web-only">仅 Web 可见</view>
+</template>
+```
+
+```html
+<template>
+  <!-- 标签名动态替换，小程序输出 view，而在 Web 平台输出时，标签名将被替换为 mpx-custom-view -->
+  <view mpxTagName@web="mpx-custom-view">will be mpx-custom-view in Web</view>
+</template>
+```
+
+---
+
+## 脚本条件编译
+
+在 `<script>` 中，可以通过访问 `__mpx_mode__` 获取当前编译 mode，进行平台差异逻辑编写（例如处理 Web 与小程序在路由、DOM、环境 API 上的差异等）。
+
+**基础用法：**
+```javascript
+if (__mpx_mode__ === 'web') {
+  // 执行 Web 环境相关逻辑，如直接访问 window / document / 第三方 H5 SDK
+} else {
+  // 执行小程序原平台相关逻辑
+}
+```
+
+**三元表达式用法：**
+```javascript
+// 对于简单的变量赋值或传参，推荐使用三元表达式
+const isWeb = __mpx_mode__ === 'web'
+const apiUrl = isWeb ? 'https://api.web.com' : 'https://api.mp.com'
+```
+
+---
+
+## 配置条件编译
+
+我们可以在 `<script name="json">` 中编写 `JS` 逻辑动态定义组件的 `JSON` 配置，可以访问 `__mpx_mode__` 和 `__mpx_env__` 环境变量进行条件编译，在不同的平台和环境下导出不同的 `JSON` 配置。
+
+**示例：**
+```html
+<script name="json">
+const isWeb = __mpx_mode__ === 'web'
+const isDidiEnv = __mpx_env__ === 'didi'
+
+module.exports = {
+  // 结合 __mpx_env__ 动态配置页面或组件的标题
+  navigationBarTitleText: isDidiEnv ? '滴滴出行' : '示例页面',
+  // 小程序专属字段在 Web 不支持，按平台隔离（示意）
+  ...(isWeb ? {} : { enablePullDownRefresh: true })
+}
+</script>
+```
diff --git a/.agents/skills/mpx2web/references/web-api-reference.md b/.agents/skills/mpx2web/references/web-api-reference.md
new file mode 100644
index 0000000000..40db830b33
--- /dev/null
+++ b/.agents/skills/mpx2web/references/web-api-reference.md
@@ -0,0 +1,1230 @@
+# 跨端输出 Web 环境 API 参考
+
+## 目录
+
+- [使用说明](#使用说明)
+- [基础](#基础)
+  - [base64ToArrayBuffer](#base64toarraybuffer)
+  - [arrayBufferToBase64](#arraybuffertobase64)
+  - [getSystemInfo](#getsysteminfo)
+  - [getSystemInfoSync](#getsysteminfosync)
+  - [getWindowInfo](#getwindowinfo)
+  - [getDeviceInfo](#getdeviceinfo)
+  - [getEnterOptionsSync](#getenteroptionssync)
+  - [getLaunchOptionsSync](#getlaunchoptionssync)
+  - [onAppShow](#onappshow)
+  - [onAppHide](#onapphide)
+  - [offAppShow](#offappshow)
+  - [offAppHide](#offapphide)
+  - [onError](#onerror)
+  - [offError](#offerror)
+  - [onUnhandledRejection](#onunhandledrejection)
+  - [offUnhandledRejection](#offunhandledrejection)
+- [路由](#路由)
+- [界面](#界面)
+  - [交互反馈](#交互反馈)
+  - [导航栏](#导航栏)
+  - [页面滚动与下拉刷新](#页面滚动与下拉刷新)
+  - [TabBar](#tabbar)
+  - [createAnimation](#createanimation)
+  - [nextTick](#nexttick)
+  - [窗口尺寸监听](#窗口尺寸监听)
+- [网络](#网络)
+  - [request](#request)
+  - [connectSocket](#connectsocket)
+- [数据缓存](#数据缓存)
+- [媒体](#媒体)
+  - [previewImage](#previewimage)
+  - [getImageInfo](#getimageinfo)
+  - [createInnerAudioContext](#createinneraudiocontext)
+  - [createVideoContext](#createvideocontext)
+- [位置](#位置)
+- [设备](#设备)
+- [WXML](#wxml)
+  - [createSelectorQuery](#createselectorquery)
+  - [createIntersectionObserver](#createintersectionobserver)
+
+---
+
+## 使用说明
+
+`@mpxjs/api-proxy` 提供跨端环境 API 抹平。输出 Web 时，在应用入口执行 `mpx.use(apiProxy, options)`，即可通过 `mpx.xxx` 使用本参考中列出的 API。
+
+```js
+import mpx from '@mpxjs/core'
+import apiProxy from '@mpxjs/api-proxy'
+
+mpx.use(apiProxy, {
+  usePromise: true,
+  whiteList: [],
+  blackList: [],
+  custom: {
+    web: {
+      myCustomApi () {
+        // 仅在 Web 编译目标下挂载为 mpx.myCustomApi
+      }
+    }
+  }
+})
+```
+
+若无需配置，可简写为 `mpx.use(apiProxy)`。
+
+### options
+
+| 选项 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `usePromise` | `boolean` | `false` | 为符合 Promise 化规则的异步 API 增加 Promise 返回值。 |
+| `whiteList` | `string[]` | `[]` | 强制指定 API 参与 Promise 化，可覆盖内置排除规则。 |
+| `blackList` | `string[]` | `[]` | 强制指定 API 保持原始回调风格。 |
+| `custom` | `Object` | `{}` | 按编译目标扩展或覆盖 API；Web 对应键为 `web`。 |
+
+### Promise 化
+
+同步 API、监听 API、名称以 `create` 开头的上下文工厂、名称以 `Sync` 结尾的 API，以及内置黑名单中的 API 默认不会 Promise 化。单次调用可在第一个参数对象中传入 `usePromise: false`，临时保留回调风格。
+
+`request`、`connectSocket` 等 API 可返回任务实例；开启 `usePromise: true` 后按 Promise 风格获取异步结果。需要操作任务实例时，优先使用回调风格调用。
+
+### 支持范围
+
+本文展开说明的 API 可在 Web 使用。未在本文列出的 `mpx.xxx` API，默认按 Web 不支持处理；如能力存疑，应扫描 `@mpxjs/api-proxy` Web 侧源码确认。需要时通过条件编译提供 Web 替代方案，或使用 `custom.web` 扩展。
+
+### 浏览器与 SSR
+
+依赖界面、媒体、位置、网络状态或浏览器存储的 API 应在客户端生命周期内调用；需要操作页面节点的 API 应在组件挂载后调用。SSR 渲染阶段不要调用此类 API。`base64ToArrayBuffer`、`arrayBufferToBase64` 等纯 JavaScript 能力不受此限制。
+
+**自定义覆盖与扩展**：Web 默认能力不满足业务需求时，可通过 `custom.web` 提供自定义 API。同名 API 会覆盖默认能力，新名称会作为 Web 专属扩展挂到 `mpx` 上。
+
+---
+
+## 基础
+
+### base64ToArrayBuffer
+
+#### 说明
+
+同步将 Base64 字符串解码为 `ArrayBuffer`。
+
+#### 入参
+
+第一个参数为 `base64`（`string`，必填）。非法 Base64 可能抛出异常，调用侧需按需捕获。
+
+#### 返回值
+
+返回解码后的 `ArrayBuffer`。
+
+---
+
+### arrayBufferToBase64
+
+#### 说明
+
+同步将 `ArrayBuffer` 或可逐字节遍历的二进制数据编码为 Base64 字符串。
+
+#### 返回值
+
+返回 Base64 字符串。
+
+---
+
+### getSystemInfo
+
+#### 说明
+
+异步获取设备概要与当前窗口尺寸。Web 可获得的信息少于小程序宿主，品牌、型号和系统版本为浏览器环境推断值，不应作为可靠的设备识别依据。
+
+#### 入参
+
+第一个参数为包含 `success`、`complete` 的 Object。
+
+#### 成功回调参数
+
+| 字段名 | 类型 | 说明 |
+| --- | --- | --- |
+| `errMsg` | `string` | `getSystemInfo:ok`。 |
+| `brand` | `string` | 根据 UA 匹配的品牌；无法识别时回退为 `Android`。 |
+| `model` | `string` | 浏览器推断值，不保证为精确机型。 |
+| `system` | `string` | 根据 UA 推断的 iOS 或 Android 版本。 |
+| `platform` | `string` | 浏览器报告的平台标识。 |
+| `language` | `string` | 浏览器语言。 |
+| `pixelRatio` | `number` | 设备像素比。 |
+| `screenWidth` / `screenHeight` | `number` | 屏幕宽高。 |
+| `windowWidth` / `windowHeight` | `number` | 文档根节点的可视区域宽高。 |
+| `statusBarHeight` / `safeArea` | `null` | Web 当前无法提供。 |
+| `version` / `SDKVersion` / `fontSizeSetting` | `null` | Web 当前无法提供。 |
+| 各类 `*Authorized`、`*Enabled` | `null` | 不可用于浏览器权限或设备能力判断。 |
+
+---
+
+### getSystemInfoSync
+
+同步版本，返回字段与 `getSystemInfo` 成功载荷一致，但不包含 `errMsg`。仅可在浏览器环境调用。
+
+---
+
+### getWindowInfo
+
+#### 说明
+
+同步读取浏览器屏幕与视口尺寸。
+
+#### 返回值
+
+| 字段名 | 类型 | 说明 |
+| --- | --- | --- |
+| `pixelRatio` | `number` | 设备像素比。 |
+| `screenWidth` / `screenHeight` | `number` | 屏幕宽高。 |
+| `windowWidth` / `windowHeight` | `number` | 页面视口宽高。 |
+| `statusBarHeight` / `safeArea` / `screenTop` | `null` | Web 当前无法提供。 |
+
+安全区域应优先使用 CSS `env(safe-area-inset-*)` 处理，不要依赖本 API 的 `safeArea`。
+
+---
+
+### getDeviceInfo
+
+#### 说明
+
+同步返回 UA 推断的设备概要。品牌、型号和系统版本只能作为展示或粗略兼容判断，不能作为可靠的设备识别依据。
+
+#### 返回值
+
+| 字段名 | 类型 | 说明 |
+| --- | --- | --- |
+| `brand` / `model` | `string` | UA 推断值，`model` 当前与 `brand` 相同。 |
+| `system` | `string` | UA 推断的系统版本。 |
+| `platform` | `string` | 浏览器报告的平台标识。 |
+| `abi` / `deviceAbi` / `benchmarkLevel` / `cpuType` / `memorySize` | `null` | Web 当前无法提供。 |
+
+---
+
+### getEnterOptionsSync
+
+#### 说明
+
+同步获取**最近一次进入应用或回到前台**时的启动参数，与冷启动参数可能不同。
+
+#### 入参
+
+无。
+
+#### 返回值
+
+返回 **Object**：
+
+| 字段名 | 类型 | 说明 |
+| --- | --- | --- |
+| `path` | `string` | 打开的页面路径或路由名。 |
+| `scene` | `number` | 场景值。 |
+| `query` | `Object` | 查询参数键值对。 |
+| `shareTicket` | `string` | 分享票据。 |
+| `referrerInfo` | `Object` | 来源信息。 |
+| `apiCategory` | `string` | API 类目等。 |
+| `chatType` | `number` | 聊天场景枚举。 |
+| （其余） | - | 随启动场景变化的其他字段。 |
+
+---
+
+### getLaunchOptionsSync
+
+#### 说明
+
+同步获取**应用冷启动**时的参数。
+
+#### 入参
+
+无。
+
+#### 返回值
+
+返回 **Object**：
+
+| 字段名 | 类型 | 说明 |
+| --- | --- | --- |
+| `path` | `string` | 启动进入的页面路径或路由名。 |
+| `scene` | `number` | 场景值。 |
+| `query` | `Object` | 查询参数键值对。 |
+| `shareTicket` | `string` | 分享票据。 |
+| `referrerInfo` | `Object` | 来源信息。 |
+| `apiCategory` | `string` | API 类目等。 |
+| `chatType` | `number` | 聊天场景枚举。 |
+| （其余） | - | 随启动场景变化的其他字段。 |
+
+---
+
+### onAppShow
+
+#### 说明
+
+监听应用进入**前台**（展示态；监听 API，非 `success` / `fail` 模型）。应用首次创建以及页面由隐藏状态恢复可见时触发。
+
+Web 不区分小程序意义上的冷启动与热启动。首次触发时回调包含当前页面的启动参数；页面从隐藏状态恢复时，回调参数为空对象。
+
+#### 入参
+
+| 字段名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `callback` | `function` | 是 | 应用进入展示态时调用。仅在浏览器环境注册。 |
+
+#### 监听回调参数
+
+首次触发时收到 **Object**：
+
+| 字段名 | 类型 | 说明 |
+| --- | --- | --- |
+| `path` | `string` | 当前路由路径，已移除开头的 `/`。 |
+| `query` | `Object` | 当前路由查询参数。 |
+| `scene` | `number` | Web 当前固定为 `0`。 |
+| `shareTicket` | `string` | Web 当前为空字符串。 |
+| `referrerInfo` | `Object` | Web 当前为空对象。 |
+
+页面从隐藏状态恢复时收到空对象。
+
+#### 返回值
+
+无。
+
+---
+
+### onAppHide
+
+#### 说明
+
+监听应用进入**后台**（隐藏态；监听 API）。Web 页面由可见状态变为隐藏状态时触发。
+
+该事件反映浏览器页面可见性变化，例如切换标签页、最小化浏览器或进入后台；具体触发时机仍受浏览器实现影响，不等同于网页被关闭或组件被卸载。
+
+#### 入参
+
+| 字段名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `callback` | `function` | 是 | 应用进入隐藏态时调用。仅在浏览器环境注册。 |
+
+#### 监听回调参数
+
+Web 端回调不传参数，业务侧只应将其作为“页面进入隐藏态”的通知使用，不应读取隐藏原因。
+
+#### 返回值
+
+无。
+
+---
+
+### offAppShow
+
+#### 说明
+
+取消 `onAppShow` 监听；不传回调则清空该事件下全部监听。
+
+#### 入参
+
+| 字段名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `callback` | `function` | 否 | 与注册时相同的函数引用；省略则移除全部展示态监听。 |
+
+#### 返回值
+
+无。
+
+---
+
+### offAppHide
+
+#### 说明
+
+取消 `onAppHide` 监听；不传回调则清空该事件下全部监听。
+
+#### 入参
+
+| 字段名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `callback` | `function` | 否 | 与注册时相同的函数引用；省略则移除全部隐藏态监听。 |
+
+#### 返回值
+
+无。
+
+---
+
+### onError
+
+#### 说明
+
+监听 Web 环境中的全局 JavaScript 错误（监听 API）。
+
+#### 入参
+
+| 字段名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `callback` | `function` | 是 | 全局错误发生时调用。仅在浏览器环境注册。 |
+
+#### 监听回调参数
+
+回调参数通常为 `Error` 对象；部分资源加载错误或浏览器受限场景下可能为空。
+
+#### 返回值
+
+无。
+
+---
+
+### offError
+
+#### 说明
+
+取消 `onError` 监听；不传回调则清空全部错误监听。
+
+#### 入参
+
+| 字段名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `callback` | `function` | 否 | 与注册时相同的函数引用；省略则移除全部错误监听。 |
+
+#### 返回值
+
+无。
+
+---
+
+### onUnhandledRejection
+
+#### 说明
+
+监听未处理的 Promise 拒绝（监听 API）。
+
+#### 入参
+
+| 字段名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `callback` | `function` | 是 | 未处理的 Promise 拒绝发生时调用。仅在浏览器环境注册。 |
+
+#### 监听回调参数
+
+| 字段名 | 类型 | 说明 |
+| --- | --- | --- |
+| `reason` | `any` | Promise 的拒绝原因。 |
+| `promise` | `Promise` | 发生未处理拒绝的 Promise。 |
+
+#### 返回值
+
+无。
+
+---
+
+### offUnhandledRejection
+
+#### 说明
+
+取消 `onUnhandledRejection` 监听；不传回调则清空全部监听。
+
+#### 入参
+
+| 字段名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `callback` | `function` | 否 | 与注册时相同的函数引用；省略则移除全部监听。 |
+
+#### 返回值
+
+无。
+
+---
+
+`onLazyLoadError` / `offLazyLoadError` 在 Web 下不可用。
+
+---
+
+## 路由
+
+业务代码统一使用下列 Mpx 导航 API，不要直接引入 `vue-router` 或手写 Web 路由跳转。
+
+以下 API 只能在浏览器且 Mpx 路由实例已初始化后工作。路由与 SSR 相关配置见 [JSON 配置参考](./web-json-reference.md)。
+
+### navigateTo
+
+#### 说明
+
+**异步 API**。保留当前页并打开新页面（入栈）。Web 下目标页面不能是 tabBar 页面，支持 `EventChannel`。
+
+#### 入参
+
+第一个参数为 **Object**。
+
+| 字段名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `url` | `string` | 是 | 打开的页面路径。 |
+| `events` | `Object` | 否 | 页面间通信通道，与小程序一致。 |
+
+#### 返回值
+
+无同步返回值。
+
+### redirectTo
+
+#### 说明
+
+**异步 API**。关闭当前页并打开指定页（替换栈顶）。Web 下目标页面不能是 tabBar 页面。
+
+#### 入参
+
+第一个参数为 **Object**。
+
+| 字段名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `url` | `string` | 是 | 打开的页面路径。 |
+
+#### 返回值
+
+无同步返回值。
+
+### navigateBack
+
+#### 说明
+
+**异步 API**。关闭当前页面，返回栈内上一层或多层。`delta` 大于当前可回退层数时会被收敛。
+
+#### 入参
+
+第一个参数为 **Object**。
+
+| 字段名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `delta` | `number` | 否 | 回退步数，默认 `1`。 |
+
+#### 返回值
+
+无同步返回值。
+
+### reLaunch
+
+#### 说明
+
+**异步 API**。清理现有页面栈后打开目标页。Web 下可通过扩展参数 `delta` 校正宿主 webview 无法统计的额外跳转层数。
+
+#### 入参
+
+第一个参数为 **Object**。
+
+| 字段名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `url` | `string` | 是 | 打开的页面路径。 |
+| `delta` | `number` | 否 | Web 扩展参数，用于校正宿主 webview 额外跳转层数。 |
+
+#### 返回值
+
+无同步返回值。
+
+### switchTab
+
+#### 说明
+
+**异步 API**。切换到 tabBar 页面。Web 下仅可切换到 tabBar 配置中的页面。
+
+#### 入参
+
+第一个参数为 **Object**。
+
+| 字段名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `url` | `string` | 是 | tabBar 页面路径。 |
+
+#### 返回值
+
+无同步返回值。
+
+---
+
+## 界面
+
+### 交互反馈
+
+#### showActionSheet
+
+##### 说明
+
+**异步 API**。显示操作菜单。
+
+##### 入参
+
+第一个参数为 **Object**。
+
+| 字段名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `itemList` | `string[]` | 是 | 按钮标题列表。 |
+| `itemColor` | `string` | 否 | 按钮文字颜色。 |
+
+##### 返回值
+
+无同步返回值。
+
+#### showModal
+
+##### 说明
+
+**异步 API**。显示模态对话框。
+
+##### 入参
+
+第一个参数为 **Object**。
+
+| 字段名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `title` | `string` | 否 | 标题。 |
+| `content` | `string` | 否 | 内容。 |
+| `showCancel` | `boolean` | 否 | 是否显示取消按钮。 |
+| `cancelText` | `string` | 否 | 取消按钮文案。 |
+| `cancelColor` | `string` | 否 | 取消按钮颜色。 |
+| `confirmText` | `string` | 否 | 确认按钮文案。 |
+| `confirmColor` | `string` | 否 | 确认按钮颜色。 |
+
+##### 返回值
+
+无同步返回值。
+
+#### showToast
+
+##### 说明
+
+**异步 API**。显示轻提示。
+
+##### 入参
+
+第一个参数为 **Object**。
+
+| 字段名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `title` | `string` | 是 | 提示文字。 |
+| `icon` | `string` | 否 | `success` / `error` / `loading` / `none` 等。 |
+| `image` | `string` | 否 | 自定义图标路径。 |
+| `duration` | `number` | 否 | 显示时长 ms。 |
+| `mask` | `boolean` | 否 | 是否显示透明蒙层。 |
+
+##### 返回值
+
+无同步返回值。
+
+#### hideToast
+
+##### 说明
+
+**异步 API**。隐藏当前 Toast。
+
+##### 入参
+
+常规异步 API 回调。
+
+##### 返回值
+
+无同步返回值。
+
+#### showLoading
+
+##### 说明
+
+**异步 API**。显示加载提示。
+
+##### 入参
+
+第一个参数为 **Object**。
+
+| 字段名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `title` | `string` | 否 | 提示文字。 |
+| `mask` | `boolean` | 否 | 是否显示透明蒙层。 |
+
+##### 返回值
+
+无同步返回值。
+
+#### hideLoading
+
+##### 说明
+
+**异步 API**。隐藏 Loading。
+
+##### 入参
+
+常规异步 API 回调。
+
+##### 返回值
+
+无同步返回值。
+
+上述交互 API 只能在客户端调用，SSR 渲染阶段不可用。
+
+---
+
+### 导航栏
+
+#### setNavigationBarTitle
+
+##### 说明
+
+**异步 API**。设置当前 Web 页面标题。
+
+##### 入参
+
+第一个参数为 **Object**。
+
+| 字段名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `title` | `string` | 是 | 标题文字。 |
+
+##### 返回值
+
+无同步返回值。
+
+#### setNavigationBarColor
+
+##### 说明
+
+**异步 API**。设置浏览器主题色。仅部分浏览器会呈现，`frontColor` 等字段在 Web 下不生效。
+
+##### 入参
+
+第一个参数为 **Object**。
+
+| 字段名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `backgroundColor` | `string` | 否 | 背景色值。 |
+
+##### 返回值
+
+无同步返回值。
+
+#### hideHomeButton
+
+##### 说明
+
+Web 不支持。
+
+---
+
+### 页面滚动与下拉刷新
+
+#### pageScrollTo
+
+##### 说明
+
+**异步 API**。将页面滚动到指定位置。必须在页面挂载后调用。
+
+##### 入参
+
+第一个参数为 **Object**。
+
+| 字段名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `scrollTop` | `number` | 否 | 纵向滚动位置 px。 |
+| `selector` | `string` | 否 | 选择器，滚动到节点。 |
+| `duration` | `number` | 否 | 滚动动画时长 ms。 |
+
+##### 返回值
+
+无同步返回值。
+
+#### startPullDownRefresh
+
+##### 说明
+
+**异步 API**。启动当前页面的下拉刷新。页面需要在 JSON 配置中开启下拉刷新。
+
+##### 入参
+
+常规异步 API 回调。
+
+##### 返回值
+
+无同步返回值。
+
+#### stopPullDownRefresh
+
+##### 说明
+
+**异步 API**。停止当前页面的下拉刷新。
+
+##### 入参
+
+常规异步 API 回调。
+
+##### 返回值
+
+无同步返回值。
+
+---
+
+### TabBar
+
+没有 tabBar 配置时调用会失败。`showTabBar` / `hideTabBar` 可操作自定义 tabBar 的显示状态，但 `setTabBarItem` / `setTabBarStyle` 不会修改自定义 tabBar 内容。
+
+#### setTabBarItem
+
+##### 说明
+
+**异步 API**。修改 Mpx 内置 tabBar 项。自定义 tabBar 不支持。
+
+##### 入参
+
+第一个参数为 **Object**。
+
+| 字段名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `index` | `number` | 是 | tabBar 项索引。 |
+| `text` | `string` | 否 | tabBar 项文案。 |
+| `iconPath` | `string` | 否 | 默认图标路径。 |
+| `selectedIconPath` | `string` | 否 | 选中图标路径。 |
+
+##### 返回值
+
+无同步返回值。
+
+#### setTabBarStyle
+
+##### 说明
+
+**异步 API**。修改 Mpx 内置 tabBar 样式。自定义 tabBar 不支持。
+
+##### 入参
+
+第一个参数为 **Object**。
+
+| 字段名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `color` | `string` | 否 | 默认文字颜色。 |
+| `selectedColor` | `string` | 否 | 选中文字颜色。 |
+| `backgroundColor` | `string` | 否 | 背景色。 |
+| `borderStyle` | `string` | 否 | 边框颜色风格。 |
+
+##### 返回值
+
+无同步返回值。
+
+#### showTabBar
+
+##### 说明
+
+**异步 API**。显示已注册的 tabBar。
+
+##### 入参
+
+常规异步 API 回调。
+
+##### 返回值
+
+无同步返回值。
+
+#### hideTabBar
+
+##### 说明
+
+**异步 API**。隐藏已注册的 tabBar。
+
+##### 入参
+
+常规异步 API 回调。
+
+##### 返回值
+
+无同步返回值。
+
+---
+
+### createAnimation
+
+#### 说明
+
+**同步风格工厂**。创建动画描述对象，用于节点 `animation` 绑定。
+
+#### 入参
+
+第一个参数为 **Object**。
+
+| 字段名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `duration` | `number` | 否 | 默认动画时长 ms。 |
+| `timingFunction` | `string` | 否 | 如 `linear`、`ease`。 |
+| `delay` | `number` | 否 | 延迟 ms。 |
+| `transformOrigin` | `string` | 否 | 变换原点。 |
+
+#### 返回值
+
+返回 **`Animation`** 实例；链式方法与 `export()` 与小程序对齐，全集以实现为准。带 `rpx` 的动画配置应在客户端使用。
+
+---
+
+### nextTick
+
+#### 说明
+
+同步调度：在下一微任务执行回调（非异步 `success` / `fail` 模型）。
+
+#### 入参
+
+| 字段名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `fn` | `function` | 是 | 要执行的函数。 |
+
+#### 返回值
+
+无。
+
+---
+
+### 窗口尺寸监听
+
+#### onWindowResize
+
+##### 说明
+
+监听窗口尺寸变化。Web 返回的是屏幕尺寸，不是文档视口尺寸。
+
+##### 入参
+
+| 字段名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `callback` | `function` | 是 | 窗口尺寸变化时调用。 |
+
+##### 返回值
+
+无。
+
+#### offWindowResize
+
+##### 说明
+
+取消窗口尺寸变化监听。
+
+##### 入参
+
+| 字段名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `callback` | `function` | 是 | 与注册时相同的函数引用。 |
+
+##### 返回值
+
+无。
+
+---
+
+## 网络
+
+### request
+
+#### 说明
+
+发起 HTTP 请求，受浏览器同源策略和 CORS 限制。跨域请求需要服务端正确配置响应头。
+
+#### 入参
+
+| 字段名 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `url` | `string` | `''` | 请求地址。 |
+| `data` | `any` | `{}` | GET 时拼接到 URL；其他方法作为请求体。 |
+| `method` | `string` | `GET` | 会转换为大写。 |
+| `header` | `Object` | `{}` | 请求头。 |
+| `dataType` | `string` | `json` | 为 `json` 且响应为字符串时尝试 `JSON.parse`。 |
+| `responseType` | `string` | `text` | 响应数据类型。 |
+| `timeout` | `number` | 应用 `networkTimeout` 或 60000 | 超时时间，单位 ms。 |
+
+`POST` 且 Content-Type 为 `application/x-www-form-urlencoded` 时，非字符串数据会自动序列化。
+
+#### 返回值
+
+返回 `RequestTask`，当前仅提供 `abort()`。
+
+Web 下不提供 `cookies`、`profile`、`exception` 字段。
+
+---
+
+### connectSocket
+
+#### 说明
+
+建立 WebSocket 连接。支持 `url` 和 `protocols`；`header` 在 Web 下不生效。
+
+#### 返回值
+
+返回 `SocketTask`。
+
+Web 不支持全局 `sendSocketMessage`、`closeSocket`、`onSocketOpen`、`onSocketError`、`onSocketMessage`、`onSocketClose`，请使用 `SocketTask` 对应方法。
+
+---
+
+## 数据缓存
+
+Web 缓存受浏览器配额、隐私模式和站点存储策略限制，写入可能失败。缓存数据应当可序列化。
+
+所有缓存 API 只能在客户端使用。`clearStorage` 会清除当前站点下的其他同源缓存数据，调用前需确认影响范围。
+
+### setStorage
+
+#### 说明
+
+**异步 API**。写入本地缓存。
+
+#### 入参
+
+第一个参数为 **Object**。
+
+| 字段名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `key` | `string` | 是 | 键。 |
+| `data` | `any` | 是 | 可序列化数据。 |
+
+#### 返回值
+
+无同步返回值。
+
+---
+
+### setStorageSync
+
+#### 说明
+
+同步写入本地缓存。
+
+#### 入参
+
+参数如下。
+
+| 字段名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `key` | `string` | 是 | 键。 |
+| `data` | `any` | 是 | 可序列化数据。 |
+
+#### 返回值
+
+无。
+
+---
+
+### getStorage
+
+#### 说明
+
+**异步 API**。读取本地缓存。
+
+#### 入参
+
+第一个参数为 **Object**。
+
+| 字段名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `key` | `string` | 是 | 键。 |
+
+#### 返回值
+
+无同步返回值。
+
+---
+
+### getStorageSync
+
+#### 说明
+
+同步读取本地缓存。
+
+#### 入参
+
+参数如下。
+
+| 字段名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `key` | `string` | 是 | 键。 |
+
+#### 返回值
+
+返回缓存数据；未找到时返回空字符串。
+
+---
+
+### getStorageInfo
+
+#### 说明
+
+**异步 API**。获取缓存键列表。Web 下不提供 `limitSize`、`currentSize`。
+
+#### 入参
+
+常规异步 API 回调。
+
+#### 返回值
+
+无同步返回值。
+
+---
+
+### getStorageInfoSync
+
+#### 说明
+
+同步获取缓存键列表。Web 下不提供 `limitSize`、`currentSize`。
+
+#### 入参
+
+无。
+
+#### 返回值
+
+返回缓存信息。
+
+---
+
+### removeStorage
+
+#### 说明
+
+**异步 API**。删除指定缓存。
+
+#### 入参
+
+第一个参数为 **Object**。
+
+| 字段名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `key` | `string` | 是 | 键。 |
+
+#### 返回值
+
+无同步返回值。
+
+---
+
+### removeStorageSync
+
+#### 说明
+
+同步删除指定缓存。
+
+#### 入参
+
+参数如下。
+
+| 字段名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `key` | `string` | 是 | 键。 |
+
+#### 返回值
+
+无。
+
+---
+
+### clearStorage
+
+#### 说明
+
+**异步 API**。清空当前站点的全部缓存。
+
+#### 入参
+
+常规异步 API 回调。
+
+#### 返回值
+
+无同步返回值。
+
+---
+
+### clearStorageSync
+
+#### 说明
+
+同步清空当前站点的全部缓存。
+
+#### 入参
+
+无。
+
+#### 返回值
+
+无。
+
+---
+
+## 媒体
+
+### previewImage
+
+预览图片列表，支持触摸横向切换和点击关闭。
+
+| 字段名 | 类型 | 必填 | 说明 |
+| --- | --- | --- | --- |
+| `urls` | `string[]` | 是 | 图片地址列表。 |
+| `current` | `string` | 否 | 初始图片地址；不在列表时从第一张开始。 |
+
+Web 下仅支持 `urls` 和 `current` 字段。
+
+---
+
+### getImageInfo
+
+基于浏览器 `Image` 加载图片，`src` 必填且不能为空。Web 下不提供 `path`、`orientation`、`type` 字段。
+
+只能在客户端调用。
+
+---
+
+### createInnerAudioContext
+
+同步创建基于 HTML `Audio` 的音频上下文。Web 下 `startTime`、`obeyMuteSwitch` 仅为兼容属性。
+
+浏览器自动播放策略可能阻止未经过用户交互触发的 `play()`。
+
+---
+
+### createVideoContext
+
+根据元素 `id` 获取页面中的 `<video>`，可传入带 `$el` 的组件实例限定查询范围。
+
+`requestBackgroundPlayback`、`exitBackgroundPlayback`、`exitPictureInPicture`、`sendDanmu` 在 Web 下不生效。全屏效果受浏览器支持与用户手势策略限制。
+
+`compressImage`、`chooseMedia` 和 `chooseImage` 在 Web 下不可用。
+
+---
+
+## 位置
+
+### getLocation
+
+获取当前地理位置。浏览器通常要求 HTTPS 安全上下文和用户授权。
+
+| 字段名 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `isHighAccuracy` | `boolean` | `false` | 是否使用高精度定位。 |
+
+Web 下不提供 `horizontalAccuracy`、`verticalAccuracy`；`speed` 不建议作为真实移动速度使用。
+
+`openLocation`、`chooseLocation`、`onLocationChange`、`offLocationChange`、`startLocationUpdate`、`stopLocationUpdate` 在 Web 下不支持。
+
+---
+
+## 设备
+
+### getNetworkType
+
+获取当前网络类型。浏览器无法识别时返回 `unknown`，枚举值不保证与小程序完全一致。
+
+### onNetworkStatusChange / offNetworkStatusChange
+
+监听或取消监听网络连接状态变化。不同浏览器能够提供的网络类型精度不同，无法识别时按未知网络处理。
+
+---
+
+## WXML
+
+### createSelectorQuery
+
+创建 `SelectorQuery`，支持 ID、class、子元素、后代、跨组件后代和并集选择器。必须在节点挂载后调用，SSR 渲染阶段不可用。
+
+---
+
+### createIntersectionObserver
+
+创建节点相交状态观察器。
+
+| 字段名 | 类型 | 说明 |
+| --- | --- | --- |
+| `thresholds` | `number[]` | 相交比例阈值，默认 `[0]`。 |
+| `initialRatio` | `number` | 初始比例过滤依据，默认 `0`。 |
+| `observeAll` | `boolean` | 为 `true` 时观察匹配选择器的全部节点。 |
+
+旧浏览器可能不支持该能力，需要按目标浏览器范围提供降级方案。
diff --git a/.agents/skills/mpx2web/references/web-hybrid-dev.md b/.agents/skills/mpx2web/references/web-hybrid-dev.md
new file mode 100644
index 0000000000..bc8e9f1f44
--- /dev/null
+++ b/.agents/skills/mpx2web/references/web-hybrid-dev.md
@@ -0,0 +1,219 @@
+# Mpx 与 H5 生态混合开发
+
+Mpx 输出 Web 时会将 `.mpx` 改写为 `vue-loader` 可处理的 Vue 2.7 单文件组件，运行时基于真实 DOM。多数小程序基础组件会被编译为 `mpx-*` Web 内建组件；HTML / SVG 原生标签可作为 Web 原生节点使用；本地 `.mpx` / `.vue` 组件可通过 JSON `usingComponents` 注册后在模板中使用。
+
+本参考用于处理三类场景：
+
+1. 在 `.mpx` 内使用 Web 原生 DOM 能力。
+2. 在 Web 输出中接入第三方 H5 SDK。
+3. 复用 Vue 生态组件，或替换/扩展 Mpx Web 内建基础组件。
+
+## 目录
+
+- [使用原生 DOM 能力](#使用原生-dom-能力)
+- [引入第三方 H5 SDK](#引入第三方-h5-sdk)
+- [使用 Vue 生态组件](#使用-vue-生态组件)
+- [替换 Web 内建基础组件](#替换-web-内建基础组件)
+- [跨端兼容隔离](#跨端兼容隔离)
+
+---
+
+## 使用原生 DOM 能力
+
+Web 输出基于真实 DOM，但跨端组件仍应优先使用 Mpx 模板、事件、样式和 `@mpxjs/api-proxy` 能力。只有在需要调用浏览器专属能力时，才直接访问 `window`、`document` 或 DOM 节点。
+
+### 直接使用 HTML / SVG 标签
+
+模板中可以使用 HTML / SVG 原生标签。它们不需要在 JSON 中注册，编译时会作为原生标签保留。
+
+```html
+<template>
+  <view class="chart-card">
+    <canvas wx:if="{{__mpx_mode__ === 'web'}}" id="salesCanvas" class="chart-canvas"></canvas>
+    <svg wx:if="{{__mpx_mode__ === 'web'}}" class="chart-icon" viewBox="0 0 16 16">
+      <circle cx="8" cy="8" r="6"></circle>
+    </svg>
+  </view>
+</template>
+```
+
+原生标签通常是 Web 专属内容，应使用 `wx:if="{{__mpx_mode__ === 'web'}}"` 隔离，避免小程序侧解析到不支持的节点。
+
+### 获取 DOM 节点
+
+需要读写节点尺寸、挂载第三方库或调用 DOM 方法时，优先使用 `wx:ref`、`createSelectorQuery` 或组件生命周期，在节点挂载后执行。
+
+```html
+<template>
+  <view wx:if="{{__mpx_mode__ === 'web'}}" class="chart-host" wx:ref="chartHost"></view>
+</template>
+
+<script>
+  import { createComponent } from '@mpxjs/core'
+
+  createComponent({
+    ready () {
+      if (__mpx_mode__ !== 'web') return
+      this.createSelectorQuery()
+        .select('.chart-host')
+        .node((res) => {
+          const el = res && res.node
+          if (!el) return
+          // 在这里挂载只依赖 DOM 的逻辑
+        })
+        .exec()
+    }
+  })
+</script>
+```
+
+在 SSR 场景下，不要在模块顶层、`setup` 同步阶段或服务端生命周期中直接访问 `window` / `document`；应放到客户端生命周期中，并用 `__mpx_mode__ === 'web'` 判断隔离。
+
+---
+
+## 引入第三方 H5 SDK
+
+第三方 H5 SDK 通常依赖浏览器全局对象，只能在 Web 分支中加载和执行。不要在跨端公共代码顶层直接 `import` 只支持浏览器的 SDK，否则小程序构建或 SSR 可能提前解析失败。
+
+推荐在 Web 条件分支内延迟加载：
+
+```js
+createComponent({
+  async ready () {
+    if (__mpx_mode__ !== 'web') return
+    const sdk = await import('third-party-h5-sdk')
+    sdk.init({
+      container: document.getElementById('sdk-root')
+    })
+  }
+})
+```
+
+如果 SDK 没有小程序等效能力，应保留小程序侧降级逻辑，例如展示占位内容、隐藏入口或调用小程序原有 API。Web 分支中引入的 SDK 配置、密钥、回调域名等仍应按业务安全要求处理，不能因为运行在 Mpx 组件内就省略浏览器侧校验。
+
+---
+
+## 使用 Vue 生态组件
+
+Web 输出产物是 Vue 2.7 组件，本地 `.vue` 组件或兼容 Vue 2 的第三方 Vue 组件可以作为普通组件注册使用。推荐通过 JSON `usingComponents` 注册，让 Mpx 编译链统一解析依赖、生成组件映射并处理异步分包等能力。
+
+```html
+<template>
+  <view>
+    <h5-chart
+      wx:if="{{__mpx_mode__ === 'web'}}"
+      data="{{ chartData }}"
+      bindchange="handleChartChange"
+    />
+  </view>
+</template>
+
+<script>
+  import { createComponent } from '@mpxjs/core'
+
+  createComponent({
+    data: {
+      chartData: []
+    },
+    methods: {
+      handleChartChange (e) {
+        this.triggerEvent('change', e.detail)
+      }
+    }
+  })
+</script>
+
+<script name="json">
+  const config = {}
+  if (__mpx_mode__ === 'web') {
+    config.usingComponents = {
+      'h5-chart': './H5Chart.vue'
+    }
+  }
+  module.exports = config
+</script>
+```
+
+注意事项：
+
+- `.vue` 组件应兼容项目当前 Vue 2.7 运行时；依赖 Vue 3-only 能力的组件不能直接使用。
+- 组件事件在 Web 侧由 Mpx 事件规则转为 Vue 事件；为了跨端一致，业务模板中仍优先使用 `bindxxx` / `catchxxx`。
+- `.vue` 组件属于 Web 专属依赖，模板节点与 JSON 注册都必须通过条件编译或文件维度隔离，不能暴露给小程序侧解析。
+
+---
+
+## 替换 Web 内建基础组件
+
+当需要扩展某个小程序基础组件在 Web 侧的实现，例如替换 `view`、`scroll-view` 或补充框架默认未覆盖的属性/事件时，使用 `webConfig.customBuiltInComponents`。
+
+```js
+// mpx.config.js
+module.exports = {
+  pluginOptions: {
+    mpx: {
+      plugin: {
+        webConfig: {
+          customBuiltInComponents: {
+            view: require('path').resolve(__dirname, 'src/builtin/MpxView.vue')
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+规则：
+
+- key 使用微信小程序原始基础标签名，如 `view`、`text`、`scroll-view`，不要写 `mpx-view`。
+- value 建议使用绝对路径或以 npm 包名开头的模块路径。
+- 命中的基础标签会优先使用自定义模块；属性、事件、子节点语义需要自定义组件自行对齐微信基础组件。
+- 该配置只影响 Web 输出；小程序侧不会读取。
+
+该能力适合替换基础组件实现，不适合普通业务组件复用。普通业务组件优先使用 JSON `usingComponents`。
+
+---
+
+## 跨端兼容隔离
+
+Web 混合开发引入的 DOM、H5 SDK、Vue 组件通常无法在小程序侧运行。根据差异大小选择隔离方式：
+
+### 局部差异：模板 / 脚本条件编译
+
+少量 Web 专属节点或属性，用模板条件编译隔离。
+
+```html
+<template>
+  <view>
+    <view class="fallback" wx:if="{{__mpx_mode__ !== 'web'}}">暂不支持</view>
+    <div wx:if="{{__mpx_mode__ === 'web'}}" class="web-panel"></div>
+  </view>
+</template>
+```
+
+脚本中只在 Web 分支访问浏览器对象。
+
+```js
+if (__mpx_mode__ === 'web') {
+  window.addEventListener('resize', handleResize)
+}
+```
+
+### 差异较大：文件维度条件编译
+
+如果组件大部分逻辑都依赖浏览器或第三方 H5 SDK，优先拆成平台文件：
+
+```text
+components/
+├── map-panel.mpx      # 小程序 / 通用实现
+└── map-panel.web.mpx  # Web 实现，可安全引入 H5 SDK / Vue 组件 / DOM 逻辑
+```
+
+文件维度隔离可以避免小程序构建解析 Web 专属依赖，也能让 Web 组件按浏览器语义组织代码。
+
+### 使用建议
+
+- 优先保持小程序原有实现不变，在 Web 分支补充 H5 能力。
+- Web 专属依赖不要放在跨端公共模块顶层静态引入。
+- SSR 场景中，浏览器对象访问必须延后到客户端执行。
+- 能用 Mpx 内建组件、统一环境 API 或 `usingComponents` 解决的问题，不要直接操作 DOM。
diff --git a/.agents/skills/mpx2web/references/web-json-reference.md b/.agents/skills/mpx2web/references/web-json-reference.md
new file mode 100644
index 0000000000..4218734c21
--- /dev/null
+++ b/.agents/skills/mpx2web/references/web-json-reference.md
@@ -0,0 +1,220 @@
+# 跨端输出 Web JSON 配置参考
+
+本文档说明 Mpx 输出 Web（`mode: 'web'`）时，`app.mpx` / 页面与组件 `.mpx` 中 JSON 配置的支持范围与使用注意。写法仍与微信小程序 `app.json`、页面/组件配置对齐；Web 侧会转成 Web 路由、组件注册与 Web 运行时页面配置。
+
+为避免文档滞后，未提到的字段默认不作为 Web 支持能力使用；有疑问时优先扫描 `packages/webpack-plugin/lib/web/processJSON.js`、`packages/webpack-plugin/lib/json-compiler/helper.js`、`packages/webpack-plugin/lib/platform/json/` 与 Web 运行时消费点。
+
+## 目录
+
+- [应用配置](#应用配置)
+- [页面配置](#页面配置)
+- [组件配置](#组件配置)
+- [分包与异步组件](#分包与异步组件)
+- [Web 相关配置](#web-相关配置)
+- [抽象节点](#抽象节点)
+
+---
+
+## 应用配置
+
+应用 JSON 用于注册页面、全局页面配置、tabBar、全局组件与分包等，写在 `app.mpx` 的 JSON 块中。
+
+示例如下（字段可按需取舍）：
+
+```JSON5
+{
+  pages: ["pages/index", { src: "pages/detail", path: "detail" }],
+  window: {
+    navigationBarTitleText: "默认标题",
+    enablePullDownRefresh: true,
+    onReachBottomDistance: 50
+  },
+  tabBar: {
+    color: "#666666",
+    selectedColor: "#1677ff",
+    backgroundColor: "#ffffff",
+    borderStyle: "black",
+    position: "bottom",
+    list: [{ pagePath: "pages/index", text: "首页" }]
+  },
+  packages: ["./packageA/app.mpx?root=packageA"],
+  usingComponents: {},
+  networkTimeout: 60000,
+  entryPagePath: "pages/index"
+}
+```
+
+下表为 Web 侧确认支持的应用级配置项，未提到的配置项默认不支持或不建议依赖。
+
+| 字段 | Web 侧支持说明 |
+| --- | --- |
+| `pages` | 注册 Web 路由页面，值可为页面路径字符串，或 `{ src, path? }` 对象；`path` 作为路由别名。 |
+| `entryPagePath` | 指定初始页面路径；未定义时使用 `pages` 数组首个页面。 |
+| `window` | 作为全局默认页面配置，与页面 JSON 合并后生效，页面配置优先。 |
+| `tabBar` | 支持，Web 侧渲染内建 tabBar；`custom: true` 时加载 `./custom-tab-bar/index`。 |
+| `usingComponents` | 全局组件注册。 |
+| `packages` | 声明额外页面包；路径上通过 `?root` 指定分包名时按异步页面包处理。 |
+| `subPackages` / `subpackages` | 兼容小程序分包写法；日常更推荐 `packages + ?root`。 |
+| `networkTimeout` | 作为 `mpx.request` 默认超时时间。 |
+| `style` | 注入 Web 运行时样式版本，未配置时为 `v1`。 |
+| `preloadRule` | 源码中未看到 Web 运行时消费，不建议依赖。 |
+
+---
+
+## 页面配置
+
+页面 JSON 写在各页面 `.mpx` 文件中，会与应用级 `window` 合并后作为当前页面配置。
+
+示例如下：
+
+```JSON5
+{
+  navigationBarTitleText: "详情",
+  enablePullDownRefresh: true,
+  disableScroll: false,
+  usingComponents: {
+    "detail-card": "../../components/detail-card"
+  }
+}
+```
+
+下表为 Web 侧确认支持的页面级配置项，未提到的配置项默认不支持或不建议依赖。
+
+| 字段 | Web 侧支持说明 |
+| --- | --- |
+| `navigationBarTitleText` | 页面激活时设置 `document.title`。 |
+| `enablePullDownRefresh` | 启用页面下拉刷新，可配合 `onPullDownRefresh` 与相关 API 使用。 |
+| `disableScroll` | 禁用页面默认滚动。 |
+| `onReachBottomDistance` | 配置 `onReachBottom` 触发距离，默认 `50`。 |
+| `backgroundColor` | 用于 Web 下拉刷新加载区域背景色。 |
+| `backgroundTextStyle` | 用于 Web 下拉刷新加载样式。 |
+| `usingComponents` | 局部组件注册，可配合 `?root` 及 `componentPlaceholder` 声明异步组件。 |
+| `componentPlaceholder` | 异步组件占位配置；占位组件需可解析，且不应再标记为异步。 |
+| `componentGenerics` | 抽象节点配置，带 `default` 的项会参与组件依赖收集。 |
+
+---
+
+## 组件配置
+
+组件 JSON 写在各组件 `.mpx` 文件中。
+
+示例如下：
+
+```JSON5
+{
+  usingComponents: {
+    inner: "./inner"
+  },
+  componentGenerics: {
+    item: {
+      default: "./default-item"
+    }
+  }
+}
+```
+
+下表为 Web 侧确认支持的组件级配置项，未提到的配置项默认不支持或不建议依赖。
+
+| 字段 | Web 侧支持说明 |
+| --- | --- |
+| `usingComponents` | 局部组件注册，可配合 `?root` 及 `componentPlaceholder` 声明异步组件。 |
+| `componentPlaceholder` | 异步组件占位配置；占位组件需可解析，且不应再标记为异步。 |
+| `componentGenerics` | 抽象节点配置，带 `default` 的项会参与组件依赖收集，详情见[抽象节点](#抽象节点)。 |
+
+---
+
+## 分包与异步组件
+
+Web 支持分包与异步组件的构建能力，运行时由 webpack 动态 `import()` 与浏览器 chunk 加载机制处理。
+
+### 使用 `packages` 定义分包
+
+在应用 JSON 的 `packages` 数组中声明分包入口，并通过 `?root=分包名` 指定分包名；分包名 `root` 不得以 `.` 开头。
+
+```JSON5
+{
+  pages: ["pages/index"],
+  packages: ["./packageA/app.mpx?root=packageA"]
+}
+```
+
+`subPackages` / `subpackages` 写法仍支持，用于兼容微信原生配置；日常更推荐 `packages + ?root`。
+
+### 异步组件
+
+在 `usingComponents` 路径上声明 `?root=分包名` 可标记异步组件，并在 `componentPlaceholder` 中配置同步占位组件。
+
+```JSON5
+{
+  usingComponents: {
+    hello: "../../packageB/components/hello?root=packageB",
+    "simple-hello": "../components/hello"
+  },
+  componentPlaceholder: {
+    hello: "simple-hello"
+  }
+}
+```
+
+占位组件需在当前页面或组件的 `usingComponents` 中可解析，且占位组件本身不要再标记为异步。
+
+### preloadRule
+
+源码中未看到 Web 运行时消费 `preloadRule`，Web 预加载不要依赖该字段，优先按路由、异步组件或业务加载逻辑处理。
+
+---
+
+## Web 相关配置
+
+以下配置不属于小程序 JSON 字段，但会影响 Web 路由、挂载和 SSR，遇到 Web 输出配置问题时一并核对。
+
+| 配置 | Web 侧说明 |
+| --- | --- |
+| `mpx.config.webConfig.routeConfig` | 推荐的 Web 路由配置入口，内容透传给 Web 路由实例。 |
+| `mpx.config.webRouteConfig` | 旧路由配置入口，仍兼容但不推荐继续使用。 |
+| `routeConfig.mode` | 路由模式；SSR 场景需使用 `history`。 |
+| `routeConfig.base` | 路由基础路径；非根路径部署时需与实际访问路径匹配。 |
+| `webConfig.el` | Web 应用挂载节点，未配置时为 `#app`。 |
+| `webConfig.useSSR` | SSR 模式下使用异步分包时设为 `true`。 |
+| `webConfig.disablePageTransition` | 是否禁用页面切换动画，默认 `true`。 |
+| `output.publicPath` | webpack 静态资源加载路径；非根路径部署时需与资源发布路径匹配。 |
+
+SSR 相关生命周期属于脚本能力：`onAppInit`、`serverPrefetch`、`onSSRAppCreated`。服务端阶段不要依赖 `window`、`document`、`getApp()`、`getCurrentPages()` 完成数据准备。
+
+---
+
+## 抽象节点
+
+Web 支持 `componentGenerics` 与模板中的 `generic:*` 组合。
+
+定义方声明抽象节点：
+
+```JSON5
+{
+  componentGenerics: {
+    item: {
+      default: "../default-item"
+    }
+  }
+}
+```
+
+使用方传入具体组件：
+
+```JSON5
+{
+  usingComponents: {
+    "custom-item": "../custom-item"
+  }
+}
+```
+
+```html
+<list generic:item="custom-item" />
+```
+
+使用要点：
+
+- 默认组件写在 `componentGenerics.xxx.default`。
+- 传入的具体组件需要在当前页面或组件的 `usingComponents` 中注册。
+- 抽象节点名保持小程序写法，Web 编译阶段会转为运行时可识别的组件映射。
diff --git a/.agents/skills/mpx2web/references/web-script-reference.md b/.agents/skills/mpx2web/references/web-script-reference.md
new file mode 100644
index 0000000000..750e29dd98
--- /dev/null
+++ b/.agents/skills/mpx2web/references/web-script-reference.md
@@ -0,0 +1,238 @@
+# 跨端输出 Web 脚本能力参考
+
+本文档说明 Mpx 输出 Web（`mode: 'web'`）时，`<script>` 中可用的构造选项、生命周期、实例 API、组合式 API 与状态管理能力。Web 侧整体能力与小程序写法高度一致；下文重点记录 Web 运行时确认支持的能力与需要隔离的小程序专属能力。
+
+## 目录
+
+- [构造选项](#构造选项)
+  - [App 构造选项](#app-构造选项)
+  - [页面 / 组件构造选项](#页面--组件构造选项)
+  - [页面 / 组件实例方法与属性](#页面--组件实例方法与属性)
+- [数据响应](#数据响应)
+- [组合式 API](#组合式-api)
+- [生命周期](#生命周期)
+- [Mpx 运行时导出](#mpx-运行时导出)
+- [全局 API](#全局-api)
+- [环境 API](#环境-api)
+- [状态管理](#状态管理)
+
+---
+
+## 构造选项
+
+### App 构造选项
+
+`createApp(options)` 用于注册应用级逻辑、全局字段与 SSR 钩子。Web 下非生命周期字段会进入 `getApp()` 返回对象；全局响应式状态建议使用 Pinia 或业务 store，不要依赖 App 自身响应式。
+
+| 选项 | Web 侧说明 |
+| --- | --- |
+| `onLaunch` | Web 应用创建后触发，入参包含当前路由 `path`、`query` 等基础信息。 |
+| `onShow` | 首次启动后触发；页面从隐藏切回可见时也会触发。 |
+| `onHide` | 页面进入隐藏态时触发，Web 下不提供隐藏原因。 |
+| `onError` | Web 侧注册到全局错误回调链。 |
+| `onUnhandledRejection` | Web 侧注册到未处理 Promise 拒绝回调链。 |
+| `onPageNotFound` | 首次进入不存在页面时可触发；非首次路由跳转找不到页面会按导航 API 失败处理。 |
+| `onSSRAppCreated` | SSR 服务端应用创建钩子，见[生命周期](#生命周期)。 |
+| `onAppInit` | SSR / 应用创建前扩展钩子，常用于创建并返回新的 Pinia 实例。 |
+| `provide` | 可作为应用级 provide 使用。 |
+| 其他顶层字段 | 挂到 `getApp()` 返回对象上。 |
+| `data` / `computed` / `watch` | App 级不作为业务响应式状态使用。 |
+
+### 页面 / 组件构造选项
+
+页面使用 `createPage`，组件使用 `createComponent`。常规选项会转换为 Web 运行时组件选项。
+
+| 选项 | 适用 | Web 侧说明 |
+| --- | --- | --- |
+| `properties` / `props` | 组件 | 转换为 Web 组件 props；`value` 会转为默认值。 |
+| `data` | 页面 / 组件 | 响应式状态，支持对象或函数形态。 |
+| `computed` | 页面 / 组件 | 计算属性。 |
+| `watch` | 页面 / 组件 | 侦听器；字符串路径支持逗号分隔多字段。 |
+| `methods` | 页面 / 组件 | 事件处理与业务方法，Web 下会包裹错误处理。 |
+| `mixins` | 页面 / 组件 | 按 Mpx 选项合并规则处理。 |
+| `provide` / `inject` | 页面 / 组件 | 支持。 |
+| `setup` | 页面 / 组件 | 支持组合式 API，详见[组合式 API](#组合式-api)。 |
+| `components` | 页面 / 组件 | 可注册 Web 组件；跨端组件依赖优先使用 JSON `usingComponents`。 |
+| `pageLifetimes.show` | 组件 | 所在页面展示时触发。 |
+| `pageLifetimes.hide` | 组件 | 所在页面隐藏时触发。 |
+| `pageLifetimes.resize` | 组件 | 所在页面尺寸变化时触发。 |
+| `relations` | 组件 | Web 下不按小程序原生 relations 能力实现，需避免依赖。 |
+| `moved` / `definitionFilter` | 组件 | Web 运行时转换不支持。 |
+
+### 页面 / 组件实例方法与属性
+
+| 名称 | 类型 | 适用 | Web 侧说明 |
+| --- | --- | --- | --- |
+| `route` | 属性 | 页面 | 当前页面路由路径。 |
+| `data` | 属性 | 页面 / 组件 | 合并后的 `$props` 与 `$data` 快照。 |
+| `dataset` | 属性 | 页面 / 组件 | 从 DOM attrs 收集的 dataset。 |
+| `id` | 属性 | 页面 / 组件 | 当前实例根节点 id。 |
+| `getPageId()` | 方法 | 页面 / 组件 | 返回当前页面 id。 |
+| `getOpenerEventChannel()` | 方法 | 页面 | 获取 `navigateTo` 创建的 `EventChannel`。 |
+| `triggerEvent(name, detail?)` | 方法 | 组件 | 派发自定义事件；`click` 会转为内部 `_click` 事件以避开原生点击冲突。 |
+| `selectComponent(selector)` | 方法 | 页面 / 组件 | 查找第一个匹配组件实例；Web 下仅支持基础选择器，不支持关系选择器。 |
+| `selectAllComponents(selector)` | 方法 | 页面 / 组件 | 查找全部匹配组件实例；规则同 `selectComponent`。 |
+| `createSelectorQuery()` | 方法 | 页面 / 组件 | 创建 selector 查询，基于 Web DOM 实现。 |
+| `createIntersectionObserver(options?)` | 方法 | 页面 / 组件 | 创建交叉观察器，基于 Web DOM / IntersectionObserver 能力。 |
+| `$refs` | 属性 | 页面 / 组件 | 支持 `wx:ref`；DOM / 内建组件 ref 会转换为 selector 查询结果。 |
+| `$watch` | 方法 | 页面 / 组件 | 实例 watch，支持 Mpx 对逗号路径的扩展。 |
+| `$forceUpdate` | 方法 | 页面 / 组件 | 强制刷新视图。 |
+| `$nextTick` | 方法 | 页面 / 组件 | 视图更新后执行回调。 |
+| `$set` / `$delete` | 方法 | 页面 / 组件 | 响应式新增 / 删除字段。 |
+| `$t` / `$tc` / `$te` / `$tm` | 方法 | 页面 / 组件 | i18n 方法，依赖工程 i18n 配置。 |
+| `setData` | 方法 | 页面 / 组件 | 小程序兼容 API；Web 业务优先直接赋值。 |
+
+---
+
+## 数据响应
+
+Web 侧支持响应式数据更新，页面和组件数据可直接赋值更新视图。
+
+| 能力 | Web 侧说明 |
+| --- | --- |
+| `data` | 响应式状态根。 |
+| `computed` | 基于依赖缓存。 |
+| `watch` / `$watch` | 支持路径、函数和对象写法。 |
+| `setData` | 兼容小程序写法，不是 Web 首选。 |
+| `$set` / `mpx.set` | 为响应式对象新增字段。 |
+| `$delete` / `mpx.delete` | 删除响应式对象字段。 |
+
+---
+
+## 组合式 API
+
+Web 支持 Mpx 组合式 API，从 `@mpxjs/core` 命名导出引入。
+
+| 能力 | Web 侧说明 |
+| --- | --- |
+| `setup(props, context)` | 支持；生命周期钩子需在 `setup` 同步执行期间注册。 |
+| `props` | 对应组件 `properties` / `props`，直接解构会丢响应式，按需使用 `toRefs`。 |
+| `context.triggerEvent` | 同实例 `triggerEvent`。 |
+| `context.refs` | 同实例 `$refs`。 |
+| `context.forceUpdate` | 同实例 `$forceUpdate`。 |
+| `context.selectComponent` / `selectAllComponents` | 同实例选择组件方法。 |
+| `context.createSelectorQuery` / `createIntersectionObserver` | 同实例查询 / 观察方法。 |
+| `context.getPageId` | 同实例 `getPageId`。 |
+| `<script setup>` | 支持 Mpx 编译宏；需要通过 `defineExpose` 显式暴露模板使用的数据和方法。 |
+| `defineProps` | `<script setup>` 编译宏，接收 `properties` 同形态声明。 |
+| `defineExpose` | `<script setup>` 编译宏，用于限定暴露给模板的绑定。 |
+| `defineOptions` | `<script setup>` 编译宏，用于声明选项式配置。 |
+| `useContext` | `<script setup>` 编译宏，用于获取 `setup` 的 `context`。 |
+
+常用响应式导出包括 `ref`、`reactive`、`computed`、`watch`、`watchEffect`、`toRef`、`toRefs`、`provide`、`inject`、`getCurrentInstance`、`useI18n` 等。
+
+---
+
+## 生命周期
+
+### 生命周期对应关系
+
+| 生命周期 | 适用 | Web 侧说明 |
+| --- | --- | --- |
+| `onLaunch` | App | 应用创建后触发。 |
+| `onShow` | App / 页面 | App 可见、页面激活时触发。 |
+| `onHide` | App / 页面 | App 隐藏、页面失活时触发。 |
+| `onError` | App | 全局错误回调。 |
+| `onUnhandledRejection` | App | 未处理 Promise 拒绝回调。 |
+| `onPageNotFound` | App | 首次进入不存在页面时触发。 |
+| `onLoad` | 页面 | 页面创建后触发，入参为路由 query。 |
+| `onReady` | 页面 | 页面首次挂载完成后触发。 |
+| `onUnload` | 页面 | 页面卸载时触发。 |
+| `onResize` | 页面 / 组件 `pageLifetimes` | 浏览器窗口尺寸变化时触发。 |
+| `onPullDownRefresh` | 页面 | 需页面 JSON 开启 `enablePullDownRefresh`。 |
+| `onReachBottom` | 页面 | 页面滚动触底时触发，距离由 `onReachBottomDistance` 控制。 |
+| `onPageScroll` | 页面 | 页面滚动时触发。 |
+| `created` / `attached` | 组件 | 组件创建 / 挂载阶段触发。 |
+| `ready` | 组件 | 组件挂载完成后触发。 |
+| `detached` | 组件 | 组件销毁时触发。 |
+| `pageLifetimes.show` / `hide` / `resize` | 组件 | 随所属页面状态触发。 |
+| `serverPrefetch` | App / 页面 / 组件 | SSR 服务端数据预取。 |
+| `onAppInit` | App | SSR / 应用创建前扩展，常用于创建 Pinia。 |
+| `onSSRAppCreated` | App | SSR 服务端应用创建后回调，可处理路由和状态注入。 |
+
+### Web 没有对应能力或需降级
+
+| 生命周期 | Web 侧说明 |
+| --- | --- |
+| `onShareAppMessage` | Web 没有小程序分享面板能力；如需分享，使用 Web 分享或业务自定义分享方案。 |
+| `onShareTimeline` | Web 没有朋友圈分享生命周期能力。 |
+| `onAddToFavorites` | Web 没有小程序收藏生命周期能力。 |
+| `onTabItemTap` | Web 有 tabBar 路由切换，但没有小程序 `onTabItemTap` 生命周期能力。 |
+| `onSaveExitState` | Web 没有小程序退出状态保存能力。 |
+| `onThemeChange` | Web 没有小程序主题变更生命周期能力；如需适配主题，使用 Web 媒体查询或业务方案。 |
+
+### 注意事项
+
+- 页面 show / hide 由 Web 路由 keep-alive 激活态与浏览器可见性变化驱动。
+- `onPullDownRefresh` 需页面配置 `enablePullDownRefresh: true`。
+- `onPageScroll` / `onReachBottom` 在 `disableScroll: true` 时不按页面滚动触发。
+- SSR 阶段不要直接访问 `window`、`document`、`localStorage` 等浏览器对象。
+
+---
+
+## Mpx 运行时导出
+
+### 默认导出
+
+默认导出的 `mpx` 对象包含全局 API、插件安装与环境 API 能力。
+
+| 能力 | Web 侧说明 |
+| --- | --- |
+| `mpx.use(plugin, options?)` | 安装插件。 |
+| `mpx.mixin` / `mpx.injectMixins` | 注入全局 mixin。 |
+| `mpx.observable` | 创建响应式对象。 |
+| `mpx.watch` | 创建侦听器。 |
+| `mpx.set` / `mpx.delete` | 响应式新增 / 删除字段。 |
+| `mpx.isReactive` / `mpx.isRef` | 响应式判断。 |
+| `mpx.nextTick` | 下一轮更新后执行。 |
+| `mpx.xxx` 环境 API | 详见 [环境 API 参考](./web-api-reference.md)。 |
+
+### 命名导出
+
+| 导出 | Web 侧说明 |
+| --- | --- |
+| `createApp` / `createPage` / `createComponent` | App / 页面 / 组件构造函数。 |
+| `nextTick` | 更新后回调。 |
+| `ref` / `reactive` / `computed` / `watch` | 组合式响应能力。 |
+| `toRef` / `toRefs` / `unref` / `isRef` | ref 工具。 |
+| `watchEffect` / `watchSyncEffect` / `watchPostEffect` | effect 类侦听。 |
+| `effectScope` / `getCurrentScope` / `onScopeDispose` | effect scope。 |
+| `provide` / `inject` | 依赖注入。 |
+| `getCurrentInstance` | 获取当前 Mpx 实例代理。 |
+| `useI18n` | i18n 组合式入口。 |
+| `onLoad` / `onShow` / `onHide` / `onReady` 等 | 组合式生命周期注册函数。 |
+
+---
+
+## 全局 API
+
+| API | Web 侧说明 |
+| --- | --- |
+| `getApp()` | 返回 App 级普通字段对象；服务端调用有风险。 |
+| `getCurrentPages()` | 返回当前 Web 路由栈对应页面实例；服务端调用有风险。 |
+| `mpx.config.webConfig.routeConfig` | Web 路由配置，见 [JSON 配置参考](./web-json-reference.md)。 |
+| `plugin.webConfig.useSSR` | SSR 异步分包编译配置，见 [JSON 配置参考](./web-json-reference.md)。 |
+
+---
+
+## 环境 API
+
+环境能力统一通过 `mpx.xxx` 调用，Web 侧由 `@mpxjs/api-proxy` 映射到浏览器实现。具体支持范围见 [环境 API 参考](./web-api-reference.md)。
+
+---
+
+## 状态管理
+
+### `@mpxjs/pinia`（推荐）
+
+Web 端 `@mpxjs/pinia` 直接适配 Pinia，推荐新项目和组合式 API 场景使用。
+
+| 场景 | Web 侧说明 |
+| --- | --- |
+| CSR | 可创建全局 Pinia 实例并使用 `defineStore`。 |
+| SSR | 需在 `onAppInit` 中为每次请求创建并返回新的 Pinia 实例。 |
+| 数据预取 | 配合 `serverPrefetch` 与 `onSSRAppCreated` 同步服务端状态。 |
+
+### `@mpxjs/store`
+
+`@mpxjs/store` 为历史 Vuex 风格状态管理方案。新状态域优先使用 `@mpxjs/pinia`；已有项目深度依赖时可继续维护。
diff --git a/.agents/skills/mpx2web/references/web-style-practice.md b/.agents/skills/mpx2web/references/web-style-practice.md
new file mode 100644
index 0000000000..fc6c3ff136
--- /dev/null
+++ b/.agents/skills/mpx2web/references/web-style-practice.md
@@ -0,0 +1,177 @@
+# 跨端输出 Web 样式实践
+
+本文档说明 Mpx 输出 Web 时样式层的少量差异与实践。Web 基于真实 CSS 引擎，CSS 能力通常比小程序更完整；不要按属性清单逐项判断 Web 是否支持，也不要为了 Web 兼容改写已有小程序样式。只有在使用 Web 专属 CSS、移动端适配或单位转换时才需要关注本文件。
+
+## 目录
+
+- [总体判断](#总体判断)
+- [单位与适配](#单位与适配)
+- [Web 专属 CSS](#web-专属-css)
+- [安全区域](#安全区域)
+- [固定定位与滚动](#固定定位与滚动)
+- [1px 边框](#1px-边框)
+- [公共样式](#公共样式)
+
+---
+
+## 总体判断
+
+| 场景 | Web 侧说明 |
+| --- | --- |
+| 常规 CSS 属性 | Web 可直接使用，不需要为 Web 兼容改写。 |
+| 复合选择器、伪类、伪元素、媒体查询 | Web 支持；小程序不支持的选择器需条件编译隔离。 |
+| `grid`、`float`、`position: sticky`、CSS 变量、`calc()` | Web 支持；其中 `position: sticky`、CSS 变量不要作为跨小程序公共样式能力。 |
+| `scoped` | Web 支持，编译阶段会添加 scope 标识。 |
+| `lang` 预处理器 | 按工程 loader 配置支持 Less / Sass / Stylus 等。 |
+| 动态样式 | 优先用 `wx:class` / `wx:style`，避免在 `class` / `style` 字符串里拼接 `{{}}`。 |
+
+---
+
+## 单位与适配
+
+### rpx
+
+Web 输出下样式中的 `rpx` 默认会转换为 `vw`，换算基准为 `750rpx = 100vw`。
+
+```css
+.box {
+  width: 750rpx; /* Web 默认约等于 100vw */
+}
+```
+
+`webConfig.transRpxFn` 可自定义 Web 输出的 `rpx` 转换规则，例如转为 `rem` 或其它单位。
+
+```js
+module.exports = {
+  pluginOptions: {
+    mpx: {
+      plugin: {
+        webConfig: {
+          transRpxFn: function (match, value) {
+            if (value === '0') return value
+            return `${value * 0.01}rem`
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+### px 转 rpx 注释
+
+如果工程使用 `transRpxRules`，保留原样式中的 `/* use rpx */` 与 `/* use px */` 注释。它们用于控制编译期是否把 `px` 转成 `rpx`，随后 Web 再按 `rpx` 规则转换。
+
+| 注释 | 常见用途 |
+| --- | --- |
+| `/* use rpx */` | `mode: only` 下，仅标记的规则或声明参与 px 到 rpx 转换。 |
+| `/* use px */` | `mode: all` 下，排除标记的规则或声明。 |
+
+### Web 原生单位
+
+`rem`、`em`、`vw`、`vh`、`vmin`、`vmax` 等 Web 原生单位可在 Web 使用。若同一份样式还要输出小程序端，优先使用 `rpx` / `px` 等跨端稳定单位；确需 Web 原生单位时用样式条件编译隔离。
+
+---
+
+## Web 专属 CSS
+
+Web 支持的 CSS 比小程序更多。以下写法可用于 Web，但不要直接放进跨端公共样式。
+
+小程序侧需按跨渲染引擎口径判断：Skyline 不支持或不稳定的 CSS 能力，即使 WebView 渲染下可能部分生效，也不要写入跨小程序公共样式。需要使用时用条件编译隔离到 Web，或只在已验证的单一小程序目标内使用。
+
+| 能力 | 小程序结论 | 建议 |
+| --- | --- | --- |
+| `::-webkit-scrollbar` 等浏览器私有伪元素 | 小程序不可用。 | Web 专属，用样式条件编译隔离。 |
+| `:hover` 等鼠标交互伪类 | 小程序不可用。 | Web 专属；小程序点击态用组件 `hover-class`。 |
+| CSS 变量 | 不作为跨小程序公共能力。 | Web 可用；只在 Web 样式或已验证的单一小程序目标内使用。 |
+| `position: sticky` | 不作为跨小程序公共能力。 | Web 可用；小程序侧需要吸顶时使用平台组件或业务实现。 |
+| `backdrop-filter`、高级滤镜等 | 小程序不可用。 | Web 专属，用样式条件编译隔离。 |
+
+样式条件编译示例：
+
+```css
+/* @mpx-if (__mpx_mode__ === 'web') */
+.scrollbar::-webkit-scrollbar {
+  width: 4px;
+}
+/* @mpx-endif */
+```
+
+---
+
+## 安全区域
+
+Web 可使用 `env(safe-area-inset-*)` 处理刘海屏和底部手势区域。
+
+```css
+.page {
+  padding-bottom: env(safe-area-inset-bottom);
+}
+```
+
+`env(safe-area-inset-*)` 在 Web 与部分小程序 WebView 场景可直接使用。若业务已在目标小程序验证可用，可以放在公共样式中；若还需覆盖 Skyline 或其他未验证容器，使用平台安全区 API 或业务注入变量做兜底。
+
+---
+
+## 固定定位与滚动
+
+Web 页面默认使用浏览器滚动。页面级滚动生命周期由 Mpx Web 运行时处理，页面 JSON 中 `disableScroll` 会影响页面滚动。
+
+| 场景 | 建议 |
+| --- | --- |
+| 页面整体滚动 | 优先使用页面默认滚动，配合 `onPageScroll` / `onReachBottom`。 |
+| 局部滚动 | 使用 `scroll-view` 或 Web 原生 `overflow`，注意小程序端滚动容器差异。 |
+| `position: fixed` | Web 支持；小程序端固定定位表现与层级可能不同，复杂场景需分端确认。 |
+| 禁止页面滚动 | 页面 JSON 使用 `disableScroll: true`，自定义滚动容器承接内容滚动。 |
+
+---
+
+## 1px 边框
+
+Web 高分屏细线不要依赖 `0.5px` 边框，优先使用伪元素缩放或业务通用 mixin。跨端公共样式中保留小程序侧稳定写法，Web 需要更细的视觉效果时用条件编译增强。
+
+```css
+.hairline {
+  position: relative;
+}
+
+/* @mpx-if (__mpx_mode__ === 'web') */
+.hairline::after {
+  content: '';
+  position: absolute;
+  left: 0;
+  top: 0;
+  width: 100%;
+  height: 100%;
+  border: 1px solid #e5e5e5;
+  pointer-events: none;
+}
+
+@media (-webkit-min-device-pixel-ratio: 2), (min-resolution: 2dppx) {
+  .hairline::after {
+    width: 200%;
+    height: 200%;
+    transform: scale(0.5);
+    transform-origin: 0 0;
+  }
+}
+
+@media (-webkit-min-device-pixel-ratio: 3), (min-resolution: 3dppx) {
+  .hairline::after {
+    width: 300%;
+    height: 300%;
+    transform: scale(0.333333);
+    transform-origin: 0 0;
+  }
+}
+/* @mpx-endif */
+```
+
+---
+
+## 公共样式
+
+- 跨端公共样式优先使用小程序与 Web 都稳定支持的写法。
+- Web 专属增强样式用条件编译最小包裹，不要整段样式大面积分叉。
+- 保留 `/* use rpx */` / `/* use px */` 注释，避免破坏工程单位转换规则。
+- 移动端 Web 页面需保证 HTML 模板配置正确的 viewport；Mpx 样式文件本身不负责注入 viewport。
diff --git a/.agents/skills/mpx2web/references/web-template-reference.md b/.agents/skills/mpx2web/references/web-template-reference.md
new file mode 100644
index 0000000000..870171f847
--- /dev/null
+++ b/.agents/skills/mpx2web/references/web-template-reference.md
@@ -0,0 +1,114 @@
+# 跨端输出 Web 模板能力参考
+
+本文档只记录 Mpx 输出 Web 时模板层需要特别判断的能力。常规小程序模板语法在 Web 下通常无需改写。
+
+## 目录
+
+- [数据绑定](#数据绑定)
+- [模板指令](#模板指令)
+- [事件处理](#事件处理)
+- [Slot](#slot)
+- [动态组件](#动态组件)
+- [WXML 模板](#wxml-模板)
+- [i18n 国际化](#i18n-国际化)
+- [无障碍访问](#无障碍访问)
+- [基础组件](#基础组件)
+
+---
+
+## 数据绑定
+
+Mustache 插值、属性绑定、三元表达式、逻辑表达式、可选链、`__mpx_mode__` / `__mpx_env__` / `defs` 变量在 Web 下支持。
+
+模板中不要直接调用普通 methods；需要加工展示数据时使用 `computed` 或 `wxs`。i18n 翻译函数可按 i18n 约束使用。
+
+## 模板指令
+
+| 指令 | Web 支持 | 说明 |
+| --- | --- | --- |
+| `wx:if` / `wx:elif` / `wx:else` | 支持 | 条件渲染。 |
+| `wx:show` | 支持 | 显示隐藏。 |
+| `wx:for` / `wx:for-item` / `wx:for-index` | 支持 | 列表渲染。 |
+| `wx:key` | 支持 | 建议列表稳定使用。 |
+| `wx:class` | 支持 | 推荐用于动态 class。 |
+| `wx:style` | 支持 | 推荐用于动态 style。 |
+| `wx:model` 及 `wx:model-*` | 支持 | 可用于基础组件和自定义组件。 |
+| `wx:ref` | 支持 | 可获取基础组件节点或自定义组件实例。 |
+
+动态 `class` / `style` 不要在字符串里拼接 `{{}}`，优先使用 `wx:class` / `wx:style`。
+
+## 事件处理
+
+Web 支持小程序事件绑定语法：`bind`、`catch`、`capture-bind`、`capture-catch`，支持事件冒泡、捕获和内联传参。
+
+常用事件字段 `type`、`detail`、`target`、`currentTarget`、`timeStamp` 可用。依赖小程序原生事件额外字段时按具体组件判断。
+
+## Slot
+
+默认插槽、具名插槽支持。自定义组件多插槽按小程序写法使用。
+
+## 动态组件
+
+`<component is="...">` 支持。目标组件需在 JSON `usingComponents`、全局组件或抽象节点配置中可解析。
+
+抽象节点在 Web 下支持，配置见 [JSON 配置参考](./web-json-reference.md)。
+
+## WXML 模板
+
+| 写法 | Web 支持 | 说明 |
+| --- | --- | --- |
+| `<template name="...">` | 支持 | 可定义可复用模板。 |
+| `<template is="..." data="{{...}}">` | 支持 | `is` 目标需能在本文件或 import 中找到。 |
+| `<import src="...">` | 支持 | 可引入外部模板定义。 |
+| `<include src="...">` | 不支持 | 改用 `import + template is` 或组件。 |
+
+Web 模板定义需要单根节点，多根模板定义会编译报错。
+
+## i18n 国际化
+
+模板内支持项目 i18n 翻译函数。组合式 API 中使用 `useI18n()` 时，返回给模板的函数名保持 `t` / `tc` / `te` / `tm`，不要重命名。
+
+## 无障碍访问
+
+`aria-*`、`role`、`tabindex` 等 Web 无障碍属性可用。
+
+小程序专属无障碍字段不要假定在 Web 有相同语义；需要 Web 无障碍时直接使用 Web 标准属性，并按跨端条件隔离小程序不接受的写法。
+
+## 基础组件
+
+### 支持组件
+
+以下组件在 Web 下可按小程序写法优先使用。
+
+| 类型 | 组件 | Web 行为 |
+| --- | --- | --- |
+| 视图容器 | `view`、`cover-view` | 常规展示可用；`cover-view` 不具备小程序原生覆盖层语义。 |
+| 滚动 | `scroll-view` | 支持滚动、下拉刷新相关能力。 |
+| 轮播 | `swiper`、`swiper-item` | 支持。 |
+| 拖拽 | `movable-area`、`movable-view` | 支持。 |
+| 基础内容 | `text`、`cover-image`、`image`、`icon`、`progress`、`rich-text` | 支持。 |
+| 表单 | `button`、`input`、`textarea`、`checkbox`、`checkbox-group`、`radio`、`radio-group`、`picker`、`picker-view`、`picker-view-column`、`slider`、`switch`、`form`、`label` | 支持；键盘、输入类型、表单提交等按浏览器能力降级。 |
+| 导航 | `navigator` | 支持；`open-type` 仅支持 Web 可实现的导航语义。 |
+| 媒体 | `video` | 支持；投屏、小程序广告、原生画中画等小程序宿主能力不可依赖。 |
+| Web 容器 | `web-view` | 以 Web 页面容器承载目标地址；域名白名单、postMessage 和导航桥接按 Web 能力工作。 |
+| 扩展组件 | `sticky-section`、`sticky-header` | 支持。 |
+
+### 没有 Web 小程序能力的组件
+
+| 组件 | Web 结论 | 建议 |
+| --- | --- | --- |
+| `camera` | Web 没有小程序相机组件能力。 | 使用浏览器媒体能力或业务 H5 SDK，并用条件编译隔离。 |
+| `live-player` / `live-pusher` | Web 没有小程序直播组件能力。 | 使用 H5 播放/推流方案，并用条件编译隔离。 |
+| `open-data` | Web 没有小程序开放数据能力。 | 改为业务接口或 Web 用户体系。 |
+| `official-account` | Web 没有小程序公众号关注组件能力。 | 改为 Web 侧业务入口。 |
+| `ad` / `ad-custom` | Web 没有小程序广告组件能力。 | 使用 Web 广告 SDK，并用条件编译隔离。 |
+| `functional-page-navigator` | Web 没有小程序功能页能力。 | 使用 Web 页面或业务流程替代。 |
+| `editor` | Web 没有对应内置组件。 | 使用 Web 富文本编辑器，并用条件编译隔离。 |
+| `map` | Web 没有小程序地图组件能力。 | 使用 Web 地图 SDK 或业务地图组件。 |
+| `audio` | Web 没有小程序 `audio` 组件能力。 | 使用原生 `<audio>` 或业务音频组件。 |
+
+### 特殊说明
+
+- `canvas` 在 Web 下可作为原生 `<canvas>` 使用，但不等同于小程序 Canvas 组件完整能力；小程序 Canvas API 迁移需结合 Web Canvas API 或业务封装处理。
+- `cover-view` 在 Web 不具备小程序原生覆盖层语义，按普通展示容器处理。
+- `customBuiltInComponents` 可接入业务自定义组件，具体能力以业务实现为准。
diff --git a/.agents/skills/mpx2web/scripts/compile-validate.js b/.agents/skills/mpx2web/scripts/compile-validate.js
new file mode 100644
index 0000000000..bc94b368ce
--- /dev/null
+++ b/.agents/skills/mpx2web/scripts/compile-validate.js
@@ -0,0 +1,613 @@
+#!/usr/bin/env node
+'use strict'
+
+const fs = require('fs')
+const path = require('path')
+const os = require('os')
+const crypto = require('crypto')
+
+class MpxCliNotFoundError extends Error {
+  constructor (msg) { super(msg); this.name = 'MpxCliNotFoundError' }
+}
+class InvalidInputError extends Error {
+  constructor (msg) { super(msg); this.name = 'InvalidInputError' }
+}
+
+function resolveProjectRoot (startPath) {
+  let cur = fs.existsSync(startPath) && fs.statSync(startPath).isDirectory()
+    ? startPath
+    : path.dirname(startPath)
+  cur = path.resolve(cur)
+  const rootDir = path.parse(cur).root
+  while (true) {
+    const pkgPath = path.join(cur, 'package.json')
+    if (fs.existsSync(pkgPath)) {
+      try {
+        const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'))
+        const deps = Object.assign({}, pkg.dependencies, pkg.devDependencies)
+        if (deps['@mpxjs/mpx-cli-service']) return cur
+      } catch (_) { /* ignore parse error */ }
+    }
+    if (fs.existsSync(path.join(cur, 'node_modules', '@mpxjs', 'mpx-cli-service'))) {
+      return cur
+    }
+    if (cur === rootDir) return null
+    cur = path.dirname(cur)
+  }
+}
+
+function resolveFromProject (name, projectRoot) {
+  try {
+    return require.resolve(name, { paths: [projectRoot] })
+  } catch (err) {
+    const anchors = [
+      '@mpxjs/mpx-cli-service',
+      '@mpxjs/vue-cli-plugin-mpx/config',
+      '@mpxjs/webpack-plugin'
+    ]
+    for (const anchor of anchors) {
+      try {
+        const anchorPath = require.resolve(anchor, { paths: [projectRoot] })
+        return require.resolve(name, { paths: [path.dirname(anchorPath)] })
+      } catch (_) {}
+    }
+    throw err
+  }
+}
+
+function requireFromProject (name, projectRoot) {
+  const resolved = resolveFromProject(name, projectRoot)
+  return require(resolved)
+}
+
+function assertProjectDeps (projectRoot) {
+  const deps = [
+    '@mpxjs/mpx-cli-service',
+    '@mpxjs/cli-shared-utils',
+    '@mpxjs/vue-cli-plugin-mpx/config',
+    '@mpxjs/vue-cli-plugin-mpx/config/base',
+    '@mpxjs/mpx-cli-service/utils/filterPlugins',
+    '@vue/cli-service/lib/PluginAPI',
+    'webpack',
+    '@mpxjs/webpack-plugin'
+  ]
+  const missing = []
+  deps.forEach(name => {
+    try {
+      resolveFromProject(name, projectRoot)
+    } catch (_) {
+      missing.push(name)
+    }
+  })
+  if (missing.length) {
+    throw new MpxCliNotFoundError(
+      `业务项目 ${projectRoot} 缺少编译校验依赖: ${missing.join(', ')}`
+    )
+  }
+}
+
+// 简单 semver 比较：a >= b 返回 true。仅支持 'x.y.z' 三段数字。
+function gteVersion (a, b) {
+  const pa = String(a).split('.').map(n => parseInt(n, 10) || 0)
+  const pb = String(b).split('.').map(n => parseInt(n, 10) || 0)
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    const da = pa[i] || 0
+    const db = pb[i] || 0
+    if (da > db) return true
+    if (da < db) return false
+  }
+  return true
+}
+
+// `partialCompileRules.components` 自 @mpxjs/webpack-plugin@2.10.20 起支持。
+// 低版本回退到前置 loader 剥离 usingComponents 的"不完美"兼容方案。
+const PARTIAL_COMPILE_COMPONENTS_MIN_VERSION = '2.10.20'
+
+function hasComponentPartialCompile (projectRoot) {
+  try {
+    const { getPartialCompileRules } = requireFromProject(
+      '@mpxjs/webpack-plugin/lib/utils/partial-compile-rules', projectRoot
+    )
+    return !!getPartialCompileRules({ components: { include: () => true } }, 'component')
+  } catch (_) {
+    try {
+      const pkg = requireFromProject('@mpxjs/webpack-plugin/package.json', projectRoot)
+      return gteVersion(pkg.version, PARTIAL_COMPILE_COMPONENTS_MIN_VERSION)
+    } catch (_) {
+      return false
+    }
+  }
+}
+
+async function compileValidate (input, options = {}) {
+  const mpxPaths = (Array.isArray(input) ? input : [input]).map(p => path.resolve(p))
+  for (const p of mpxPaths) {
+    if (!fs.existsSync(p) || !fs.statSync(p).isFile()) {
+      throw new InvalidInputError(`输入不是有效文件: ${p}`)
+    }
+  }
+
+  const {
+    target = 'web',
+    type = 'component',
+    projectRoot: explicitRoot,
+    ignoreSubComponents = true,
+    cleanup = true
+  } = options
+
+  if (type !== 'page' && type !== 'component') {
+    throw new InvalidInputError(`不支持的 type: ${type}，只接受 'page' 或 'component'`)
+  }
+
+  const projectRoot = explicitRoot
+    ? path.resolve(explicitRoot)
+    : resolveProjectRoot(mpxPaths[0])
+  if (!projectRoot) {
+    throw new MpxCliNotFoundError(
+      `未找到安装了 @mpxjs/mpx-cli-service 的业务项目，无法执行真实编译校验。起点: ${mpxPaths[0]}`
+    )
+  }
+  assertProjectDeps(projectRoot)
+
+  const targets = Array.isArray(target) ? target : [target]
+  if (targets.length === 1) {
+    return compileOne(projectRoot, mpxPaths, targets[0], type, ignoreSubComponents, cleanup)
+  }
+  const out = {}
+  for (const t of targets) {
+    out[t] = await compileOne(projectRoot, mpxPaths, t, type, ignoreSubComponents, cleanup)
+  }
+  return out
+}
+
+async function compileOne (projectRoot, mpxPaths, targetMode, type, ignoreSubComponents, cleanup) {
+  const startedAt = Date.now()
+  const originalCwd = process.cwd()
+
+  const Service = requireFromProject('@mpxjs/mpx-cli-service', projectRoot)
+  const sharedUtils = requireFromProject('@mpxjs/cli-shared-utils', projectRoot)
+  const { setTargetProcessEnv, SUPPORT_MODE } = sharedUtils
+  const { resolveBuildWebpackConfigByTarget } = requireFromProject(
+    '@mpxjs/vue-cli-plugin-mpx/config', projectRoot
+  )
+  const { addBuildWebpackConfig } = requireFromProject(
+    '@mpxjs/vue-cli-plugin-mpx/config/base', projectRoot
+  )
+  const filterPluginsByPlatform = requireFromProject(
+    '@mpxjs/mpx-cli-service/utils/filterPlugins', projectRoot
+  )
+  const PluginAPI = requireFromProject('@vue/cli-service/lib/PluginAPI', projectRoot)
+  const webpack = requireFromProject('webpack', projectRoot)
+  const MpxWebpackPlugin = requireFromProject('@mpxjs/webpack-plugin', projectRoot)
+  const supportsComponentPartialCompile = hasComponentPartialCompile(projectRoot)
+
+  if (!SUPPORT_MODE.includes(targetMode)) {
+    throw new InvalidInputError(
+      `不支持的 target: ${targetMode}，支持的列表: ${SUPPORT_MODE.join(', ')}`
+    )
+  }
+
+  const target = { mode: targetMode }
+  setTargetProcessEnv(target)
+  process.env.NODE_ENV = 'production'
+  process.env.BABEL_ENV = 'production'
+
+  process.chdir(projectRoot)
+  try {
+    const service = new Service(projectRoot)
+    const rawArgv = ['build', `--targets=${targetMode}`]
+    const args = { _: ['build'], targets: targetMode, clean: false, watch: false }
+
+    const origSetPluginsToSkip = service.setPluginsToSkip.bind(service)
+    service.setPluginsToSkip = function (a) {
+      origSetPluginsToSkip(a, rawArgv)
+      let plugins = filterPluginsByPlatform(process.env.MPX_CLI_MODE)
+      if (process.env.MPX_CLI_MODE !== 'web') {
+        plugins = plugins.concat([
+          'built-in:config/base',
+          'built-in:config/app',
+          'built-in:config/css'
+        ])
+      }
+      plugins.forEach(p => this.pluginsToSkip.add(p))
+    }
+    service.setPluginsToSkip(args)
+    await service.init('production')
+
+    const api = new PluginAPI('compile-validate', service)
+    const projectOptions = service.projectOptions
+
+    const entryPaths = new Set(mpxPaths)
+    const inTargetSet = (resourcePath) => entryPaths.has(path.resolve(resourcePath))
+
+    api.chainWebpack((cfg) => {
+      addBuildWebpackConfig(api, projectOptions, cfg, target, args)
+      if (ignoreSubComponents && supportsComponentPartialCompile) {
+        // 首选方案 (webpack-plugin >= 2.10.20)：通过 partialCompileRules 让 resolver
+        // 把非目标 page/component 替换为内置占位实现，保留 usingComponents 声明、
+        // 依赖解析仍正常进行，但不递归编译子组件内部。
+        cfg.plugin('mpx-webpack-plugin').tap((pluginArgs) => {
+          const opts = pluginArgs[0] = Object.assign({}, pluginArgs[0])
+          if (type === 'page') {
+            opts.partialCompileRules = {
+              pages: { include: inTargetSet },
+              components: { include: () => false }
+            }
+          } else {
+            opts.partialCompileRules = {
+              components: { include: inTargetSet }
+            }
+          }
+          return pluginArgs
+        })
+      }
+    })
+
+    const webpackConfigs = await resolveBuildWebpackConfigByTarget(
+      api, projectOptions, target, args
+    )
+    if (typeof api.runAfterResolveWebpackCallBack === 'function') {
+      await api.runAfterResolveWebpackCallBack(webpackConfigs)
+    }
+
+    const outDir = path.join(
+      os.tmpdir(),
+      'mpx-compile-validate',
+      crypto.createHash('md5')
+        .update(mpxPaths.join('|') + '|' + targetMode + '|' + process.pid)
+        .digest('hex')
+    )
+    fs.mkdirSync(outDir, { recursive: true })
+
+    // 仅当宿主 webpack-plugin 不支持组件级 partialCompileRules 时启用前置 loader
+    const useLegacyStripLoader = ignoreSubComponents && !supportsComponentPartialCompile
+    const preLoaderPath = useLegacyStripLoader
+      ? path.resolve(__dirname, 'strip-using-components-loader.js')
+      : null
+
+    rewriteWebpackConfigs(webpackConfigs, {
+      mpxPaths, outDir, type, useLegacyStripLoader, preLoaderPath, entryPaths, MpxWebpackPlugin
+    })
+
+    const errors = []
+    const warnings = []
+
+    await new Promise((resolve, reject) => {
+      webpack(webpackConfigs, (err, stats) => {
+        if (err) {
+          errors.push(normalizeIssue(err))
+          resolve()
+          return
+        }
+        const statsArr = stats && stats.stats
+          ? stats.stats
+          : stats
+            ? [stats]
+            : []
+        for (const s of statsArr) {
+          const info = s.toJson({
+            all: false,
+            errors: true,
+            warnings: true,
+            moduleTrace: true,
+            errorDetails: false
+          })
+          ;(info.errors || []).forEach(e => errors.push(normalizeIssue(e)))
+          ;(info.warnings || []).forEach(w => warnings.push(normalizeIssue(w)))
+        }
+        resolve()
+      })
+    })
+
+    if (cleanup) {
+      try { fs.rmSync(outDir, { recursive: true, force: true }) } catch (_) { /* ignore */ }
+    }
+
+    const summary = { total: errors.length, byCategory: {} }
+    errors.forEach(e => {
+      summary.byCategory[e.category] = (summary.byCategory[e.category] || 0) + 1
+    })
+
+    return {
+      success: errors.length === 0,
+      target: targetMode,
+      projectRoot,
+      errors,
+      warnings,
+      summary,
+      durationMs: Date.now() - startedAt
+    }
+  } finally {
+    process.chdir(originalCwd)
+  }
+}
+
+function rewriteWebpackConfigs (webpackConfigs, ctx) {
+  const { mpxPaths, outDir, type, useLegacyStripLoader, preLoaderPath, entryPaths, MpxWebpackPlugin } = ctx
+  const makeEntry = type === 'page'
+    ? MpxWebpackPlugin.getPageEntry.bind(MpxWebpackPlugin)
+    : MpxWebpackPlugin.getComponentEntry.bind(MpxWebpackPlugin)
+  const stripPluginNames = new Set([
+    'BundleAnalyzerPlugin',
+    'ESLintWebpackPlugin',
+    'ESLintPlugin',
+    'HtmlWebpackPlugin',
+    'CopyPlugin',
+    'CopyWebpackPlugin',
+    'WebpackBar',
+    'FriendlyErrorsWebpackPlugin',
+    'CaseSensitivePathsPlugin',
+    'PreloadPlugin'
+  ])
+
+  for (const cfg of webpackConfigs) {
+    const entry = {}
+    mpxPaths.forEach((p, i) => {
+      entry[`__validate_${i}`] = makeEntry(p)
+    })
+    cfg.entry = entry
+
+    cfg.output = Object.assign({}, cfg.output, { path: outDir, clean: false })
+
+    cfg.devtool = 'source-map'
+    cfg.cache = false
+    cfg.performance = false
+    cfg.bail = false
+    cfg.stats = 'errors-warnings'
+    cfg.optimization = Object.assign({}, cfg.optimization, {
+      minimize: false,
+      splitChunks: false,
+      runtimeChunk: false
+    })
+
+    if (Array.isArray(cfg.plugins)) {
+      cfg.plugins = cfg.plugins.filter(p => {
+        const n = p && p.constructor && p.constructor.name
+        return !stripPluginNames.has(n)
+      })
+    }
+
+    if (useLegacyStripLoader) {
+      cfg.module = cfg.module || {}
+      cfg.module.rules = cfg.module.rules || []
+      cfg.module.rules.unshift({
+        enforce: 'pre',
+        test (resource) {
+          return entryPaths.has(path.resolve(resource))
+        },
+        resourceQuery (query) {
+          return !query || !/[?&]type=/.test(query)
+        },
+        use: [preLoaderPath]
+      })
+    }
+  }
+}
+
+function normalizeIssue (raw) {
+  const obj = typeof raw === 'string' ? { message: raw } : (raw || {})
+  const msg = obj.message || String(raw)
+  const moduleIdent = obj.moduleIdentifier || obj.moduleName || ''
+  const mpxDiagnostic = parseMpxDiagnosticHeader(msg)
+  const file = mpxDiagnostic.file || extractFile(moduleIdent) || obj.file
+  const loc = parseLoc(obj.loc) || mpxDiagnostic.loc
+  const blockType = detectBlock(moduleIdent)
+  const category = categorize({ message: msg, moduleIdent, blockType, name: obj.name })
+  return {
+    category,
+    message: truncate(msg, 20),
+    file,
+    block: blockType,
+    loc,
+    raw: msg
+  }
+}
+
+function truncate (msg, maxLines) {
+  const lines = String(msg).split('\n')
+  if (lines.length <= maxLines) return msg
+  return lines.slice(0, maxLines).join('\n') + '\n...'
+}
+
+function parseMpxDiagnosticHeader (msg) {
+  const match = String(msg).match(/^\[Mpx [^\]]+\]\[([^\]]+)\]:/)
+  if (!match) return {}
+  return parseFileLoc(match[1])
+}
+
+function parseFileLoc (raw) {
+  const match = String(raw).match(/^(.*):(\d+):(\d+)$/)
+  if (match) {
+    return {
+      file: match[1],
+      loc: {
+        line: +match[2],
+        column: +match[3]
+      }
+    }
+  }
+  return {
+    file: raw
+  }
+}
+
+function extractFile (moduleIdent) {
+  if (!moduleIdent) return undefined
+  const m = moduleIdent.match(/([^!?\s]+\.mpx)(?:[?!]|$)/)
+  if (m) return m[1]
+  const segs = moduleIdent.split('!').filter(Boolean)
+  const last = segs[segs.length - 1] || moduleIdent
+  return last.split('?')[0]
+}
+
+function parseLoc (loc) {
+  if (!loc) return undefined
+  if (typeof loc === 'object' && loc.start) {
+    return { line: loc.start.line, column: loc.start.column }
+  }
+  if (typeof loc === 'string') {
+    const m = loc.match(/(\d+):(\d+)/)
+    if (m) return { line: +m[1], column: +m[2] }
+  }
+  return undefined
+}
+
+function detectBlock (moduleIdent) {
+  if (!moduleIdent) return undefined
+  const q = moduleIdent.split('?')[1] || ''
+  if (/[?&]type=styles?/.test('?' + q)) return 'style'
+  if (/[?&]type=template/.test('?' + q)) return 'template'
+  if (/[?&]type=script/.test('?' + q)) return 'script'
+  if (/[?&]type=json/.test('?' + q)) return 'json'
+  return undefined
+}
+
+function categorize ({ message, moduleIdent, blockType, name }) {
+  const msg = String(message || '')
+  const hay = `${moduleIdent || ''}\n${msg}`.toLowerCase()
+  if (name === 'ModuleNotFoundError' || /can't resolve|module not found/.test(hay)) {
+    return 'dependency'
+  }
+  if (/\[mpx style (error|warn)/i.test(msg)) return 'style'
+  if (/\[mpx template (error|warn)/i.test(msg)) return 'template'
+  if (/\[mpx json (error|warn)/i.test(msg)) return 'json'
+  if (/\[mpx script (error|warn)/i.test(msg)) return 'script'
+  if (blockType === 'style' || /style-compiler|postcss-loader|wxss-loader/.test(hay)) return 'style'
+  if (blockType === 'template' || /template-compiler/.test(hay)) return 'template'
+  if (blockType === 'json' || /json-compiler|pre-process-json|json5|name=json/.test(hay)) return 'json'
+  if (blockType === 'script' || /script-compiler|babel-loader|ts-loader|\[tsl\]/.test(hay)) return 'script'
+  return 'other'
+}
+
+module.exports = compileValidate
+module.exports.compileValidate = compileValidate
+module.exports.resolveProjectRoot = resolveProjectRoot
+module.exports.categorize = categorize
+module.exports.MpxCliNotFoundError = MpxCliNotFoundError
+module.exports.InvalidInputError = InvalidInputError
+
+if (require.main === module) {
+  runCli().catch(err => {
+    if (err instanceof MpxCliNotFoundError || err instanceof InvalidInputError) {
+      console.error(`${err.name}: ${err.message}`)
+    } else {
+      console.error(err && err.stack ? err.stack : err)
+    }
+    process.exit(2)
+  })
+}
+
+async function runCli () {
+  const argv = process.argv.slice(2)
+  const files = []
+  let targetArg = 'web'
+  let typeArg = 'component'
+  let jsonOut = false
+  let ignoreSubComponents = true
+  let projectRoot
+
+  for (const a of argv) {
+    if (a === '-h' || a === '--help') {
+      printHelp()
+      process.exit(0)
+    } else if (a.startsWith('--target=')) {
+      targetArg = a.slice('--target='.length)
+    } else if (a.startsWith('--type=')) {
+      typeArg = a.slice('--type='.length)
+    } else if (a.startsWith('--project-root=')) {
+      projectRoot = a.slice('--project-root='.length)
+    } else if (a === '--json') {
+      jsonOut = true
+    } else if (a === '--no-ignore-sub-components') {
+      ignoreSubComponents = false
+    } else if (a.startsWith('-')) {
+      console.error(`未知参数: ${a}`); process.exit(2)
+    } else {
+      files.push(a)
+    }
+  }
+  if (!files.length) { printHelp(); process.exit(2) }
+
+  const target = targetArg.includes(',') ? targetArg.split(',') : targetArg
+  let restoreOutput
+  if (jsonOut) {
+    restoreOutput = silenceOutput()
+  }
+
+  let result
+  try {
+    result = await compileValidate(files, {
+      target, type: typeArg, ignoreSubComponents, projectRoot
+    })
+  } finally {
+    if (restoreOutput) restoreOutput()
+  }
+
+  if (jsonOut) {
+    console.log(JSON.stringify(result, null, 2))
+  } else {
+    prettyPrint(result)
+  }
+  process.exit(isSuccess(result) ? 0 : 1)
+}
+
+function silenceOutput () {
+  const stdoutWrite = process.stdout.write
+  const stderrWrite = process.stderr.write
+  process.stdout.write = function (chunk, encoding, callback) {
+    if (typeof encoding === 'function') encoding()
+    if (typeof callback === 'function') callback()
+    return true
+  }
+  process.stderr.write = function (chunk, encoding, callback) {
+    if (typeof encoding === 'function') encoding()
+    if (typeof callback === 'function') callback()
+    return true
+  }
+  return function restoreOutput () {
+    process.stdout.write = stdoutWrite
+    process.stderr.write = stderrWrite
+  }
+}
+
+function printHelp () {
+  console.log(`usage: compile-validate <file.mpx>... [options]
+
+options:
+  --target=<mode>              编译目标 (默认 web)，多个用逗号分隔
+  --type=<page|component>      入口类型，默认 component
+  --project-root=<path>        显式指定宿主项目根目录（覆盖自动探测）
+  --no-ignore-sub-components   不忽略子组件，一并纳入编译
+  --json                       输出结构化 JSON
+  -h, --help                   查看帮助`)
+}
+
+function isSuccess (result) {
+  if (!result) return true
+  if (typeof result.success === 'boolean') return result.success
+  return Object.values(result).every(r => r && r.success)
+}
+
+function prettyPrint (result) {
+  if (result && typeof result.success === 'boolean') { prettyPrintOne(result); return }
+  for (const [t, r] of Object.entries(result)) {
+    console.log(`\n=== target=${t} ===`)
+    prettyPrintOne(r)
+  }
+}
+
+function prettyPrintOne (r) {
+  console.log(`target: ${r.target}  success: ${r.success}  duration: ${r.durationMs}ms`)
+  console.log(`errors: ${r.errors.length}  warnings: ${r.warnings.length}`)
+  if (r.summary.total > 0) {
+    const pairs = Object.entries(r.summary.byCategory)
+      .map(([k, v]) => `${k}=${v}`).join(', ')
+    console.log(`by category: ${pairs}`)
+  }
+  r.errors.forEach((e, i) => {
+    const locStr = e.loc ? `:${e.loc.line}:${e.loc.column}` : ''
+    const fileStr = e.file ? ` ${e.file}${locStr}` : ''
+    console.log(`\n[${i + 1}][${e.category}${e.block ? '/' + e.block : ''}]${fileStr}`)
+    console.log(e.message)
+  })
+}
diff --git a/.agents/skills/mpx2web/scripts/strip-using-components-loader.js b/.agents/skills/mpx2web/scripts/strip-using-components-loader.js
new file mode 100644
index 0000000000..b2e98908c0
--- /dev/null
+++ b/.agents/skills/mpx2web/scripts/strip-using-components-loader.js
@@ -0,0 +1,54 @@
+'use strict'
+
+// Web 编译校验的旧版本兜底：当前 @mpxjs/webpack-plugin 已支持
+// `partialCompileRules.components`，可在 resolver 层把非目标组件替换为
+// 默认占位组件。若业务项目安装的旧版插件缺少该能力，校验脚本才会启用
+// 这个前置 loader，在源码层移除目标 .mpx 的 usingComponents，避免递归编译
+// 子组件。该兜底会跳过 usingComponents 对应的依赖解析与 json-compiler 校验，
+// 只用于尽量跑出目标文件自身的 Web 编译错误。
+
+function removeUsingComponents (source) {
+  const re = /(["']?)usingComponents\1\s*:\s*\{/g
+  let out = source
+  let match
+  let guard = 0
+  while ((match = re.exec(out)) !== null) {
+    if (guard++ > 50) break
+    const startBrace = match.index + match[0].length - 1
+    let depth = 1
+    let i = startBrace + 1
+    let inStr = null
+    while (i < out.length && depth > 0) {
+      const c = out[i]
+      if (inStr) {
+        if (c === '\\') { i += 2; continue }
+        if (c === inStr) inStr = null
+      } else if (c === '"' || c === '\'') {
+        inStr = c
+      } else if (c === '{') {
+        depth++
+      } else if (c === '}') {
+        depth--
+      }
+      i++
+    }
+    if (depth === 0) {
+      out = out.slice(0, startBrace) + '{}' + out.slice(i)
+      re.lastIndex = startBrace + 2
+    } else {
+      break
+    }
+  }
+  return out
+}
+
+module.exports = function stripUsingComponentsLoader (source) {
+  const callback = this.async()
+  try {
+    callback(null, removeUsingComponents(source))
+  } catch (err) {
+    callback(err)
+  }
+}
+
+module.exports.removeUsingComponents = removeUsingComponents