@doubao-apps/ai 0.0.20 → 0.0.23

package/dist/skills/uniapp-to-doubao/SKILL.md

@@ -0,0 +1,334 @@
+---
+name: uniapp-to-doubao
+description: Migrate uni-app mini program projects to Doubao Apps SDK (React Lynx). Use when converting uni-app Vue2 SFC pages/components, pages.json, App.vue, main.js, or uni.* APIs.
+---
+
+# uni-app 2.0.0 to Doubao Apps Migration Skill
+
+## When to Use
+
+- Converting `uni-app` mini program projects to Doubao Apps
+- User mentions "uni-app 转豆包小程序", "uniapp to doubao", "Vue SFC 小程序迁移"
+- Working with `App.vue`, `main.js`, `pages.json`, `manifest.json`, `.vue` page/component files
+- Replacing `uni.*` APIs and uni-app template syntax with Doubao Apps patterns
+
+---
+
+## Core Principles
+
+**CRITICAL RULES - MUST FOLLOW:**
+
+1. **Lock Source Major Version**: This skill targets **uni-app `2.0.0` 系列**。Do not assume Vue3, Composition API, `<script setup>`, or APIs/components introduced in later uni-app versions.
+2. **Preserve Business Logic**: Only change framework APIs and syntax, never alter business rules.
+3. **Plan Before Execute**: Always analyze the source project and present a migration plan before editing files.
+4. **Mapping First**: Read mapping docs first; only fall back to raw source docs for uncovered cases.
+5. **Incremental Migration**: Convert page by page / component by component and keep a migration report.
+6. **Record Gaps**: Document platform-specific or version-ambiguous capabilities instead of guessing.
+
+---
+
+## 官方文档入口（已于 2026-04-09 校验可访问）
+
+以下链接用于确认 `uni-app 2.0.0` 的官方历史版本与基础语法入口：
+
+- 历史版本归档（包含 `2.0.0` 系列历史构建）: `https://uniapp.dcloud.net.cn/release-archive.html`
+- `2.0.0` 系列发布记录：见归档页中 `2.0.0.x` 相关条目（如 `2.0.0.20190610`）
+- 页面与生命周期: `https://uniapp.dcloud.io/tutorial/page.html`
+- `pages.json` 配置: `https://uniapp.dcloud.io/collocation/pages.html`
+- 网络请求 / `uni.request`: `https://uniapp.dcloud.io/api/request/request.html`
+- 条件编译: `https://uniapp.dcloud.io/tutorial/platform`
+- 组件总览入口: `https://uniapp.dcloud.io/component/`
+
+**使用约束**：
+
+- 当前官网文档会持续更新，因此它们只能用来确认 **uni-app 的基础语法形态**。
+- 只要当前文档中出现了 `2.0.0` 系列之后新增的能力，均不得迁入目标代码。
+- 本 skill 内部所有示例均按 **Vue2 Options API + uni-app 2.0.0** 口径编写。
+
+---
+
+## 知识来源速查
+
+### 目标框架文档（按需读取）
+
+安装路径（`$SKILLS_BASE`，由 Step 0 检测确定）：
+
+| Agent 环境 | 知识库路径 |
+|------------|-----------|
+| Codex / Cursor / Cline | `.agents/skills/doubao-apps-dev` |
+| Claude Code | `.claude/skills/doubao-apps-dev` |
+
+通过以下命令安装：
+
+```bash
+npx @doubao-apps/ai skills add doubao-apps-dev --agent codex
+```
+
+| 文档 | 路径 | 用途 |
+|------|------|------|
+| 框架 API 速查 | `$SKILLS_BASE/.ai/reference/framework-api-quick-ref.md` | `definePage` / `defineApp` / `getViewData` 等 |
+| 开发规则 | `$SKILLS_BASE/.ai/rules/dos-and-donts.md` | 必须遵守的目标框架规范 |
+| 组件开发指南 | `$SKILLS_BASE/.ai/guides/component-development.md` | 页面/组件组织方式 |
+| 组件库参考 | `$SKILLS_BASE/.ai/reference/components-quick-ref.md` | 目标组件 API |
+
+### 映射文档（迁移核心依据）
+
+| 文档 | 路径 |
+|------|------|
+| 核心 API 映射 | `./references/mapping/core-api-mapping.md` |
+| 生命周期映射 | `./references/mapping/lifecycle-mapping.md` |
+| 组件映射 | `./references/mapping/component-mapping.md` |
+| 样式映射 | `./references/mapping/style-mapping.md` |
+| 事件映射 | `./references/mapping/event-mapping.md` |
+
+### 源框架文档（按问题读取）
+
+| 文档 | 路径 | 何时读取 |
+|------|------|----------|
+| uni-app 2.0.0 API / 配置参考 | `./references/source-framework/api-reference.md` | 识别 `uni.*`、`App.vue`、`pages.json`、条件编译 |
+| uni-app 2.0.0 组件 / 模板参考 | `./references/source-framework/components.md` | 识别模板语法、内置组件、`v-if` / `v-for` / `@tap` 等 |
+
+### 代码导入来源
+
+| 包名 | 用途 | 示例 |
+|------|------|------|
+| `@doubao-apps/framework` | 框架 API 和 React Hooks | `import { definePage, useEffect } from '@doubao-apps/framework'` |
+| `@doubao-apps/framework/api` | 端能力 API（替代 `uni.*`） | `import { request, showToast, navigateTo } from '@doubao-apps/framework/api'` |
+| `@doubao-apps/framework/components` | 目标组件库导出；大部分已支持的小写标签会由 loader 自动注入 import | `import { PickerView, PickerColumn } from '@doubao-apps/framework/components'` |
+
+> 当前工程已支持直接写小写标签：`<view>`、`<text>`、`<image>`、`<input>`、`<textarea>`、`<scroll-view>`、`<list>`、`<list-item>`、`<button>`、`<switch>`、`<slider>`、`<swiper>`、`<swiper-item>`、`<map>`、`<map-marker>`、`<movable-area>`、`<movable-view>`、`<popup>`、`<radio>`、`<radio-group>`、`<picker-view>`、`<picker-column>`、`<web-view>`、`<svg>`。其中大部分标签会由 loader 自动补 import；`<list-item>` 当前主要依赖 JSX intrinsic / Lynx 原生标签能力，不要假设 loader 会补组件导入。
+
+---
+
+## 迁移流程
+
+### Step 0: 环境检查
+
+**1. 确定知识库路径（`$SKILLS_BASE`）**
+
+依次检测以下路径，取第一个存在的作为 `$SKILLS_BASE`：
+
+```bash
+ls .agents/skills/doubao-apps-dev/AGENTS.md 2>/dev/null && echo "SKILLS_BASE=.agents/skills/doubao-apps-dev"
+ls .claude/skills/doubao-apps-dev/AGENTS.md 2>/dev/null && echo "SKILLS_BASE=.claude/skills/doubao-apps-dev"
+```
+
+**2. 如未安装，执行安装**
+
+```bash
+npx @doubao-apps/ai skills add doubao-apps-dev --agent codex
+```
+
+**3. 初始化 Doubao Apps 目标项目**
+
+询问用户目标项目目录名（默认为源项目目录名加 `-doubao` 后缀），然后创建空项目：
+
+```bash
+npx @doubao-apps/create <target-dir> --template empty -y
+```
+
+创建成功后，将 `<target-dir>` 记录为 `$TARGET_PROJECT_PATH`，后续迁移产物统一输出到该目录。
+
+---
+
+### Step 1: 分析源项目
+
+扫描 uni-app `2.0.0` 项目，识别：
+
+- `App.vue`、`main.js`、`pages.json`、`manifest.json` 是否齐全
+- `.vue` 页面和组件数量及目录分布
+- 使用的 `uni.*` API 清单
+- 是否存在平台原生 API 穿透：`wx.*`、`my.*`、`swan.*`、`tt.*` 等
+- 模板指令：`v-if` / `v-else` / `v-for` / `:prop` / `@tap` / `@click` / `v-model`
+- 样式特征：`scoped`、`lang="scss"`、`rpx`、全局样式、`@import`
+- 条件编译：`#ifdef` / `#ifndef` / `#endif`
+- 页面路由、导航栏、下拉刷新、tabBar 等 `pages.json` 配置
+
+**输出示例**：
+
+```text
+📊 项目分析报告
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+源框架：uni-app 2.0.0（Vue2 Options API）
+
+文件数量：22 个页面/组件
+  └─ 页面（pages/）：14 个
+  └─ 组件（components/）：8 个
+
+uni.* API：
+  ✅ 可直接迁移：uni.request, uni.showToast, uni.navigateTo, uni.setStorageSync
+  ⚠️  需人工决策：uni.login, 条件编译下的 wx.* 原生调用
+
+模板语法：
+  ✅ 常规：v-if, v-for, :prop, @tap, @input
+  ⚠️  需重写：v-model, slot, scoped 样式深层选择器
+
+pages.json：
+  ⚠️  需重建：tabBar、navigationBarTitleText、enablePullDownRefresh
+
+复杂度评估：中高
+```
+
+---
+
+### Step 2: 读取映射文档
+
+按以下顺序读取，建立转换规则索引：
+
+1. `./references/mapping/core-api-mapping.md`
+2. `./references/mapping/lifecycle-mapping.md`
+3. `./references/mapping/component-mapping.md`
+4. `./references/mapping/style-mapping.md`
+5. `./references/mapping/event-mapping.md`
+
+遇到未覆盖场景时，再回读源框架文档：
+
+1. `./references/source-framework/api-reference.md`
+2. `./references/source-framework/components.md`
+
+---
+
+### Step 3: 生成迁移计划
+
+基于项目分析和映射规则，生成迁移计划并**展示给用户确认**：
+
+```text
+📋 迁移计划
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+迁移顺序（共 22 个文件）：
+  [1] pages/index/index.vue       → 简单，纯展示页
+  [2] pages/list/index.vue        → 中等，含 uni.request / scroll-view
+  [3] components/goods-card.vue   → 中等，含 props / emit / scoped 样式
+  ...
+
+风险点：
+  ⚠️ uni.login 需要重接登录链路
+  ⚠️ pages.json 的 tabBar / 下拉刷新要在目标工程重建
+  ⚠️ 条件编译里的平台原生 API 不能机械迁移
+
+是否开始迁移？(y/n)
+```
+
+---
+
+### Step 4: 执行迁移
+
+#### 4.1 文件转换规则
+
+uni-app `2.0.0` 页面/组件通常以 `.vue` 单文件组件存在；迁移后统一拆为 Doubao Apps 的 `index.tsx` + `index.scss`：
+
+| uni-app 2.0.0 | Doubao Apps | 说明 |
+|--------------|-------------|------|
+| `page.vue` 的 `<template>` | `index.tsx` TSX 部分 | 模板转 TSX |
+| `page.vue` 的 `<script>` | `index.tsx` 逻辑部分 | Vue2 Options API 转 React / `definePage` |
+| `page.vue` 的 `<style>` | `index.scss` | 样式尽量保留 class 语义 |
+| `pages.json` | 目标工程路由与页面元信息 | 逐项重建，不直接复制 |
+| `App.vue` + `main.js` | `src/app.ts` | 应用生命周期与入口重写 |
+
+> **⚠️ 命名约束**：页面/组件目录下的入口文件必须命名为 **`index.tsx`**，样式文件为 **`index.scss`**。
+
+#### 4.2 单文件转换步骤（每个页面/组件）
+
+1. **入口与配置拆分**：`App.vue` / `main.js` / `pages.json` / 单个 `.vue`
+2. **Vue2 Options API 转换**：`data` / `props` / `computed` / `watch` / `methods`
+3. **页面定义方式**：页面输出为 `definePage({ ... })`，子组件输出为 `FC<Props>`
+4. **页面输入获取**：不要假设存在 uni-app 同名页面参数钩子，优先通过 `getViewData()` / `getViewContext()` 或页面容器注入
+5. **模板转 TSX**：`v-if` / `v-for` / `:prop` / `@tap` / `slot`
+6. **样式转 `index.scss`**：保留 class 语义，动态值才用内联 `style`
+7. **`uni.*` API 替换**：迁到 `@doubao-apps/framework/api`；必须按目标 API 的真实参数签名改写，不能只做同名替换
+8. **条件编译拆分**：`#ifdef` 中的宿主原生代码单独评估
+
+#### 4.3 转换策略（优先级从高到低）
+
+```text
+映射文档 → 官方源文档 / 2.0.0 系列发布记录 → 目标框架文档 → AI 推断 → 询问用户
+```
+
+---
+
+### Step 5: 迁移摘要
+
+```text
+📋 迁移摘要
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+已迁移：22/22 文件
+  └─ 页面：14 个  └─ 组件：8 个
+
+需重建配置：
+  - pages.json tabBar
+  - 页面导航栏标题
+  - 下拉刷新配置
+
+需人工处理：
+  - uni.login × 1 处
+  - #ifdef MP-WEIXIN 内的 wx.chooseAddress × 2 处
+```
+
+---
+
+### Step 6: 质量门禁（Quality Gate）
+
+**⚠️ 必须完成三层质量门禁，迁移才算完成。**
+
+参数：
+
+| 参数 | 值 |
+|------|----|
+| `source_code_path` | uni-app 源项目路径 |
+| `target_code_path` | `$TARGET_PROJECT_PATH` |
+| `source_platform` | `uniapp` |
+| `target_platform` | `doubao` |
+| `framework_rules` | `$SKILLS_BASE/.ai/rules/dos-and-donts.md` |
+
+**根据当前 Agent 环境选择调用方式**：
+
+- **Claude Code**（支持 Skill tool）：
+  ```text
+  Skill(skill="quality-gate", args="source_code_path=<源项目路径> target_code_path=<目标项目路径> source_platform=uniapp target_platform=doubao")
+  ```
+
+- **Codex / 其他 Agent**：
+  读取 `packages/ai/skills/quality-gate/SKILL.md`，按其中流程执行。
+
+---
+
+## uni-app 2.0.0 专项规则
+
+### 1. 只按 Vue2 Options API 迁移
+
+遇到以下写法时，**不要**把它们当作 `uni-app 2.0.0` 的标准能力：
+
+- `<script setup>`
+- Composition API（`setup`, `ref`, `reactive`, `computed()` 等）
+- Vue3 专有语法
+- 后续版本新增的 uni-app API / 组件 / 条件编译能力
+
+如果源项目出现这些写法，先标记为“源项目版本已超出本 skill 范围”。
+
+### 2. `pages.json` 是关键迁移点
+
+uni-app 页面注册、首页、导航栏、下拉刷新、tabBar 都依赖 `pages.json`。迁移时：
+
+- 必须完整扫描 `pages`、`subPackages`、`globalStyle`、`tabBar`
+- 不要只迁 `.vue` 文件而忽略页面配置
+- 不要把 `pages.json` 原样复制到目标工程
+
+### 3. 条件编译不能机械搬运
+
+`#ifdef MP-WEIXIN`、`#ifdef APP-PLUS` 等代码说明源项目包含平台分支：
+
+- 先确认该分支是否是“小程序业务必须逻辑”
+- 再确认目标 Doubao 工程是否存在等价能力
+- 无等价物时必须记录缺口，不得默默删除或假造实现
+
+### 4. uni-app 不等于纯微信小程序
+
+虽然 uni-app `2.0.0` 很多 API / 组件语义接近微信小程序，但它仍有：
+
+- Vue2 单文件组件结构
+- `pages.json` 配置中心
+- `uni.$on / $emit / $off / $once`
+- 条件编译
+- `App.vue` / `main.js` 入口组织方式
+
+因此不要简单套用微信小程序 skill；必须优先使用本 skill 的映射规则。

package/dist/skills/uniapp-to-doubao/assets/migration-checklist-template.md

@@ -0,0 +1,145 @@
+# uni-app 2.0.0 → Doubao Apps 迁移检查清单
+
+> 对每个迁移的页面 / 组件，逐项执行本清单。
+
+---
+
+## 前置准备
+
+- [ ] 确认源项目按 `uni-app 2.0.0` 系列口径处理
+- [ ] 安装 Doubao Apps 知识库：`npx @doubao-apps/ai skills add doubao-apps-dev --agent codex`
+- [ ] 梳理 `App.vue`、`main.js`、`pages.json`、`manifest.json`
+- [ ] 梳理所有 `.vue` 页面与组件
+- [ ] 识别所有 `uni.*` API
+- [ ] 识别所有条件编译块（`#ifdef` / `#ifndef`）
+- [ ] 识别所有平台原生 API 穿透（`wx.*` / `tt.*` / `my.*` / `swan.*`）
+
+---
+
+## 依赖与入口处理
+
+- [ ] 移除 Vue / uni-app 运行时依赖
+- [ ] 添加 `@doubao-apps/framework`
+- [ ] `main.js` 入口迁到 `src/app.ts`
+- [ ] `App.vue` 生命周期迁到 `defineApp`
+- [ ] `pages.json` 配置逐项重建
+
+---
+
+## 逐文件迁移清单
+
+对每个 `.vue` 文件，执行以下步骤：
+
+### 1. 文件拆分
+
+- [ ] `<template>` → `index.tsx`
+- [ ] `<script>` → `index.tsx`
+- [ ] `<style>` → `index.scss`
+- [ ] 添加 `import './index.scss'`
+
+### 2. 页面 / 组件定义转换
+
+- [ ] 页面 `.vue` → `definePage({ ..., render() { return <PageView /> } })`
+- [ ] 组件 `.vue` → `FC<Props>`
+- [ ] `App.vue` → `defineApp({...})`
+
+### 3. Vue2 Options API 转换
+
+- [ ] `data()` → `useState`
+- [ ] `computed` → `useMemo`
+- [ ] `watch` → `useEffect`
+- [ ] `methods` → 普通函数
+- [ ] `props` → `interface Props`
+- [ ] `this.$emit(...)` → `props.onXxx?.(...)`
+
+### 4. 生命周期转换
+
+- [ ] `onLoad(options)` → `getViewData()` + `onMounted` / `useEffect`
+- [ ] `onShow / onHide` → 目标页面生命周期
+- [ ] `onReady` → `onMounted` / `useEffect`
+- [ ] `onUnload` → `onDestroy`
+- [ ] `App.vue onShow / onHide` → `onForeground / onBackground`
+
+### 5. 模板转 TSX
+
+- [ ] `{{ expression }}` → `{expression}`
+- [ ] `v-if / v-else-if / v-else` → 条件表达式
+- [ ] `v-for` → `.map(...)`
+- [ ] `:prop="expr"` → `prop={expr}`
+- [ ] `@tap` / `@click` → `onClick`
+- [ ] `v-model` → 受控组件
+- [ ] `<template>` / `<block>` → Fragment 或移除
+- [ ] 直接文本内容统一包裹 `<text>`
+
+### 6. 样式迁移
+
+- [ ] `<style>` 内容迁到 `index.scss`
+- [ ] `class="xxx"` → `className="xxx"`
+- [ ] 动态 class → 字符串拼接 / 条件 class
+- [ ] 只有动态值才使用 `style={{}}`
+- [ ] `scoped` 样式改成局部 class 组织
+
+### 7. `uni.*` API 替换
+
+- [ ] `uni.request(...)` → `request(...)`
+- [ ] `uni.navigateTo / redirectTo / navigateBack / reLaunch` → 改写为对应路由 API
+- [ ] `uni.switchTab` → 重建 tab 导航能力或记录缺口，不假设存在同名 API
+- [ ] `uni.showToast({ title })` → `showToast({ message })`
+- [ ] `uni.showLoading / hideLoading / showModal` → 改为页面内交互方案或记录缺口
+- [ ] `uni.setStorageSync / getStorageSync / removeStorageSync` → 改为对象参数签名
+- [ ] `uni.$on / $emit / $off / $once` → 显式 props / 状态提升 / 容器协调
+
+### 8. 配置与宿主能力
+
+- [ ] 重建 `pages.json -> pages`
+- [ ] 评估 `pages.json -> globalStyle`
+- [ ] 重建 `pages.json -> tabBar` 或记录缺口
+- [ ] 重写 `enablePullDownRefresh` 或记录缺口
+- [ ] 将 `navigationBarTitleText` 转到目标页面元信息
+- [ ] 逐项处理条件编译块
+
+### 9. 组件专项处理
+
+- [ ] 将 `scroll-view` 的滚动事件改写到目标事件模型
+- [ ] `swiper / swiper-item` 优先保留小写标签
+- [ ] `navigator` → 改成显式路由 API
+- [ ] `picker` 按 `mode` 分流处理，而不是统一按单列弹层重写
+- [ ] 确认 `editor` 是否存在目标等价能力
+
+---
+
+## 验证步骤
+
+- [ ] TypeScript 编译无报错：`npx tsc --noEmit`
+- [ ] 构建成功：`pnpm run build`
+- [ ] 页面可正常渲染
+- [ ] 事件触发正常
+- [ ] 状态更新正常
+- [ ] 网络请求正常
+- [ ] 路由跳转正常
+- [ ] 样式结构正确
+- [ ] `pages.json` 相关页面能力已核对
+
+---
+
+## 能力缺口记录
+
+| 功能 | 原因 | 处理状态 |
+|------|------|---------|
+| | | |
+
+---
+
+## 迁移报告模板
+
+```text
+迁移完成时间：YYYY-MM-DD
+迁移文件数量：____ 个（页面 ____ + 组件 ____）
+完成率：____/____（____%）
+
+未完成项：
+  - [文件] [原因]
+
+能力缺口：
+  - [能力名称] × [调用次数]：[处理建议]
+```

package/dist/skills/uniapp-to-doubao/references/mapping/component-mapping.md

@@ -0,0 +1,157 @@
+# Component Mapping
+
+> **Mapping Version**: 1.0.0
+> **Source Framework**: uni-app `2.0.0`
+> **Target Framework**: Doubao Apps (React Lynx)
+> **Last Updated**: 2026-04-09
+
+## 当前项目组件现状
+
+基于 `packages/components/src`、`packages/framework/jsx-runtime.d.ts` 与 `packages/kit/src/builder/loader/components-loader/index.ts`，当前工程已支持以下小写标签直接写入 TSX：
+
+- 基础标签：`<view>`、`<text>`、`<image>`、`<input>`、`<textarea>`、`<scroll-view>`、`<list>`、`<list-item>`、`<svg>`
+- 扩展标签：`<button>`、`<switch>`、`<slider>`、`<swiper>`、`<swiper-item>`、`<map>`、`<map-marker>`、`<movable-area>`、`<movable-view>`、`<popup>`、`<radio>`、`<radio-group>`、`<picker-view>`、`<picker-column>`、`<web-view>`
+
+迁移 uni-app 时，能保留这些小写标签就优先保留；需要显式 ref、类型或更高层封装时，再使用命名导入。
+
+- 大部分标签会由 loader 自动补 `@doubao-apps/framework/components` 导入
+- `list-item` 当前主要由 JSX intrinsic / Lynx 原生标签能力提供，不要假设 loader 会自动补组件 import
+
+---
+
+## 文件结构转换
+
+uni-app 页面 / 组件通常是单个 `.vue` 文件，迁移后统一收敛为 `index.tsx` + `index.scss`：
+
+| uni-app 2.0.0 | Doubao Apps | 内容 |
+|--------------|-------------|------|
+| `<template>` | `index.tsx` | 模板结构 |
+| `<script>` | `index.tsx` | 逻辑 |
+| `<style>` | `index.scss` | 样式 |
+
+---
+
+## 模板语法映射
+
+| uni-app 2.0.0 | Doubao Apps | 说明 |
+|--------------|-------------|------|
+| `{{ expr }}` | `{expr}` | 文本插值 |
+| `v-if="cond"` | `{cond && ...}` | 条件渲染 |
+| `v-else-if` / `v-else` | 三元表达式 | 条件分支 |
+| `v-for="item in list"` | `list.map(...)` | 列表渲染 |
+| `:key="item.id"` | `key={item.id}` | 列表键 |
+| `:prop="expr"` | `prop={expr}` | 动态属性 |
+| `@tap="handleTap"` | `onClick={handleTap}` | 事件绑定 |
+| `<template>` / `<block>` | `<>...</>` | 结构块 |
+
+### 示例
+
+```tsx
+// Before (uni-app 2.0.0)
+<view class="list">
+  <view v-for="item in list" :key="item.id" class="item" @tap="handleTap(item)">
+    <text>{{ item.title }}</text>
+  </view>
+</view>
+
+// After (Doubao Apps)
+<view className="list">
+  {list.map((item) => (
+    <view key={item.id} className="item" onClick={() => handleTap(item)}>
+      <text>{item.title}</text>
+    </view>
+  ))}
+</view>
+```
+
+---
+
+## 页面容器
+
+| uni-app 2.0.0 | Doubao Apps | 说明 |
+|--------------|-------------|------|
+| `<view>` | `<view>` | 通用容器 |
+| `<scroll-view scroll-y>` | `<scroll-view>` | 垂直滚动容器 |
+| `<scroll-view scroll-x>` | `<scroll-view>` | 水平滚动容器，属性按目标组件改写 |
+| `<swiper>` / `<swiper-item>` | `<swiper>` / `<swiper-item>` | 优先保留 |
+
+---
+
+## 文本与媒体
+
+| uni-app 2.0.0 | Doubao Apps | 说明 |
+|--------------|-------------|------|
+| `<text>` | `<text>` | 文本组件 |
+| 直接文本节点 | `<text>` 包裹 | 统一文本容器语义 |
+| `<image>` | `<image>` | 图片组件 |
+| `<video>` | `<video>` 或等价组件 | 纯播放可迁 |
+| `<web-view>` | `<web-view>` | 需补宿主校验 |
+| `<editor>` | 需专项确认 | `2.0.0` 新增，不能默认可迁 |
+
+---
+
+## 表单组件
+
+| uni-app 2.0.0 | Doubao Apps | 说明 |
+|--------------|-------------|------|
+| `<button>` | `<button>` | 直接保留 |
+| `<input>` | `<input>` | 受控写法 |
+| `<textarea>` | `<textarea>` | 受控写法 |
+| `<switch>` | `<switch>` | 布尔回调 |
+| `<slider>` | `<slider>` | 数值回调 |
+| `<picker mode="selector">` | `<popup>` + `<picker-view>` / `<picker-column>`，或宿主等价选择器 | 普通单列选择可这样重写 |
+| `<picker mode="multiSelector">` | `<popup>` + 多列 `<picker-column>` | 需要按列重建 |
+| `<picker mode="time" / "date" / "region">` | 优先查目标宿主是否有等价能力；无则记录缺口或以业务可接受方式重构 | 不要一律降级成普通滚轮选择器 |
+| `<picker-view>` | `<picker-view>` + `<picker-column>` | 优先保留 |
+| `<radio-group>` | `<radio-group>` + `<radio>` | 优先保留 |
+
+---
+
+## 导航组件
+
+| uni-app 2.0.0 | Doubao Apps | 说明 |
+|--------------|-------------|------|
+| `<navigator :url="...">` | `onClick={() => navigateTo({ url })}` | 显式路由 |
+
+```tsx
+// Before
+<navigator :url="`/pages/detail/index?id=${item.id}`">
+  <view class="link">查看详情</view>
+</navigator>
+
+// After
+import { navigateTo } from '@doubao-apps/framework/api';
+
+<view className="link" onClick={() => navigateTo({ url: `/pages/detail/index?id=${item.id}` })}>
+  <text>查看详情</text>
+</view>
+```
+
+---
+
+## `v-model` 规则
+
+`v-model` 不应机械迁移。统一改成受控组件：
+
+```tsx
+// Before
+<input v-model="keyword" />
+
+// After
+<input
+  value={keyword}
+  onInput={(e) => setKeyword(e.detail.value)}
+/>
+```
+
+---
+
+## 条件编译里的组件
+
+以下组件若出现在条件编译块中，不要直接平移：
+
+- 平台原生组件
+- 只在某个小程序宿主存在的开放组件
+- 依赖平台审核能力、登录态、订阅消息或分享链路的组件
+
+这些应在迁移计划中单列。