@doubao-apps/ai 0.0.20 → 0.0.23

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

@@ -0,0 +1,208 @@
+# Core API Mapping
+
+> **Mapping Version**: 1.0.0
+> **Source Framework**: uni-app `2.0.0` (Vue2 Options API)
+> **Target Framework**: Doubao Apps (React Lynx)
+> **Last Updated**: 2026-04-09
+
+## 官方事实依据
+
+- uni-app `2.0.0` 系列历史归档: `https://uniapp.dcloud.net.cn/release-archive.html`
+- 页面与生命周期: `https://uniapp.dcloud.io/tutorial/page.html`
+- `uni.request`: `https://uniapp.dcloud.io/api/request/request.html`
+
+---
+
+## Vue2 状态管理
+
+| uni-app 2.0.0 | Doubao Apps | 说明 |
+|--------------|-------------|------|
+| `data() { return { foo: 1 } }` | `const [foo, setFoo] = useState(1)` | 本地状态 |
+| `this.foo = val` / `this.list = [...]` | `setFoo(val)` / `setList(...)` | 响应式更新 |
+| `this.someMethod()` | 组件内普通函数 | 方法定义 |
+
+### 示例
+
+```tsx
+// Before (uni-app 2.0.0)
+export default {
+  data() {
+    return {
+      count: 0,
+      keyword: ''
+    };
+  },
+  methods: {
+    increment() {
+      this.count += 1;
+    }
+  }
+}
+
+// After (Doubao Apps)
+import { definePage, useState } from '@doubao-apps/framework';
+
+function PageView() {
+  const [count, setCount] = useState(0);
+  const [keyword, setKeyword] = useState('');
+
+  const increment = () => setCount((prev) => prev + 1);
+
+  return <view />;
+}
+
+export default definePage({
+  render() {
+    return <PageView />;
+  }
+});
+```
+
+---
+
+## `computed`
+
+| uni-app 2.0.0 | Doubao Apps | 说明 |
+|--------------|-------------|------|
+| `computed: { doubled() { return this.count * 2; } }` | `useMemo(() => count * 2, [count])` | 派生状态 |
+
+---
+
+## `watch`
+
+| uni-app 2.0.0 | Doubao Apps | 说明 |
+|--------------|-------------|------|
+| `watch: { keyword(val) { ... } }` | `useEffect(() => { ... }, [keyword])` | 监听状态变化 |
+
+---
+
+## `props`
+
+| uni-app 2.0.0 | Doubao Apps | 说明 |
+|--------------|-------------|------|
+| `props: { title: String }` | `interface Props { title?: string }` | 属性声明 |
+| `this.title` | `props.title` | 访问方式 |
+
+---
+
+## 页面 / 组件 / 应用定义
+
+| uni-app 2.0.0 | Doubao Apps | 说明 |
+|--------------|-------------|------|
+| 页面 `.vue` | `definePage({ render })` | 页面入口 |
+| 组件 `.vue` | `FC<Props>` | 普通组件 |
+| `App.vue` + `main.js` | `app.ts` + `defineApp({ ... })` | 应用入口 |
+
+### 页面输入
+
+| uni-app 2.0.0 | Doubao Apps | 说明 |
+|--------------|-------------|------|
+| `onLoad(options)` 获取页面参数 | `getViewData()` / `getViewContext()` | 不要假设存在同名 `onLoad` 参数钩子 |
+
+---
+
+## `uni.*` API 映射
+
+### 网络
+
+| uni-app 2.0.0 | Doubao Apps | 说明 |
+|--------------|-------------|------|
+| `uni.request({ ... })` | `request({ ... })` | Promise 化网络请求 |
+
+```tsx
+// Before
+uni.request({
+  url: '/api/list',
+  data: { page: 1 },
+  success: (res) => {
+    this.list = res.data.list;
+  }
+});
+
+// After
+import { request } from '@doubao-apps/framework/api';
+
+const res = await request({
+  url: '/api/list',
+  data: { page: 1 }
+});
+setList(res.data.list);
+```
+
+### 导航
+
+| uni-app 2.0.0 | Doubao Apps | 说明 |
+|--------------|-------------|------|
+| `uni.navigateTo({ url })` | `navigateTo({ url })` | 页面跳转 |
+| `uni.redirectTo({ url })` | `redirectTo({ url })` | 替换当前页 |
+| `uni.navigateBack({ delta })` | `navigateBack({ delta })` | 返回 |
+| `uni.reLaunch({ url })` | `reLaunch({ url })` | 重启路由栈 |
+| `uni.switchTab({ url })` | 无已确认公共同名 API | 目标工程需重建 tab 导航能力或记录缺口，不能假设存在 `switchTab` |
+
+### UI 交互
+
+| uni-app 2.0.0 | Doubao Apps | 说明 |
+|--------------|-------------|------|
+| `uni.showToast({ title, icon })` | `showToast({ message, icon, type })` | 参数名不同，必须改写 |
+| `uni.showLoading(...)` | 无已确认公共同名 API | 目标侧改为页面内 loading 状态 / 自定义蒙层，或记录缺口 |
+| `uni.hideLoading()` | 无已确认公共同名 API | 与 `showLoading` 配套重写 |
+| `uni.showModal(...)` | 无已确认公共同名 API | 优先用页面内 `Dialog` / `Popup` 组件流重写，不做同名替换 |
+
+### 存储
+
+| uni-app 2.0.0 | Doubao Apps | 说明 |
+|--------------|-------------|------|
+| `uni.setStorageSync(key, data)` | `setStorageSync({ key, data })` | 参数形态不同 |
+| `uni.getStorageSync(key)` | `getStorageSync({ key })` | 返回值需读 `.data` |
+| `uni.removeStorageSync(key)` | `removeStorageSync({ key })` | 参数形态不同 |
+
+### 参数改写示例
+
+```tsx
+// Before
+uni.showToast({ title: '保存成功', icon: 'success' });
+uni.setStorageSync('token', token);
+const token = uni.getStorageSync('token');
+
+// After
+import { getStorageSync, setStorageSync, showToast } from '@doubao-apps/framework/api';
+
+await showToast({
+  message: '保存成功',
+  icon: 'success',
+  type: 'success'
+});
+
+setStorageSync({
+  key: 'token',
+  data: token
+});
+
+const storedToken = getStorageSync<string>({
+  key: 'token'
+}).data;
+```
+
+---
+
+## 页面通信
+
+`2.0.0` 系列发布记录中可确认 `uni.$on / $once / $off / $emit` 已进入该大版本范围。
+
+| uni-app 2.0.0 | Doubao Apps | 说明 |
+|--------------|-------------|------|
+| `uni.$emit('refresh', payload)` | 显式 props / 页面输入 / 状态提升 | 优先去事件总线化 |
+| `uni.$on('refresh', handler)` | 目标侧订阅能力或上层容器协调 | 避免全局事件散落 |
+
+---
+
+## 不要机械迁移的能力
+
+- `uni.login`
+- 条件编译中的原生 `wx.*` / `tt.*` / `my.*`
+- `pages.json` 的 tabBar / 原生导航栏 / 下拉刷新配置
+- `uni.switchTab`
+- `uni.showLoading` / `uni.hideLoading` / `uni.showModal`
+- `editor` 组件（需先确认目标等价物）
+
+这些能力需要单列处理，不属于“同名 API 替换”。

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

@@ -0,0 +1,133 @@
+# Event Mapping
+
+> **Mapping Version**: 1.0.0
+> **Source Framework**: uni-app `2.0.0`
+> **Target Framework**: Doubao Apps (React Lynx)
+> **Last Updated**: 2026-04-09
+
+## 最关键的迁移差异
+
+| 特性 | uni-app 2.0.0 | Doubao Apps |
+|------|---------------|-------------|
+| 事件绑定 | Vue 模板语法 `@tap="handleTap"` | 函数引用 `onClick={handleTap}` |
+| 参数传递 | `@tap="handleTap(item)"` | `onClick={() => handleTap(item)}` |
+| `v-model` | 双向绑定语法糖 | 显式 `value + onInput/onChange` |
+
+---
+
+## 点击 / 触摸事件
+
+| uni-app 2.0.0 | Doubao Apps | 说明 |
+|--------------|-------------|------|
+| `@tap="handleTap"` | `onClick={handleTap}` | 常见点击 |
+| `@click="handleClick"` | `onClick={handleClick}` | Web 风格点击 |
+| `@longpress="handleLongPress"` | `onLongPress={handleLongPress}` | 长按 |
+
+### 示例
+
+```tsx
+// Before
+<view class="card" @tap="handleTap(item)">
+  <text>{{ item.title }}</text>
+</view>
+
+// After
+<view className="card" onClick={() => handleTap(item)}>
+  <text>{item.title}</text>
+</view>
+```
+
+---
+
+## 表单事件
+
+| uni-app 2.0.0 | Doubao Apps | 说明 |
+|--------------|-------------|------|
+| `@input="handleInput"` | `onInput={handleInput}` | 输入 |
+| `@change="handleChange"` | `onChange={handleChange}` 或按组件实际签名处理 | 变更 |
+| `@confirm="handleConfirm"` | `onConfirm={handleConfirm}` | 键盘确认 |
+| `v-model="keyword"` | `value={keyword}` + `onInput` | 受控改写 |
+
+### 示例
+
+```tsx
+// Before
+<input v-model="keyword" @confirm="handleSearch" />
+
+// After
+<input
+  value={keyword}
+  onInput={(e) => setKeyword(e.detail.value)}
+  onConfirm={handleSearch}
+/>
+```
+
+---
+
+## 滚动事件
+
+| uni-app 2.0.0 | Doubao Apps | 说明 |
+|--------------|-------------|------|
+| `@scroll="handleScroll"` | `onScroll={handleScroll}` | 滚动中 |
+| `@scrolltoupper="handleTop"` | `onScrollToUpper={handleTop}` | 滚动到顶部 |
+| `@scrolltolower="loadMore"` | `onScrollToLower={loadMore}` | 滚动到底部 |
+
+---
+
+## 自定义事件 / `$emit`
+
+Vue2 组件内常见：
+
+```js
+this.$emit('change', value);
+```
+
+**迁移**：
+
+| uni-app 2.0.0 | Doubao Apps | 说明 |
+|--------------|-------------|------|
+| `this.$emit('change', value)` | `props.onChange?.(value)` | 显式回调 props |
+
+---
+
+## 事件对象
+
+uni-app 事件处理器通常接收 `event`：
+
+```js
+methods: {
+  handleInput(e) {
+    const value = e.detail.value;
+  }
+}
+```
+
+迁移后仍可保留相似的 `e.detail` 读取方式，但要按目标组件真实签名校对：
+
+- `input` 常见为 `e.detail.value`
+- `switch` / `slider` 可能直接回调值
+- 不要假设所有组件都传统一事件对象
+
+---
+
+## dataset 改写
+
+源端常见：
+
+```vue
+<view :data-id="item.id" @tap="handleTap"></view>
+```
+
+```js
+handleTap(e) {
+  const id = e.currentTarget.dataset.id;
+}
+```
+
+迁移建议：
+
+```tsx
+<view onClick={() => handleTap(item.id)}></view>
+```
+
+优先改为闭包传值，而不是继续依赖 dataset。

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

@@ -0,0 +1,152 @@
+# Lifecycle 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/framework/src/define-api/types.ts`
+- `packages/framework/src/define-api/define-app.ts`
+- `packages/framework/src/define-api/define-page.ts`
+
+当前可确认的目标页面生命周期：
+
+- `onCreated`
+- `onMounted`
+- `onShow`
+- `onHide`
+- `onDestroy`
+- `onError`
+
+当前可确认的目标应用生命周期：
+
+- `onLaunch`
+- `onPageOpened`
+- `onForeground`
+- `onBackground`
+- `onDestroy`
+- `onError`
+
+---
+
+## 页面生命周期
+
+| uni-app 2.0.0 | Doubao Apps | 迁移建议 |
+|--------------|-------------|----------|
+| `onLoad(options)` | 无同名参数钩子 | 页面输入通过 `getViewData()` / `getViewContext()` 获取；初始化逻辑放 `onMounted` 或 `useEffect` |
+| `onShow()` | `onShow()` | 页面显示 |
+| `onReady()` | `onMounted()` 或 `useEffect(() => {}, [])` | 首次渲染完成 |
+| `onHide()` | `onHide()` | 页面隐藏 |
+| `onUnload()` | `onDestroy()` | 页面销毁 |
+| `onPullDownRefresh()` | 无直接同名钩子 | 结合页面容器 / 刷新组件重写 |
+| `onReachBottom()` | 无直接同名钩子 | 结合 `scroll-view` 触底事件重写 |
+| `onPageScroll(e)` | 无直接同名钩子 | 结合滚动容器事件重写 |
+
+### 示例
+
+```tsx
+// Before (uni-app 2.0.0)
+export default {
+  onLoad(options) {
+    this.id = options.id;
+    this.fetchDetail();
+  },
+  onShow() {
+    console.log('show');
+  },
+  onUnload() {
+    clearInterval(this.timer);
+  },
+  methods: {
+    fetchDetail() {}
+  }
+}
+
+// After (Doubao Apps)
+import { definePage, getViewData, useEffect } from '@doubao-apps/framework';
+
+function DetailPage() {
+  const input = getViewData() as { id?: string } | undefined;
+
+  useEffect(() => {
+    if (!input?.id) {
+      return;
+    }
+    // fetchDetail(input.id)
+  }, [input?.id]);
+
+  return <view />;
+}
+
+export default definePage({
+  onShow() {
+    console.log('show');
+  },
+  onDestroy() {
+    // clearInterval(...)
+  },
+  render() {
+    return <DetailPage />;
+  }
+});
+```
+
+---
+
+## 组件生命周期
+
+uni-app 组件本质上是 Vue2 组件生命周期：
+
+| uni-app 2.0.0 | Doubao Apps | 说明 |
+|--------------|-------------|------|
+| `beforeCreate` | - | 一般无需保留 |
+| `created` | `onCreated` 或组件初始化阶段 | 轻量初始化 |
+| `mounted` | `useEffect(() => {}, [])` / `onMounted` | 挂载后 |
+| `beforeDestroy` / `destroyed` | `useEffect(() => () => {}, [])` | 卸载清理 |
+
+---
+
+## 应用生命周期
+
+| uni-app 2.0.0 (`App.vue`) | Doubao Apps (`defineApp`) | 说明 |
+|--------------------------|---------------------------|------|
+| `onLaunch()` | `onLaunch()` | 冷启动 |
+| `onShow()` | `onForeground()` | 进入前台 |
+| `onHide()` | `onBackground()` | 进入后台 |
+| `onError(err)` | `onError(err)` | 错误处理 |
+
+### 示例
+
+```ts
+// After (Doubao Apps)
+import { defineApp } from '@doubao-apps/framework';
+
+export default defineApp({
+  aiMeta: {
+    id: 'app',
+    name: 'uniapp-migrated-app'
+  },
+  onLaunch() {
+    console.log('app launched');
+  },
+  onForeground() {
+    console.log('app foreground');
+  },
+  onBackground() {
+    console.log('app background');
+  }
+});
+```
+
+---
+
+## 迁移规则
+
+1. 不要把 uni-app 页面生命周期机械复制为目标框架同名钩子。
+2. 页面参数读取优先改为 `getViewData()`，不要依赖 `onLoad(options)` 形态继续存在。
+3. 页面滚动、触底、下拉刷新等能力通常要结合容器级重写。
+4. `App.vue` 的 `onShow/onHide` 应改为目标应用的前后台生命周期，而不是继续保留原名。

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

@@ -0,0 +1,139 @@
+# Style Mapping
+
+> **Mapping Version**: 1.0.0
+> **Source Framework**: uni-app `2.0.0`
+> **Target Framework**: Doubao Apps (React Lynx)
+> **Last Updated**: 2026-04-09
+
+## 样式系统差异总览
+
+| 特性 | uni-app 2.0.0 | Doubao Apps |
+|------|---------------|-------------|
+| 样式位置 | `.vue` 内 `<style>` | 同目录 `index.scss` |
+| 类名属性 | `class="xxx"` | `className="xxx"` |
+| 内联样式 | `:style="..."` / `style="..."` | `style={{...}}` 或收敛到 `index.scss` |
+| 常见单位 | `rpx`, `px`, `%` | 保留原有语义并按目标样式能力校对 |
+| scoped 样式 | `scoped` attribute | 用局部 class 组织代替自动 scope 注入 |
+
+---
+
+## 基本规则
+
+### 文件与导入
+
+```tsx
+import './index.scss';
+```
+
+### 类名迁移
+
+```tsx
+// Before
+<view class="card active"></view>
+
+// After
+<view className="card active"></view>
+```
+
+### 内联样式迁移
+
+```tsx
+// Before
+<view :style="{ padding: padding + 'rpx' }"></view>
+
+// After
+<view style={{ padding: `${padding}rpx` }}></view>
+```
+
+**优先级**：
+
+1. 静态样式放 `index.scss`
+2. 只有动态值才放 `style={{}}`
+
+---
+
+## `<style>` → `index.scss`
+
+### 示例
+
+```vue
+<!-- Before -->
+<style scoped lang="scss">
+.page {
+  padding: 24rpx;
+}
+
+.card {
+  background: #fff;
+  border-radius: 16rpx;
+}
+</style>
+```
+
+```scss
+/* After (index.scss) */
+.page {
+  padding: 24rpx;
+}
+
+.card {
+  background: #fff;
+  border-radius: 16rpx;
+}
+```
+
+---
+
+## 动态 class
+
+```tsx
+// Before
+<view :class="['item', { 'item--active': active }]"></view>
+
+// After
+<view className={active ? 'item item--active' : 'item'}></view>
+```
+
+---
+
+## `scoped` 样式
+
+uni-app `scoped` 依赖编译器自动加作用域标记。迁移到 Doubao 时：
+
+- 通过更稳定的局部 class 命名保持样式隔离
+- 避免依赖深层级或编译器生成的 attribute 选择器
+- 若源样式大量依赖 `scoped` 深穿透，需手工整理
+
+---
+
+## 常见单位处理
+
+- `rpx`：优先原样保留
+- `px`：原样保留并在视觉验证时校准
+- `%`：原样保留
+- 视口单位、复杂 `calc()`：按目标样式能力逐项核对
+
+---
+
+## 全局样式与 `pages.json`
+
+uni-app 项目常有：
+
+- `App.vue` 全局样式
+- `uni.scss`
+- `pages.json -> globalStyle`
+
+迁移建议：
+
+- 页面局部样式放各自 `index.scss`
+- 全局基础样式放目标工程可控的全局入口
+- `pages.json` 的视觉配置（导航栏、背景色、下拉刷新）按目标工程重建，不要当普通 CSS 复制
+
+---
+
+## 样式迁移禁忌
+
+- 不要把所有 `<style>` 内容硬改成超长内联对象
+- 不要丢失 class 语义
+- 不要默认 `scoped` 深层选择器在目标侧还能成立
+- 不要无脑改写 `rpx` 单位