@doubao-apps/ai 0.0.19 → 0.0.20

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

@@ -0,0 +1,200 @@
+# Component Mapping
+
+> **Mapping Version**: 1.1.0
+> **Source Framework**: 抖音小程序 (Douyin Mini Program)
+> **Target Framework**: Doubao Apps (React Lynx)
+> **Last Updated**: 2026-04-02
+
+## 官方事实依据
+
+- 组件概述: `https://developer.open-douyin.com/docs/resource/zh-CN/mini-app/develop/component/overview/`
+- TTML 数据绑定: `https://developer.open-douyin.com/docs/resource/zh-CN/mini-app/develop/tutorial/miniapp-framework/view/ttml-data-bind`
+- TTML 列表渲染: `https://developer.open-douyin.com/docs/resource/zh-CN/mini-app/develop/tutorial/miniapp-framework/view/ttml-list-draw`
+- `Component()` 构造器: `https://developer.open-douyin.com/docs/resource/zh-CN/mini-app/develop/tutorial/custom-component/component-constructor`
+
+---
+
+## 当前项目组件现状
+
+基于 `packages/components/src` 与 `packages/kit/src/builder/loader/components-loader/index.ts`，当前工程已支持以下小写标签直接写入 TSX，并由 loader 自动从 `@doubao-apps/framework/components` 注入组件 import：
+
+- 基础标签：`<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>`
+
+迁移抖音小程序时，能保留这些小写标签就优先保留；需要显式 ref、类型或更高层封装时，再使用命名导入。
+
+---
+
+## 文件结构转换
+
+抖音小程序页面/组件通常由 4 个文件组成，迁移后统一收敛为 `index.tsx` + `index.scss`：
+
+| 抖音小程序 | Doubao Apps | 内容 |
+|-----------|-------------|------|
+| `page.ttml` | `index.tsx` | 模板结构 |
+| `page.ttss` | `index.scss` | 样式 |
+| `page.js` / `page.ts` | `index.tsx` | 页面逻辑 |
+| `page.json` | 合并到工程配置 | 页面/组件配置 |
+
+---
+
+## TTML 指令映射
+
+| 抖音小程序 | Doubao Apps | 说明 |
+|-----------|-------------|------|
+| `{{expr}}` | `{expr}` | 表达式输出 |
+| `tt:if="{{cond}}"` | `{cond && ...}` 或三元 | 条件渲染 |
+| `tt:for="{{list}}"` | `{list.map(...)}` | 列表渲染 |
+| `tt:key="id"` | `key={item.id}` | 唯一键 |
+| `<block>` | `<>...</>` | 结构块 |
+
+### TTML 转 TSX 示例
+
+```tsx
+// Before (抖音小程序)
+<view class="list">
+  <block tt:for="{{items}}" tt:key="id">
+    <view class="item" bind:tap="handleTap" data-id="{{item.id}}">
+      <text>{{item.title}}</text>
+    </view>
+  </block>
+</view>
+
+// After (Doubao Apps)
+<view className="list">
+  {items.map((item) => (
+    <view key={item.id} className="item" onClick={() => handleTap(item.id)}>
+      <text>{item.title}</text>
+    </view>
+  ))}
+</view>
+```
+
+---
+
+## 页面参数与 `Component()` 页面
+
+官方 `Component()` 构造器文档说明，页面也可以通过 `Component()` 构造，并让 `properties` 接收页面参数。
+
+**迁移规则**：
+
+- 发现页面使用 `Component({ properties: { id: String } })` 时，仍归类为页面
+- 不要假设 `definePage.render(query)` 这类参数签名存在；当前仓库优先通过 `getViewData()/getViewContext()` 或页面容器显式注入页面输入
+- 不保留“页面像组件一样靠 properties 接参”的模式
+
+---
+
+## 布局容器
+
+| 抖音小程序 | Doubao Apps | 说明 |
+|-----------|-------------|------|
+| `<view>` | `<view>` | 通用容器 |
+| `<block>` | `<>` 或移除 | 不渲染实体节点 |
+| `<scroll-view scroll-y>` | `<scroll-view scrollOrientation="vertical">` | 垂直滚动 |
+| `<scroll-view scroll-x>` | `<scroll-view scrollOrientation="horizontal">` | 水平滚动 |
+| `<movable-area>` / `<movable-view>` | `<movable-area>` / `<movable-view>` | 当前项目已有对应组件，优先保留拖拽语义；复杂缩放细节需逐项校对 |
+
+---
+
+## 文本
+
+| 抖音小程序 | Doubao Apps | 说明 |
+|-----------|-------------|------|
+| `<text>` | `<text>` | 文本组件 |
+| 直接文本节点 | `<text>` 包裹 | 统一文本容器语义 |
+
+```tsx
+// Before
+<view>{{title}}</view>
+
+// After
+<view>
+  <text>{title}</text>
+</view>
+```
+
+---
+
+## 媒体
+
+| 抖音小程序 | Doubao Apps | 说明 |
+|-----------|-------------|------|
+| `<image src mode>` | `<image src mode>` | 图片组件 |
+| `<video src>` | `<video src>` 或对应组件 | 纯播放可迁移 |
+| `<camera>` | 需专项适配 | 宿主能力相关 |
+
+---
+
+## 视图与列表
+
+### `scroll-view`
+
+```tsx
+// Before
+<scroll-view scroll-y style="height: 400rpx;" bindscrolltolower="loadMore">
+  <view tt:for="{{list}}" tt:key="id">{{item.name}}</view>
+</scroll-view>
+
+// After
+<scroll-view className="feed-scroll" scrollOrientation="vertical" onScrollToLower={loadMore}>
+  {list.map((item) => (
+    <view key={item.id} className="feed-item">
+      <text>{item.name}</text>
+    </view>
+  ))}
+</scroll-view>
+```
+
+### `swiper`
+
+源端 `swiper` / `swiper-item` 优先保留为小写 `<swiper>` / `<swiper-item>` 标签。当前项目已支持这些标签，并会自动注入 import；不要手写低质量横向滚动替代。
+
+---
+
+## 表单组件
+
+| 抖音小程序 | Doubao Apps | 说明 |
+|-----------|-------------|------|
+| `<button>` | `<button>` | 普通点击可直迁，保留小写标签即可 |
+| `<input>` | `<input>` | 输入框 |
+| `<textarea>` | `<textarea>` | 多行输入 |
+| `<switch>` | `<switch>` | 回调改为 `checked` |
+| `<slider>` | `<slider>` | 回调改为数值 |
+| `<picker>` | `<popup>` + `<picker-view>` / `<picker-column>` | 按需重写弹出式选择器 |
+| `<picker-view>` | `<picker-view>` + `<picker-column>` | 当前项目已有滚动选择器 |
+| `<checkbox-group>` | 受控多选组件 | 当前项目暂无现成组件，按需重写 |
+| `<radio-group>` | `<radio-group>` + `<radio>` | 当前项目已有单选组件，优先直接映射 |
+
+---
+
+## 导航组件
+
+| 抖音小程序 | 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>
+```
+
+---
+
+## 平台强绑定组件能力
+
+以下场景不要做“同名替换”：
+
+- `button open-type="share"`
+- 依赖抖音视频发布链路的组件
+- 依赖直播挂载或直播预览流的组件
+
+这类能力要在迁移计划里单列处理。

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

@@ -0,0 +1,231 @@
+# Core API Mapping
+
+> **Mapping Version**: 1.0.0
+> **Source Framework**: 抖音小程序 (Douyin Mini Program)
+> **Target Framework**: Doubao Apps (React Lynx)
+> **Last Updated**: 2026-04-01
+
+## 官方事实依据
+
+- 框架概述: `https://developer.open-douyin.com/docs/resource/zh-CN/mini-app/develop/tutorial/miniapp-framework/introduction`
+- `Component()` 构造器: `https://developer.open-douyin.com/docs/resource/zh-CN/mini-app/develop/tutorial/custom-component/component-constructor`
+- 网络连接 / `tt.request`: `https://developer.open-douyin.com/docs/resource/zh-CN/mini-app/develop/tutorial/basic-ability/net-connection`
+- `tt.login`: `https://developer.open-douyin.com/docs/resource/zh-CN/mini-app/develop/api/open-interface/log-in/tt-login`
+- `tt.authorize`: `https://developer.open-douyin.com/docs/resource/zh-CN/mini-app/develop/api/open-interface/authorization/tt-authorize`
+
+---
+
+## 状态管理
+
+抖音小程序使用 `data` + `setData`；Doubao Apps 使用 React Hooks。
+
+| 抖音小程序 | Doubao Apps | 转换规则 |
+|-----------|-------------|----------|
+| `this.data.foo` | `foo` | 状态变量直接读取 |
+| `this.setData({ foo: val })` | `setFoo(val)` | 单状态更新 |
+| `this.setData({ foo: val, bar: val2 })` | `setFoo(val); setBar(val2)` | 拆分状态 |
+| `this.setData({ 'list[0].name': val })` | `setList(prev => ...)` | 不做字符串路径更新 |
+
+### 状态转换示例
+
+```tsx
+// Before (抖音小程序)
+Page({
+  data: {
+    count: 0,
+    keyword: '',
+  },
+  increase() {
+    this.setData({ count: this.data.count + 1 });
+  },
+  onInput(e) {
+    this.setData({ keyword: e.detail.value });
+  },
+});
+
+// After (Doubao Apps)
+import { FC, useState, definePage } from '@doubao-apps/framework';
+
+const IndexPage: FC = () => {
+  const [count, setCount] = useState(0);
+  const [keyword, setKeyword] = useState('');
+
+  return (
+    <view className="page">
+      <text>{count}</text>
+      <input value={keyword} onInput={(e) => setKeyword(e.detail.value)} />
+      <view onClick={() => setCount((prev) => prev + 1)}>
+        <text>+1</text>
+      </view>
+    </view>
+  );
+};
+
+export default definePage({
+  render() {
+    return <IndexPage />;
+  },
+});
+```
+
+---
+
+## 派生值与副作用
+
+| 抖音小程序 | Doubao Apps | 说明 |
+|-----------|-------------|------|
+| 在 `setData` 前手动算派生值 | `useMemo()` | 派生值显式声明 |
+| `onLoad` / `attached` 中做初始化请求 | `useEffect(() => {...}, [])` | 初始化副作用 |
+| `observer` / 人工比较旧值 | `useEffect(() => {...}, [dep])` | 响应依赖变化 |
+
+---
+
+## 页面 / 组件 / 应用定义
+
+| 抖音小程序 | Doubao Apps | 说明 |
+|-----------|-------------|------|
+| `Page({ ... })` | `definePage({ ..., render })` | 页面定义 |
+| `Component({ properties, methods })` | `FC<Props>` | 组件定义 |
+| `Component({ ... })` 构造页面 | `definePage({ ... })` | 页面仍按页面迁移 |
+| `App({ ... })` | `defineApp({ ... })` | 应用定义 |
+| `this.properties.foo` | `props.foo` | 属性访问 |
+| `this.triggerEvent('tap', detail)` | `props.onTap?.(detail)` | 自定义事件 |
+
+### 组件定义示例
+
+```tsx
+// Before (抖音小程序)
+Component({
+  properties: {
+    title: {
+      type: String,
+      value: '',
+    },
+  },
+  methods: {
+    handleTap() {
+      this.triggerEvent('tap', { title: this.properties.title });
+    },
+  },
+});
+
+// After (Doubao Apps)
+import { FC } from '@doubao-apps/framework';
+
+interface CardProps {
+  title?: string;
+  onTap?: (detail: { title: string }) => void;
+}
+
+export const Card: FC<CardProps> = ({ title = '', onTap }) => {
+  return (
+    <view className="card" onClick={() => onTap?.({ title })}>
+      <text>{title}</text>
+    </view>
+  );
+};
+```
+
+---
+
+## `tt.*` API 映射
+
+### 网络
+
+| 抖音小程序 | Doubao Apps | 说明 |
+|-----------|-------------|------|
+| `tt.request({ url, method, data, success, fail })` | `request({ url, method, data, header })` | Promise 化 |
+| `tt.uploadFile(...)` | `uploadFile(...)` | 视目标能力而定 |
+| `tt.downloadFile(...)` | `downloadFile(...)` | 视目标能力而定 |
+
+```tsx
+// Before
+tt.request({
+  url: 'https://api.example.com/list',
+  success: (res) => {
+    this.setData({ list: res.data.list });
+  },
+});
+
+// After
+import { request } from '@doubao-apps/framework/api';
+
+const res = await request({ url: 'https://api.example.com/list' });
+setList(res.data.list);
+```
+
+### 路由导航
+
+| 抖音小程序 | Doubao Apps | 说明 |
+|-----------|-------------|------|
+| `tt.navigateTo({ url })` | `navigateTo({ url })` | 保留当前页跳转 |
+| `tt.navigateBack({ delta })` | `navigateBack({ delta })` | 返回 |
+| `tt.redirectTo({ url })` | `redirectTo({ url })` | 关闭当前页后跳转 |
+| `tt.switchTab({ url })` | 需先核对当前项目是否暴露 `switchTab` | 当前仓库未检索到公开实现，不要机械替换 |
+| `tt.reLaunch({ url })` | `reLaunch({ url })` | 重启路由栈 |
+
+### UI 交互
+
+| 抖音小程序 | Doubao Apps | 说明 |
+|-----------|-------------|------|
+| `tt.showToast({ title, icon })` | `showToast({ message: title, icon })` | 当前仓库参数名是 `message`，不是 `title` |
+| `tt.showLoading({ title })` | 需先核对当前项目是否暴露对应 API | 当前仓库未在 `packages/open-api/src` 中检索到直接实现 |
+| `tt.hideLoading()` | 需先核对当前项目是否暴露对应 API | 当前仓库未在 `packages/open-api/src` 中检索到直接实现 |
+| `tt.showModal({ ... })` | 需先核对当前项目是否暴露对应 API | `showModal` 曾被标记为临时移除，不要假设稳定可用 |
+
+### 缓存
+
+| 抖音小程序 | Doubao Apps | 说明 |
+|-----------|-------------|------|
+| `tt.setStorageSync(key, value)` | `setStorageSync({ key, data: value })` | 当前仓库是对象参数签名 |
+| `tt.getStorageSync(key)` | `getStorageSync({ key })` | 当前仓库是对象参数签名 |
+| `tt.setStorage({ key, data })` | `setStorage({ key, data })` | 异步写入 |
+| `tt.getStorage({ key })` | `getStorage({ key })` | 异步读取 |
+
+> 当前仓库源码确认 `setStorageSync/getStorageSync` 使用对象参数签名；若迁移目标不是当前仓库模板，再额外核对目标项目封装。
+
+---
+
+## 必须人工判断的 API
+
+### 登录
+
+| 抖音小程序 | Doubao Apps | 迁移判断 |
+|-----------|-------------|----------|
+| `tt.login()` | 无一键等价物 | 需要服务端登录链路改造 |
+| `tt.checkSession()` | 视目标登录态设计 | 不要直接删掉 session 语义 |
+
+### 授权
+
+| 抖音小程序 | Doubao Apps | 迁移判断 |
+|-----------|-------------|----------|
+| `tt.authorize()` | 不建议保留 | 官方已标记逐步废弃 |
+
+### 分享 / 平台挂载
+
+| 抖音小程序 | Doubao Apps | 迁移判断 |
+|-----------|-------------|----------|
+| `onShareAppMessage` | 视目标宿主能力决定 | 不是普通函数替换 |
+| `button open-type="share"` | 无机械等价物 | 需重写交互 |
+| 抖音视频/直播挂载能力 | 无机械等价物 | 平台强绑定，单列迁移项 |
+
+---
+
+## 推荐导入模板
+
+```tsx
+import { FC, definePage, useEffect, useMemo, useState } from '@doubao-apps/framework';
+import {
+  navigateBack,
+  navigateTo,
+  redirectTo,
+  reLaunch,
+  request,
+  showToast,
+  getStorage,
+  getStorageSync,
+  setStorage,
+  setStorageSync,
+} from '@doubao-apps/framework/api';
+import './index.scss';
+```

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

@@ -0,0 +1,196 @@
+# Event Mapping
+
+> **Mapping Version**: 1.0.0
+> **Source Framework**: 抖音小程序 (Douyin Mini Program)
+> **Target Framework**: Doubao Apps (React Lynx)
+> **Last Updated**: 2026-04-01
+
+## 官方事实依据
+
+- TTML 事件: `https://developer.open-douyin.com/docs/resource/zh-CN/mini-app/develop/tutorial/miniapp-framework/view/ttml-event`
+- 组件概述: `https://developer.open-douyin.com/docs/resource/zh-CN/mini-app/develop/component/overview/`
+
+---
+
+## 最关键的迁移差异
+
+| 特性 | 抖音小程序 | Doubao Apps |
+|------|-----------|-------------|
+| 事件处理器 | 字符串方法名 `"handleTap"` | 函数引用 `{handleTap}` |
+| 事件语法 | `bindtap` / `bind:tap` / `bind:tap.stop` | `onClick` / `onCatchTap` / 显式逻辑 |
+| 捕获阶段 | `capture-bind:*` / `bind:*.capture` | 无机械等价，需重构 |
+| dataset 取值 | `event.currentTarget.dataset.xxx` | 优先闭包传值 |
+
+```tsx
+// ❌ 源端写法
+<view bind:tap="handleTap"></view>
+
+// ✅ 目标写法
+<view onClick={handleTap}></view>
+```
+
+---
+
+## 触摸 / 点击事件
+
+| 抖音小程序 | Doubao Apps | 说明 |
+|-----------|-------------|------|
+| `bindtap` / `bind:tap` | `onClick` | 点击 |
+| `catchtap` / `catch:tap` / `bind:tap.stop` | `onCatchTap` | 阻止冒泡 |
+| `bindlongpress` / `bind:longpress` | `onLongPress` | 长按 |
+| `bindtouchstart` / `bind:touchstart` | `onTouchStart` | 触摸开始 |
+| `bindtouchmove` / `bind:touchmove` | `onTouchMove` | 触摸移动 |
+| `bindtouchend` / `bind:touchend` | `onTouchEnd` | 触摸结束 |
+
+### 基础示例
+
+```tsx
+// Before (抖音小程序)
+<view bind:tap="handleTap" bind:longpress="handleLongPress">
+  <text>点击我</text>
+</view>
+
+// After (Doubao Apps)
+<view onClick={handleTap} onLongPress={handleLongPress}>
+  <text>点击我</text>
+</view>
+```
+
+---
+
+## 捕获阶段与 modifier
+
+官方文档说明，自基础库 `2.66.0` 起，支持：
+
+- `capture-bind:event`
+- `bind:event.capture`
+- `bind:event.stop`
+- `bind:event.prevent`
+- `bind:event.stop.prevent`
+
+### 迁移原则
+
+| 源写法 | 迁移策略 |
+|------|----------|
+| `bind:tap.capture` | 重构事件流，不做字符串级替换 |
+| `bind:tap.stop` | 优先改为 `onCatchTap` |
+| `bind:tap.prevent` | 显式重写默认行为，不机械映射 |
+| `bind:tap.stop.prevent` | 通常需要重写交互结构 |
+
+> `prevent` 与捕获语义在目标侧通常不是同名属性就能保留，必须结合组件行为重写。
+
+---
+
+## 输入类事件
+
+| 抖音小程序 | Doubao Apps | 说明 |
+|-----------|-------------|------|
+| `bindinput` / `bind:input` | `onInput` | 输入变化 |
+| `bindfocus` / `bind:focus` | `onFocus` | 获取焦点 |
+| `bindblur` / `bind:blur` | `onBlur` | 失去焦点 |
+| `bindconfirm` / `bind:confirm` | `onConfirm` | 键盘确认 |
+
+```tsx
+// Before
+<input value="{{keyword}}" bind:input="handleInput" bind:confirm="handleConfirm" />
+
+// After
+<input value={keyword} onInput={handleInput} onConfirm={handleConfirm} />
+```
+
+---
+
+## 滚动事件
+
+| 抖音小程序 | Doubao Apps | 说明 |
+|-----------|-------------|------|
+| `bindscroll` | `onScroll` | 滚动中 |
+| `bindscrolltoupper` | `onScrollToUpper` | 到顶 |
+| `bindscrolltolower` | `onScrollToLower` | 到底 |
+
+```tsx
+<scroll-view className="feed-scroll" scrollOrientation="vertical" onScrollToLower={loadMore}>
+  ...
+</scroll-view>
+```
+
+---
+
+## 事件对象与 dataset
+
+官方 TTML 事件文档说明：
+
+- 事件对象可包含 `type`、`timeStamp`、`target`、`currentTarget`、`detail`
+- `data-element-type` 会映射为 `dataset.elementType`
+
+### 推荐迁移方式
+
+```tsx
+// Before
+<view data-id="{{item.id}}" bind:tap="handleTap"></view>
+
+// After
+<view onClick={() => handleTap(item.id)}></view>
+```
+
+只有在需要通用事件代理或复用组件协议时，才继续保留 `data-*`。
+
+---
+
+## switch / slider 事件
+
+Doubao 侧常见组件回调更偏“受控组件”风格：
+
+| 源端 | 目标端 |
+|------|--------|
+| `switch bindchange="onSwitchChange"` | `onChange={(checked) => ...}` |
+| `slider bindchange="onSliderChange"` | `onChange={(value) => ...}` |
+
+```tsx
+<switch checked={checked} onChange={setChecked} />
+```
+
+```tsx
+<slider value={progress} onChange={(value) => setProgress(value)} />
+```
+
+---
+
+## 自定义事件
+
+| 抖音小程序 | Doubao Apps |
+|-----------|-------------|
+| `this.triggerEvent('select', detail)` | `props.onSelect?.(detail)` |
+
+### 自定义事件示例
+
+```tsx
+// Before
+Component({
+  methods: {
+    handleTap() {
+      this.triggerEvent('select', { id: 1 });
+    },
+  },
+});
+
+// After
+interface Props {
+  onSelect?: (detail: { id: number }) => void;
+}
+
+const Item = ({ onSelect }: Props) => {
+  return <view onClick={() => onSelect?.({ id: 1 })}></view>;
+};
+```
+
+---
+
+## 不要机械迁移的事件
+
+- `bind:tap.capture`
+- `bind:tap.prevent`
+- 抖音分享、视频挂载、直播挂载相关回调
+- 依赖 `dataset` 大量透传对象的旧代码
+
+这些事件必须基于目标交互模型重写。