@doubao-apps/ai 0.0.19 → 0.0.20

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

@@ -0,0 +1,216 @@
+# Lifecycle Mapping
+
+> **Mapping Version**: 1.0.0
+> **Source Framework**: 抖音小程序 (Douyin Mini Program)
+> **Target Framework**: Doubao Apps (React Lynx)
+> **Last Updated**: 2026-04-01
+
+## 官方事实依据
+
+- App: `https://developer.open-douyin.com/docs/resource/zh-CN/mini-app/develop/framework/app`
+- 组件生命周期: `https://developer.open-douyin.com/docs/resource/zh-CN/mini-app/develop/tutorial/custom-component/lifetime`
+- 小程序启动流程: `https://developer.open-douyin.com/docs/resource/zh-CN/mini-app/develop/tutorial/experience-optimization/launch/process`
+
+## 目标端事实边界
+
+本文件的 Doubao 侧结论以当前仓库源码为准：
+
+- `packages/framework/src/define-api/types.ts`
+- `packages/framework/src/define-api/define-page.ts`
+- `packages/framework/src/define-api/define-app.ts`
+
+未在上述源码中检索到的 Hook，不应写成“同名机械映射”。
+
+---
+
+## 页面生命周期（Page）
+
+抖音小程序 `Page` 不能机械映射成一组同名的 Doubao 页面 Hook。当前仓库源码可确认的 `definePage` 生命周期只有 `onCreated / onMounted / onShow / onHide / onDestroy / onError / render()`。
+
+| 抖音小程序 | 当前 Doubao 仓库可确认能力 | 迁移策略 |
+|-----------|-----------------------------|----------|
+| `onLoad(options)` | 无同名页面钩子 | 页面输入通过 `getViewData()/getViewContext()` 或页面容器显式注入；初始化请求放 `onMounted` 或组件内 `useEffect` |
+| `onShow()` | `onShow()` | 页面显示 |
+| `onReady()` | `onMounted()` | 首次渲染完成后的逻辑 |
+| `onHide()` | `onHide()` | 页面隐藏 |
+| `onUnload()` | `onDestroy()` | 页面销毁 |
+| `onPullDownRefresh()` | 无同名页面钩子 | 结合页面容器或下拉交互重写 |
+| `onReachBottom()` | 无同名页面钩子 | 优先使用列表或 `scroll-view` 的触底事件 |
+| `onPageScroll({ scrollTop })` | 无同名页面钩子 | 通过页面容器或 `scroll-view` 事件重写 |
+| `onShareAppMessage()` | 视宿主能力决定 | 分享能力，不做机械映射 |
+
+### 页面生命周期示例
+
+```tsx
+// Before (抖音小程序)
+Page({
+  data: { id: '', detail: null },
+  onLoad(options) {
+    this.setData({ id: options.id });
+    this.loadDetail(options.id);
+  },
+  onHide() {
+    console.log('page hide');
+  },
+  onUnload() {
+    clearInterval(this.timer);
+  },
+  loadDetail(id) {
+    tt.request({
+      url: `/api/detail/${id}`,
+      success: (res) => this.setData({ detail: res.data }),
+    });
+  },
+});
+
+// After (Doubao Apps)
+import { FC, definePage, getViewData, useEffect, useState } from '@doubao-apps/framework';
+import { request } from '@doubao-apps/framework/api';
+
+const DetailPage: FC = () => {
+  const input = getViewData() as { id?: string } | undefined;
+  const id = input?.id ?? '';
+  const [detail, setDetail] = useState<any>(null);
+
+  useEffect(() => {
+    if (!id) return;
+    request({ url: `/api/detail/${id}` }).then((res) => setDetail(res.data));
+  }, [id]);
+
+  return <view className="detail-page">{detail ? <text>{detail.title}</text> : null}</view>;
+};
+
+export default definePage({
+  onMounted() {
+    console.log('page mounted');
+  },
+  onHide() {
+    console.log('page hide');
+  },
+  onDestroy() {
+    // cleanup
+  },
+  render() {
+    return <DetailPage />;
+  },
+});
+```
+
+---
+
+## 页面初始化顺序
+
+官方“小程序启动流程”文档说明，启动页面在渲染树构建过程中会先触发 `Page.onLoad`，视图层页面树构建后通知逻辑层触发 `Page.onShow`。
+
+**迁移建议**：
+
+- 当前仓库没有公开的 `definePage.onLoad` / `render(query)` 接口，不要把源端页面参数读取逻辑原样平移
+- 页面输入优先通过 `getViewData()/getViewContext()` 或页面容器显式注入
+- 首次数据请求尽量放到 `onMounted` 或组件内 `useEffect`
+- 页面曝光日志可保留在 `onShow`
+
+---
+
+## 组件生命周期（Component）
+
+| 抖音小程序 Component | Doubao Apps | 说明 |
+|---------------------|-------------|------|
+| `created()` | 普通变量初始化 | 不能直接等价成 Hook 生命周期 |
+| `attached()` | `useEffect(() => {...}, [])` | 组件挂载初始化 |
+| `ready()` | `useEffect(() => {...}, [])` 或布局完成后逻辑 | 视具体需求合并 |
+| `detached()` | `useEffect(() => () => {...}, [])` | 清理资源 |
+
+### 组件生命周期示例
+
+```tsx
+// Before (抖音小程序)
+Component({
+  properties: { itemId: String },
+  data: { detail: null },
+  lifetimes: {
+    attached() {
+      this.loadData();
+    },
+    detached() {
+      clearInterval(this.timer);
+    },
+  },
+  methods: {
+    loadData() {
+      tt.request({
+        url: `/api/item/${this.properties.itemId}`,
+        success: (res) => this.setData({ detail: res.data }),
+      });
+    },
+  },
+});
+
+// After (Doubao Apps)
+import { FC, useEffect, useState } from '@doubao-apps/framework';
+import { request } from '@doubao-apps/framework/api';
+
+export const ItemCard: FC<{ itemId: string }> = ({ itemId }) => {
+  const [detail, setDetail] = useState<any>(null);
+
+  useEffect(() => {
+    request({ url: `/api/item/${itemId}` }).then((res) => setDetail(res.data));
+
+    return () => {
+      // cleanup
+    };
+  }, [itemId]);
+
+  return <view className="item-card">{detail ? <text>{detail.name}</text> : null}</view>;
+};
+```
+
+---
+
+## `pageLifetimes` 迁移
+
+官方组件生命周期文档说明，自定义组件从基础库 `2.41.0` 起支持：
+
+- `pageLifetimes.show`
+- `pageLifetimes.hide`
+- `pageLifetimes.resize`
+
+| 抖音小程序 | Doubao Apps | 迁移策略 |
+|-----------|-------------|----------|
+| `pageLifetimes.show({ showFrom })` | 页面 `onShow` + props 透传 | 组件感知页面展示 |
+| `pageLifetimes.hide()` | 页面 `onHide` + props 透传 | 组件感知页面隐藏 |
+| `pageLifetimes.resize(size)` | 页面容器统一监听，再透传尺寸状态 | 不要留在叶子组件内 |
+
+### 推荐改写方式
+
+1. 在页面层统一持有“是否可见”“窗口尺寸”“分屏比例”等状态。
+2. 通过 props 传给原组件迁移后的 FC。
+3. 组件内部只保留纯展示和基于 props 的副作用。
+
+---
+
+## App 生命周期
+
+| 抖音小程序 | 当前 Doubao 仓库可确认能力 | 说明 |
+|-----------|----------------------------|------|
+| `onLaunch(options)` | `onLaunch()` | 冷启动，仅一次 |
+| `onShow(options)` | `onForeground()` | 应用切前台；若需要监听页面打开，可结合 `onPageOpened({ viewId })` |
+| `onHide()` | `onBackground()` | 应用切后台 |
+| `onError(msg)` | `onError(error)` | 错误监听 |
+| `onPageNotFound(res)` | 未检索到同名 Hook | 需在路由层或宿主层兜底 |
+| `onUnhandledRejection(res)` | 未检索到同名 Hook | Promise 拒绝兜底需放到应用初始化层 |
+
+**迁移建议**：
+
+- `globalData` 不要直接复制，优先迁移成显式模块状态或上下文
+- `onPageNotFound` / `onUnhandledRejection` 不要假设存在同名 `defineApp` Hook
+- `onUnhandledRejection` 若目标 runtime 无等价入口，则放到应用初始化层统一兜底
+
+---
+
+## 不应机械迁移的生命周期
+
+- `onShareAppMessage`
+- 视频挂载 / 直播挂载相关回调
+- 与抖音宿主分屏、分享入口强绑定的页面钩子
+
+这些能力必须结合目标宿主能力重新设计。

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

@@ -0,0 +1,195 @@
+# Style 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/component/overview/`
+- 小程序启动流程（TTML/TTSS 编译说明）: `https://developer.open-douyin.com/docs/resource/zh-CN/mini-app/develop/tutorial/experience-optimization/launch/process`
+
+---
+
+## 样式系统差异总览
+
+| 特性 | 抖音小程序 | Doubao Apps |
+|------|-----------|-------------|
+| 样式文件 | `.ttss` | `index.scss` |
+| 类名属性 | `class="xxx"` | `className="xxx"` |
+| 内联样式 | `style="..."` | `style={{...}}` 或尽量收敛到 `index.scss` |
+| 竖向滚动约束 | `scroll-view` 需要固定高度 | 同样需要明确高度 |
+| 单位 | `px`, `rpx` | 以目标样式能力和视觉校验为准 |
+
+---
+
+## 基本规则
+
+### 文件与导入
+
+```tsx
+import './index.scss';
+```
+
+### 类名迁移
+
+```tsx
+// Before
+<view class="card title-wrap"></view>
+
+// After
+<view className="card title-wrap"></view>
+```
+
+### 内联样式迁移
+
+```tsx
+// Before
+<view style="padding: 16rpx; background: #fff;"></view>
+
+// After
+<view className="card"></view>
+```
+
+```scss
+.card {
+  padding: 16rpx;
+  background: #fff;
+}
+```
+
+**优先级**：
+
+1. 能落到 `index.scss` 的，优先落样式文件
+2. 只有动态值才用 `style={{}}`
+
+---
+
+## TTSS → `index.scss`
+
+### 保留 class 语义
+
+```scss
+/* Before (page.ttss) */
+.page {
+  padding: 24rpx;
+}
+
+.card {
+  border-radius: 16rpx;
+  background: #fff;
+}
+```
+
+```tsx
+// After (index.tsx)
+<view className="page">
+  <view className="card"></view>
+</view>
+```
+
+```scss
+/* After (index.scss) */
+.page {
+  padding: 24rpx;
+}
+
+.card {
+  border-radius: 16rpx;
+  background: #fff;
+}
+```
+
+---
+
+## 动态样式处理
+
+### `hidden`
+
+官方源端支持 `hidden` 通用属性；迁移到 Doubao 时优先用条件渲染，其次再考虑 class 切换。
+
+```tsx
+// Before
+<view hidden="{{isLoading}}"></view>
+
+// After
+{!isLoading ? <view className="content"></view> : null}
+```
+
+### 动态 class
+
+```tsx
+// Before
+<view class="item {{active ? 'item--active' : ''}}"></view>
+
+// After
+<view className={active ? 'item item--active' : 'item'}></view>
+```
+
+---
+
+## 选择器迁移策略
+
+### 推荐保留的选择器
+
+- 单类选择器
+- 多类组合
+- 简单后代选择器
+- 伪类较少、作用域明确的局部样式
+
+### 需要谨慎处理的选择器
+
+- 过深层级选择器
+- 大范围全局重置
+- 依赖宿主默认样式继承的写法
+- 强耦合页面结构的选择器
+
+**迁移建议**：把复杂样式收敛到组件局部 class，不要把源项目整套全局样式表原样搬过来。
+
+---
+
+## `scroll-view` 样式
+
+官方源端要求竖向滚动时给定固定高度。迁移到 Doubao 时同样要保留这个约束：
+
+```scss
+.feed-scroll {
+  height: 400rpx;
+}
+```
+
+```tsx
+<scroll-view className="feed-scroll" scrollOrientation="vertical">
+  ...
+</scroll-view>
+```
+
+---
+
+## 图片与布局样式
+
+```tsx
+// Before
+<image class="banner" src="{{url}}" mode="aspectFill" />
+
+// After
+<image className="banner" src={url} mode="aspectFill" />
+```
+
+```scss
+.banner {
+  width: 100%;
+  height: 320rpx;
+  border-radius: 24rpx;
+}
+```
+
+---
+
+## 样式迁移禁忌
+
+- 不要把所有 `.ttss` 强行展开成超长内联对象
+- 不要保留无效 class 名但删除对应样式
+- 不要依赖抖音宿主默认按钮、输入框外观
+- 不要在没有视觉回归的前提下批量改单位

package/dist/skills/douyin-to-doubao/references/source-framework/api-reference.md

@@ -0,0 +1,223 @@
+# 抖音小程序 API 参考
+
+> 本文档为迁移参考，仅列出常用 API 与页面/组件模型。
+> 事实优先来源为抖音开放平台官方文档，已于 `2026-04-01` 校验。
+
+## 官方文档入口
+
+- 框架概述: `https://developer.open-douyin.com/docs/resource/zh-CN/mini-app/develop/tutorial/miniapp-framework/introduction`
+- 应用 / `App()`: `https://developer.open-douyin.com/docs/resource/zh-CN/mini-app/develop/framework/app`
+- `Component()` 构造器: `https://developer.open-douyin.com/docs/resource/zh-CN/mini-app/develop/tutorial/custom-component/component-constructor`
+- 组件生命周期: `https://developer.open-douyin.com/docs/resource/zh-CN/mini-app/develop/tutorial/custom-component/lifetime`
+- 网络连接 / `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`
+- 分享: `https://developer.open-douyin.com/docs/resource/zh-CN/mini-app/develop/tutorial/open-capabilities/general-capabilities/share`
+- `tt.authorize`（逐步废弃）: `https://developer.open-douyin.com/docs/resource/zh-CN/mini-app/develop/api/open-interface/authorization/tt-authorize`
+
+---
+
+## 页面 / 组件 / 应用定义
+
+### Page(options)
+
+抖音小程序页面通常通过 `Page({})` 定义，常见能力包括：
+
+```js
+Page({
+  data: { key: value },
+
+  onLoad(options) {},
+  onShow() {},
+  onReady() {},
+  onHide() {},
+  onUnload() {},
+
+  onPullDownRefresh() {},
+  onReachBottom() {},
+  onPageScroll({ scrollTop }) {},
+  onShareAppMessage() {},
+
+  customMethod() {},
+});
+```
+
+**迁移**：不要假设 Doubao 存在 `onLoad/onReady/onReachBottom/onPageScroll` 这类同名页面钩子；应按当前项目真实的 `definePage` 接口拆到 `onMounted/onShow/onHide/onDestroy` 与组件内 `useEffect`，页面输入优先通过 `getViewData()/getViewContext()` 或页面容器显式注入。
+
+### Component(options)
+
+抖音小程序组件通过 `Component({})` 定义，支持 `properties`、`data`、`methods`、`lifetimes`、`pageLifetimes`：
+
+```js
+Component({
+  properties: {
+    title: {
+      type: String,
+      value: '',
+      observer(newVal, oldVal) {},
+    },
+    count: Number,
+  },
+  data: {},
+  lifetimes: {
+    attached() {},
+    detached() {},
+  },
+  pageLifetimes: {
+    show() {},
+    hide() {},
+    resize(size) {},
+  },
+  methods: {
+    handleTap() {},
+  },
+});
+```
+
+**迁移**：优先转为 `FC<Props>`；若源页面本身是用 `Component()` 构造，则仍按页面迁移到 `definePage({})`。
+
+### App(options)
+
+```js
+App({
+  onLaunch(options) {},
+  onShow(options) {},
+  onHide() {},
+  onError(msg) {},
+  onPageNotFound(res) {},
+  onUnhandledRejection(res) {},
+  globalData: {},
+});
+```
+
+**迁移**：按当前项目真实的 `defineApp` 接口重写；当前仓库可确认的是 `onLaunch/onPageOpened/onForeground/onBackground/onDestroy/onError`，不要直接假设存在 `onShow/onHide/onPageNotFound` 同名 Hook。
+
+---
+
+## 生命周期与页面关系
+
+根据官方文档：
+
+- `App.onLaunch` 在冷启动完成时触发，全局只触发一次
+- `App.onShow` 在小程序启动或从后台进入前台时触发
+- `App.onHide` 在小程序从前台进入后台时触发
+- 组件 `created / attached / detached` 是组件实例生命周期关键节点
+- 自定义组件 `pageLifetimes.show/hide/resize` 在基础库 `2.41.0` 起可用
+
+**迁移建议**：
+
+- App 生命周期保留到 `defineApp`，但要按当前项目真实接口改写
+- 页面生命周期保留到 `definePage`，但不要假设存在源端同名 Hook
+- 组件生命周期转为 `useEffect`
+- `pageLifetimes` 上提到页面容器或通过 props 显式透传
+
+---
+
+## 网络
+
+### `tt.request`
+
+官方网络教程明确使用 `tt.request` 发起 HTTP(S) 请求：
+
+```js
+Page({
+  data: {
+    serverText: '',
+  },
+  sendRequest() {
+    tt.request({
+      url: 'http://localhost:3000/',
+      success: (res) => {
+        if (res.statusCode === 200) {
+          this.setData({
+            serverText: res.data,
+          });
+        }
+      },
+    });
+  },
+});
+```
+
+**迁移**：→ `request({ url, method, data, header })`，返回 Promise。
+
+---
+
+## 登录
+
+### `tt.login`
+
+官方文档要点：
+
+- `tt.login(options)` 为异步方法
+- `force` 默认值为 `true`
+- 登录成功时可能返回 `code`、`anonymousCode`
+- `code`、`anonymousCode` 均有效期 5 分钟
+- `code` 用于服务端换取 `openid / unionid / session_key`
+
+```js
+tt.login({
+  force: true,
+  success(res) {
+    console.log(res.code, res.anonymousCode);
+  },
+});
+```
+
+**迁移判断**：
+
+- 这不是简单的 UI API 替换
+- 如果目标 Doubao 项目仍需要登录态，必须重建服务端登录链路
+- 不要把 `tt.login` 机械替换成普通请求或本地 mock
+
+---
+
+## 分享与挂载
+
+官方分享教程说明，抖音小程序分享入口包括：
+
+- `button open-type="share"`
+- 右上角更多面板分享
+- 截图分享（页面实现 `onShareAppMessage` 后触发）
+
+**迁移判断**：
+
+- `onShareAppMessage`
+- `button open-type="share"`
+- 抖音视频/直播挂载能力
+
+以上都属于宿主平台能力，不应被当作普通按钮点击逻辑直接平移。
+
+---
+
+## 授权
+
+### `tt.authorize`
+
+官方文档明确写明：
+
+- 该接口“将逐步废弃，后续不再维护”
+- 授权仅支持对应接口触发，不再支持提前向用户发起统一授权请求
+
+**迁移建议**：
+
+- 遇到旧代码调用 `tt.authorize`，按具体能力重构
+- 不要在新目标代码里继续沿用“先统一授权，再调用能力”的思路
+
+---
+
+## 缓存 / 导航 / UI 交互
+
+官方框架概述明确列举了以下典型能力：
+
+- `tt.showToast`：界面交互提示
+- `tt.navigateTo`：页面跳转
+
+基于官方概述与源项目常见实践，抖音小程序还广泛使用：
+
+- 数据缓存：`tt.getStorage` / `tt.setStorage` / 同步版本
+- 导航：`tt.navigateBack` / `tt.redirectTo` / `tt.switchTab` / `tt.reLaunch`
+- UI 交互：`tt.showLoading` / `tt.hideLoading` / `tt.showModal`
+
+> 上述细分 API 名称与行为属于对官方概述、源项目实践和宿主小程序一致性的综合归纳；迁移时若某个 API 成为关键路径，应再回读对应官方 API 页面。
+
+**迁移**：在 Doubao 侧通常对应 `@doubao-apps/framework/api` 的同名或近似 API。