diff --git a/.agents/skills/mpx2skyline/SKILL.md b/.agents/skills/mpx2skyline/SKILL.md
new file mode 100644
index 0000000000..4c7c7307e2
--- /dev/null
+++ b/.agents/skills/mpx2skyline/SKILL.md
@@ -0,0 +1,248 @@
+---
+name: mpx2skyline
+description: |
+  微信小程序 WebView 适配 Skyline 渲染引擎指南，覆盖布局、样式、组件、配置四大维度。
+  当用户要求对已有微信小程序页面进行 Skyline 适配、创建符合 Skyline 兼容规范的页面、
+  排查 Skyline 下样式不生效/组件不渲染/布局异常/层级错乱等问题、或查询某项能力在
+  Skyline 下的支持情况时强制调用。当用户问题不涉及 Skyline 适配时不应调用，如
+  Mpx 输出 RN 问题、支付宝小程序问题、纯 webview 小程序开发问题等。
+metadata:
+  version: "1.0.1"
+---
+
+# Mpx 输出 Skyline 渲染引擎的开发&适配指南
+
+## 背景介绍
+
+Mpx 是一个以微信小程序语法为基础、进行了类 Vue 语法拓展支持的跨端开发框架，支持将同一套代码输出到小程序（微信、支付宝、百度等）、Web 和 React Native 平台。
+
+Skyline 是微信小程序新一代渲染引擎，旨在替代 WebView 渲染以获得更接近原生的性能和体验。与 WebView 模式相比，Skyline 在布局模型、层叠机制、样式能力、组件支持、页面行为上存在系统性差异。
+
+### 适用场景
+
+本 SKILL 是 Mpx WebView 适配 Skyline 渲染引擎的统一指南，覆盖布局、样式、组件、配置四大维度。涉及 Mpx Skyline 适配的任务均应在动笔前阅读本 SKILL 的[通用约束与适配原则](#通用约束与适配原则)，包括但不限于：
+
+- **技术方案设计**：评估需求在 Skyline 下的可行性、跨渲染模式（WebView & Skyline）兼容方案选型、是否需要通过 `this.renderer === 'skyline'` 进行运行时模式隔离等;
+- **WebView 页面 Skyline 适配改造**：对已基于 WebView 模式编写、未适配 Skyline 的存量页面进行兼容性补齐（参见下文[任务一](#任务一对已有-webview-页面进行-skyline-适配改造)）;
+- **页面 / 组件开发迭代**：从零编写或迭代符合 WebView & Skyline 双模式兼容规范的 `.mpx` 页面与组件（参见下文[任务二](#任务二创建符合-skyline-兼容规范的页面)）;
+- **运行时报错与异常排查**：定位 Skyline 下样式不生效（如不支持选择器/属性静默失效）、组件不渲染（如 `scroll-view` 缺失 `type`）、布局异常（如默认 `display: flex` / `border-box` 引发的差异）、层级错乱（z-index 无层叠上下文）、glass-easel 框架变更点（如 `wx-if` 废弃、模板转义、SelectorQuery 数字开头）、worklet 动画失效等问题;
+- **能力查询**：查询某项基础组件、属性、样式、API、滚动 API、worklet 能力在 Skyline 下的支持情况、版本要求与 WebView 差异;
+- **Code Review**：以本 SKILL 的[通用约束与适配原则](#通用约束与适配原则)为标准对照检查 Skyline 兼容性与跨渲染模式兼容性。
+
+### 不适用场景
+
+以下场景与 Mpx Skyline 适配无关，**不应调用**本 SKILL：
+
+- 仅面向微信小程序 Webview 的开发和适配问题（不涉及 Skyline 适配，无需 Skyline 兼容性约束）;
+- 支付宝、百度、抖音等其他小程序平台的开发问题（Skyline 是微信小程序专属渲染引擎，不适用于其他厂商）;
+- Skyline only 项目的开发问题（本 SKILL 强调 Mpx 框架下 WebView & Skyline 双模式兼容，纯 Skyline 项目应直接参考 [微信官方Skyline skills](https://github.com/wechat-miniprogram/skyline-skills/tree/master/skills)）;
+- Mpx 跨端输出 RN（Mpx2RN / Mpx2DRN）相关问题;
+- Mpx 跨端输出 Web（Mpx2Web）相关问题;
+- 不经 Mpx 框架编译的纯微信原生小程序开发问题。
+
+## 知识库索引
+
+| 知识库 | 说明                                             |
+| --- |------------------------------------------------|
+| [Skyline 基础组件支持与差异参考](./references/skyline-component-reference.md) | 查询组件支持情况与差异，涉及不支持组件的替代方案、Skyline 新增组件、组件使用注意事项 |
+| [Skyline WXSS 样式能力参考](./references/skyline-style-reference.md) | 查询样式属性/选择器/单位是否支持，逐属性支持详情与 WebView 差异对比        |
+| [WebView→Skyline 适配改造最佳实践](./references/skyline-migration-practice.md) | 进行适配改造时读取，覆盖布局适配、样式适配、组件适配、层叠适配的完整实操方案         |
+| [Skyline 配置项与接入规范参考](./references/skyline-configuration.md) | 接入代码配置等项目级配置时读取                                |
+| [Skyline 适配检查矩阵](./references/skyline-audit-matrix.md) | 适配完成前强制执行的审计矩阵，覆盖扫描 pattern、判定、修复、例外与验证要求 |
+
+> 若有涉及到纯 Skyline 相关的问题（比如共享元素、手势系统、worklet 动画）可查询 [微信官方Skyline skills](https://github.com/wechat-miniprogram/skyline-skills/tree/master/skills)
+
+### 知识库使用建议
+
+参考文档体量较大，**不要一次性预读全部参考**，按需取用即可：
+
+1. **入口只读本 SKILL.md**：完整读完本文档（含下方[通用约束与适配原则](#通用约束与适配原则)与任务流程）足以覆盖 80% 常见场景的判断；不要在动笔前预读 references 目录。
+2. **触发式读取**：只在通用约束或任务流程中**明确指向**某份参考（及其锚点）时读取，且仅读取与当前问题相关的小节——四份参考均含目录与章节锚点，用 grep / 锚点跳读，不要整文件 Read。
+3. **典型任务的最小阅读集**（仅当本 SKILL.md 已无法判断时再补充）：
+   - **存量 WebView 页面 Skyline 适配改造**：先按本 SKILL.md 的[通用约束](#通用约束与适配原则)逐维度核对，识别出问题维度后再点读对应参考的相关小节，通常 1–2 份足够——样式属性/选择器/单位是否支持查 [`skyline-style-reference.md`](./references/skyline-style-reference.md)，具体改造写法（布局/样式/组件/层叠的可复制方案）查 [`skyline-migration-practice.md`](./references/skyline-migration-practice.md) 对应小节。
+   - **组件能力存疑**（某组件/属性/裁剪模式是否支持、替代方案）：点查 [`skyline-component-reference.md`](./references/skyline-component-reference.md) 相关行。
+   - **新建双模式兼容页面/组件**：先按通用约束起手，遇到能力存疑（某属性是否支持、某 API 是否存在）时再点查对应参考。
+   - **项目级配置接入**（app.json / page.json / worklet Babel）：直接读 [`skyline-configuration.md`](./references/skyline-configuration.md)。
+   - **排查 Skyline 运行时问题**（样式静默失效 / 组件不渲染 / 布局异常 / 层级错乱 / worklet 失效）：先定位到报错所属维度，再读该维度能力参考的相关小节。
+   - **适配完成前检查 / Code Review**：必须读取并执行 [`skyline-audit-matrix.md`](./references/skyline-audit-matrix.md)。
+
+## 通用约束与适配原则
+
+适配改造、新建组件、Code Review 均须遵循以下约束：
+
+适配/重构类任务，读到 skill 给出的具体改造规则时：
+- 规则带有知识库路由或外链的，**先读链接文档**再动手；
+- skill 给出明确可复制代码片段（属性值、CSS snippet、组件属性写法）→ 默认按 skill 执行；
+- skill 方案明显偏复杂且有公认更简写法需要澄清确认；
+- skill 没有明确替代方案的组件或者样式属性、规则不清楚、文档有歧义等场景先要求澄清；
+- skill 方案与其他方案（如"和邻近文件保持一致""拆开写更精确""有更简单的写法"）冲突时，先验证两点：语义是否等价；skill 方案是否在未显式声明的上下文里更稳，再确认是否改方案
+
+### 跨渲染模式兼容约束
+
+产物代码须在 WebView 与 Skyline 下均正常运行：
+
+- 新方案若 WebView & Skyline & RN 三端兼容，直接对齐为新方案；
+- 新方案若属 Skyline-only 改造，**必须**通过 `this.renderer === 'skyline'` 运行时隔离，若有细则明确要求 WebView 保留原有逻辑且 Skyline 无副作用则保留，阅读 [运行时 renderer 判断](./references/skyline-migration-practice.md#判断当前渲染模式)；
+- 特定版本起支持的 Skyline 特性（如 `position: fixed` 8.0.43+、`:nth-child` 8.0.50+）按已支持处理，不做低版本兼容。
+
+该原则贯穿模板 / 脚本 / 样式 / JSON 四个维度。
+
+### 布局（layout）约束
+
+1. **默认布局差异**：Skyline 默认 `display: flex`，WebView 默认 `display: block` → app.json 配置 `defaultDisplayBlock` 对齐 WebView 默认 `display:block`。
+2. **box-sizing 默认值**：Skyline 默认 `border-box`（WebView 默认 `content-box`）→ app.json  配置 `defaultContentBox` 对齐 WebView 默认 `content-box`。
+3. **页面滚动**：Skyline 不支持页面滚动，`onPullDownRefresh` / `onReachBottom` / `onPageScroll` 不会触发 → 使用 `scroll-view type="list"` 替代，页面需声明 `disableScroll: true`。**原页面生命周期需迁移到 scroll-view 对应事件**（`bindrefresherrefresh` / `bindscrolltolower` / `bindscroll`），WebView 对齐 Skyline 写法。事件映射与示例详见 [适配最佳实践 · 页面滚动替代方案](./references/skyline-migration-practice.md#页面滚动替代方案)。
+4. **自定义导航**：Skyline 不支持默认导航 → 自定义导航栏，页面需声明 `navigationStyle: 'custom'`。
+5. **z-index 与层叠**：z-index 仅兄弟节点生效，无层叠上下文机制 → 阅读 [适配最佳实践 · z-index 与层叠适配](./references/skyline-migration-practice.md#z-index-与层叠适配)，理解 WebView & Skyline 层级差异，重新排布页面内所有子孙节点的层级结构。**优先用非负兄弟序（不要调整 DOM 顺序，需要调整 DOM 顺序时需先确认）控制层级，尽量避免负 z-index**。
+
+### 样式（style）约束
+
+1. **选择器**：不支持通配选择器 `*` 和属性选择器 `[attr]`；伪元素仅 `::before` / `::after`；`:nth-child` 需 8.0.50+，选择器支持详情阅读 [样式能力参考 · 选择器支持](./references/skyline-style-reference.md#选择器支持)。
+2. **单位**：避免 `em` / `currentColor`，使用 `rpx` / `px` / `rem`，单位支持阅读 [样式能力参考 · 值类型支持](./references/skyline-style-reference.md#值类型支持)。
+3. **overflow**：`overflow: scroll` 不支持 → 使用 `scroll-view` 组件；不支持单独设置 `overflow-x` / `overflow-y`。
+4. **边框一致性**：`border-radius` 非 0 时四边 `border-color` / `border-style` 需一致。
+5. **伪元素 animation**：Skyline 下伪元素的 `animation` 不生效 → 使用真实节点 + CSS animation。
+6. **font-weight**：部分机型不支持 `font-weight: 500` / `600` 数值加粗，需使用 `bold` / `700`，webview 对齐 skyline，可直接全局替换。
+7. **box-shadow**：不支持多个叠加。
+8. **不支持 CSS 属性**：`float` / `contain` / `resize` / `writing-mode` / `text-indent` / `overflow-wrap` / `background-attachment` / `background-clip` / `background-origin` / `mask-origin` / `mask-clip` / `mask-mode` / `justify-items` 等属性设置后静默不生效，阅读 [样式适配 · 不支持的 CSS 属性](./references/skyline-migration-practice.md#不支持的-css-属性)，无等效方案时抛出提示
+9. **渐变与背景多值限制**：`radial-gradient` 仅支持 `circle`（不支持 `ellipse`）；`background-image` / `mask-image` 最多支持 2 个值；`background-repeat` / `background-size` 不支持多组值，阅读 [样式适配 · 渐变与背景多值限制](./references/skyline-migration-practice.md#渐变与背景多值限制)。
+10. **filter / backdrop-filter**：不支持 `url()` / `drop-shadow()` 及多函数组合；用 `box-shadow` 替代 `drop-shadow`。详见 [样式适配 · filter / backdrop-filter 限制](./references/skyline-migration-practice.md#filter--backdrop-filter-限制)。
+11. **text-decoration-line 单值**：仅支持单个值，多值组合（如 `underline line-through`）不生效 → 需双值时用运行时判断嵌套 `text` 节点拆分，详见 [适配最佳实践 · text-decoration-line 多值适配](./references/skyline-migration-practice.md#text-decoration-line-多值适配)。
+12. **calc() 不支持角度**：`calc()` 支持长度计算但不支持角度类型，需直接写角度值（如 `135deg`）。
+
+### 组件（component）约束
+
+1. **scroll-view 必须指定 type**：`<scroll-view type="list">`，Skyline 下缺少 type 属性将无法正常工作。**嵌套场景下每一层 scroll-view 都必须显式声明 type**（外层 `type="nested"`、内层 `type="list"` / `"custom"`），遗漏内层 type 会让内层退化为 WebView 渲染路径。
+2. **不支持组件**：`web-view` / `movable-area` / `movable-view` / `editor` / `progress` / `navigation-bar` → 简单场景使用替代方案，复杂场景给出替代方案或者降级方案待确认，参考 [组件支持详情](./references/skyline-component-reference.md#组件支持详情)。
+3. **自定义组件样式隔离**：`tag` / `id` 选择器不支持跨自定义组件匹配，`class` 遵循组件样式隔离机制 → 全局配置 `"tagNameStyleIsolation": "legacy"` 对齐 WebView 标签选择器全局匹配。
+4. **不使用 WebView-only** image 的 WebView-only 裁剪模式（`top` / `bottom` / `center` / `left` / `right`）。
+5. **sticky-header 必须显式声明背景色**：Skyline 下 `sticky-header` 默认透明，吸顶时会与下层列表内容透字穿透；同时 `sticky-header` 必须是 `sticky-section` 的第一个子节点（且每个 section 仅一个 header）。详见 [适配最佳实践 · sticky 吸顶替代方案](./references/skyline-migration-practice.md#sticky-吸顶替代方案)。
+6. **navigator 嵌套限制**：`<navigator>` 内**只能嵌套 `<text>` 或纯文本**，不能嵌套 `<view>` / `<image>` 等其他组件；
+7. **图文混排须用 `<span>` 内联包裹**：Skyline 下 `<view>`/`<text>` 无法直接图文内联混排，需用 `<span>` 包裹各内联片段，实现参考 [图文混排](./references/skyline-migration-practice.md#图文混排)。
+8. **scroll-view 按内容撑开**：需在 app.json 配置 `enableScrollViewAutoSize` 对齐 Webview scroll-view 自动撑开高度。
+
+### 滚动 API（Scroll API）约束
+
+1. **ScrollViewContext 需 enhanced 属性**：通过 `NodesRef.node()` 获取 `ScrollViewContext` 时，`scroll-view` 必须开启 `enhanced` 属性，否则返回的不是 ScrollViewContext 实例。详见 [Scroll API 适配 · ScrollViewContext：必须开启 enhanced 属性](./references/skyline-migration-practice.md#scrollviewcontext必须开启-enhanced-属性)。
+2. **worklet.scrollViewContext 必须通过 ref() 获取**：在 worklet 中控制滚动须用 `NodesRef.ref()` + `SharedValue`，不能用 `node()`（`node()` 返回的是逻辑线程 ScrollViewContext，无法在 UI 线程使用）。详见 [Scroll API 适配 · worklet.scrollViewContext：必须通过 ref 获取](./references/skyline-migration-practice.md#workletscrollviewcontext必须通过-ref-获取)。
+3. **worklet.scrollViewContext.scrollTo 只能在 worklet 中调用**：调用该 API 的函数必须声明 `'worklet'` 指令（仅 UI 线程可用），且不支持小程序插件。详见 [Scroll API 适配 · worklet.scrollViewContext.scrollTo：调用函数必须声明 'worklet' 指令](./references/skyline-migration-practice.md#workletscrollviewcontextscrollto调用函数必须声明-worklet-指令)。
+4. **DraggableSheetContext.scrollTo 的 size 与 pixels 互斥**：同时传入时仅 `size` 生效，`pixels` 被静默忽略。详见 [Scroll API 适配 · DraggableSheetContext：size 和 pixels 不可同时传入](./references/skyline-migration-practice.md#draggablesheetcontextsize-和-pixels-不可同时传入)。
+
+### 动画策略约束
+
+跨端（WebView + Skyline + RN）场景下，动画方案的选择优先级：
+
+1. 简单状态切换动画（缩放、透明度、位移等交互反馈）：**CSS `transition`**：三端均支持，通过 class 切换或动态 style 触发，无需平台判断。
+2. 循环/多步骤动画：**CSS `animation` + `@keyframes`**：Webview & Skyline支持，RN 暂不支持可暂时区分平台使用 API `mpx.createAnimation`。
+3. 手势/滚动场景：**Skyline Worklet 动画**，仅用于需要 UI 线程 60fps 驱动的场景（手势跟手、滚动联动），必须通过 `this.renderer === 'skyline'` 隔离。
+4. **禁止使用** `this.animate` / `this.applyAnimation` — 这些是 WebView-only API，Skyline 下静默不生效，RN 下不存在。
+5. `wx.createAnimation` mpx2RN & WebView 支持，Skyline 不支持，Skyline 适配时需改造为 CSS `transition` 或者 CSS `animation` + `@keyframes`
+
+> 简单交互动画（如按钮缩放、卡片翻转）直接用 transition，不要为了"性能最优"引入 worklet — worklet 的价值在于手势跟手的实时性，不在于简单状态动画。
+
+### Worklet 动画约束
+
+1. **必须声明 'worklet' 指令**：在 UI 线程执行的函数（手势/滚动回调等）必须在函数顶部声明 `'worklet'` 字符串，缺少指令将在逻辑线程执行，导致动画延迟。详见 [Worklet 动画适配 · worklet 函数必须声明 'worklet' 指令](./references/skyline-migration-practice.md#worklet-函数必须声明-worklet-指令)。
+2. **SharedValue 通过 .value 读写**：`wx.worklet.shared()` 创建的共享变量必须通过 `.value` 读写，直接赋值会替换对象本身导致动画驱动失效。详见 [Worklet 动画适配 · SharedValue 必须通过 .value 读写](./references/skyline-migration-practice.md#sharedvalue-必须通过-value-读写)。
+3. **worklet 中调用普通函数必须使用 runOnJS**：worklet 运行在 UI 线程，不能直接调用页面方法或 `wx.*` API，必须通过 `runOnJS` 切换回 JS 线程。详见 [Worklet 动画适配 · 在 worklet 中调用普通函数必须使用 runOnJS](./references/skyline-migration-practice.md#在-worklet-中调用普通函数必须使用-runonjs)。
+4. **runOnJS 调用页面方法必须 bind(this)**：通过 `runOnJS` 调用页面方法前必须先 `bind(this)`，否则 `this` 指向丢失。详见 [Worklet 动画适配 · 页面方法必须通过 bind(this) 绑定后传入 runOnJS](./references/skyline-migration-practice.md#页面方法必须通过-bindthis-绑定后传入-runonjs)。
+5. **禁止在 worklet 中解构 this.data**：解构赋值会触发 `Object.freeze` 冻结 `this.data`，导致页面后续所有 `setData` 失效。详见 [Worklet 动画适配 · 禁止在 worklet 中解构 this](./references/skyline-migration-practice.md#禁止在-worklet-中解构-this)。
+
+### glass-easel 框架约束
+
+1. **模板转义改用 XML 实体**：数据绑定**外**的引号须改为 `&quot;`，数据绑定**内**无需转义（不再用反斜杠）。详见 [glass-easel 变更点适配 · 模板转义](./references/skyline-migration-practice.md#必须-模板中数据绑定外的转义改为标准-xml-转义)。
+2. **不再支持 wx-if / wx-for**：短横线写法已废弃，仅支持冒号写法 `wx:if` / `wx:for`（两种框架均支持冒号写法，可直接改）。详见 [glass-easel 变更点适配 · wx-if / wx-for](./references/skyline-migration-practice.md#必须-不再支持-wx-if--wx-for仅支持-wxif--wxfor)。
+3. **wx:for 内嵌 include 须改为 template**：`<include>` 引入的模板中 `item` / `index` 变量失效，须改用 `<template>` + `<import>` 方案。详见 [glass-easel 变更点适配 · wx:for 内嵌 include](./references/skyline-migration-practice.md#必须-wxfor-内嵌-include-时改为-template)。
+4. **SelectorQuery 选择器不支持以数字开头**：`#1` 等以数字开头的 id 选择器不合 CSS 规范，需重命名（如 `#element-1`）。详见 [glass-easel 变更点适配 · SelectorQuery](./references/skyline-migration-practice.md#必须-selectorquery-选择器不再支持以数字开头)。
+5. **[仅 Skyline] 不支持 animate / applyAnimation / clearAnimation / setInitialRenderingCache**：调用后静默不生效，须改用 CSS transition 或 Worklet 动画。详见 [glass-easel 变更点适配 · 不支持的实例方法](./references/skyline-migration-practice.md#必须仅-skyline-不支持的组件实例方法)。
+
+## 任务一：对已有 WebView 页面进行 Skyline 适配改造
+
+### 输入
+
+基于 WebView 模式编写的 `.mpx` 页面（已在微信 WebView 模式下运行，但未适配 Skyline）。
+
+### 输出
+
+以用户指示为准；若无特殊指示则默认在原文件中进行修改。输出修改后代码时应输出完整页面代码，避免使用省略号，确保用户可以直接复制或应用修改。
+
+### 任务流程
+
+#### 1. 页面配置适配
+
+- 页面 json 需新增 `renderer` / `componentFramework` / `disableScroll` / `navigationStyle` `renderer: 'skyline'`、`componentFramework: 'glass-easel'`、`disableScroll: true`、`navigationStyle: 'custom'`
+- 全局配置 app.json 需新增 `lazyCodeLoading`（顶层），以及 `rendererOptions.skyline` 下的 `defaultDisplayBlock` / `defaultContentBox` / `tagNameStyleIsolation` / `enableScrollViewAutoSize`，阅读[配置参考](./references/skyline-configuration.md)
+
+#### 2. 布局适配改造
+
+- 读取 [适配最佳实践 · 布局适配](./references/skyline-migration-practice.md#布局适配)，对页面的布局与层叠逐一核对 Skyline 兼容性。
+- 默认 flex 布局差异处理（配置 `defaultDisplayBlock`）。
+- 页面滚动 → `scroll-view type="list"` 替代。
+- 自定义导航替代默认导航。
+
+#### 3. 样式适配改造
+
+- 读取 [样式能力参考](./references/skyline-style-reference.md) 检查 `<style>` 中所有样式属性的 Skyline 支持情况。
+- 读取 [适配最佳实践 · 样式适配](./references/skyline-migration-practice.md#样式适配) 改造为 Skyline 兼容实现。
+- 不支持选择器替代（`*` → 类选择器、`[attr]` → 类选择器）。
+- 不支持属性替代（`overflow: scroll` → `scroll-view` 等）读取 [与 webview 的关键样式差异及替代方案](./references/skyline-style-reference.md#与-webview-模式的关键样式差异及兼容方案)。
+- 增加配置 `defaultContentBox` `defaultDisplayBlock` 默认样式对齐 webview。
+- 文本溢出省略适配（`text-overflow: ellipsis` / 超长打点），可在承载文本的 `view` / `text` / `rich-text` / `special-text` 上新增 Skyline 特有属性 `max-lines` 与 `overflow`，阅读 [适配最佳实践 · 文本溢出省略适配](./references/skyline-migration-practice.md#文本溢出省略适配)。
+- flex 布局子节点依赖百分比 `min-width` 撑开或等分时，百分比 `min-width` 可能不生效，必须以同一 flex 容器链为单位成组处理并替换为明确长度单位；若基准宽度是一屏，可按 `750rpx` 换算（如 `min-width: 100%` → `750rpx`，`min-width: 25%` → `187rpx/187.5rpx`），须读取 [适配最佳实践 · flex 布局的子节点 min-width 百分比撑开失效](./references/skyline-migration-practice.md#flex-布局的子节点-min-width-百分比撑开失效) 与 [样式能力参考·百分比支持情况](./references/skyline-style-reference.md#百分比支持情况)
+- 媒体查询 `@media screen` 替换为动态类，详见[适配最佳实践 · @media screen 替换方案](./references/skyline-migration-practice.md#media-screen-替换方案)
+
+#### 4. 组件适配改造
+
+- 读取 [组件支持参考](./references/skyline-component-reference.md)，对 `<template>` 中使用的组件及其属性与事件逐一核对 Skyline 支持情况。
+- `scroll-view` 必须指定 `type`。
+- 配置 `tagNameStyleIsolation": "legacy"` 自定义组件样式隔离处理对齐 webview。
+- `picker-view` skyline 下默认会有上下边框，适配 skyline 时没有自定义边框时需设置 `indicator-style="border: none;"` 去除默认边框，`indicator-style` 仅支持 `height`、`border`、`background-color`。
+- 若同一视觉行内存在 `image` / icon 与 `text` / `rich-text` / `special-text` / 自定义文本组件混排，必须读取并执行 [适配最佳实践 · 图文混排](./references/skyline-migration-practice.md#图文混排)。
+
+#### 5. 检查与确认
+
+检查前必须读取并执行 [Skyline 适配检查矩阵](./references/skyline-audit-matrix.md)。
+
+执行要求：
+- 指定单个 `.mpx` 组件：以该文件为 scope 跑完整矩阵。
+- 指定页面：以页面文件 + 模板实际引用组件树为 scope 跑完整矩阵；若只覆盖部分子树，最终输出必须说明未覆盖范围。
+- 不允许只扫描本次怀疑的问题类型。
+- 每个 `error` 命中必须处理或说明例外；最终输出需概述 `error` / `warn` 残留原因。
+
+人工复核：
+- 跨渲染模式：Skyline-only 逻辑已通过 `renderer === 'skyline'` 或项目封装隔离，WebView 原有逻辑保留。
+- 页面配置：页面 JSON 与 app.json Skyline 配置齐全；涉及 Worklet 时 Babel 插件已配置。
+- 页面滚动：页面滚动、下拉刷新、触底、滚动监听已迁移到 `scroll-view` 对应事件。
+- 层级结构：z-index 仅依赖兄弟层级，未引入负 z-index 或跨层叠上下文假设。
+- Worklet：worklet 函数、SharedValue、runOnJS、滚动上下文获取方式符合约束。
+- 覆盖范围：页面适配时已说明覆盖到的组件树和未覆盖子树。
+
+## 任务二：创建符合 Skyline 兼容规范的页面
+
+### 输入
+
+用户描述的页面需求，包括视图结构、交互、数据来源、是否需要使用 worklet 增强特性等。
+
+### 输出
+
+完整的 `.mpx` 页面文件，结构包含 `<template>`、`<script>`、`<style>` 与 JSON 配置区块。代码须直接满足 [通用约束与适配原则](#通用约束与适配原则)，避免新建后再走一轮适配改造。
+
+### 任务流程
+
+#### 1. 设计阶段
+
+- 与用户对齐需求要点：页面视图结构、数据流、是否需要 Skyline 增强特性（worklet 动画、手势、自定义路由）。
+- 若页面需要交互动画或自定义转场，读取 [适配最佳实践 · Worklet 动画适配](./references/skyline-migration-practice.md#worklet-动画适配) 及 [Worklet 动画](https://developers.weixin.qq.com/miniprogram/dev/framework/runtime/skyline/worklet.html) / [手势系统](https://developers.weixin.qq.com/miniprogram/dev/framework/runtime/skyline/gesture.html) 官方文档，确定增强方案。
+
+#### 2. 实施阶段
+
+按 SFC 各区块依次实现，全程遵循 [通用约束与适配原则](#通用约束与适配原则)：
+
+- **JSON 配置**：页面必须配置 `renderer: 'skyline'`、`componentFramework: 'glass-easel'`、`disableScroll: true`、`navigationStyle: 'custom'`。读取 [配置参考](./references/skyline-configuration.md) 确认项目全局配置。
+- **`<template>`**：读取 [组件支持参考](./references/skyline-component-reference.md)，仅选用 Skyline 支持的组件、属性与事件；`scroll-view` 必须指定 `type`；页面滚动使用 `scroll-view` 包裹；文本内容按语义选用 `view` / `text`，需要超长打点时在承载文本的组件上补 `max-lines` / `overflow`。
+- **`<style>`**：读取 [样式能力参考](./references/skyline-style-reference.md) 与 [适配最佳实践](./references/skyline-migration-practice.md)，从一开始就使用 flex 布局、`rpx` 单位、双冒号伪元素、组件属性式文本截断等 Skyline 兼容写法。
+- **`<script>`**：通过 `this.renderer === 'skyline'` 判断渲染模式，Skyline 专属逻辑做运行时隔离；需要 worklet 能力时按 [配置参考 · Worklet Babel 插件](./references/skyline-configuration.md#worklet-babel-插件) 配置 Babel 插件。
+
+#### 3. 检查与确认
+
+复用 [任务一 · 检查与确认](#5-检查与确认) 的清单，确认新建页面不引入任何 Skyline 不兼容写法。
diff --git a/.agents/skills/mpx2skyline/references/skyline-audit-matrix.md b/.agents/skills/mpx2skyline/references/skyline-audit-matrix.md
new file mode 100644
index 0000000000..8612156933
--- /dev/null
+++ b/.agents/skills/mpx2skyline/references/skyline-audit-matrix.md
@@ -0,0 +1,50 @@
+# Skyline 适配检查矩阵
+
+本矩阵用于把 Skyline 适配从经验扫描收敛为固定门禁。执行适配、排障、Code Review 时，按任务 scope 跑完整矩阵；不要只扫描本次怀疑的问题类型。
+
+## 使用方式
+
+- **指定单个 `.mpx` 组件**：以该文件为 scope 跑完整矩阵。
+- **指定页面**：以页面文件 + 模板实际引用的组件树为 scope 跑完整矩阵；若只处理部分子树，必须说明未覆盖范围。
+- **最终输出**：对所有 `error` 命中给出处理结果：已修 / 保留原因 / 非目标平台分支 / 待确认。
+- **例外规则**：`.ios.mpx`、RN-only、非 wx 分支可跳过，但要在结果中说明。
+
+## 与 SKILL.md 的边界
+
+- 本文件维护可扫描、可枚举的 Skyline 兼容规则。
+- `SKILL.md` 只维护流程门禁和人工验收项。
+- 新增可扫描规则时只改本文件，不要同步复制到 `SKILL.md` checklist。
+
+## 聚合扫描
+
+第一阶段可用以下命令兜底扫描；结构化场景（多行 `scroll-view` 等）仍需人工或脚本复核。
+
+```bash
+rg -n "@media screen|font-weight\\s*:?\\s*(500|600)|text-overflow|truncate|<image|<rich-text|<special-text|<mpx-icon|min-width\\s*:?\\s*[0-9.]+%|flex\\s*:?\\s*1\\s+0\\s+auto|overflow-x|overflow-y|overflow\\s+scroll|float\\s|text-indent|overflow-wrap|justify-items|box-shadow:.*?,|background-image|mask-image|background-size|background-repeat|<scroll-view|movable-area|movable-view|web-view|editor|progress|navigation-bar|\\.animate\\(|\\.applyAnimation\\(|wx\\.createAnimation|wx-if|wx-for" <scope> -g '*.mpx'
+```
+
+## 规则矩阵
+
+| id | level | scope | pattern | 判定 | 标准修复 | 允许例外 |
+| --- | --- | --- | --- | --- | --- | --- |
+| `STYLE_MEDIA_SCREEN` | error | style | `@media screen` | Skyline 下静默失效，且可能把内部规则当裸样式应用 | WebView 保留 `@media`；Skyline 用 `isSkyline && isSmall` 动态类兜底，必要时加 normal 类反向兜底 | 非 wx / RN-only / `.ios.mpx` |
+| `STYLE_FONT_WEIGHT` | warn | style/template/script | `font-weight\\s*:?\\s*(500\|600)` | 部分机型数字字重不稳定 | 改 `bold` / `700`；WebView 对齐 | iOS 专用分支可保留 |
+| `STYLE_TEXT_OVERFLOW` | warn | template/style | `text-overflow\\s+ellipsis\|truncate` | Skyline 省略需由组件属性承载，`view` / `text` / `rich-text` / `special-text` 均可直接补属性 | 承载文本的节点补 `max-lines` + `overflow="ellipsis"` | 容器只做裁剪时说明 |
+| `COMP_INLINE_MIXED_CONTENT` | warn | template | `mpxTagName@wx="span"\|<image\|<rich-text\|<special-text\|<mpx-icon\|line-clamp\|truncate` | 同一视觉行内图标/图片与文本组件混排时，Skyline 下 `view` / `text` 不能直接完成 WebView 式内联混排；| 人工确认是否为同段图文混排；若是，按「图文混排」改造：`useSkyline()`、容器 `mpxTagName@wx="span"`、Skyline 下 `whitespace-nowrap`、图片 `inline-block`、组件 virtual-host `inline-flex`、文本承载节点 `max-lines` / `overflow` | 普通独立图片、独立图标按钮、非同一视觉行混排可说明 |
+| `STYLE_FLEX_MIN_WIDTH_PERCENT` | warn | style | `min-width\\s*:?\\s*[0-9.]+%\|flex\\s*:?\\s*1\\s+0\\s+auto` | flex 布局子节点依赖百分比 `min-width` 撑开或等分时，Skyline 下可能按内容收缩，导致宽度、间距或滚动范围异常 | 以同一 flex 容器链为单位成组处理；按实际基准宽度换算为明确长度单位，若基准宽度是一屏：`min-width: 100%` → `750rpx`，`min-width: 25%` → `187rpx/187.5rpx` | 非 flex 布局、百分比不承担撑开/等分语义，或已有明确基准宽度且视觉无依赖时说明 |
+| `COMP_SCROLL_TYPE` | error | template | `<scroll-view` | Skyline 下 `scroll-view` 必须显式声明 `type` | 补 `type="list"` / `nested` / `custom` | 无 |
+| `STYLE_OVERFLOW_AXIS` | error | style | `overflow-x\|overflow-y\|overflow\\s+scroll` | Skyline 不支持单轴 overflow 与 scroll overflow | 改 `scroll-view` 或统一 `overflow hidden` | 非 wx 分支 |
+| `STYLE_UNSUPPORTED_PROP` | warn | style | `float\\s\|contain\|resize\|writing-mode\|text-indent\|overflow-wrap\|justify-items` | Skyline 不支持或静默失效 | 替换实现、删除或给出降级说明 | 确认无视觉依赖 |
+| `STYLE_BACKGROUND_LIMIT` | warn | style | `background-image\|mask-image\|background-size\|background-repeat` | 背景/遮罩多值能力有限 | 限制到支持范围；多层背景拆节点 | 单值且已确认支持 |
+| `STYLE_BOX_SHADOW_MULTI` | warn | style | `box-shadow:.*?,` | Skyline 不支持多个 shadow 叠加 | 合并为单 shadow 或拆节点 | 无 |
+| `COMP_UNSUPPORTED` | error | template | `movable-area\|movable-view\|web-view\|editor\|progress\|navigation-bar` | Skyline 不支持组件 | 替代组件、独立 WebView 页面或 renderer 降级 | 明确 WebView-only 页面 |
+| `GLASS_WX_DASH` | warn | template | `wx-if\|wx-for` | glass-easel 推荐/要求冒号写法 | 改 `wx:if` / `wx:for` | 旧编译链确认兼容时可延后 |
+| `ANIMATION_WEBVIEW_API` | error | script/template | `\\.animate\\(\|\\.applyAnimation\\(\|wx\\.createAnimation` | Skyline 不支持或静默不生效 | CSS transition/animation 或 Worklet；Skyline 专属逻辑运行时隔离 | WebView-only 分支 |
+
+## 复核要求
+
+1. `rg` 命中只是候选项，必须结合 SFC 区块和平台条件判断。
+2. 多行 `<scroll-view>` 不能只靠单行 pattern 判定，需读取完整标签。
+3. 保留 `@media screen` 时必须说明 WebView 路径仍需要它；Skyline 路径必须有动态类兜底。
+4. 最终结果中 `error` 不允许无说明残留。
+5. `COMP_INLINE_MIXED_CONTENT` 不能只按 `STYLE_TEXT_OVERFLOW` 处理；命中 `truncate` 且同一行附近存在 `image` / icon / `rich-text` / `special-text` 时，必须进一步套用图文混排规则或说明为什么不是同段混排。
diff --git a/.agents/skills/mpx2skyline/references/skyline-component-reference.md b/.agents/skills/mpx2skyline/references/skyline-component-reference.md
new file mode 100644
index 0000000000..e63264079a
--- /dev/null
+++ b/.agents/skills/mpx2skyline/references/skyline-component-reference.md
@@ -0,0 +1,754 @@
+# Skyline 基础组件支持与差异参考
+
+## 目录
+
+- [通用特性](#通用特性)
+- [组件支持详情](#组件支持详情)
+- [高频组件用法](#高频组件用法)
+  - [scroll-view](#scroll-view)
+  - [swiper](#swiper)
+  - [view](#view)
+  - [text](#text)
+  - [image](#image)
+  - [button](#button)
+  - [input](#input)
+  - [textarea](#textarea)
+  - [navigator](#navigator)
+- [Skyline 新增组件](#skyline-新增组件)
+  - [span](#span)
+  - [snapshot](#snapshot)
+  - [sticky-header / sticky-section](#sticky-header--sticky-section)
+  - [nested-scroll-header / nested-scroll-body](#nested-scroll-header--nested-scroll-body)
+  - [list-view / grid-view](#list-view--grid-view)
+  - [list-builder / grid-builder](#list-builder--grid-builder)
+  - [draggable-sheet](#draggable-sheet)
+  - [share-element](#share-element)
+  - [手势组件族](#手势组件族)
+
+---
+
+## 通用特性
+
+| 特性 | 支持情况 |
+| --- | --- |
+| 无障碍访问 | 暂只支持 `aria-role` / `label` / `hidden` / `disabled` |
+| DarkMode | 支持 |
+| 原生组件 | 均支持同层渲染 |
+| WeUI v2 | 支持 |
+
+## 组件支持详情
+
+| 组件 | 支持情况 | 差异备注/替代方案                                                                        |
+| --- | --- |----------------------------------------------------------------------------------|
+| text | 基本支持 | 内联文本只能用 text 组件；可通过 span 组件与 text / image 内联                                     |
+| view / cover-view | 完全支持 | 涉及文本节点见 text 组件                                                                  |
+| image / cover-image | 基本支持 | SVG 支持度已完善；部分低频 mode 未支持；                     |
+| button | 完全支持 |                                                                                  |
+| scroll-view | 完全支持 | **需显式指定 `type="list"`**；部分属性无需对齐；额外支持大量新特性                                       |
+| swiper / swiper-item | 完全支持 | 增强大量特性；单项无限循环可能异常；                                                               |
+| input / textarea | 完全支持 | 光标选区、菜单略有不同；键盘收起/恢复行为与 WebView 有差异，可能导致布局跳动                                      |
+| navigator | 完全支持 | 只能嵌套 text 组件或文本节点；可通过 span 组件与 text/image 内联                                     |
+| map | 完全支持 | 开发者工具暂未支持调试，请使用真机预览； |
+| canvas | 完全支持 | 开发者工具暂未支持调试，请使用真机预览                                                              |
+| radio / radio-group | 完全支持 |                                                                                  |
+| label | 完全支持 |                                                                                  |
+| video | 基本支持 | 全屏已支持，投屏暂未支持，开发者工具暂未支持调试                                                         |
+| checkbox / checkbox-group | 完全支持 |                                                                                  |
+| picker | 完全支持 |                                                                                  |
+| camera | 完全支持 | 开发者工具暂未支持调试                                                                      |
+| root-portal | 完全支持 |                                                                                  |
+| form | 完全支持 |                                                                                  |
+| ad | 完全支持 |                                                                                  |
+| official-account | 完全支持 |                                                                                  |
+| live-player / live-pusher | 完全支持 |                                                                                  |
+| picker-view | 基本支持 | `indicator-style` 仅支持 `height`、`border`、`background-color`， `indicator-class` / `mask-style` 属性暂未支持； |
+| voip-room | 完全支持 |                                                                                  |
+| rich-text | 完全支持 | 渲染结果可能略为不同；`mode=web` 时则完全对齐 webview                                             |
+| match-media | 待考虑 | 用 `wx.createMediaQueryObserver()` 监听媒体条件,或 `getWindowInfo()` 取屏幕尺寸配合条件渲染实现响应式布局  |
+| keyboard-accessory | 待考虑 | 可通过 input 的 `worklet:onkeyboardheightchange` 回调实现                                |
+| page-meta | 基本支持 | 与全局滚动相关的属性不支持                                                                    |
+| editor | 暂不考虑 | 纯文本编辑用 `textarea`;富文本编辑场景将承载页面单独配置 `"renderer": "webview"`,或用 `rich-text` 只读展示   |
+| web-view | 暂不考虑 | 承载 web-view 的页面单独配置 `"renderer": "webview"`                                      |
+| movable-area / movable-view | 暂不考虑 | 必须用手势组件 + worklet 动画方案替代                                                         |
+| page-container | 基本支持 |                                                                                  |
+| share-element | 完全支持 | 与 WebView 使用方式有异，特性有所增强                                                          |
+| icon | 完全支持 |                                                                                  |
+| progress | 暂不考虑 | 用 `view` 嵌套(外层底色 + 内层动态 `width` 百分比)自行实现进度条,动画进度可配合 worklet 驱动                   |
+| slider | 完全支持 |                                                                                  |
+| switch | 完全支持 |                                                                                  |
+| xr-frame | 暂未支持 | 将承载 3D/XR 内容的页面单独配置 `"renderer": "webview"`;或用 `canvas`(WebGL)自行渲染               |
+| navigation-bar | 不考虑 | Skyline 只能用自定义导航                                                                 |
+| open-data | 完全支持 | 已废弃特性不支持                                                                         |
+
+## 高频组件用法
+
+### scroll-view
+
+可滚动视图区域，Skyline 下必须通过 `type` 属性声明滚动模式，否则性能会退化。
+
+#### 属性
+
+| 属性名 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| scroll-x | boolean | false | 允许横向滚动 |
+| scroll-y | boolean | false | 允许纵向滚动 |
+| scroll-top | number/string | — | 设置竖向滚动条位置 |
+| scroll-left | number/string | — | 设置横向滚动条位置 |
+| scroll-into-view | string | — | 滚动到指定子节点 id（id 不能以数字开头） |
+| scroll-into-view-offset | number | 0 | 跳转到 scroll-into-view 目标时的额外偏移（Skyline 3.1.0+，WebView 3.6.0+） |
+| scroll-with-animation | boolean | false | 滚动时使用动画 |
+| upper-threshold | number | 50 | 距顶部/左侧多远时触发 scrolltoupper |
+| lower-threshold | number | 50 | 距底部/右侧多远时触发 scrolltolower |
+| refresher-enabled | boolean | false | 开启自定义下拉刷新 |
+| refresher-threshold | number | 45 | 下拉刷新触发阈值 |
+| refresher-default-style | string | black | 刷新器默认样式（black/white/none） |
+| refresher-background | string | #FFF | 刷新器背景色 |
+| refresher-triggered | boolean | false | 刷新状态（true 为已触发） |
+
+#### Skyline 特有属性
+
+| 属性名 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| type | string | — | **必填**，滚动模式：list / custom / nested |
+| cache-extent | number | — | 视口外预渲染距离（px） |
+| reverse | boolean | false | 反向滚动 |
+| clip | boolean | true | 是否裁剪溢出内容 |
+| min-drag-distance | number | 18 | 触发滚动的最小拖动距离（px） |
+| padding | Array | [0,0,0,0] | 内边距 [top, right, bottom, left]（px） |
+| scroll-into-view-alignment | string | start | scroll-into-view 对齐方式：start / center / end / nearest |
+| scroll-into-view-within-extent | boolean | false | 目标在预渲染区内时是否仍触发滚动 |
+| associative-container | string | — | 关联的外层容器：draggable-sheet / nested-scroll-view / pop-gesture |
+| worklet:onscrollstart | worklet | — | 滚动开始回调（UI 线程） |
+| worklet:onscrollupdate | worklet | — | 滚动过程回调（UI 线程） |
+| worklet:onscrollend | worklet | — | 滚动结束回调（UI 线程） |
+| worklet:adjust-deceleration-velocity | worklet | — | 调整惯性滚动初速度 |
+
+#### 事件
+
+| 事件名 | 说明 | detail |
+| --- | --- | --- |
+| bindscrolltoupper | 滚动到顶部/左侧 | — |
+| bindscrolltolower | 滚动到底部/右侧 | — |
+| bindscroll | 滚动时持续触发 | scrollLeft, scrollTop, scrollHeight, scrollWidth, deltaX, deltaY |
+| bindrefresherrefresh | 下拉刷新触发 | — |
+| bindrefresherpulling | 下拉过程 | — |
+| bindrefresherrestore | 刷新复位 | — |
+| bindrefresherabort | 下拉中止 | — |
+| bind:refresherwillrefresh | 即将触发刷新（拖动超过阈值） | — |
+| bind:refresherstatuschange | 下拉刷新状态变化 | status, dy |
+
+#### 下拉刷新与下拉二级
+
+自定义下拉刷新区域必须声明 `slot="refresher"`。下拉二级（二楼）是下拉刷新的扩展，需同时开启 `refresher-enabled` 和 `refresher-two-level-enabled`。
+
+| 属性 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| refresher-two-level-enabled | boolean | false | 开启下拉二级能力 |
+| refresher-two-level-triggered | boolean | false | 打开/关闭二级 |
+| refresher-two-level-threshold | number | 150 | 下拉二级阈值 |
+| refresher-two-level-close-threshold | number | 80 | 滑动返回时关闭二级的阈值 |
+| refresher-two-level-scroll-enabled | boolean | false | 二级状态时是否可滑动 |
+| refresher-two-level-pinned | boolean | false | 即将打开二级时是否定住 |
+| refresher-ballistic-refresh-enabled | boolean | false | 惯性滚动是否触发下拉刷新 |
+
+`bind:refresherstatuschange` 的 `detail.status` 为 `RefreshStatus` 枚举：`Idle(0)` / `CanRefresh(1)` / `Refreshing(2)` / `Completed(3)` / `Failed(4)` / `CanTwoLevel(5)` / `TwoLevelOpening(6)` / `TwoLeveling(7)` / `TwoLevelClosing(8)`。
+
+**ScrollViewContext 程序化控制**（需 `enhanced="true"`，通过 `createSelectorQuery().node()` 获取）：`triggerRefresh()` / `closeRefresh()` / `triggerTwoLevel()` / `closeTwoLevel()`，以及设置 `scrollEnabled = false` 程序化禁用滚动。
+
+> 注意事项
+>
+> - Skyline 下**必须**显式设置 `type`（list / custom / nested），否则性能退化为 WebView 模式
+> - list 模式下列表项必须是 scroll-view 的直接子节点；若只有一个直接子节点，按需渲染退化
+> - nested 模式下，内层 scroll-view 需设置 `associative-container="nested-scroll-view"`
+> - `scroll-into-view` 优先级高于 `scroll-top`
+> - 在 scroll-view 内滚动会阻止页面回弹，无法触发页面级 `onPullDownRefresh`
+> - 滚动条长度为预估值，直接子节点高度差异较大时可能不准确
+
+---
+
+### swiper
+
+滑块视图容器，Skyline 下支持多种布局形态和指示器样式。
+
+#### 属性
+
+| 属性名 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| indicator-dots | boolean | false | 是否显示面板指示点 |
+| indicator-color | string | rgba(0,0,0,.3) | 指示点颜色 |
+| indicator-active-color | string | #000 | 当前指示点颜色 |
+| autoplay | boolean | false | 自动切换 |
+| current | number | 0 | 当前所在滑块索引 |
+| interval | number | 5000 | 自动切换时间间隔（ms） |
+| duration | number | 500 | 滑动动画时长（ms） |
+| circular | boolean | false | 衔接滑动（循环） |
+| vertical | boolean | false | 竖向滑动 |
+| display-multiple-items | number | 1 | 同时显示的滑块数量 |
+| previous-margin | string | 0px | 前边距，露出前一项 |
+| next-margin | string | 0px | 后边距，露出后一项（Skyline 3.5.1+ 支持） |
+| easing-function | string | default | 切换缓动函数 |
+| scroll-with-animation | boolean | true | 改变 current 时使用动画 |
+
+#### Skyline 特有属性
+
+| 属性名 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| layout-type | string | normal | 布局形态：normal / stackLeft / stackRight / tinder / transformer |
+| transformer-type | string | scaleAndFade | layout-type=transformer 时的变换效果：scaleAndFade / accordion / threeD / zoomIn / zoomOut / deepthPage |
+| indicator-type | string | normal | 指示器样式：normal / worm / wormThin / wormUnderground / wormThinUnderground / expand / jump / jumpWithOffset / scroll / scrollFixedCenter / slide / slideUnderground / scale / swap / swapYRotation / color |
+| indicator-margin | number | 10 | 指示器外边距 |
+| indicator-spacing | number | 4 | 指示器间距 |
+| indicator-radius | number | 4 | 指示点圆角 |
+| indicator-width | number | 8 | 指示点宽度 |
+| indicator-height | number | 8 | 指示点高度 |
+| indicator-alignment | string/Array | auto | 指示器对齐方式。auto：横滑居底中、纵滑居中右；数组 [x, y] 取值范围 [-1, 1]（底边中点为 [0, 1]） |
+| indicator-offset | Array | [0,0] | 指示器偏移量 [x, y]（px） |
+| cache-extent | number | 0 | 预渲染区域大小，值为 1 表示提前渲染上下各一屏 |
+| direction | string | all | 可滑动方向：all / positive / negative（3.8.10+） |
+| worklet:onscrollstart | worklet | — | 滑动开始回调（UI 线程） |
+| worklet:onscrollupdate | worklet | — | 滑动过程回调（UI 线程） |
+| worklet:onscrollend | worklet | — | 滑动结束回调（UI 线程） |
+
+#### 事件
+
+| 事件名 | 说明 | detail |
+| --- | --- | --- |
+| bindchange | 当前滑块变化 | current（索引）, source（autoplay / touch / ""） |
+
+> 注意事项
+>
+> - Skyline 下单项循环（circular + 仅一项）可能表现异常
+> - swiper-item 自定义宽度建议通过内部子节点控制，直接设置可能不生效
+> - layout-type 为 stackLeft / stackRight / tinder 时，仅支持 indicator-type=normal
+> - indicator-type 为 scrollFixedCenter / swap / swapYRotation 时，不支持 circular
+> - Skyline 的 `previous-margin`、`display-multiple-items`、`vertical` 与 WebView 表现略有不同
+> - 当 `next-margin > 0` 时，Skyline 会将上述属性（`previous-margin` / `display-multiple-items` / `vertical`）对齐 WebView 实现
+> - swiper 自身无禁用拖拽属性；如需屏蔽用户拖拽，外层套 `horizontal-drag-gesture-handler` + `native-view="swiper"`，并在 `worklet:should-accept-gesture` 返回 false
+
+---
+
+### view
+
+最基础的容器组件，Skyline 下布局能力与 WebView 基本一致，但有若干差异。
+
+#### 属性
+
+| 属性名 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| hover-class | string | none | 点击时附加的样式类 |
+| hover-start-time | number | 50 | 按下后出现 hover 的等待时间（ms） |
+| hover-stay-time | number | 400 | 松开后 hover 保留时间（ms） |
+
+#### Skyline 特有文本截断属性
+
+`view` 可直接承载文本超长打点能力，无需仅为省略效果额外包一层 `text`。
+
+| 属性名 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| overflow | string | visible | 文本溢出处理：visible / clip / fade / ellipsis |
+| max-lines | number | — | 最大显示行数 |
+
+> 注意事项
+>
+> - z-index 不支持 Web 标准的层叠上下文，只在同层级节点间有效
+> - 块级文本省略可在 `view` 上直接使用 `max-lines` / `overflow`；内联文本、文本嵌套、可选中文本仍优先使用 `text`
+
+---
+
+### text
+
+文本组件，Skyline 下扩展了溢出处理和行数限制能力。
+
+#### 属性
+
+| 属性名 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| user-select | boolean | false | 是否可选中文本（设置后节点显示变为 inline-block） |
+
+#### Skyline 特有属性
+
+| 属性名 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| overflow | string | visible | 文本溢出处理：visible / clip / fade / ellipsis |
+| max-lines | number | — | 最大显示行数 |
+
+#### WebView 特有属性
+
+| 属性名 | 类型 | 说明 |
+| --- | --- | --- |
+| space | string | 连续空格处理方式：ensp / emsp / nbsp |
+| decode | boolean | 是否解码 HTML 实体，可识别 `&nbsp;` `&lt;` `&gt;` `&amp;` `&apos;` `&ensp;` `&emsp;` |
+
+> 注意事项
+>
+> - `text` 内只能嵌套 `text`，不能嵌套其他类型组件
+> - 块级文本超长打点也可直接在 `view` 上使用 `max-lines` / `overflow`
+> - 图文混排使用 Skyline 专属的 `span` 组件；WebView 下用 `display: flex` 的 view 替代
+> - `space`、`decode` 属性仅 WebView 支持，Skyline 忽略
+> - 仅文本节点可长按选中，其他节点无法选中
+
+---
+
+### image
+
+图片组件，Skyline 下默认开启懒加载，并新增渐显效果。
+
+#### 属性
+
+| 属性名 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| src | string | — | 图片资源地址（支持网络地址、本地路径及云文件 ID） |
+| mode | string | scaleToFill | 裁剪/缩放模式（见下表） |
+| show-menu-by-longpress | boolean | false | 长按显示菜单 |
+| binderror | eventhandler | — | 加载失败回调 |
+| bindload | eventhandler | — | 加载成功回调，detail: { width, height } |
+
+**通用 mode 值**（两端均支持）：scaleToFill / aspectFit / aspectFill / widthFix / heightFix
+
+**WebView-only mode 值**：top / bottom / center / left / right / top left / top right / bottom left / bottom right
+
+#### Skyline 特有属性
+
+| 属性名 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| fade-in | boolean | false | 图片加载完成后是否渐显 |
+
+#### WebView 特有属性
+
+| 属性名 | 类型 | 说明 |
+| --- | --- | --- |
+| webp | boolean | 是否解析 WebP 格式（默认 false） |
+| lazy-load | boolean | 是否懒加载，进入三屏内才加载（默认 false；Skyline 默认懒加载无需设置） |
+| forceHttps | boolean | 是否强制使用 HTTPS（默认 false） |
+
+> 注意事项
+>
+> - 默认尺寸为 320 × 240 px，必须显式指定宽高
+> - Skyline 默认懒加载，WebView 需手动设置 `lazy-load`
+> - top / bottom / center 等裁剪 mode 仅 WebView 支持，需在运行时判断渲染器后兼容
+> - SVG 不支持百分比单位和 `<style>` 元素；`mode=scaleToFill` 时 WebView 居中（除非加 `preserveAspectRatio="none"`），Skyline 撑满
+> - 缩放后宽高可能含小数，不同内核渲染时可能抹去小数
+
+---
+
+### button
+
+按钮组件，Skyline 下与 WebView 行为一致，无差异。
+
+#### 属性
+
+| 属性名 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| size | string | default | 大小：default / mini |
+| type | string | default | 样式类型：default / primary / warn |
+| plain | boolean | false | 是否镂空 |
+| disabled | boolean | false | 是否禁用 |
+| loading | boolean | false | 是否显示 loading 状态 |
+| form-type | string | — | 触发 form 的 submit / reset |
+| open-type | string | — | 微信开放能力 |
+
+---
+
+### input
+
+单行输入框，原生组件，字体固定为系统字体。
+
+#### 属性
+
+| 属性名 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| value | string | — | 输入内容 |
+| type | string | text | 键盘类型：text / number / idcard / digit / nickname（nickname 需 2.21.2+） |
+| password | boolean | false | 是否密码类型 |
+| placeholder | string | — | 占位文本 |
+| placeholder-style | string | — | 占位文本样式 |
+| disabled | boolean | false | 是否禁用 |
+| maxlength | number | 140 | 最大输入长度，-1 为不限制 |
+| cursor-spacing | number | 0 | 光标与键盘的距离（px） |
+| focus | boolean | false | 是否自动聚焦 |
+| confirm-type | string | done | 键盘右下角按钮文字：send / search / next / go / done |
+| confirm-hold | boolean | false | 点击确认时是否保持键盘 |
+| cursor | number | — | 指定光标位置 |
+| cursor-color | string | — | 光标颜色（Skyline 下无限制，支持任意颜色值） |
+| selection-start | number | -1 | 选区起始位置，-1 为不设置 |
+| selection-end | number | -1 | 选区结束位置 |
+| adjust-position | boolean | true | 键盘弹起时是否上推页面 |
+| hold-keyboard | boolean | false | focus 时是否不收起键盘 |
+
+#### Skyline 特有属性
+
+| 属性名 | 类型 | 说明 |
+| --- | --- | --- |
+| bind:selectionchange | eventhandler | 选区改变，detail: { selectionStart, selectionEnd } |
+| bind:keyboardcompositionstart | eventhandler | 输入法组合开始 |
+| bind:keyboardcompositionupdate | eventhandler | 输入法组合更新 |
+| bind:keyboardcompositionend | eventhandler | 输入法组合结束 |
+| worklet:onkeyboardheightchange | worklet | 键盘高度变化（UI 线程），detail: { height, pageBottomPadding } |
+
+#### 事件
+
+| 事件名 | 说明 | detail |
+| --- | --- | --- |
+| bindinput | 输入时触发 | value, cursor, keyCode |
+| bindchange | 失焦时触发 | value |
+| bindfocus | 聚焦时触发 | value, height |
+| bindblur | 失焦时触发 | value |
+| bindconfirm | 点击确认时触发 | value |
+| bindkeyboardheightchange | 键盘高度变化 | height, duration |
+
+> 注意事项
+>
+> - input / textarea 是原生组件，字体固定为系统字体，无法设置 font-family
+> - 自定义组件中的 input 需使用 `wx://form-field` behavior 才能被外层 form 组件获取值
+> - 聚焦期间避免使用 CSS 动画，可能导致光标/选区异常
+> - 键盘高度变化事件可能多次触发，应忽略相同高度值以避免重复布局
+> - `placeholder-class`、`safe-password-*`（安全键盘）等属性仅 WebView 生效
+
+---
+
+### textarea
+
+多行输入框，属性基本与 input 一致，以下列出特有属性。
+
+#### 属性
+
+| 属性名 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| auto-height | boolean | false | 是否自动增高 |
+| fixed | boolean | false | 在 position:fixed 区域内时是否固定（WebView 兼容用） |
+| show-confirm-bar | boolean | true | 是否显示键盘上方的完成工具栏 |
+
+> 其余通用属性（value、placeholder、disabled、maxlength、cursor-spacing、focus 等）与 input 相同。
+
+> 注意事项
+>
+> - 同 input，字体固定为系统字体，无法设置 font-family
+
+---
+
+### navigator
+
+页面链接组件，Skyline 下内容嵌套有限制。
+
+#### 属性
+
+| 属性名 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| url | string | — | 跳转页面路径 |
+| open-type | string | navigate | 跳转方式：navigate / redirect / switchTab / reLaunch / navigateBack / exit |
+| delta | number | 1 | navigateBack 时回退层数 |
+| hover-class | string | navigator-hover | 点击时附加的样式类 |
+| hover-start-time | number | 50 | 按下后出现 hover 的等待时间（ms） |
+| hover-stay-time | number | 600 | 松开后 hover 保留时间（ms） |
+
+> 注意事项
+>
+> - Skyline 下 navigator 内只能嵌套 `text` 组件或纯文本节点，不能嵌套 image 或 view
+
+---
+
+## Skyline 新增组件
+
+### span
+
+Skyline 专属内联容器，用于实现 text、image 的图文混排。
+
+> 注意事项
+>
+> - Skyline 专属，WebView 实测运行无异常
+> - Mpx 中通过 `mpxTagName@wx="span"` 条件渲染；WebView 下用 `display: flex` 的 view 替代
+> - 内部可嵌套 text、image
+
+---
+
+### snapshot
+
+截图组件，可将组件内容渲染为图片，Skyline 专属。
+
+#### 属性
+
+| 属性名 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| mode | string | view | view：与普通 view 无差别，样式变化实时体现；picture：对子节点截图为纹理，后续样式变化不反映到界面，适合 scale/rotate 动画优化（3.1.0+） |
+
+**takeSnapshot 方法**（通过 `createSelectorQuery` 获取节点后调用）：
+
+| 参数 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| type | string | file | 输出类型：file / arraybuffer |
+| format | string | png | 图片格式：png / jpg |
+| quality | number | 1.0 | 压缩质量（0~1，仅 jpg 有效） |
+
+另含 `success` / `fail` 回调；返回值：data（文件路径或 ArrayBuffer）、width、height。
+
+> 注意事项
+>
+> - Skyline 专属
+> - 截图前需确保组件内图片已加载完成，否则结果可能缺图
+> - 大尺寸截图耗时较长，建议显示加载态
+> - 需隐藏截图源区域时，用 `position: fixed; left: -9999px;` 移出屏幕而非 display:none
+
+---
+
+### sticky-header / sticky-section
+
+吸顶布局组件，实现分组列表的吸顶效果，必须在 `scroll-view type="custom"` 中使用。
+
+#### sticky-section 属性
+
+| 属性名 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| push-pinned-header | boolean | true | 新 header 吸顶时是否推动之前已吸顶的 header |
+
+#### sticky-header 属性
+
+| 属性名 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| padding | Array | [0,0,0,0] | 内边距 [top, right, bottom, left] |
+| offset-top | number | 0 | 吸顶时与视窗顶部的距离（px），3.0.0+ |
+| allow-overlapping | boolean | false | 是否允许与前一个 sticky-header 重叠，3.7.11+ |
+
+#### 事件
+
+| 事件名 | 说明 | detail |
+| --- | --- | --- |
+| bind:stickontopchange | 吸顶状态变化，3.6.2+ | isStickOnTop |
+
+> 注意事项
+>
+> - 必须在 `scroll-view type="custom"` 中使用
+> - sticky-header 必须是 sticky-section 的第一个子节点
+> - 每个 sticky-section 只能有一个 sticky-header
+> - sticky-header 背景必须显式设置，否则会透出下层内容
+> - 建议为 sticky-header 显式设置 `z-index`（如 10），确保吸顶时位于上层
+
+---
+
+### nested-scroll-header / nested-scroll-body
+
+嵌套滚动布局组件，实现外层 `scroll-view type="nested"` 与内层 scroll-view 的无缝联动。
+
+#### nested-scroll-body 属性
+
+| 属性名 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| offset-top | number | 0 | 外层滚动时此组件逐渐撑开，直到顶部与视窗顶部距离达到该值才切换为内层滚动（3.6.2+） |
+
+> 注意事项
+>
+> - nested-scroll-header 和 nested-scroll-body 均只渲染第一个子节点，其余子节点不渲染
+> - 一个 `type="nested"` 的 scroll-view 只能包含一个 nested-scroll-body
+> - 可以有多个 nested-scroll-header，每个只包裹一个元素
+> - nested-scroll-header 只能渲染在 nested-scroll-body 上方，禁止放在其下方
+> - 内层 scroll-view 需设置 `associative-container="nested-scroll-view"`
+> - 下拉刷新的 `slot="refresher"` 与 header / body 平级
+> - 联动策略：向下滚动先滚外层再滚内层；向上滚动先滚内层再滚外层
+
+---
+
+### list-view / grid-view
+
+列表/网格布局容器，必须作为 `scroll-view type="custom"` 或 `sticky-section` 的直接子节点，Skyline 专属。
+
+#### list-view 属性
+
+| 属性名 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| padding | Array | [0,0,0,0] | 内边距 [top, right, bottom, left]（px） |
+
+#### grid-view 属性
+
+| 属性名 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| type | string | aligned | 网格类型：aligned（每行高度由该行最高子节点决定）/ masonry（瀑布流，可不等高） |
+| cross-axis-count | number | 2 | 交叉轴（列）数量 |
+| cross-axis-gap | number | 0 | 列间距（px） |
+| main-axis-gap | number | 0 | 行间距（px） |
+| padding | Array | [0,0,0,0] | 内边距 [top, right, bottom, left]（px），3.0.0+ |
+| max-cross-axis-extent | number | 0 | 交叉轴方向单元格最大尺寸 |
+
+> 注意事项
+>
+> - 必须作为 `scroll-view type="custom"` 或 `sticky-section` 的直接子节点
+> - grid-view 基础库 2.29.0 起支持，2.30.4 起提供 WebView 兼容实现；WebView 下 masonry 子元素需有可见宽高
+> - Skyline 专属
+
+---
+
+### list-builder / grid-builder
+
+虚拟列表/网格组件，仅渲染视口内元素，适合超长列表（1000+ 项），Skyline 专属。
+
+#### list-builder 属性
+
+| 属性名 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| type | string | static | 高度模式：static（定高）/ dynamic（不定高） |
+| list | Array | — | 数据列表 |
+| child-count | number | — | 列表项数量 |
+| child-height | number | — | 列表项高度（定高模式必填，px） |
+| padding | Array | [0,0,0,0] | 内边距 [top, right, bottom, left]（px） |
+| initial-child-count | number | 0 | 首次渲染数量（3.7.12+） |
+
+#### grid-builder 属性
+
+在 list-builder 基础上增加网格布局参数（用法与不定高列表类似）：
+
+| 属性名 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| type | string | aligned | 网格类型：aligned / masonry |
+| cross-axis-count | number | — | 交叉轴（列）数量 |
+| cross-axis-gap | number | 0 | 列间距（px） |
+| main-axis-gap | number | 0 | 行间距（px） |
+| max-cross-axis-extent | number | 0 | 交叉轴单元格最大尺寸 |
+| padding | Array | [0,0,0,0] | 内边距 [top, right, bottom, left]（px） |
+
+#### 事件
+
+| 事件名 | 说明 | detail |
+| --- | --- | --- |
+| bind:itembuild | 列表项被创建 | index |
+| bind:itemdispose | 列表项被回收 | index |
+
+列表项通过具名插槽 `slot:item slot:index` 渲染，例如 `<view slot:item slot:index>{{index}}</view>`。
+
+> 注意事项
+>
+> - 必须在 `scroll-view type="custom"` 中使用
+> - 目前仅支持纵向滚动列表
+> - 不定高（dynamic）模式因无法预知未创建项高度，存在滚动条跳动问题
+> - 不支持 `scroll-into-view`
+> - grid-builder 已知 Bug：列表项进屏后再滚出屏幕会被判定为需重新布局，进而自动滚回顶部
+> - Skyline 专属
+
+---
+
+### draggable-sheet
+
+半屏可拖拽面板，实现从底部弹出的半屏交互（类似地图 App 底部面板），Skyline 专属。
+
+#### 属性
+
+| 属性名 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| initial-child-size | number | 0.5 | 初始高度比例（相对父容器，0~1） |
+| min-child-size | number | 0.25 | 最小高度比例 |
+| max-child-size | number | 1.0 | 最大高度比例 |
+| snap | boolean | false | 松手后是否自动吸附到关键点 |
+| snap-sizes | Array | [] | 吸附关键点列表（不含 min/max，会自动包含） |
+| worklet:onsizeupdate | worklet | — | UI 线程尺寸变化回调，参数 { pixels, size } |
+
+**DraggableSheetContext.scrollTo 参数**（通过 `createSelectorQuery` 获取节点后调用）：
+
+| 参数 | 类型 | 说明 |
+| --- | --- | --- |
+| size | number | 目标高度比例（0~1） |
+| animated | boolean | 是否启用动画 |
+| duration | number | 动画时长（ms） |
+| easingFunction | string | 缓动函数：ease / ease-in / ease-out / ease-in-out / linear |
+
+> 注意事项
+>
+> - Skyline 专属
+> - 内部 scroll-view 必须设置 `associative-container="draggable-sheet"`
+> - 所有尺寸属性均为相对父容器高度的比例（0~1），非像素值
+> - 联动策略：向上拖先展开面板到最大，再滚动内部内容；向下拖先将内容滚到顶，再收起面板
+> - snap-sizes 与 min/max 合并后取最近吸附点（如 min 0.2、max 0.9、snap-sizes [0.3,0.5,0.7] → 吸附点 [0.2,0.3,0.5,0.7,0.9]）
+
+---
+
+### share-element
+
+共享元素动画组件，实现页面间元素过渡动画（类似 Flutter Hero），双端支持，Skyline 下能力增强。
+
+#### 属性
+
+| 属性名 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| key | string | — | **必填**，页面内唯一标识，源页面与目标页面必须相同 |
+| transform | boolean | false | 是否启用动画（两端均需设置为 true） |
+| duration | number | 300 | 动画时长（ms） |
+| easing-function | string | ease-out | 缓动函数 |
+
+#### Skyline 特有属性
+
+| 属性名 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| transition-on-gesture | boolean | false | 手势返回时触发动画 |
+| shuttle-on-push | string | to | push 阶段飞跃物：from / to |
+| shuttle-on-pop | string | to | pop 阶段飞跃物：from / to |
+| rect-tween-type | string | materialRectArc | 动画轨迹：materialRectArc / materialRectCenterArc / linear / elasticIn / elasticOut / elasticInOut / bounceIn / bounceOut / bounceInOut，或自定义 `cubic-bezier(x1,y1,x2,y2)` |
+| worklet:onframe | worklet | — | 动画帧回调（UI 线程），参数含 progress（0~1） |
+
+> 注意事项
+>
+> - 源页面和目标页面的 key 必须完全匹配，两端均需设置 `transform="{{true}}"` 才触发动画
+> - 共享元素内容不宜过于复杂，否则影响动画性能
+> - 源与目标元素内容不同时，动画会在两者之间过渡
+> - 手势返回动画、worklet 帧回调、飞跃物选择（shuttle-on-push/pop）均为 Skyline 增强，WebView 不支持
+> - 可配合 `page-container` 实现同页模态转场，用 `transform="{{currentId === item.id}}"` 条件触发
+
+---
+
+### 手势组件族
+
+Skyline 专属，在 UI 线程直接响应手势，避免跨线程延迟。手势组件是"虚组件"，不参与布局，**只能有一个直接子节点**。
+
+**组件列表**：
+
+| 组件 | 触发条件 | 典型用途 |
+| --- | --- | --- |
+| tap-gesture-handler | 点击 | 按钮点击 |
+| double-tap-gesture-handler | 双击 | 点赞、图片放大 |
+| long-press-gesture-handler | 长按 | 菜单弹出 |
+| pan-gesture-handler | 拖动（横向/纵向） | 拖拽排序 |
+| horizontal-drag-gesture-handler | 横向滑动 | 左滑删除 |
+| vertical-drag-gesture-handler | 纵向滑动 | 下拉刷新 |
+| scale-gesture-handler | 多指缩放 | 图片缩放 |
+| force-press-gesture-handler | iPhone 重按 | 3D Touch |
+
+#### 通用属性
+
+| 属性名 | 类型 | 说明 |
+| --- | --- | --- |
+| tag | string | 手势协商标识 |
+| worklet:ongesture | worklet | 手势回调（必须为 worklet 函数） |
+| simultaneous-handlers | Array\<string\> | 可同时触发的手势 tag 列表 |
+| worklet:should-response-on-move | worklet | 移动过程中是否响应 |
+| worklet:should-accept-gesture | worklet | 手势是否应被识别 |
+| native-view | string | 代理的原生节点类型（如 scroll-view） |
+
+**手势状态**（回调参数 `evt.state`，常量挂在 `GestureState` 命名空间，如 `evt.state === GestureState.ACTIVE`）：
+
+| 值 | 常量名 | 含义 |
+| --- | --- | --- |
+| 0 | POSSIBLE | 待识别 |
+| 1 | BEGIN | 手势开始 |
+| 2 | ACTIVE | 手势进行中 |
+| 3 | END | 手势结束 |
+| 4 | CANCELLED | 手势取消 |
+
+**额外回调参数**：
+
+- pan / horizontal-drag / vertical-drag：absoluteX/Y（屏幕坐标）、deltaX/Y（相对上次位移）、velocityX/Y（px/s，手指离开时）
+- long-press：translationX/Y（相对初始触摸点偏移）
+- scale：scale（累计缩放比）、rotation（弧度）、focalX/Y（缩放中心）、focalDeltaX/Y（中心点相对上次移动）、pointerCount
+- force-press：pressure（0~1 压力值）
+
+#### 手势协商
+
+- `native-view` 仅支持 `scroll-view` 和 `swiper` 两个值
+- `simultaneous-handlers` 需双向声明：两个手势各自把对方的 tag 写入列表，声明后两者回调都会触发
+- `worklet:should-accept-gesture` 在手势开始时仅调用一次；`worklet:should-response-on-move` 每次手指移动都调用（避免在其中做复杂计算）
+- 默认嵌套行为：内层手势优先，内层激活后外层失效
+
+> 注意事项
+>
+> - Skyline 专属，WebView 下使用 bind:touchstart / touchmove / touchend + WXS 替代
+> - 回调函数必须在函数体顶部声明 `'worklet'` 指令
+> - 每个手势组件只能有一个直接子节点
+> - 必须处理 CANCELLED 状态，避免状态残留
+> - 手势不冒泡（与普通 touch 事件不同）
+> - 需使用最新 Nightly 工具调试
+
+手势协商（多手势并存）见 [手势系统参考](https://developers.weixin.qq.com/miniprogram/dev/framework/runtime/skyline/gesture.html)。
diff --git a/.agents/skills/mpx2skyline/references/skyline-configuration.md b/.agents/skills/mpx2skyline/references/skyline-configuration.md
new file mode 100644
index 0000000000..30b300f544
--- /dev/null
+++ b/.agents/skills/mpx2skyline/references/skyline-configuration.md
@@ -0,0 +1,125 @@
+# Skyline 配置项与接入规范参考
+
+## 目录
+
+- [适用场景](#适用场景)
+- [skyline 配置](#skyline-配置)
+  - [三级配置层次](#三级配置层次)
+  - [rendererOptions.skyline 配置项](#rendereroptionsskyline-配置项)
+  - [其他配置项](#其他配置项)
+- [Worklet Babel 插件](#worklet-babel-插件)
+
+---
+
+## 适用场景
+
+- 创建新的 Skyline 小程序项目
+- 从 WebView 迁移到 Skyline 渲染引擎
+- 配置混合渲染（部分页面 Skyline、部分 WebView）
+- 配置 rendererOptions 优化样式兼容性
+- 排查 Skyline 配置相关的编译错误
+
+## skyline 配置
+
+### 三级配置层次
+
+| 层级 | 文件 | 作用 | 关键配置 |
+|------|------|------|----------|
+| 全局 | `app.json` | 全局启用 Skyline | renderer, componentFramework, rendererOptions |
+| 页面 | `页面.json` | 页面级配置/覆盖 | navigationStyle, disableScroll, renderer |
+| 工具 | `project.config.json` | 开发者工具调试 | setting.skylineRenderEnable |
+
+
+### rendererOptions.skyline 配置项
+
+| 配置项 | 类型 | 默认值 | 推荐值 | 说明                                    |
+|--------|------|--------|--------|---------------------------------------|
+| `defaultDisplayBlock` | boolean | false | true | 默认 display:block（对齐 WebView）          |
+| `defaultContentBox` | boolean | false | true | 默认 box-sizing:content-box（对齐 WebView） |
+| `tagNameStyleIsolation` | string | "isolated" | "legacy" | 标签选择器全局匹配（对齐 WebView）                 |
+| `enableScrollViewAutoSize` | boolean | false | true | scroll-view 自动撑开高度                    |
+| `keyframeStyleIsolation` | string | - | "legacy" | `@keyframes` 全局共享，避免迁移项目中动画关键帧作用域变化 |
+| `disableABTest` | boolean | false | true | 关闭 Skyline AB 实验，确保稳定性（非必要配置）         |
+
+> 说明：前 5 项（`defaultDisplayBlock` / `defaultContentBox` / `tagNameStyleIsolation` / `enableScrollViewAutoSize` / `keyframeStyleIsolation`）是对齐 WebView 行为的**推荐补齐项**，适配时务必逐项核对。`disableABTest` 为**非必填**：仅在需要关闭 Skyline 灰度 AB 实验、强制全量走 Skyline 以排除实验态干扰时按需开启，常规适配可不配，不作为校验项。
+
+### 其他配置项
+
+| 配置项 | 位置 | 类型 | 推荐值 / 示例 | 说明 |
+|--------|------|------|---------------|------|
+| `convertRpxToVw` | `app.json` 顶层 | boolean | true | 基础库 3.3.0+；开启后将 `rpx` 单位转换为 `vw` 单位，用于修复部分 `rpx` 精度问题 |
+| `backgroundColorContent` | 页面 json | HexColor | `"#00000000"` | Skyline 特有页面配置；设置页面容器背景色，支持 `#RRGGBBAA` 透明度格式，常用于自定义路由透明背景 |
+
+**项目配置 app.json 新增以下配置**
+
+ ```json5
+// 对齐 webview
+{
+  "lazyCodeLoading": "requiredComponents",
+  "convertRpxToVw": true,
+  "rendererOptions": {
+    "skyline": {
+      "defaultDisplayBlock": true,
+      "defaultContentBox": true,
+      "tagNameStyleIsolation": "legacy",
+      "enableScrollViewAutoSize": true,
+      "keyframeStyleIsolation": "legacy"
+    }
+  }
+}
+```
+
+> 注意：`defaultDisplayBlock` / `defaultContentBox` / `tagNameStyleIsolation` / `enableScrollViewAutoSize` / `keyframeStyleIsolation` 均为 `rendererOptions.skyline` 的子项，须写在该对象内，**不要**放到 app.json 顶层；`lazyCodeLoading` 与 `convertRpxToVw` 是 app.json 顶层配置。补齐 app.json 时务必逐项核对上述推荐项都不遗漏；`disableABTest` 按需选配。
+
+**适配 skyline 页面的 page.json新增以下配置**
+
+```json5
+// 
+{
+  "renderer": "skyline",
+  "componentFramework": "glass-easel",
+  "navigationStyle": "custom",
+  "disableScroll": true
+}
+```
+
+`backgroundColorContent` 按页面需要配置：普通页面可不配；需要透明页面容器背景（如自定义路由转场、弹层页）时单独添加：
+
+```json5
+{
+  "backgroundColorContent": "#00000000"
+}
+```
+
+---
+
+## Worklet Babel 插件
+
+如果页面使用到 worklet 函数，需要配置 Babel 插件：
+
+```bash
+npm i babel-plugin-worklet@0.0.5
+```
+
+Mpx 项目中通过 `overrides` 配置：
+
+```json5
+{
+  "overrides": [{
+    // 组件路径
+    "include": ["./src/components/worklet/gesture.mpx"],
+    "plugins": [
+      ["@babel/plugin-transform-arrow-functions"],
+      ["@babel/plugin-transform-shorthand-properties"],
+      ["@babel/plugin-proposal-class-properties"],
+      "babel-plugin-worklet"
+    ]
+  }]
+}
+```
+
+**注意**：
+- 配置 worklet Babel 插件后，**不需要勾选**「将 JS 编译成 ES5」（会导致包体积增加）
+- 若未配置以上插件，则需要在开启开发者工具 "编译 worklet 函数" 选项（（"将 JS 编译成 ES5" 选项也可以，更推荐集成 babel 插件按需编译）
+
+---
diff --git a/.agents/skills/mpx2skyline/references/skyline-migration-practice.md b/.agents/skills/mpx2skyline/references/skyline-migration-practice.md
new file mode 100644
index 0000000000..d27b594358
--- /dev/null
+++ b/.agents/skills/mpx2skyline/references/skyline-migration-practice.md
@@ -0,0 +1,1629 @@
+# WebView → Skyline 适配改造最佳实践
+
+## 目录
+
+- [判断当前渲染模式](#判断当前渲染模式)
+- [布局适配](#布局适配)
+  - [默认 Flex 布局差异处理](#默认-flex-布局差异处理)
+  - [不要依赖 BFC 和 margin 合并](#不要依赖-bfc-和-margin-合并)
+  - [图文混排](#图文混排)
+  - [页面滚动替代方案](#页面滚动替代方案)
+  - [z-index 与层叠适配](#z-index-与层叠适配)
+  - [sticky 吸顶替代方案](#sticky-吸顶替代方案)
+  - [scroll-view 高度自适应](#scroll-view-高度自适应)
+- [样式适配](#样式适配)
+  - [CSS 属性值不支持替代](#css-属性值不支持替代)
+  - [不支持的 CSS 属性](#不支持的-css-属性)
+  - [渐变与背景多值限制](#渐变与背景多值限制)
+  - [filter / backdrop-filter 限制](#filter--backdrop-filter-限制)
+  - [选择器适配](#选择器适配)
+  - [伪类适配](#伪类适配)
+  - [单位适配](#单位适配)
+  - [overflow 适配](#overflow-适配)
+  - [文本溢出省略适配](#文本溢出省略适配)
+  - [字体 PostScript name 兼容](#字体-postscript-name-兼容)
+  - [伪元素 animation 不支持的处理](#伪元素-animation-不支持的处理)
+  - [其他属性适配](#其他属性适配)
+  - [text-decoration-line 多值适配](#text-decoration-line-多值适配)
+  - [flex 布局的子节点 min-width 百分比撑开失效](#flex-布局的子节点-min-width-百分比撑开失效)
+  - [flex 布局的子节点文本超出未自动换行](#flex-布局的子节点文本超出未自动换行)
+  - [@media screen 替换方案](#media-screen-替换方案)
+- [组件适配](#组件适配)
+  - [不支持组件的替代方案](#不支持组件的替代方案)
+  - [scroll-view 行为差异](#scroll-view-行为差异)
+  - [list-view / grid-view 适配](#list-view--grid-view-适配)
+  - [嵌套滚动适配](#嵌套滚动适配)
+  - [navigator 嵌套限制](#navigator-嵌套限制)
+- [Scroll API 适配](#scroll-api-适配)
+  - [ScrollViewContext：必须开启 enhanced 属性](#scrollviewcontext必须开启-enhanced-属性)
+  - [worklet.scrollViewContext：必须通过 ref 获取](#workletscrollviewcontext必须通过-ref-获取)
+  - [worklet.scrollViewContext.scrollTo：调用函数必须声明 'worklet' 指令](#workletscrollviewcontextscrollto调用函数必须声明-worklet-指令)
+  - [DraggableSheetContext：size 和 pixels 不可同时传入](#draggablesheetcontextsize-和-pixels-不可同时传入)
+- [Worklet 动画适配](#worklet-动画适配)
+  - [worklet 函数必须声明 'worklet' 指令](#worklet-函数必须声明-worklet-指令)
+  - [SharedValue 必须通过 .value 读写](#sharedvalue-必须通过-value-读写)
+  - [在 worklet 中调用普通函数必须使用 runOnJS](#在-worklet-中调用普通函数必须使用-runonjs)
+  - [页面方法必须通过 bind(this) 绑定后传入 runOnJS](#页面方法必须通过-bindthis-绑定后传入-runonjs)
+  - [禁止在 worklet 中解构 this](#禁止在-worklet-中解构-this)
+- [glass-easel 变更点适配](#glass-easel-变更点适配)
+  - [[必须] 模板转义改为标准 XML 转义](#必须-模板中数据绑定外的转义改为标准-xml-转义)
+  - [[必须] 不再支持 wx-if / wx-for](#必须-不再支持-wx-if--wx-for仅支持-wxif--wxfor)
+  - [[必须] wx:for 内嵌 include 改为 template](#必须-wxfor-内嵌-include-时改为-template)
+  - [[推荐] 用 this.createSelectorQuery 替代 wx.createSelectorQuery](#推荐-用-thiscreateselectorquery-替代-wxcreateselectorquery)
+  - [[必须] SelectorQuery 选择器不再支持以数字开头](#必须-selectorquery-选择器不再支持以数字开头)
+  - [[必须·仅 Skyline] Worklet 回调函数名称变更](#必须仅-skyline-worklet-回调函数名称变更)
+  - [[必须·仅 Skyline] 不支持的组件实例方法](#必须仅-skyline-不支持的组件实例方法)
+- [常见问题与踩坑记录](#常见问题与踩坑记录)
+  - [properties 默认值必须使用 value 而非 default](#properties-默认值必须使用-value-而非-default)
+  - [The for-list data is neither Array nor Object 报错](#the-for-list-data-is-neither-array-nor-object-报错)
+  - [properties type 校验报错](#properties-type-校验报错)
+  - [animation API 不支持 → 使用 CSS transition](#animation-api-不支持--使用-css-transition)
+  - [movable-area / movable-view 替代方案](#movable-area--movable-view-替代方案)
+  - [wxs 跨包引用错误](#wxs-跨包引用错误typeerror-rwxsstringify4ccc0480-is-not-a-function)
+  - [SVG 在 Skyline 下的限制与适配](#svg-在-skyline-下的限制与适配)
+- [性能优化](#性能优化)
+  - [列表用 list / custom 模式按需渲染](#列表用-list--custom-模式按需渲染)
+  - [列表项样式共享（list-item）](#列表项样式共享list-item)
+  - [cache-extent 预渲染（按需启用）](#cache-extent-预渲染按需启用)
+  - [超长列表用 list-builder / grid-builder](#超长列表用-list-builder--grid-builder)
+  - [预加载 Skyline 环境](#预加载-skyline-环境)
+
+---
+
+## 判断当前渲染模式
+
+在页面或组件实例上可读取 `renderer` 成员，取值为 `webview` 或 `skyline`。如果在模板中要判断，可以拿到值后设置到 data 上。
+
+在生命周期（如 `onLoad`）中赋值到 data，供模板使用：
+
+```js
+// 选项式 API
+createPage({
+  data: {
+    isSkyline: this.renderer === 'skyline'
+  }
+})
+```
+
+```js
+// setup script
+import { getCurrentInstance, onMounted } from '@mpxjs/core'
+
+const instance = getCurrentInstance()
+const renderer = instance.proxy.renderer
+
+onMounted(() => {
+  console.log('当前 renderer:', renderer)
+})
+```
+
+> 注意事项：Skyline & Webview 只能通过运行时的变量区分，在编译时仅能区分微信平台，无法区分是否是 Skyline 渲染
+
+## 布局适配
+
+### 默认 Flex 布局差异处理
+
+Skyline 下节点默认为 `display: flex` 布局，WebView 下默认为 `display: block`，这导致 WebView 下正常排列的元素在 Skyline 下表现为 Flex 行为，需在 `app.json` 中配置 `rendererOptions`，将 Skyline 默认布局改为 block。
+
+### 不要依赖 BFC 和 margin 合并
+
+Skyline 没有 BFC（块级格式化上下文），也没有 margin 合并机制：相邻节点的垂直 `margin` 总是相加，`overflow: hidden` 不会创建 BFC 隔离子节点的 margin。WebView 上依赖 margin 合并或 BFC hack 得到的最终间距，在 Skyline 下会出现叠加，需改为显式、单向地定义间距归属。
+
+**适配原则**：
+
+1. **容器外沿空间用父容器 `padding` 表达**：不要依赖首项 / 末项 margin 与父容器合并。
+2. **兄弟节点间距只交给一侧负责**：列表项之间统一使用后一项的 `margin-top` 或前一项的 `margin-bottom`，避免双向 margin 叠加。
+3. **首尾项差异化用模板状态标记**：需要去掉首项或末项间距时，用 `wx:class` + `index` 显式绑定单类。
+4. **不要把 BFC hack 当作 Skyline 布局手段**：`overflow: hidden` 在 Skyline 中仅用于裁剪，不再具备隔离 margin 的副作用。
+5. **必要时显式声明纵向 Flex**：容器内仍存在难以拆解的垂直 margin 关系时，可同时声明 `display: flex` 与 `flex-direction: column`,使子节点作为 flex item 参与布局,进一步避免垂直 margin 合并。
+
+```html
+<!-- ❌ Bad — 依赖 overflow: hidden 创建 BFC 隔离父子 margin 合并 -->
+<view class="card">
+  <view class="card-title">标题</view>
+  <view class="card-desc">说明</view>
+</view>
+
+<!-- ✅ Good — 父容器 padding 表达外沿空间,兄弟间距交给单侧节点 -->
+<view class="card">
+  <view class="card-title">标题</view>
+  <view class="card-desc">说明</view>
+</view>
+```
+
+```css
+/* ❌ Bad */
+.card { overflow: hidden; }
+.card-title { margin-top: 24rpx; margin-bottom: 16rpx; }
+.card-desc { margin-top: 12rpx; }
+
+/* ✅ Good */
+.card { padding-top: 24rpx; }
+.card-desc { margin-top: 16rpx; }
+```
+
+**列表场景**：用 `index > 0` 标记非首项,只对非首项加 `margin-top`：
+
+```html
+<view class="list">
+  <view
+    wx:for="{{items}}"
+    wx:key="id"
+    class="list-item"
+    wx:class="{{ { 'list-item-gap': index > 0 } }}"
+  >
+    {{item.text}}
+  </view>
+</view>
+```
+
+```css
+.list { padding-top: 24rpx; padding-bottom: 24rpx; }
+.list-item-gap { margin-top: 16rpx; }
+```
+
+### 图文混排
+
+触发条件：同一视觉行内同时出现 `image` / icon 与 `text` / `rich-text` / `special-text` / 自定义文本组件，尤其容器带 `truncate` / `line-clamp` / `whitespace-nowrap` 或 `mpxTagName@wx="span"` 时，必须按本节处理。不要只补 `max-lines` / `overflow`，否则 Skyline 下图片、组件 virtual-host 与文本可能仍无法按 WebView 方式内联对齐或截断。
+
+```html
+<view class="flex-1 w-0 truncate">
+  <image 
+          class="v-middle flex-none w-10px h-10px mb-2px mr-2px"
+          src="https://img-hxy021.didistatic.com/static/starimg/img/tbLezkOe9q1670901034023.png"
+          mode="heightFix" />
+  <rich-text text="儿童贴心服务｜设置本次乘车新偏好" />
+</view>
+```
+
+```html
+<script setup lang="ts">
+import useSkyline from 'common/skyline/useSkyline'
+
+defineExpose({
+  isSkyline: useSkyline()
+})
+</script>
+
+<!-- truncate 为原子类中超长打点类，包含样式 `overflow: hidden; text-overflow: ellipsis; white-space: nowrap;`
+     Skyline 仅需保留 `white-space: nowrap;` 
+     Skyline 超长打点通过 `max-lines`/`overflow` 属性实现
+-->
+<view
+        mpxTagName@wx="span"
+        mpxTagName@ios|android|harmony="text"
+        max-lines="{{1}}"
+        overflow="ellipsis"
+        class="flex-1 w-0 {{isSkyline ? 'whitespace-nowrap' : 'truncate'}}">
+  <!-- Skyline 下将 image 组件 节点改为 inline-block 布局 -->
+  <image
+          class="v-middle flex-none w-10px h-10px mb-2px mr-2px {{isSkyline ? 'inline-block' : ''}}"
+          src="https://img-hxy021.didistatic.com/static/starimg/img/tbLezkOe9q1670901034023.png"
+          mode="heightFix"
+  />
+  <!-- Skyline 下将组件 virtual-host 节点改为 inline-flex 布局 -->
+  <rich-text
+          class="v-middle"
+          style="{{isSkyline ? 'display: inline-flex;' : ''}}"
+          text="儿童贴心服务｜设置本次乘车新偏好"
+  />
+</view>
+```
+
+适配要点：
+
+1. `isSkyline` 用运行时判断注入模板，只在 Skyline 下切换 `whitespace-nowrap`、`inline-block`、`inline-flex` 等兼容样式，非 Skyline 保持不变。
+2. `rich-text` 补 `wrapperStyle="font-size:10px"`，避免组件内部 wrapper 字号与外层不一致。
+3. 图标、`rich-text`、分隔符同属一段图文混排时，放在同一个 `mpxTagName@wx="span"` 容器内；同时兼容 RN 侧时需用 `mpxTagName@ios|android|harmony="text"` 和 `numberOfLines` 对齐单行截断。
+
+### 页面滚动替代方案
+
+Skyline 不支持页面滚动，`onPullDownRefresh` / `onReachBottom` / `onPageScroll` 不会触发。需要滚动的页面必须使用 `scroll-view` 替代页面滚动，页面 json 同时声明 `disableScroll: true`。
+
+```html
+<scroll-view type="list" style="height:100%" show-scrollbar="{{false}}" scroll-y="true">
+  <!-- 页面内容 -->
+</scroll-view>
+```
+
+**原页面生命周期需迁移到 scroll-view 对应事件**（不要只删不补，否则下拉刷新/触底加载/滚动监听等业务逻辑会静默失效）：
+
+| 原页面生命周期 | scroll-view 事件 | 备注 |
+| --- | --- | --- |
+| `onPullDownRefresh` | `bindrefresherrefresh` | 需同时开 `refresher-enabled` |
+| `onReachBottom` | `bindscrolltolower` | 可配合 `lower-threshold` 调阈值 |
+| `onPageScroll(e.scrollTop)` | `bindscroll(e.detail.scrollTop)` | 高频事件，按需节流 |
+
+WebView 直接对齐 Skyline 写法（统一走 scroll-view 事件），避免双份实现带来的维护成本与行为漂移。
+
+```html
+<scroll-view
+  type="list"
+  scroll-y="true"
+  enhanced="true"
+  refresher-enabled="{{true}}"
+  bindrefresherrefresh="onRefresh"
+  bindscrolltolower="onLoadMore"
+  bindscroll="onScroll"
+>
+  <!-- 页面内容 -->
+</scroll-view>
+```
+
+```js
+createPage({
+  onRefresh() {
+    // 原 onPullDownRefresh 的逻辑
+  },
+  onLoadMore() {
+    // 原 onReachBottom 的逻辑
+  },
+  onScroll(e) {
+    const scrollTop = e.detail.scrollTop  // 原 onPageScroll 的 e.scrollTop
+  }
+})
+```
+
+### z-index 与层叠适配
+
+Skyline 没有层叠上下文（stacking-context）的概念。`z-index` 默认值为 `0`，**只在兄弟节点间生效**，节点的最终层级由两套机制决定：**normal-context**（非 fixed 节点）和 **fixed-context**（fixed 节点）。
+
+**核心差异**：
+
+| 维度 | WebView | Skyline |
+| --- | --- | --- |
+| 层叠上下文 | 有，子节点 z-index 在不同层叠上下文间不可比较 | 无，z-index 只在兄弟节点间直接比较 |
+| 跨父级层级 | 由各自所属层叠上下文的层级决定 | 向上回溯到「共同父级下的那对兄弟节点」，比较这对兄弟的 z-index |
+| fixed 节点 | 参与正常层叠上下文 | 全局提升到 fixed-context，整体层级永远高于 normal-context |
+| 相同 z-index | 层叠水平 + 文档顺序决定 | DOM 靠后的层级更高 |
+| `transform` / `opacity` | 会创建新层叠上下文，影响 z-index 比较 | 不创建层叠上下文，对层级无影响 |
+
+**normal-context 机制**（非 fixed 节点）：
+
+```
+      a
+   b      c
+   ↓      ↓
+   d      e
+   ↓      ↓
+   f      g
+```
+
+比较 f 和 g 的层级时，并不直接比较 f、g 自身的 z-index，而是向上回溯到它们在同一父级下的祖先分支 b 和 c，比较 b 与 c 的 z-index——谁更大，其整条子树的层级就更高。若 b、c 的 z-index 相同，则 DOM 靠后的层级更高。
+
+**fixed-context 机制**（fixed 节点）：
+
+不关心 fixed 节点在 DOM 中的父子层级，所有 fixed 节点在全局范围内统一提升到 fixed-context 上渲染：DOM 结构保持不变，但渲染时全部「拍平」为兄弟节点，再仅依据各自的 z-index 排序。
+
+```
+fixed-a (z-index: 2)
+  fixed-b (z-index: 3)
+    fixed-c (z-index: 1)
+  fixed-d (未设置 → 0)
+fixed-e (z-index: 4)
+
+渲染层级排序：fixed-d(0) < fixed-c(1) < fixed-a(2) < fixed-b(3) < fixed-e(4)
+```
+
+注意 fixed-c 虽然 DOM 上嵌套最深，但因 z-index 最小（1），渲染层级反而靠下；fixed-b 的 z-index(3) 高于其父 fixed-a(2)，但因整体拍平比较，仍能盖住 fixed-a。
+
+**适配方案**：
+
+1. **把需要层级控制的节点重构为兄弟节点结构**：页面内非全屏元素用 `relative` + `absolute`，按 normal-context 规则确定层级；全屏元素（弹窗、弹层、toast）按需用 `fixed`，按 fixed-context 规则确定层级，且层级天然高于所有非 fixed 内容。
+2. **不要依赖层叠上下文机制做层级控制**：WebView 上用 `transform` / `opacity` / `will-change` 隐式开启层叠上下文来抬升层级的技巧，在 Skyline 下完全失效。
+3. **`z-index` 不能用在 `scroll-view` 的直接子节点上**：该位置设置 `z-index` 不生效；如需对滚动项做层级控制，应在其内部再包一层节点，或借助 fixed 元素提升到 fixed-context。
+
+### sticky 吸顶替代方案
+
+`position: sticky` 在 Skyline 下不可用，需用 `sticky-header` / `sticky-section` 组件替代。但 `sticky-header` / `sticky-section` 是 Skyline 专属组件，WebView 下不识别，而 WebView 的 `position: sticky` 本就可用，属于「Skyline 支持但 WebView 不需要」的写法，**不要替换 WebView 原生写法**，而是用 [运行时 renderer 判断](#判断当前渲染模式) 隔离两条分支。
+
+```html
+<!-- isSkyline 来自 renderer 判断,见「判断当前渲染模式」 -->
+<scroll-view type="list" scroll-y="true">
+  <!-- Skyline:sticky-section + sticky-header 组件 -->
+  <sticky-section wx:if="{{isSkyline}}">
+    <sticky-header class="sticky-title">吸顶标题</sticky-header>
+    <view>列表内容</view>
+  </sticky-section>
+  <!-- WebView:保留 position: sticky 原生写法 -->
+  <block wx:else>
+    <view class="sticky-title webview-sticky">吸顶标题</view>
+    <view>列表内容</view>
+  </block>
+</scroll-view>
+```
+
+```css
+/* 两端都需显式背景色,避免吸顶时透字穿透 */
+.sticky-title { background: #fff; }
+/* WebView 专属:position: sticky 在 Skyline 下静默失效,仅 WebView 分支使用 */
+.webview-sticky { position: sticky; top: 0; }
+```
+
+```js
+// isSkyline 写入 data 供模板 wx:if 使用
+createPage({
+  onLoad() {
+    this.isSkyline = this.renderer === 'skyline'
+  }
+})
+```
+
+**Skyline 分支结构约束**：
+
+- `sticky-header` 必须是 `sticky-section` 的**第一个子节点**；每个 `sticky-section` 仅允许一个 `sticky-header`。
+- `sticky-section` 必须放在 `scroll-view type="custom"` 或 `type="list"` 内（不可裸用）。
+- `sticky-header` **必须显式声明背景色**（`background` / `background-color`）。Skyline 下 `sticky-header` 默认透明，吸顶时下层列表内容会透字穿透，常见症状是"吸顶后文字与列表叠在一起"。
+
+
+### scroll-view 高度自适应
+
+Skyline 下 scroll-view 默认不会自动根据内容撑开，需配置 `enableScrollViewAutoSize` 开启自动撑开。
+
+**全局配置**：使用 `max-height` + 配置 `enableScrollViewAutoSize` 实现自动撑开（8.0.54+）实现 scroll-view 根据内容撑开
+
+```html
+<!-- 模板：scroll-view 设置 max-height -->
+<scroll-view
+  type="list"
+  scroll-y="{{true}}"
+  enhanced="{{true}}"
+  show-scrollbar="{{false}}"
+  style="max-height: 375px;{{ height }}"
+>
+  <view id="scrollContent">
+    <!-- 动态内容 -->
+  </view>
+</scroll-view>
+```
+
+```json5
+{
+  "rendererOptions": {
+    "skyline": {
+      // app.json 全局配置 `enableScrollViewAutoSize` 开启自动撑开
+      "enableScrollViewAutoSize": true
+    }
+  }
+}
+```
+
+**动态获取方案（getScrollViewHeight）**：明确要求动态获取 scroll-view 高度时使用
+
+在内容渲染后通过 `createSelectorQuery` 查询内容节点的实际高度，将结果写入 style 绑定到 scroll-view。
+
+```ts
+// useSkyline.ts — 工具函数
+import { nextTick, ref } from '@mpxjs/core'
+
+export function getScrollViewHeight(context: Obj, query: string, defaultHeight = 0) {
+  // height 初始为空（或传入兜底高度），格式为内联 style 字符串
+  const height = ref(defaultHeight ? `height:${defaultHeight}px;` : '')
+
+  const updateHeight = () => {
+    // 必须在 nextTick 后查询，确保内容已渲染到 DOM
+    nextTick(() => {
+      context.createSelectorQuery()
+        .select(query)
+        .boundingClientRect((rect: Obj) => {
+          height.value = `height:${Math.ceil(rect?.height || 0)}px;`
+        })
+        .exec()
+    })
+  }
+
+  return { height, updateHeight }
+}
+```
+
+```ts
+// 组件 setup 中使用（仅 Skyline 模式下启用）
+import isSkyline, { getScrollViewHeight } from 'useSkyline'
+
+const context = useContext()
+
+// isSkyline() 为 false（WebView）时退化为空实现，不影响 WebView 逻辑
+const { height, updateHeight } = isSkyline()
+  ? getScrollViewHeight(context, '#scrollContent')
+  : { height: ref(''), updateHeight: () => {} }
+
+// 在内容加载完成后调用 updateHeight，例如接口返回后
+watch(isShow, (val) => {
+  if (val) {
+    fetchData().finally(() => {
+      nextTick(() => { updateHeight() })
+    })
+  }
+})
+```
+
+```html
+<!-- 模板：scroll-view 同时设置 max-height（上限）和动态 height（内容实际高度） -->
+<!-- height 为空时 max-height 生效兜底；height 有值时以实际内容高度为准 -->
+<scroll-view
+  type="list"
+  scroll-y="{{true}}"
+  enhanced="{{true}}"
+  show-scrollbar="{{false}}"
+  style="max-height: 375px;{{ height }}"
+>
+  <view id="scrollContent">
+    <!-- 动态内容 -->
+  </view>
+</scroll-view>
+```
+
+```json
+{
+  "rendererOptions": {
+    "skyline": {
+      "enableScrollViewAutoSize": true
+    }
+  }
+}
+```
+
+## 样式适配
+
+### CSS 属性值不支持替代
+
+部分 CSS 属性的特定值在 Skyline 下不生效，需替换为等效方案：
+
+```css
+/* ❌ Bad — 以下属性值在 Skyline 下不生效 */
+.container {
+  display: grid;     /* 不支持 grid，改用 flex */
+  position: sticky;  /* 不支持 sticky，改用 sticky-header 组件 */
+  overflow: auto;    /* 不支持 auto */
+  overflow: scroll;  /* 不支持 scroll，改用 scroll-view */
+}
+
+/* ✅ Good */
+.container {
+  display: flex;      /* 使用 flex 替代 grid */
+  position: relative; /* sticky 效果使用 sticky-header / sticky-section 组件 */
+  overflow: hidden;   /* 截断溢出内容 */
+}
+```
+
+### 不支持的 CSS 属性
+
+以下属性在 Skyline 下设置后**静默不生效**，需替换为等效方案：
+
+| 属性 | 替代方案 |
+| --- | --- |
+| `float` | 使用 flex 布局 |
+| `contain` | 使用 `-wx-contain` |
+| `resize` | 无替代 |
+| `writing-mode` | 无替代 |
+| `text-indent` | 使用 `padding-left` 模拟 |
+| `overflow-wrap` | 使用 `word-break` |
+| `background-attachment` | 无替代 |
+| `background-clip` | 无替代 |
+| `background-origin` | 无替代 |
+| `mask-origin` / `mask-clip` / `mask-mode` | 无替代 |
+| `justify-items` | 无替代 |
+| `list-style-type` / `list-style-image` / `list-style-position` | 无替代 |
+
+### 渐变与背景多值限制
+
+- **radial-gradient**：仅支持 `circle` 形状，不支持 `ellipse`；尺寸仅支持 `px`；颜色停止仅支持 `%`
+- **linear-gradient**：停止位置仅支持 `%` 和固定长度单位（px、rpx 等）
+- **conic-gradient**：完全支持，无额外限制
+- **background-image / mask-image**：最多支持 **2 个值**，超出忽略
+- **background-repeat / background-size**：不支持多组值
+
+```css
+/* ❌ Bad — ellipse 形状不支持 */
+.bg {
+  background: radial-gradient(ellipse at center, #fff, #000);
+}
+
+/* ✅ Good — 使用 circle */
+.bg {
+  background: radial-gradient(circle at center, #fff, #000);
+}
+```
+
+### filter / backdrop-filter 限制
+
+不支持 `url()` 和 `drop-shadow()`，也不支持多函数组合。用 `box-shadow` 替代 `drop-shadow`。
+
+支持的函数：`blur()`, `brightness()`, `contrast()`, `grayscale()`, `hue-rotate()`, `invert()`, `opacity()`, `saturate()`, `sepia()`
+
+```css
+/* ❌ Bad — 多函数组合 / drop-shadow() 不支持 */
+.el {
+  filter: blur(4px) drop-shadow(2px 2px 4px #000);
+}
+
+/* ✅ Good — 单个支持的函数，drop-shadow 改用 box-shadow */
+.el {
+  filter: blur(4px);
+  box-shadow: 2px 2px 4px #000;
+}
+```
+
+### 选择器适配
+
+| 不支持的选择器 | 替代方案 |
+| --- | --- |
+| `* {}` 通配选择器 | 使用类选择器替代 |
+| `[attr] {}` 属性选择器 | 使用类选择器替代 |
+
+Skyline 下伪元素只支持 `::before` 和 `::after`， 其他伪元素在 Skyline 下不支持，需使用真实节点替代。
+
+### 伪类适配
+
+| 伪类 | 支持情况 | 替代方案 |
+| --- | --- | --- |
+| `:first-child` / `:last-child` | ✓ 支持 | 直接使用 |
+| `:not` / `:only-child` / `:empty` | ✓ 支持（8.0.49+） | 直接使用 |
+| `:nth-child` | ✓ 支持（8.0.50+） | 直接使用 |
+| `:active` | ✓ 支持 | 直接使用 |
+| 其他伪类 | × 不支持 | 使用动态类或兄弟/后代选择器实现 |
+
+### 单位适配
+
+| 不支持的单位/值 | 替代方案 |
+| --- | --- |
+| `em` | 使用 `rpx` / `px` / `rem` |
+| `currentColor` | 显式指定颜色值 |
+
+### overflow 适配
+
+Skyline 下 `overflow: scroll` 不支持，只能通过 `scroll-view` 组件实现滚动。不支持单独设置 `overflow-x` / `overflow-y`。
+
+```css
+/* ❌ Bad — Skyline 不支持 overflow-x/y 单独设置 */
+.scrollable {
+  overflow-y: scroll;
+}
+.overflow-x-hidden {
+  overflow-x: hidden;
+}
+
+/* ✅ Good — 使用 scroll-view 组件代替 overflow: scroll */
+/* <scroll-view type="list" scroll-y>...</scroll-view> */
+```
+
+### 文本溢出省略适配
+
+文本溢出省略，或者文本超长打点，在 Skyline 下需要在对应的 `view`/`text`/`rich-text`/`special-text` 组件上增加 `max-lines`/`overflow` 属性
+
+> **完整扫描要求**：适配时须扫描组件/页面内**所有**包含文本省略样式（`text-overflow: ellipsis` / `-webkit-line-clamp` / `overflow: hidden` + `white-space: nowrap` 组合）的节点，逐一为其补齐 `max-lines`/`overflow`。
+
+> 注意事项
+>
+> **新增/替换 `text` 节点时务必把插值压回单行**：`<view>` 会折叠首尾空白，`<text>` 则字面保留。开闭标签之间留下换行 + 缩进会被当作前导/尾随空格渲染出来，影响 `max-lines`/`overflow` 的截断点与视觉对齐。属性多到必须折行时，只折属性、把插值紧贴 `>`
+> **WebView 样式与 Skyline 属性共存**：原 WebView 的 webkit 省略样式（`-webkit-line-clamp`/`-webkit-box-orient`/`display:-webkit-box`/`text-overflow:ellipsis`/`white-space: nowrap`/`overflow: hidden;`）**保留不删**（WebView 仍需要），同时在承载文本的 `view` / `text` / `rich-text` / `special-text` 节点**新增** `max-lines`/`overflow` 属性给 Skyline 使用。两者共存互不冲突。
+
+**单行省略**：
+
+```html
+<!-- ❌ Bad -->
+<view class="ellipsis">
+  {{title}}
+<view/>
+
+<!-- ✅ Good -->
+<view class="ellipsis" max-lines="{{1}}" overflow="ellipsis">{{title}}</view>
+```
+
+```css
+.ellipsis {
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+```
+
+**多行省略**：
+
+> 注意：文本省略场景下不要删除原 webview 下的文本省略样式，尤其是 `display: -webkit-box;`
+
+```html
+<view class="ellipsis" max-lines="{{2}}" overflow="ellipsis">{{title}}</view>
+```
+
+```css
+.test {
+  overflow: hidden;
+  white-space: nowrap;
+  display: -webkit-box;
+  -webkit-line-clamp: 2;
+  -webkit-box-orient: vertical;
+  text-overflow: ellipsis
+}
+```
+
+### 字体 PostScript name 兼容
+
+部分机型不支持 `font-weight: 500` / `600` 等数值加粗，只能使用 `font-weight: bold` / `700`。
+
+自定义字体的 PostScript name 映射：
+
+| PostScript name | CSS 写法 | 备注 |
+| --- | --- | --- |
+| `xx-Regular` | `font-family: xx;` | 默认值可不加后缀 |
+| `xx-Medium` | `font-family: xx; font-weight: bold;` | |
+| `xx-Semibold` | `font-family: xx; font-weight: bold;` | |
+| `xx-Bold` | `font-family: xx; font-weight: bold;` | |
+
+> 注意事项：如需兼容 WebView 同时使用其它格式，但至少需要有 ttf 格式来保证 skyline 上的展示
+
+```css
+@font-face {
+  font-family: 'BrandFont';
+  src: url('https://cdn.example.com/brand.ttf') format('truetype'),
+  url('https://cdn.example.com/brand.woff2') format('woff2');
+}
+```
+
+### 伪元素 animation 不支持的处理
+
+Skyline 下伪元素的 `animation` 不生效，需要改用真实节点。
+
+**使用真实节点 + CSS animation**
+
+```css
+/* ❌ Bad — 伪元素 animation 在 Skyline 不生效 */
+.loading::after {
+  content: '';
+  animation: spin 1s linear infinite;
+}
+
+/* ✅ Good — 使用真实节点 animation */
+.loading-spinner {
+  animation: spin 1s linear infinite;
+}
+```
+
+### 其他属性适配
+
+| 不支持/受限属性 | 限制说明 | 替代方案 |
+| --- | --- | --- |
+| `box-shadow` 多层 | 不支持多个叠加 | 拆分为多节点或合并为单层 |
+| `text-decoration` | 仅 text 节点生效 | view 内文字用 `<text>` 包裹 |
+| `text-overflow` | 仅 text 节点生效 | 同上 |
+| `backdrop-filter` | 不支持 multi function / drop-shadow / url | 简化滤镜 |
+| `filter` | 不支持 multi function / drop-shadow / url | 简化滤镜 |
+| `border-radius` 非 0 | 四边 border-color / border-style 需一致 | 保持一致或拆分节点 |
+| `animation-fill-mode` | 不支持 `none` / `backwards` | 注意默认表现为 `forwards` |
+| `text-decoration-line` | 仅支持单值，`underline line-through` 等多值组合不生效 | 单值直接用；需双值见 [text-decoration-line 多值适配](#text-decoration-line-多值适配) |
+| `calc()` | 不支持角度类型计算（`calc(90deg + 45deg)`） | 直接写角度值（`135deg`） |
+
+### text-decoration-line 多值适配
+
+Skyline 下 `text-decoration-line` 只取单值，`underline line-through` 这类双值组合会被截断为单值（实际只渲染其中一条线），WebView 则正常叠加两条线。删除线 + 下划线常见于「划线价 + 强调」类价格文案，直接迁移会丢失一条装饰线。
+
+由于 Skyline 下装饰线只能由 `text` 节点单值承载，**双值需拆成嵌套 `text` 节点，每层承担一条装饰线**。用 [运行时 renderer 判断](#判断当前渲染模式) 区分：Skyline 下增加一层 `text` 节点，WebView 维持单节点双值，避免给 WebView 引入无谓的嵌套。
+
+```html
+<!-- ❌ Bad — Skyline 下双值被截断，只剩一条装饰线 -->
+<text class="dual-decoration">{{price}}</text>
+```
+
+```css
+.dual-decoration {
+  text-decoration-line: underline line-through;
+}
+```
+
+```html
+<!-- ✅ Good — 运行时判断:Skyline 嵌套 text 各承担一条装饰线;WebView 维持单节点双值 -->
+<!-- 嵌套 text 的插值务必紧贴标签,text 节点会字面保留首尾空白 -->
+<text wx:if="{{isSkyline}}" class="underline"><text class="line-through">{{price}}</text></text>
+<text wx:else class="dual-decoration">{{price}}</text>
+```
+
+```css
+/* WebView:单节点双值即可叠加两条线 */
+.dual-decoration { text-decoration-line: underline line-through; }
+/* Skyline:外层节点画下划线,内层节点画删除线,嵌套后两条线同时生效 */
+.underline { text-decoration-line: underline; }
+.line-through { text-decoration-line: line-through; }
+```
+
+```js
+// isSkyline 来自 renderer 判断,在生命周期里写入 data 供模板使用
+createPage({
+  data: {
+    isSkyline: this.renderer === 'skyline'
+  }
+})
+```
+> 嵌套的内外层只设 `text-decoration-line`，字号/颜色等由外层继承，避免重复声明导致两层样式打架。两条装饰线归属哪层不影响最终视觉，但内层文本节点要紧贴标签写,防止 `text` 字面保留空白把价格文案撑出多余间距。
+
+### flex 布局的子节点 min-width 百分比撑开失效
+
+Skyline 下 flex 布局子节点依赖百分比 `min-width` 撑开或等分时，百分比可能无法按预期生效，节点会按内容收缩。
+这个 case 中，外层 `.estimate-form` 的 `min-width: 100%` 未能撑满一屏，子项 `.form-item` 的 `min-width: 25%` 也未能按四等分撑开。典型表现是业务工具栏在 WebView 下 4 个按钮均分一屏，但 Skyline 下子项宽度按内容收缩，导致间距和滚动范围异常。
+
+```html
+<!-- ❌ Bad — 子项依赖百分比 min-width 撑开 -->
+<scroll-view
+  class="operation-bar h-38px"
+  scroll-x="{{true}}"
+  enhanced="{{true}}"
+  type="list"
+>
+  <view class="estimate-form text-12px" id="estimate-form">
+    <view class="form-item" wx:for="{{operationList}}" wx:key="key">
+      <view class="form-item-content-wrapper normal">
+        <image wx:if="{{item.icon}}" src="{{item.icon}}" class="form-item-icon normal" />
+        <view wx:else class="form-item-text normal">{{item.title}}</view>
+      </view>
+    </view>
+  </view>
+</scroll-view>
+```
+
+```stylus
+/* ❌ Bad — flex 布局内的 min-width 百分比在 Skyline 下可能不生效 */
+.estimate-form
+  d-flex()
+  min-width 100% // Skyline 下这里也未能按一屏宽度撑开
+  box-sizing border-box
+  min-height 38px
+  color #444
+  .form-item
+    position relative
+    d-flex(,center,center)
+    padding 0 10px
+    flex 1 0 auto
+    min-width 25% // Skyline 下这里也未能按四等分宽度撑开
+    max-width 100%
+    box-sizing border-box
+```
+
+```html
+<!-- ✅ Good — 用 rpx 固定换算值替代百分比 min-width -->
+<scroll-view
+  class="operation-bar h-38px"
+  scroll-x="{{true}}"
+  enhanced="{{true}}"
+  type="list"
+>
+  <view class="estimate-form text-12px" id="estimate-form">
+    <view class="form-item" wx:for="{{operationList}}" wx:key="key">
+      <view class="form-item-content-wrapper normal">
+        <image wx:if="{{item.icon}}" src="{{item.icon}}" class="form-item-icon normal" />
+        <view
+          wx:else
+          class="form-item-text normal"
+          max-lines="{{1}}"
+          overflow="ellipsis"
+        >
+          {{item.title}}
+        </view>
+      </view>
+    </view>
+  </view>
+</scroll-view>
+```
+
+```stylus
+/* ✅ Good — 用 rpx 固定换算值替代百分比 min-width */
+.estimate-form
+  d-flex()
+  flex-shrink 0
+  box-sizing border-box
+  min-height 38px
+  color #444
+  //  ✅ Good — min-width 100% 换算为 min-width 750rpx
+  min-width 750rpx
+  justify-content space-around
+  .form-item
+    position relative
+    d-flex(,center,center)
+    padding 0 10px
+    flex 1 0 auto
+    //  ✅ Good — min-width 25% 换算为 min-width 187rpx
+    min-width 187rpx
+    max-width 100%
+    box-sizing border-box
+```
+
+适配要点：
+
+0. 必须以 flex 容器链为单位处理，扫描并替换同一撑开/等分关系里的所有百分比 `min-width`；不要只处理命中的子项规则。
+1. 不再依赖 `min-width` 百分比撑开，按实际基准宽度换算为 `rpx` / `px` 等明确长度单位。若基准宽度是一屏，750rpx 代表屏宽，25% 可写为约 187rpx。
+2. 若外层内容容器预期至少撑满一屏，使用 `min-width: 750rpx`；若基准不是一屏，应按实际容器设计宽度换算，不要机械套用 750rpx。
+
+### flex 布局的子节点文本超出未自动换行
+
+skyline 下 flex 布局的子节点文本超出未能自动换行，原因是这种场景下 skyline 下 width 为文本内容的宽，需要自行指定宽度来实现自动换行
+
+```html
+<view class="wrapper">
+  <text class="content">测试文案测试文案测试文案测试文案测试文案测试文案测试文案测试文案测试文案</text>
+  <view class="content">测试文案测试文案测试文案测试文案测试文案测试文案测试文案测试文案测试文案</view>
+  <span class="content">测试文案测试文案测试文案测试文案测试文案测试文案测试文案测试文案测试文案</span>
+</view>
+```
+
+```css
+/* ❌ Bad — .content 未定义 width skyline 下未能自动换行  */
+.wrapper {
+  display: flex;
+  flex-direction: column;
+  justify-content: center;
+  align-items: center;
+}
+```
+
+```css
+/* ✅ Good — .content 显示定义 width 来支持自动换行  */
+.wrapper {
+  display: flex;
+  flex-direction: column;
+  justify-content: center;
+  align-items: center;
+}
+.content {
+  width: 100%;
+}
+```
+
+### @media screen 替换方案
+
+Skyline 不支持 `@media screen` 的条件判断：`@media screen and (...)` 外层条件会被忽略，但内部样式仍会生效，等价于把媒体查询内的规则裸写到全局样式里。因此，原本依赖 `@media screen` 区分大小屏的逻辑，在 Skyline 下必须改为运行时动态类。
+
+适配目标是：**WebView 继续使用原生 `@media` 实时响应屏幕变化；Skyline 只使用运行时类控制大小屏状态**。因此需要用 [运行时 renderer 判断](#判断当前渲染模式) 隔离 WebView 与 Skyline，并在 Skyline 分支额外提供一个默认类，用来覆盖 `@media screen` 内部规则泄漏后的默认态。
+
+❌ Bad — Skyline 下 `@media screen` 条件被忽略，内部规则全局生效
+```html
+<view class="wrapper"></view>
+```
+
+```css
+@media screen and (max-width: 320px) {
+  .wrapper { display: none; }
+}
+```
+
+✅ Good — 用 `isSkyline` 门控 Skyline 默认类与状态类，WebView 仍走原生 `@media`
+```html
+<!-- 仅 Skyline 加 .wrapper-skyline / .small;WebView 不加,继续走原生 @media -->
+<view wx:class="wrapper {{ { 'wrapper-skyline': isSkyline, small: isSkyline && isSmall } }}"></view>
+```
+
+```js
+// isSkyline 来自 renderer 判断;isSmall 为屏宽快照
+const isSmall = ref(mpx.getWindowInfo().screenWidth <= 320)
+```
+
+```css
+/* 默认态先声明,WebView 大屏与 Skyline 默认态都以此为基准 */
+.wrapper {
+  display: block;
+}
+
+/* WebView:原生 @media 实时响应横竖屏/resize */
+@media screen and (max-width: 320px) {
+  .wrapper { display: none; }
+}
+
+/*
+ * Skyline:上面的 @media 条件会被忽略,.wrapper { display: none; } 会泄漏为全局规则。
+ * 必须在 @media 之后声明 Skyline 默认类,把非小屏状态覆盖回默认样式。
+ */
+.wrapper-skyline {
+  display: block;
+}
+
+/* Skyline 小屏态 */
+.wrapper-skyline.small { display: none; }
+```
+
+- WebView：`isSkyline=false` → 动态类永不加 → `@media` 生效，保留原生响应式。
+- Skyline：`isSkyline=true` → `.wrapper-skyline` 先覆盖 `@media` 泄漏的默认态，`.small` 再表达小屏态。
+
+> `@media` 与 `.small` 两份规则需同步（阈值 / 样式改动要两处一起改）。`getWindowInfo` 是一次性快照，若 Skyline 下需响应运行时屏宽变化（横竖屏），要再用 `wx.onWindowResize` / 页面 `onResize` 更新 `isSmall`。
+> ⚠️ 声明顺序陷阱：不要直接把 `.wrapper { display: block; }` 写在 `@media` 后面覆盖泄漏规则，这会在 WebView 小屏下同样覆盖原生 `@media`。需要使用 `isSkyline` 门控的 Skyline 默认类（如 `.wrapper-skyline`）放在 `@media` 后面，只覆盖 Skyline 分支。
+
+## 组件适配
+
+### 不支持组件的替代方案
+
+| 组件 | 替代方案 |
+| --- | --- |
+| `web-view` | 建议承载 web-view 的页面单独配置 `"renderer": "webview"` |
+| `movable-area` / `movable-view` | 手势组件 + worklet 动画方案替代 |
+| `navigation-bar` | 自定义导航栏（`common-nav` 通用组件） |
+| `editor` | 暂无替代方案 |
+| `progress` | 自定义实现 |
+
+### scroll-view 行为差异
+
+- **必须指定 `type` 属性**：`type="list"`（列表滚动）、`type="custom"`（自定义布局）、`type="nested"`（嵌套滚动）
+- `show-scrollbar` / `enhanced` 等属性在 Skyline 下行为可能略有差异
+- 暂不支持自动撑开（8.0.54+ 可配置 `enableScrollViewAutoSize`）
+
+### list-view / grid-view 适配
+
+`list-view` 和 `grid-view` 必须放在 `type="custom"` 的 `scroll-view` 内，否则无法正常工作。
+
+```html
+<!-- ❌ Bad — list-view 必须在 type="custom" 的 scroll-view 内 -->
+<scroll-view scroll-y="true">
+  <list-view>
+    <view wx:for="{{list}}" wx:key="id">{{item.name}}</view>
+  </list-view>
+</scroll-view>
+
+<!-- ✅ Good — 使用 type="custom" -->
+<scroll-view type="custom" scroll-y="true">
+  <list-view>
+    <view wx:for="{{list}}" wx:key="id">{{item.name}}</view>
+  </list-view>
+</scroll-view>
+```
+
+### 嵌套滚动适配
+
+父子 `scroll-view` 嵌套时，外层必须使用 `type="nested"` 配合 `nested-scroll-header` 和 `nested-scroll-body`，内层设置 `associative-container="nested-scroll-view"`。直接嵌套两个 `scroll-view` 会导致滚动联动失效。
+
+**重要：嵌套场景下每一层 `scroll-view` 都必须显式声明 `type`**——外层 `type="nested"`、内层 `type="list"` / `"custom"`。遗漏内层 `type` 会让内层退化为 WebView 渲染路径，性能与手势均异常。`list-view` / `grid-view` 仅在 `type="custom"` 或 `sticky-section` 的直接子节点位置生效，放在 `type="list"` 或裸 scroll-view 内不会生效。
+
+```html
+<!-- ❌ Bad — 直接嵌套 scroll-view 导致滚动联动失效 -->
+<scroll-view scroll-y="true">
+  <view>顶部区域</view>
+  <scroll-view scroll-y="true">
+    <view wx:for="{{list}}" wx:key="id">{{item.name}}</view>
+  </scroll-view>
+</scroll-view>
+
+<!-- ❌ Bad — 内层 scroll-view 缺 type -->
+<scroll-view type="nested" scroll-y="true">
+  <nested-scroll-body>
+    <scroll-view scroll-y="true" associative-container="nested-scroll-view">...</scroll-view>
+  </nested-scroll-body>
+</scroll-view>
+
+<!-- ✅ Good — 使用 type="nested" + nested-scroll-header/body，且每层都显式 type -->
+<scroll-view type="nested" scroll-y="true">
+  <nested-scroll-header>
+    <view>顶部固定区域</view>
+  </nested-scroll-header>
+  <nested-scroll-body>
+    <scroll-view
+      type="list"
+      scroll-y="true"
+      associative-container="nested-scroll-view"
+    >
+      <view wx:for="{{list}}" wx:key="id">{{item.name}}</view>
+    </scroll-view>
+  </nested-scroll-body>
+</scroll-view>
+```
+
+### navigator 嵌套限制
+
+Skyline 下 `<navigator>` 内**只能嵌套 `<text>` 组件或纯文本节点**，**不能嵌套** `<view>` / `<image>` / `<swiper>` 等任意其他组件。WebView 下常见的"navigator 内放图标 + 文字"业务结构会让 Skyline 静默渲染异常（图标不显示，或点击区域错位）。
+
+```html
+<!-- ❌ Bad — navigator 内嵌 view + image 在 Skyline 下渲染异常 -->
+<navigator url="/pages/chat/index">
+  <view class="row">
+    <image src="/static/chat.png" />
+    <text>联系客服</text>
+  </view>
+</navigator>
+
+<!-- ✅ Good — 仅嵌套 text -->
+<navigator url="/pages/chat/index">
+  <text>联系客服</text>
+</navigator>
+```
+
+## Scroll API 适配
+
+### ScrollViewContext：必须开启 enhanced 属性
+
+通过 `NodesRef.node()` 获取 `ScrollViewContext` 时，`scroll-view` 必须开启 `enhanced` 属性，否则返回的不是 ScrollViewContext 实例，调用 `scrollTo` 等方法会报错。
+
+```html
+<!-- ❌ Bad — 未开启 enhanced，node() 返回的不是 ScrollViewContext -->
+<scroll-view type="list" scroll-y="true" id="sv">
+  <view wx:for="{{list}}" wx:key="id">{{item.name}}</view>
+</scroll-view>
+
+<!-- ✅ Good — 开启 enhanced，才能获取 ScrollViewContext 实例 -->
+<scroll-view type="list" scroll-y="true" enhanced="true" id="sv">
+  <view wx:for="{{list}}" wx:key="id">{{item.name}}</view>
+</scroll-view>
+```
+
+```js
+createPage({
+  onReady() {
+    this.createSelectorQuery().select('#sv').node()
+      .exec(res => {
+        const ctx = res[0].node  // 只有开启 enhanced 才是 ScrollViewContext
+        ctx.scrollTo({ top: 200, animated: true })
+      })
+  }
+})
+```
+
+### worklet.scrollViewContext：必须通过 ref 获取
+
+在 worklet 函数中控制 scroll-view 滚动，必须使用 `NodesRef.ref()` 获取引用并存入 SharedValue，不能用 `node()`。`node()` 返回的是逻辑线程的 ScrollViewContext，不能在 UI 线程使用。
+
+```js
+// ❌ Bad — 使用 node() 返回的是逻辑线程 ScrollViewContext，无法在 worklet 中使用
+createPage({
+  onLoad() {
+    this.createSelectorQuery().select('.scroll').node()
+      .exec(res => { /* 这是逻辑线程的 ScrollViewContext，不能在 worklet 中使用 */ })
+  }
+})
+
+// ✅ Good — 使用 ref() + shared() 存入 SharedValue，供 worklet 使用
+createPage({
+  onLoad() {
+    this.scrollRef = wx.worklet.shared(null)
+    this.createSelectorQuery().select('.scroll')
+      .ref(res => { this.scrollRef.value = res.ref })
+      .exec()
+  }
+})
+```
+
+### worklet.scrollViewContext.scrollTo：调用函数必须声明 'worklet' 指令
+
+调用 `wx.worklet.scrollViewContext.scrollTo` 的函数必须在 UI 线程执行，即函数顶部必须声明 `'worklet'` 指令。
+
+```js
+// ❌ Bad — 缺少 'worklet' 指令，该 API 只能在 UI 线程调用
+createPage({
+  onTap() {
+    wx.worklet.scrollViewContext.scrollTo(this.scrollRef.value, { top: 200 })
+  }
+})
+
+// ✅ Good — 声明 'worklet' 指令，在 UI 线程执行
+createPage({
+  onTap() {
+    'worklet'
+    wx.worklet.scrollViewContext.scrollTo(this.scrollRef.value, { top: 200 })
+  }
+})
+```
+
+### DraggableSheetContext：size 和 pixels 不可同时传入
+
+`DraggableSheetContext.scrollTo` 中 `size`（相对比例 0–1）和 `pixels`（绝对像素）是互斥参数，同时传入时仅 `size` 生效，`pixels` 被静默忽略。
+
+```js
+// ❌ Bad — 同时传入 size 和 pixels，pixels 被静默忽略
+sheetContext.scrollTo({ size: 0.7, pixels: 200 })
+
+// ✅ Good — size 和 pixels 二选一
+sheetContext.scrollTo({ size: 0.7 })    // 相对比例（0 ~ 1）
+sheetContext.scrollTo({ pixels: 200 })  // 绝对像素值
+```
+
+## Worklet 动画适配
+
+### worklet 函数必须声明 'worklet' 指令
+
+在 UI 线程执行的函数（手势回调、滚动回调等）必须在函数体顶部声明 `'worklet'` 字符串指令。缺少指令时函数在逻辑线程执行，手势动画会有明显延迟。
+
+```js
+// ❌ Bad — 缺少 'worklet' 指令，函数在逻辑线程执行，手势动画有延迟
+createPage({
+  handleGesture(evt) {
+    this.offset.value += evt.deltaX
+  }
+})
+
+// ✅ Good — 声明 'worklet' 指令，函数在 UI 线程直接响应
+createPage({
+  handleGesture(evt) {
+    'worklet'
+    this.offset.value += evt.deltaX
+  }
+})
+```
+
+### SharedValue 必须通过 .value 读写
+
+`wx.worklet.shared()` 创建的共享变量必须通过 `.value` 属性读写。直接赋值会替换整个 SharedValue 对象，之后动画驱动失效。
+
+```js
+// ❌ Bad — 直接赋值替换整个 SharedValue 对象，动画驱动失效
+const { shared } = wx.worklet
+let offset = shared(0)
+offset = 100
+
+// ✅ Good — 通过 .value 读写，驱动所有绑定节点更新
+const { shared } = wx.worklet
+const offset = shared(0)
+offset.value = 100
+```
+
+### 在 worklet 中调用普通函数必须使用 runOnJS
+
+worklet 函数运行在 UI 线程，不能直接调用普通 JS 函数（页面方法、`wx.showToast` 等）。必须通过 `runOnJS` 切换回 JS 线程执行。
+
+```js
+// ❌ Bad — worklet 运行在 UI 线程，不能直接调用普通 JS 函数
+createPage({
+  showTip(msg) {
+    wx.showToast({ title: msg })
+  },
+  handleTap() {
+    'worklet'
+    this.showTip('操作成功')  // 直接调用会报错
+  }
+})
+
+// ✅ Good — 通过 runOnJS 切换回 JS 线程执行
+const { runOnJS } = wx.worklet
+
+createPage({
+  showTip(msg) {
+    wx.showToast({ title: msg })
+  },
+  handleTap() {
+    'worklet'
+    const fn = this.showTip.bind(this)
+    runOnJS(fn)('操作成功')
+  }
+})
+```
+
+### 页面方法必须通过 bind(this) 绑定后传入 runOnJS
+
+在 worklet 中通过 `runOnJS` 调用页面方法时，必须先 `bind(this)` 绑定上下文，否则执行时 `this` 指向丢失。
+
+```js
+// ❌ Bad — 未 bind(this)，runOnJS 调用时 this 指向丢失
+createPage({
+  handleTap() {
+    'worklet'
+    runOnJS(this.showTip)(msg)
+  }
+})
+
+// ✅ Good — 先 bind(this) 再传入 runOnJS
+createPage({
+  handleTap() {
+    'worklet'
+    const showTip = this.showTip.bind(this)
+    runOnJS(showTip)(msg)
+  }
+})
+```
+
+### 禁止在 worklet 中解构 this
+
+在 worklet 函数中对 `this` 进行解构赋值，会触发 `Object.freeze` 冻结整个 `this` 对象，导致页面后续所有 `setData` 调用全部失效。
+
+```js
+// ❌ Bad — 解构触发 Object.freeze 冻结 this.data，后续 setData 全部失效
+createPage({
+  handleTap() {
+    'worklet'
+    const { msg, count } = this
+  }
+})
+
+// ✅ Good — 逐属性访问，不冻结 this
+createPage({
+  handleTap() {
+    'worklet'
+    const msg = this.msg
+    const count = this.count
+  }
+})
+```
+
+## glass-easel 变更点适配
+
+glass-easel 在设计上兼容绝大多数旧版组件框架 exparser 的接口，仅有少数地方需要适配。以下变更点来自[官方适配指引](https://developers.weixin.qq.com/miniprogram/dev/framework/custom-component/glass-easel/migration.html)。
+
+### [必须] 模板中数据绑定外的转义改为标准 XML 转义
+
+数据绑定**外**的引号须改用 XML 实体转义；数据绑定**内**无需再转义。
+
+```html
+<!-- ❌ Bad — 旧写法：反斜杠转义 -->
+<view prop-a="\"test\"" prop-b="{{ test === \"test\" }}" />
+
+<!-- ✅ Good — 新写法：XML 实体转义（外）、不转义（内） -->
+<view prop-a="&quot;test&quot;" prop-b="{{ test === "test" }}" />
+```
+
+### [必须] 不再支持 wx-if / wx-for，仅支持 wx:if / wx:for
+
+`wx-if` / `wx-for`（短横线写法）已废弃，仅支持 `wx:if` / `wx:for`（冒号写法）。exparser 同样支持冒号写法，可直接变更。
+
+```html
+<!-- ❌ Bad -->
+<view wx-if="{{ arr }}" />
+
+<!-- ✅ Good -->
+<view wx:if="{{ arr }}" />
+```
+
+### [必须] wx:for 内嵌 &lt;include&gt; 时改为 &lt;template&gt;
+
+在 `wx:for` 中使用 `<include>` 时，被引入的模板中的 `item` / `index` 变量不再有效，需改为 `<template>` + `<import>` 方案。
+
+```html
+<!-- ❌ Bad -->
+<block wx:for="{{ arr }}">
+  <include src="inc.wxml" />
+</block>
+
+<!-- inc.wxml -->
+<view>{{ index }}. {{ item }}</view>
+```
+
+```html
+<!-- ✅ Good -->
+<import src="inc.wxml" />
+<block wx:for="{{ arr }}">
+  <template is="wx-for-content" data="{{ index, item }}" />
+</block>
+
+<!-- inc.wxml -->
+<template name="wx-for-content">
+  <view>{{ index }}. {{ item }}</view>
+</template>
+```
+
+### [推荐] 用 this.createSelectorQuery 替代 wx.createSelectorQuery
+
+glass-easel 下 `wx.createSelectorQuery` 性能不如 `this.createSelectorQuery`，推荐使用后者（exparser 同样支持）。
+
+```js
+// ❌ Bad
+wx.createSelectorQuery().in(this).select('#el').exec(res => {})
+
+// ✅ Good
+this.createSelectorQuery().select('#el').exec(res => {})
+```
+
+### [必须] SelectorQuery 选择器不再支持以数字开头
+
+`#1` 等以数字开头的 id 选择器在 glass-easel 下不合法（与 CSS 选择器规范保持一致），需重命名。
+
+```js
+// ❌ Bad
+this.createSelectorQuery().select('#1').exec(res => {})
+
+// ✅ Good
+this.createSelectorQuery().select('#element-1').exec(res => {})
+```
+
+### [必须] Skyline Worklet 回调函数名称变更
+
+Skyline 渲染后端上的 Worklet 事件名已更新，旧版本基础库同样支持新事件名，可直接变更。
+
+| 组件 | 旧 Worklet 事件名 | 新 Worklet 事件名 |
+| --- | --- | --- |
+| `pan-gesture-handler` | `on-gesture-event` | `worklet:ongesture` |
+| `pan-gesture-handler` | `should-response-on-move` | `worklet:should-response-on-move` |
+| `pan-gesture-handler` | `should-accept-gesture` | `worklet:should-accept-gesture` |
+| `scroll-view` | `bind:scroll-start` | `worklet:onscrollstart` |
+| `scroll-view` | `bind:scroll` | `worklet:onscrollupdate` |
+| `scroll-view` | `bind:scroll-end` | `worklet:onscrollend` |
+| `scroll-view` | `adjust-deceleration-velocity` | `worklet:adjust-deceleration-velocity` |
+| `swiper` | `bind:transition` | `worklet:onscrollstart` / `worklet:onscrollupdate` |
+| `swiper` | `bind:animationfinish` | `worklet:onscrollend` |
+| `share-element` | `on-frame` | `worklet:onframe` |
+
+```html
+<!-- ❌ Bad -->
+<scroll-view bindscroll="onScrollWorklet" />
+<swiper bind:transition="onTransitionWorklet" />
+
+<!-- ✅ Good -->
+<scroll-view worklet:onscrollupdate="onScrollWorklet" />
+<swiper
+  worklet:onscrollstart="onTransitionWorklet"
+  worklet:onscrollupdate="onTransitionWorklet"
+  worklet:onscrollend="onTransitionWorklet"
+/>
+```
+
+### [必须] Skyline 不支持的组件实例方法
+
+Skyline 下以下组件实例方法暂不支持，调用后静默不生效，需改用 CSS transition 或 Worklet 动画替代：
+
+- `animate`
+- `applyAnimation`
+- `clearAnimation`
+- `setInitialRenderingCache`
+
+## 常见问题与踩坑记录
+
+### properties 默认值必须使用 `value` 而非 `default`
+
+glass-easel 要求组件 properties 的默认值通过 `value` 字段声明，使用 `default` 字段会被忽略，导致属性值为 `undefined`。
+
+```js
+// ❌ Bad — glass-easel 下 default 字段无效，属性值为 undefined
+createComponent({
+  properties: {
+    title: {
+      type: String,
+      default: ''
+    }
+  }
+})
+
+// ✅ Good — 使用 value 字段声明默认值
+createComponent({
+  properties: {
+    title: {
+      type: String,
+      value: ''
+    }
+  }
+})
+```
+
+### The for-list data is neither Array nor Object 报错
+
+当 `wx:for` 绑定的数据是 computed 计算属性时，组件初始化阶段 computed 尚未计算完成，`wx:for` 会收到 `undefined`，触发 `"The for-list data is neither Array nor Object"` 错误。
+
+```js
+// ❌ Bad — 初始化阶段 computed 未完成，wx:for 收到 undefined 导致崩溃
+createComponent({
+  properties: {
+    compData: {
+      type: Object,
+      value: () => ({
+        data: {}
+      })
+    }
+  },
+  computed: {
+    list() {
+      return this.compData?.data.recommend_info
+    }
+  }
+})
+
+// ✅ Good — 通过 initData 提供初始值防护
+createComponent({
+  properties: {
+    compData: {
+      type: Object,
+      value: () => ({
+        data: {}
+      })
+    }
+  },
+  initData: {
+    list: []
+  },
+  computed: {
+    list() {
+      return this.compData?.data.recommend_info
+    }
+  }
+})
+```
+
+### properties type 校验报错
+
+在 glass-easel 下，如果 properties 的 type 声明与实际传入值不匹配，会触发 `"the tyle of property "xxx" is not illegal"` 类型校验错误。两种解决方式：
+
+
+方式一：initData 提供正确类型（更推荐）
+
+```js
+createComponent({
+  properties: {
+    config: {
+      // 通过 optionalTypes 补充定义其他类型
+      type: Object,
+      optionalTypes: [Array],
+      value: () => {}
+    }
+  }
+})
+```
+
+方式二：type 设为 null 跳过校验
+
+> 2.17.2 及以上的基础库增加了对未填写的兼容（未填写时兼容为填写 null），更低版本的基础库无法处理未填写的情况
+
+```js
+createComponent({
+  properties: {
+    config: {
+      // 跳过类型校验
+      type: null,
+      value: {}
+    }
+  }
+})
+```
+
+### animation API 不支持 → 使用 CSS transition
+
+Skyline 不支持 `wx.createAnimation` API（`animation` 属性赋值方式），需要改用 CSS `transition` 或 worklet 动画。
+
+```js
+// ❌ Bad — wx.createAnimation 在 Skyline 下无效
+const animation = wx.createAnimation({
+  duration: 300,
+  timingFunction: 'ease'
+})
+const animationData = ref(animation.opacity(0).step().export())
+```
+
+```css
+/* ✅ Good — 使用 CSS transition 替代 */
+.fade-element {
+  transition: opacity 0.3s ease;
+}
+.fade-element.hidden {
+  opacity: 0;
+}
+```
+
+### movable-area / movable-view 替代方案
+
+Skyline 不支持 `movable-area` / `movable-view`，推荐使用手势组件 + worklet 动画方案替代，需用户确认是否改动：
+
+```html
+<!-- 使用手势组件 + worklet 动画替代 movable-view -->
+<horizontal-drag-gesture-handler worklet:ongesture="onDrag">
+  <view style="transform: translateX({{translateX}})">
+    可拖拽内容
+  </view>
+</horizontal-drag-gesture-handler>
+```
+
+详见 [Worklet 动画与手势系统参考](https://developers.weixin.qq.com/miniprogram/dev/framework/runtime/skyline/gesture.html)。
+
+### wxs 跨包引用错误：TypeError: R.wxs/stringify4ccc0480 is not a function
+
+触发条件：当主包的 wxs 在分包中被 "componentFramework" 为 "glass-easel" 的组件/页面的使用，且在主包没有使用 "componentFramework" 为 "glass-easel" 的组件/页面的时会出现
+
+规避方案：在主包的任意一个 "componentFramework" 为 "glass-easel" 的组件/页面的 wxml 中引用一下这个 wxs 即可，如果没有可以创建一个空组件来引用。
+
+### SVG 在 Skyline 下的限制与适配
+
+**1. 不支持 `<style>` 选择器匹配**
+
+SVG 内嵌的 `<style>` 标签中的 CSS 选择器在 Skyline 下不生效，需将样式转为内联属性。
+
+```xml
+<!-- ❌ Bad — <style> 选择器在 Skyline 下不匹配 -->
+<svg>
+  <style>.icon { fill: #FF6400; }</style>
+  <path class="icon" d="..." />
+</svg>
+
+<!-- ✅ Good — 改为内联样式属性 -->
+<svg>
+  <path fill="#FF6400" d="..." />
+</svg>
+```
+
+**2. 不支持 `rgba()` 颜色格式**
+
+SVG 属性中的 `rgba()` 颜色值在 Skyline 下不生效，需拆分为颜色值 + `fill-opacity` / `stroke-opacity`。
+
+```xml
+<!-- ❌ Bad — rgba() 在 Skyline 下不生效 -->
+<path fill="rgba(255, 100, 0, 0.5)" d="..." />
+
+<!-- ✅ Good — 用 fill-opacity 替代透明度 -->
+<path fill="#FF6400" fill-opacity="0.5" d="..." />
+```
+
+> 建议用 [SVGO 在线工具](https://jakearchibald.github.io/svgomg/) 优化 SVG，可自动清理冗余属性、合并路径，减小体积并降低兼容性风险。
+
+## 性能优化
+
+### 列表用 list / custom 模式按需渲染
+
+`scroll-view` 不指定 `type` 会退化为 WebView 渲染路径，整个列表一次性全量渲染。Skyline 下务必声明 `type`，让滚动容器只渲染在屏节点：
+
+- `type="list"`：列表模式，根据**直接子节点**是否在屏按需渲染。
+- `type="custom"`：自定义模式，子节点可用 `sticky-section` / `list-view` / `grid-view` 等。
+
+```html
+<!-- ❌ Bad — 未声明 type，退化为全量渲染 -->
+<scroll-view scroll-y>
+  <view wx:for="{{list}}" wx:key="id">{{item.name}}</view>
+</scroll-view>
+
+<!-- ✅ Good — list 模式，只渲染在屏节点 -->
+<scroll-view type="list" scroll-y>
+  <view wx:for="{{list}}" wx:key="id">{{item.name}}</view>
+</scroll-view>
+```
+
+> 注意：`list` 模式下列表项必须是 `scroll-view` 的**直接子节点**；若只有一个直接子节点（例如外面又包了一层 `view`），按需渲染会退化为全量渲染。
+
+### 列表项样式共享（list-item）
+
+在 `scroll-view type="list"` 的列表项上声明 `list-item`,Skyline 会把样式计算结果在所有结构相似的列表项之间复用,只计算一次,长列表滚动时显著减少样式重算开销。
+
+```html
+<scroll-view type="list" scroll-y>
+  <view wx:for="{{list}}" wx:key="id" list-item>
+    {{item.name}}
+  </view>
+</scroll-view>
+```
+
+适用前提:列表项结构、样式一致(差异仅由数据驱动)。结构差异较大的卡片混排不要无脑标注 `list-item`,否则共享失败反而增加判定成本。
+
+### cache-extent 预渲染（按需启用）
+
+`cache-extent` 指定预渲染范围，默认视口外节点不渲染。设置后可减少快速滚动 / 切换时的白屏、提升流畅度，但**会提高内存占用并拖慢首屏**——属于用内存换流畅的权衡，不要无脑全开。
+
+`scroll-view`（单位 px）：
+
+```html
+<!-- 预渲染视口上下各约 500px 的内容 -->
+<scroll-view type="list" scroll-y cache-extent="{{500}}">
+  <view wx:for="{{list}}" wx:key="id">{{item.name}}</view>
+</scroll-view>
+```
+
+`swiper`（单位「屏」，默认 `1`，即前后各预渲染一屏）：
+
+```html
+<!-- 预渲染相邻 1 页（默认值），重内容场景不建议盲目调大 -->
+<swiper cache-extent="{{1}}">
+  <swiper-item wx:for="{{banners}}" wx:key="id">...</swiper-item>
+</swiper>
+```
+
+- 首屏敏感的页面：首屏不设或设小值，渲染完成后再调大。
+- 仅在出现明显白屏 / 掉帧时按需加，并以真机表现为准。
+
+### 超长列表用 list-builder / grid-builder
+
+列表项达到千级（1000+）时，`type="list"` 的按需渲染仍会保留已滚出屏幕的节点。改用 `list-builder` / `grid-builder` 可**回收**离屏列表项（进入视口创建、离开视口回收），内存占用更稳定。必须放在 `type="custom"` 的 `scroll-view` 内。
+
+```html
+<scroll-view type="custom" scroll-y>
+  <list-builder
+    list="{{list}}"
+    child-count="{{list.length}}"
+    child-height="{{200}}"
+    bind:itembuild="onItemBuild"
+    bind:itemdispose="onItemDispose"
+  >
+    <view slot:item slot:index style="height: 200px;">{{index}}</view>
+  </list-builder>
+</scroll-view>
+```
+
+- 默认定高模式，需用 `child-height` 指定且所有列表项等高；不定高模式下因无法预知未创建项高度，滚动条会跳动。
+- 目前仅支持纵向滚动，且不支持 `scroll-into-view`。
+- 回收范围取决于 `cache-extent` 配置。
+
+### 预加载 Skyline 环境
+
+微信客户端默认不预加载 Skyline 环境(WebView 为主),首次进入 Skyline 页面会有冷启动开销。在可能跳转到 Skyline 页面的前置页面手动预加载,可显著缩短首屏:
+
+```js
+createPage({
+  onShow() {
+    // 延迟调用,避免阻塞当前页面渲染
+    setTimeout(() => {
+      wx.preloadSkylineView()
+    }, 500)
+  }
+})
+```
+
+- 放在 `onShow` 而非 `onLoad`:用户从 Skyline 页面返回时,前置页 `onShow` 会再次触发,保证下次跳转仍是热环境。
+- 延迟约 500ms 触发,避开当前页首帧高峰。
diff --git a/.agents/skills/mpx2skyline/references/skyline-style-reference.md b/.agents/skills/mpx2skyline/references/skyline-style-reference.md
new file mode 100644
index 0000000000..0503393710
--- /dev/null
+++ b/.agents/skills/mpx2skyline/references/skyline-style-reference.md
@@ -0,0 +1,458 @@
+# Skyline WXSS 样式能力参考
+
+Skyline 渲染引擎 CSS 支持范围与 WebView 有所不同。本文档说明 Skyline 下的样式能力支持情况与属性差异。
+
+## 目录
+
+
+- [Skyline WXSS 样式能力参考](#skyline-wxss-样式能力参考)
+  - [目录](#目录)
+  - [样式能力支持情况](#样式能力支持情况)
+    - [模块支持](#模块支持)
+    - [选择器支持](#选择器支持)
+    - [值类型支持](#值类型支持)
+    - [CSS 变量与函数](#css-变量与函数)
+  - [样式属性支持详情](#样式属性支持详情)
+    - [布局](#布局)
+    - [Flex布局](#flex布局)
+    - [定位与层级](#定位与层级)
+    - [尺寸（Width/Height）](#尺寸widthheight)
+    - [间距（Margin/Padding）](#间距marginpadding)
+    - [边框（Border）](#边框border)
+    - [背景（Background）](#背景background)
+    - [文本与字体](#文本与字体)
+    - [变换（Transform）](#变换transform)
+    - [阴影与不透明度](#阴影与不透明度)
+    - [动画与过渡](#动画与过渡)
+    - [滤镜与遮罩](#滤镜与遮罩)
+    - [其他属性](#其他属性)
+    - [不支持的属性](#不支持的属性)
+  - [与 WebView 模式的关键样式差异](#与-webview-模式的关键样式差异及兼容方案)
+
+---
+
+## 样式能力支持情况
+
+### 模块支持
+
+| 模块 | 支持情况 | 备注 |
+| --- | --- | --- |
+| Flex 布局 | ✅ | 含 `inline-flex`，是 Skyline 默认布局 |
+| Block 布局 | ✅ | 推荐开启默认Block布局，配置 `rendererOptions.skyline.defaultDisplayBlock: true` |
+| Positioned 布局 | ✅ | `sticky` 不支持，使用 `sticky-header`/`sticky-section` 替代 |
+| CSS Animation | ✅ | Android 8.0.37+，iOS 8.0.39+ |
+| CSS Transition | ✅ | |
+| CSS Variable | ✅ | Android 8.0.35+，iOS 8.0.38+ |
+| 背景与边框 | ✅ | |
+| 盒子模型 | ✅ | 支持 `border-box` 和 `content-box`，**无 BFC** |
+| 字体 / `@font-face` | ✅ | 仅支持 ttf 格式 |
+| Media queries | 部分支持 | 仅支持 DarkMode（`@media (prefers-color-scheme: dark)`） |
+| Grid 布局 | ❌ | 使用 Flex 布局或 `grid-view` 组件替代 |
+
+
+### 选择器支持
+
+| 类别 | 示例 | 支持 | 最低版本 | 备注 |
+| --- | --- | --- | --- | --- |
+| 通配选择器 | `* {}` | ❌ | | |
+| 元素选择器 | `tag {}` | ✅ | | |
+| 类选择器 | `.class {}` | ✅ | | |
+| ID 选择器 | `#id {}` | ✅ | | |
+| 分组选择器 | `a, b {}` | ✅ | | |
+| 后代选择器 | `a b {}` | ✅ | | |
+| 直接子代选择器 | `a > b {}` | ✅ | | |
+| 一般兄弟选择器 | `a ~ b {}` | ✅ | 8.0.49 | |
+| 紧邻兄弟选择器 | `a + b {}` | ✅ | 8.0.49 | |
+| 属性选择器 | `[attr] {}` | ❌ | | |
+| 伪类 `:active` | `:active {}` | ✅ | | |
+| 伪类 `:first-child` / `:last-child` | | ✅ | | |
+| 伪类 `:not` / `:only-child` / `:empty` | | ✅ | 8.0.49 | |
+| 伪类 `:nth-child` | | ✅ | 8.0.50 | 对应 Skyline 1.3.3 |
+| 伪元素 | `::before {}` / `::after {}` | ✅ | | 只支持 ::before 和 ::after |
+
+### 值类型支持
+
+#### 长度（`<length>`）
+
+| 单位/格式 | 支持 | 说明                                                                                                                          |
+| --- | --- |-----------------------------------------------------------------------------------------------------------------------------|
+| `px` | ✅ | 物理像素                                                                                                                        |
+| `rpx` | ✅ | 响应式像素，按设备宽度 750rpx 折算                                                                                                       |
+| `vw` / `vh` | ✅ | 视口宽 / 高的 1%                                                                                                                 |
+| `vmin` / `vmax` | ✅ | 视口宽高中的较小 / 较大值的 1%                                                                                                          |
+| `rem` | ✅ | 相对根节点 `font-size`（Skyline 默认根 `font-size` 为 `16px`）                                                                         |
+| `em` | ✅ | 建议优先使用 `rpx` / `px`                                                                                                 |
+| `auto` | ✅ | 用于尺寸、定位、外边距等场景                                                                                                              |
+| `calc()` | ✅ | 仅支持长度类型计算（加减乘除、混合单位），**不支持 `<angle>` 等其他类型计算**；不要嵌套使用                                                                       |
+| `env()` | ✅ | 仅支持 `safe-area-inset-*` 系列：`safe-area-inset-top` / `safe-area-inset-right` / `safe-area-inset-bottom` / `safe-area-inset-left` |
+
+#### 百分比（`%`）支持情况
+
+**支持 `%` 的属性**
+
+| 属性 | `%` 参照对象 |
+| --- | --- |
+| `line-height` | 当前 `font-size` |
+| `transform-origin` | 元素自身的 `width` / `height` |
+| `background-position` | 元素尺寸 - 背景图尺寸 |
+| `width` / `height` | 包含块的同方向尺寸 |
+| `min-width` / `min-height` / `max-width` / `max-height` | 包含块的同方向尺寸 |
+| `top` / `right` / `bottom` / `left` | 包含块的尺寸 |
+| `padding` / `padding-*` | 包含块的同方向尺寸 |
+| `margin` / `margin-*` | 包含块的同方向尺寸 |
+| `flex-basis` | Flex 容器的主轴尺寸 |
+| `gap` / `row-gap` / `column-gap` | Flex 容器的对应方向尺寸 |
+| `border-radius` / `border-*-radius` | 元素自身的 border-box 尺寸 |
+| `background-size` | 背景定位区域 - 背景图尺寸 |
+| `box-shadow` / `text-shadow` 偏移 | 元素自身的 width / height |
+| `letter-spacing` / `word-spacing` | 元素自身的 font-size |
+| `transform: translate*()` / `translateZ()` | 元素自身的 width / height |
+
+**不支持 `%` 的属性：**
+- `border-width` / `border-*-width`
+- `font-size`
+- `box-shadow` / `text-shadow` 模糊半径
+- `perspective`
+
+> 实践建议：
+> 
+> 优先使用 `rpx` / `px` / `vw` / `vh` 等明确长度单位；
+> `flex: 1 0 auto` + `min-width` 实现自动扩展的场景下，min-width 需要使用 rpx 单位
+
+#### `auto` 关键字支持情况
+
+**支持 `auto` 的属性：**
+
+| 属性 | 文档原文（取值 / 默认值） |
+| --- | --- |
+| `pointer-events` | `auto / none`，默认 `auto` |
+| `align-self` | `auto / stretch / center / flex-start / flex-end / baseline`，默认 `auto` |
+| `background-size` | `contain / cover / [<length> | auto]{1, 2}`，默认 `auto` |
+| `will-change` | `auto / contents`，默认 `auto` |
+| `width` / `height` | `<length>`，默认 `auto` |
+| `min-width` / `max-width` | `<length>`，默认 `auto` |
+| `top` / `right` / `bottom` / `left` | `<length>`,默认 `auto` |
+| `flex-basis` | `<length>`，默认 `auto` |
+| `margin` / `margin-*` | `<length>{1,4} \| auto`，默认 `0` |
+
+**不支持 `auto` 的属性：**
+
+| 属性 | 文档原文 |
+| --- | --- |
+| `overflow` | 仅支持 `hidden` / `visible`，「scroll 不支持，只能通过 scroll-view 实现」（无 `auto`） |
+| `min-height` / `max-height` | 默认值为 `none`（非 `auto`） |
+
+
+#### 颜色值（`<color>`）
+
+| 格式 | 支持 | 说明 |
+| --- | -- | -- |
+| color keywords（`red` 等） | ✅ | |
+| `transparent` | ✅ | |
+| `currentColor` | ✅ | |
+| `#RGB` / `#RRGGBB` / `#RGBA` / `#RRGGBBAA` | ✅ | |
+| `rgb()` / `rgba()` | ✅ | |
+| `hsl()` / `hsla()` | ✅ | |
+| `hwb()` | ✅ | |
+
+**渐变（`<gradient>`）：**
+
+| 格式 | 支持 | 限制 |
+| --- | --- | --- |
+| `linear-gradient()` | ✅ | 颜色停止位置仅支持 `%` 和固定长度单位（px、rpx 等） |
+| `radial-gradient()` | ✅ | 仅支持 `circle` 形状（不支持 `ellipse`）；尺寸仅支持 `px`；颜色停止位置仅支持 `%` |
+| `conic-gradient()` | ✅ | 完全支持 |
+
+**其他类型：**
+
+| 类型 | 格式 | 支持 | 说明                                   |
+| --- | --- | --- |--------------------------------------|
+| `<url>` | `url()` | ✅ |                                      |
+| `<angle>` | `deg` / `grad` / `rad` / `turn` | ✅ |                                      |
+| `<time>` | `s` / `ms` | ✅ |                                      |
+| `<border-style>` | `none` / `solid` / `dashed` / `dotted` / `hidden` | ✅ |                                      |
+| `<timing-function>` | `ease` / `ease-in` / `ease-out` / `ease-in-out` / `linear` / `cubic-bezier()` / `steps()` | ✅ |                                      |
+| `<filter-function>` | `blur()` / `brightness()` / `contrast()` / `grayscale()` / `hue-rotate()` / `invert()` / `opacity()` / `saturate()` / `sepia()` | 部分支持 | 不支持 `url()`/`drop-shadow()`；不支持多函数组合 |
+
+### CSS 变量与函数
+
+```css
+page {
+  --primary-color: #1890ff;
+  --spacing: 16px;
+}
+
+.container {
+  color: var(--primary-color);
+  padding: var(--spacing);
+  width: var(--box-width, 100px);  /* 支持默认值 */
+}
+```
+
+- 变量名必须以 `--` 开头
+- `var()` 支持 fallback 默认值语法：`var(--name, fallback)`
+
+---
+
+## 样式属性支持详情
+
+### 布局
+
+| 属性 | 值 | 默认值                                                                                                            | 说明 |
+| --- | --- |----------------------------------------------------------------------------------------------------------------| -- |
+| `display` | `none` \| `block` \| `flex` \|`inline` \|`inline-flex` \| `inline-block` | `flex` | 默认值与 WebView（`block`）不同，`defaultDisplayBlock: true` 时默认值改为 `block`。不支持 `grid`、`flow-root` |
+| `box-sizing` | `content-box` \| `border-box` | `border-box` | 默认值与 WebView（`content-box`）不同；配置 `defaultContentBox: true` 时改为 `content-box`。不支持`padding-box` |
+| `overflow` | `visible` \| `hidden` | `visible` | 不支持 `auto`/`scroll`（滚动请使用 `scroll-view`）；不支持单独设置 `overflow-x`/`overflow-y` |
+| `visibility` | `visible` \| `hidden` | `visible` | |
+| `pointer-events` | `auto` \| `none` | `auto` | |
+| `aspect-ratio` | `auto` \| `<number>` \| `<number> / <number>` | `auto` | |
+
+### Flex布局
+
+| 属性 | 值 | 默认值                                                                                                            | 说明 |
+| --- | --- |----------------------------------------------------------------------------------------------------------------| --- |
+| `flex-direction` | `row` \| `row-reverse` \| `column` \| `column-reverse` | `column`                                                                                                       | `defaultDisplayBlock: true` 时默认值改为 `row` |
+| `flex-wrap` | `nowrap` \| `wrap` \| `wrap-reverse` | `nowrap`                                                                                                       | |
+| `flex` | `none`\|`auto`\| 简写属性 |                                                                                                                | 简写属性，支持解析但以展开属性为准 |
+| `flex-grow` | `<number>` | `0`                                                                                                            | |
+| `flex-shrink` | `<number>` | `1`                                                                                                            | |
+| `flex-basis` | `<length>` \| `auto` | `auto`                                                                                                         | |
+| `order` | `<integer>` | `0`                                                                                                            | |
+| `align-items` | `stretch` \| `center` \| `flex-start` \| `flex-end` \| `baseline` \| `normal` \| `start` \| `end` \| `self-start` \| `self-end` | `stretch`                                                                                                      | `defaultDisplayBlock: true` 时默认值改为 `normal` |
+| `align-self` | `auto` \| `stretch` \| `center` \| `flex-start` \| `flex-end` \| `baseline` \| `start` \| `end` \| `self-start` \| `self-end` \| `normal` | `auto`                                                                                                         | |
+| `align-content` | `stretch` \| `center` \| `flex-start` \| `flex-end` \| `space-between` \| `space-around` \| `space-evenly` \| `normal` \| `start` \| `end` \| `baseline` | `normal`                                                                                                       | |
+| `justify-content` | `center` \| `flex-start` \| `flex-end` \| `space-between` \| `space-around` \| `space-evenly` \| `start` \| `end` \| `left` \| `right` \| `baseline` \| `stretch` | `flex-start`                                                                                                   | |
+| `gap` / `row-gap` / `column-gap` | `<length>` | `0`                                                                                                            | |
+| `justify-items` | — | —                                                                                                              | ⛔ 不可用 |
+
+### 定位与层级
+
+| 属性 | 值 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `position` | `static` \| `relative` \| `absolute` \| `fixed` | `relative` | 不支持 `sticky`（使用 `sticky-header`/`sticky-section` 替代）；`fixed` 不支持 `auto` 偏移默认值解析 |
+| `top` / `right` / `bottom` / `left` | `<length>` | `auto` | |
+| `z-index` | `auto` \| `<integer>` | `0` | **不支持 Web 标准的层叠上下文，`z-index` 只在同层级节点间有效** |
+
+
+### 尺寸（Width/Height）
+
+| 属性 | 值 | 默认值 | 说明                                                                           |
+| --- | --- | --- |------------------------------------------------------------------------------|
+| `width` / `height` | `<length>` \| `auto` | `auto` |                                                                              |
+| `min-width` / `min-height` | `<length>` | `0` |                                                                              |
+| `max-width` / `max-height` | `<length>` | `none` |                                                                              |
+
+### 间距（Margin/Padding）
+
+| 属性 | 值 | 说明 |
+| --- | --- | --- |
+| `padding` / `padding-*` | `<length>{1,4}` | 内边距，支持 1-4 值简写 |
+| `margin` / `margin-*` | `<length>{1,4}` \| `auto` | 外边距，支持 1-4 值简写；`auto` 可用于水平居中 |
+
+### 边框（Border）
+
+| 属性 | 值 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `border-width` / `border-*-width` | `thin` \| `medium` \| `thick` \| `<length>` | `3` | 支持 1-4 值简写 |
+| `border-style` / `border-*-style` | `none` \| `solid` \| `dashed` \| `dotted` \| `hidden` | `none` | 支持 1-4 值简写 |
+| `border-color` / `border-*-color` | `<color>` | `black` | 支持 1-4 值简写 |
+| `border-radius` / `border-*-radius` | `<length>{1,4} [ / <length>{1,4} ]?` | `0` | **`border-radius` 非 0 时，四边的 `border-color` 和 `border-style` 需一致**（`border-width` 可不一致）；支持双值语法 `X/Y` |
+| `border` / `border-*` 简写 | | | 支持解析，展开后以子属性为准 |
+
+### 背景（Background）
+
+| 属性 | 值 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `background-color` | `<color>` | `transparent` | |
+| `background-image` | `none` \| `<url>` \| `<gradient>` | `none` | 最多支持 **2 个值** |
+| `background-size` | `auto` \| `cover` \| `contain` \| `<length>{1,2}` | `auto` | 最多支持 **2 组值** |
+| `background-position` | `<bg-position>` | `0 0` | 最多支持 **2 组值** |
+| `background-repeat` | `repeat-x` \| `repeat-y` \| `repeat` \| `no-repeat` | `repeat` | 不支持 `space`/`round`；最多支持 **2 组值** |
+| `background` 简写 | | | 展开后 `background-attachment`/`background-origin`/`background-clip` 不生效，其余子属性正常 |
+
+**渐变语法支持：**
+
+- `background-attachment`/`background-origin`/`background-clip` 不支持
+- `linear-gradient([ <angle> | to <side-or-corner> ,]? <color-stop-list>)` — 颜色停止位置仅支持 `%` 和固定长度单位（px、rpx 等）
+- `radial-gradient(circle [<size>]? [at <position>]?, <color-stop-list>)` — 仅支持 `circle` 形状（不支持 `ellipse`）；尺寸仅支持 `px`；颜色停止位置仅支持 `%`
+- `conic-gradient([from <angle>]? [at <position>]?, <angular-color-stop-list>)` — 完整支持
+
+### 文本与字体
+
+| 属性 | 值 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `color` | `<color>` | `#000` | 继承属性 |
+| `font-size` | `<length>` | `16px` | 继承；不支持百分比；不支持 `smaller` 等关键字 |
+| `font-weight` | `normal` \| `bold` \| `100–900` | `normal` | 继承；不支持 `bolder`/`lighter`；**部分机型不支持 500/600 数值**，建议使用 `bold`/`700` |
+| `font-style` | `normal` \| `italic` | `normal` | 不支持 `oblique` |
+| `font-family` | `<family-name>` | | 继承；支持自定义字体（仅 ttf 格式） |
+| `font-feature-settings` | `normal` \| `<feature-tag-value>` | `normal` | 继承 |
+| `line-height` | `normal` \| `<number>` \| `<length>` \| `<percentage>` | `normal` | 继承 |
+| `text-align` | `left` \| `center` \| `right` \| `justify` \| `start` \| `end` | `start` | 不支持 `justify-all`/`match-parent` |
+| `vertical-align` | `baseline` \| `top` \| `middle` \| `bottom` | — | 不支持 `text-top`/`text-bottom` |
+| `white-space` | `normal` \| `nowrap` | `normal` | 不支持 `pre`/`pre-wrap`/`pre-line` |
+| `word-break` | `normal` \| `break-all` | `normal` | `keep-all` 可解析但无实际效果；`break-word` 映射为 `normal` |
+| `letter-spacing` | `normal` \| `<length>` | `normal` | 继承 |
+| `word-spacing` | `normal` \| `<length>` | `normal` | 继承 |
+| `text-decoration` 简写 | | | `text-decoration-thickness` 不生效；**仅在 `<text>` 和 `<input>` 上生效** |
+| `text-decoration-line` | `none` \| `underline` \| `overline` \| `line-through` | `none` | 仅支持单值；**仅在 `<text>` 和 `<input>` 上生效** |
+| `text-decoration-style` | `solid` \| `double` \| `dotted` \| `dashed` \| `wavy` | `solid` | **仅在 `<text>` 和 `<input>` 上生效** |
+| `text-decoration-color` | `<color>` | `black` | **仅在 `<text>` 和 `<input>` 上生效** |
+| `text-shadow` | `none` \| `<length>{2,3} <color>?` | `none` | |
+| `text-overflow` | `clip` \| `ellipsis` | `clip` | CSS 属性生效范围有限；文本超长打点推荐在承载文本的 `view` / `text` / `rich-text` / `special-text` 上使用 `overflow` / `max-lines` 属性 |
+| `direction` | — | — | ⛔ 不可用 |
+
+### 变换（Transform）
+
+| 属性 | 值 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `transform` | `none` \| `<transform-function>+` | `none` | 支持 `matrix()` / `matrix3d()` / `translate()` / `translateX()` / `translateY()` / `translateZ()` / `translate3d()` / `scale()` / `scaleX()` / `scaleY()` / `scaleZ()` / `scale3d()` / `rotate()` / `rotateX()` / `rotateY()` / `rotateZ()` / `rotate3d()` / `skew()` / `skewX()` / `skewY()` / `perspective()` |
+| `transform-origin` | `<length> && <length> && <length>?` | `50% 50% 0` | |
+
+### 阴影与不透明度
+
+| 属性 | 值 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `box-shadow` | `inset? && <length>{2,4} && <color>?` | `none` | 不支持多个叠加 |
+| `opacity` | `<number>` | `1` | |
+
+### 动画与过渡
+
+#### 过渡（Transition）
+
+| 属性 | 值 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `transition-property` | `none` \| `all` \| `<animatable-property>#` | `all` | 支持逗号分隔的多属性列表;可动画属性见下方完整列表 |
+| `transition-duration` | `<time>#` | `0s` | 支持逗号分隔的多值,与 `transition-property` 一一对应 |
+| `transition-timing-function` | `<timing-function>#` | `ease` | 支持逗号分隔的多值 |
+| `transition-delay` | `<time>#` | `0s` | 支持逗号分隔的多值 |
+| `transition` 简写 | | | 展开为上述四个子属性 |
+
+#### 动画（Animation）
+
+| 属性 | 值 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `animation-name` | `none` \| `<custom-ident>` \| `<string>` | `none` | 引用 `@keyframes` 名称,支持逗号分隔的多值;**伪元素的 `animation` 不支持** |
+| `animation-duration` | `<time>#` | `0s` | 支持逗号分隔的多值 |
+| `animation-timing-function` | `<timing-function>#` | `ease` | 支持逗号分隔的多值 |
+| `animation-delay` | `<time>#` | `0s` | 支持逗号分隔的多值 |
+| `animation-iteration-count` | `infinite` \| `<number>` | `1` | 支持逗号分隔的多值 |
+| `animation-direction` | `normal` \| `reverse` \| `alternate` \| `alternate-reverse` | `normal` | 支持逗号分隔的多值 |
+| `animation-fill-mode` | `forwards` \| `both` | — | `none` 和 `backwards` 可写但实际均表现为 `forwards` |
+| `animation-play-state` | `running` \| `paused` | `running` | 支持逗号分隔的多值 |
+| `animation` 简写 | | | 展开为上述子属性 |
+
+**`@keyframes`**
+
+```css
+@keyframes <animation-name> {
+  <keyframe-selector># { <declaration-list> }
+}
+```
+
+- `<keyframe-selector>`(关键帧选择器)取值:`from` \| `to` \| `<percentage>`(如 `0%` / `50%` / `100%`)
+- 单条规则可用逗号分隔多个选择器,如 `0%, 100% { ... }`
+
+```css
+@keyframes fade-in {
+  from { opacity: 0; }
+  to   { opacity: 1; }
+}
+.box {
+  animation: fade-in 0.3s ease-in-out forwards;
+}
+```
+
+#### 缓动函数（`<timing-function>`）
+
+`linear` / `ease` / `ease-in` / `ease-out` / `ease-in-out` / `cubic-bezier(<n>,<n>,<n>,<n>)` / `steps(<integer>[, start|end|jump-*]?)`
+
+#### `transition-property` / 可动画属性完整列表
+
+| 类别 | 可动画属性 |
+| --- | --- |
+| 通用 | `all` \| `none` |
+| 变换与不透明度 | `transform` / `transform-origin` / `opacity` |
+| 尺寸 | `width` / `height` / `min-width` / `max-width` / `min-height` / `max-height` |
+| 外边距 | `margin` / `margin-top` / `margin-right` / `margin-bottom` / `margin-left` |
+| 内边距 | `padding` / `padding-top` / `padding-right` / `padding-bottom` / `padding-left` |
+| 定位 | `top` / `right` / `bottom` / `left` |
+| Flex | `flex` / `flex-grow` / `flex-shrink` / `flex-basis` |
+| 边框宽度/颜色/圆角 | `border` / `border-width` / `border-color` / `border-radius` |
+| 边框单边宽度 | `border-top-width` / `border-right-width` / `border-bottom-width` / `border-left-width` |
+| 边框单边颜色 | `border-top-color` / `border-right-color` / `border-bottom-color` / `border-left-color` |
+| 边框单角圆角 | `border-top-left-radius` / `border-top-right-radius` / `border-bottom-left-radius` / `border-bottom-right-radius` |
+| 边框单边简写 | `border-top` / `border-right` / `border-bottom` / `border-left` |
+| 背景 | `background-color` / `background-position` / `background-position-x` / `background-position-y` / `background-size` / `background` |
+| 滤镜与层级 | `filter` / `backdrop-filter` / `box-shadow` / `z-index` |
+| 文本 | `text-decoration-color` |
+| 遮罩 | `mask` / `mask-size` / `mask-position` / `mask-position-x` / `mask-position-y` |
+
+**不支持 transition/animation 的属性：**
+
+- 文本：`text-align`、`text-shadow`、`direction`、`white-space`、`word-break`
+- 字体：`color`、`font-size`、`font-weight`、`font-style`、`font-family`、`font-feature-settings`、`line-height`、`letter-spacing`、`word-spacing`
+- 其他：`visibility`、`pointer-events`
+
+### 滤镜与遮罩
+
+| 属性 | 值 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `filter` | `none` \| `<filter-function>` | `none` | 不支持多函数组合；不支持 `drop-shadow()`、`url()` |
+| `backdrop-filter` | `none` \| `<filter-function>` | `none` | 同 `filter`；与 `opacity` 混合有问题；iOS `blur` 在某些情况表现不一致 |
+| `mask-image` | `none` \| `<url>` | `none` | 最多 **2 个值**；不支持渐变 |
+| `mask-size` | `auto` \| `cover` \| `contain` \| `<length>{1,2}` | `auto` | |
+| `mask-repeat` | `<repeat-style>` | `no-repeat` | 默认值与 Web 标准（`repeat`）不同 |
+| `mask-position` | `<bg-position>` | `center` | 简写有效，自动展开为 `mask-position-x` + `mask-position-y` |
+| `mask-position-x` / `mask-position-y` | `<bg-position-value>` | `center` | |
+| `mask` 简写 | | | 展开后 `mask-origin`/`mask-clip`/`mask-mode` 不生效，其余子属性正常 |
+
+### 其他属性
+
+| 属性 | 值 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `will-change` | `auto` \| `contents` | `auto` | 声明绘制边界，优化渲染性能；不支持 `scroll-position` 和自定义属性名 |
+| `content` | `normal` \| `<string>` | `normal` | `none` 等同于 `normal`；不支持 `url()` |
+| `-wx-contain` | | | `contain` 属性的 Skyline 替代写法 |
+
+### 不支持的属性
+
+- `float` 及相关清除浮动属性 → 使用 Flex 布局替代
+- `display: grid` → 使用 Flex 布局或 `grid-view` 组件
+- `overflow: scroll` / 单独设置 `overflow-x`/`overflow-y` → 使用 `scroll-view` 组件
+- `position: sticky` → 使用 `sticky-header`/`sticky-section` 组件
+- `justify-items` / `direction` → ⛔ 不可用
+- `text-indent` / `overflow-wrap` / `writing-mode` / `text-decoration-thickness` → ⛔ 不可用
+- `list-style-type` / `list-style-image` / `list-style-position` → ⛔ 列表样式属性不可用
+- 多列布局（`column-*`）→ 使用 Flex 布局或 `grid-view` 组件
+- `outline` / `resize` / `cursor` → 不支持
+- `calc()` 角度类型计算 → 不支持
+- `backdrop-filter` / `filter` 多函数组合 → 不支持
+- `mask-image` 渐变值 → 不支持
+
+---
+
+## 与 WebView 模式的关键样式差异及兼容方案
+
+| 属性/行为                             | WebView | Skyline | 兼容方案                                                        |
+|-----------------------------------| --- | --- |-------------------------------------------------------------|
+| `display` 默认值                     | `block` | **`flex`** | 配置 `defaultDisplayBlock: true`                              |
+| `box-sizing` 默认值                  | `content-box` | **`border-box`** | 配置 `defaultContentBox: true`                    |
+| `overflow: scroll`                | 支持 | **不支持** | 使用 `scroll-view` 组件                                         |
+| `overflow-x` / `overflow-y`       | 支持单独设置 | **不支持** | 整体 `overflow` 或 `scroll-view`                               |
+| `position: sticky`                | 支持 | **不支持** | 使用 `sticky-header` / `sticky-section`                       |
+| `z-index`                         | 层叠上下文机制 | **仅兄弟节点生效**，无层叠上下文 | [z-index 与层叠适配](./skyline-migration-practice.md#z-index-与层叠适配) |
+| `*` 通配选择器                         | 支持 | **不支持** | 使用类选择器替代                                                    |
+| `[attr]` 属性选择器                    | 支持 | **不支持** | 使用类选择器替代                                                    |
+| `:nth-child`                      | 支持 | 需 **8.0.50+** |                                                             |
+| 伪元素 `animation`                   | 支持 | **不支持** | 真实节点 + CSS animation                                        |
+| `text-decoration` 作用范围            | 所有元素 | **仅 `<text>` 和 `<input>`** | view 内文字用 `<text>` 包裹                                       |
+| `text-overflow` 作用范围              | 所有元素 | CSS 属性生效范围有限；组件属性可覆盖 `view` / `text` / `rich-text` / `special-text` | 文本超长打点优先补 `max-lines` / `overflow` 属性，`view` 可直接承载 |
+| `border-color`/`border-style` 四边  | 四边可不同 | **`border-radius` 非 0 时需一致** | 保持四边一致或拆分节点                                                 |
+| `font-weight` 数值                  | 完全支持 | **部分机型 500/600 不生效** | 使用 `bold` / `700`                                           |
+| `box-shadow` 多层                   | 支持 | **不支持多个叠加** | 拆分节点或合并                                                     |
+| `animation-fill-mode`             | `none`/`forwards`/`backwards`/`both` | **`none`/`backwards` 表现均为 `forwards`** | 注意动画行为差异    |
+| BFC                               | 支持 | **不支持** | 不依赖 BFC，使用 Flex 布局                                          |
+| 页面滚动                              | 支持 | **不支持** | 使用 `scroll-view type="list"`                                |
+| `margin` 合并                       | 相邻块级元素上下合并 | **不合并** | 不依赖上下合并                                                       |
+| `wx.createAnimation`              | 支持 | **不支持** | 使用 CSS `transition`                           |