@doubao-apps/ai 0.0.28 → 0.0.29

package/dist/skills/doubao-apps-dev/references/rules/dos-and-donts.md

@@ -22,29 +22,105 @@ npm install @doubao-apps/framework
 
 ### 组件开发
 
-#### ✅ 定义完整的 aiMeta
-```tsx
+#### ✅ 在 app.config.ts 配置 App 元信息
+```ts
+import { defineAppConfig } from '@doubao-apps/kit';
+
+export default defineAppConfig({
+  appId: 'com.example.my-doubao-app',
+  name: '我的豆包应用'
+});
+```
+
+#### ✅ 需要稳定首页时在 app.config.ts 明确入口
+```ts
+// ✅ pages 数组第一项会作为首页（appletEntry）
+import { defineAppConfig } from '@doubao-apps/kit';
+
+export default defineAppConfig({
+  appId: 'com.example.my-doubao-app',
+  name: '我的豆包应用',
+  pages: [
+    {
+      entry: 'pages/home/index',
+      id: 'home',
+      title: '首页',
+      description: '应用默认打开的页面'
+    }
+  ]
+});
+```
+
+一级页面目录不写进 `pages` 也会自动发现；如果首页不是历史默认的 `index`，或需要固定首页顺序，建议显式配置 `pages`
+数组第一项。
+
+#### ✅ 需要补充展示信息时在 app.config.ts 定义 metadata
+```ts
 // ✅ 好的做法
-export default definePage({
-  aiMeta: {
-    id: 'user-profile',
-    title: '用户资料',
-    description: '展示和编辑用户个人资料'
-  },
-  // ...
+import { defineAppConfig } from '@doubao-apps/kit';
+
+export default defineAppConfig({
+  appId: 'com.example.my-doubao-app',
+  name: '我的豆包应用',
+  pages: [
+    {
+      entry: 'pages/user-profile/index',
+      id: 'user-profile',
+      title: '用户资料',
+      description: '展示和编辑用户个人资料'
+    }
+  ]
 });
 ```
 
-```tsx
-// ❌ 不好的做法
-export default definePage({
-  aiMeta: {
-    id: 'page1'  // 缺少 title、description 等信息
-  },
-  // ...
+```ts
+// ❌ 不好的做法：缺少 title、description 等信息
+import { defineAppConfig } from '@doubao-apps/kit';
+
+export default defineAppConfig({
+  appId: 'com.example.my-doubao-app',
+  name: '我的豆包应用',
+  pages: [
+    {
+      entry: 'pages/user-profile/index',
+      id: 'page1'
+    }
+  ]
+});
+```
+
+#### ✅ 多级目录必须显式声明 entry
+```ts
+// src/pages/account/demo/index.tsx
+// src/widgets/order/detail/index.tsx
+import { defineAppConfig } from '@doubao-apps/kit';
+
+export default defineAppConfig({
+  appId: 'com.example.my-doubao-app',
+  name: '我的豆包应用',
+  pages: [
+    // 只声明入口、不补 metadata 时，可以直接写字符串
+    'pages/account/demo/index',
+    {
+      entry: 'pages/account/settings/index',
+      id: 'account-settings',
+      title: '账号设置页'
+    }
+  ],
+  widgets: [
+    'widgets/order/detail/index',
+    {
+      entry: 'widgets/order/summary/index',
+      id: 'order-summary',
+      name: '订单摘要卡片'
+    }
+  ]
 });
 ```
 
+如果不配置 `id`，默认取入口最后一级目录名：`pages/account/demo/index` 默认为 `demo`，`widgets/order/detail/index`
+默认为 `detail`。
+
 #### ✅ 分离样式文件
 ```tsx
 // ✅ 好的做法
@@ -88,8 +164,8 @@ interface UserInfo {
 
 export default defineWidget({
   render() {
-    const input = getViewData<UserInfo>();
-    return <view>{input.name}</view>;
+    const viewData = getViewData<UserInfo>();
+    return <view>{viewData.name}</view>;
   }
 });
 ```
@@ -99,13 +175,16 @@ export default defineWidget({
 import { defineAppConfig } from '@doubao-apps/kit';
 
 export default defineAppConfig({
-  widgets: {
-    'widgets/user-card': {
+  appId: 'com.example.my-doubao-app',
+  name: '我的豆包应用',
+  widgets: [
+    {
+      entry: 'widgets/user-card/index',
       id: 'user-card',
       name: '用户卡片',
       description: '用户信息卡片'
     }
-  }
+  ]
 });
 ```
 
@@ -113,8 +192,8 @@ export default defineAppConfig({
 // ❌ 不好的做法
 export default defineWidget({
   render() {
-    const input = getViewData<any>();  // 使用 any 类型，失去类型检查
-    return <view>{input.name}</view>;
+    const viewData = getViewData<any>();  // 使用 any 类型，失去类型检查
+    return <view>{viewData.name}</view>;
   }
 });
 ```
@@ -123,8 +202,6 @@ export default defineWidget({
 ```tsx
 // ✅ 好的做法
 export default definePage({
-  aiMeta: { /* ... */ },
-
   onShow() {
     console.log('Page shown');
   },
@@ -149,15 +226,15 @@ export default definePage({
 // ✅ 好的做法
 export default defineWidget({
   render() {
-    const input = getViewData<{ items: string[] }>();
+    const viewData = getViewData<{ items: string[] }>();
     // 处理空数据
-    if (!input.items || input.items.length === 0) {
+    if (!viewData.items || viewData.items.length === 0) {
       return <view>暂无数据</view>;
     }
 
     return (
       <view>
-        {input.items.map((item, index) => (
+        {viewData.items.map((item, index) => (
           <view key={index}>{item}</view>
         ))}
       </view>
@@ -170,11 +247,11 @@ export default defineWidget({
 // ❌ 不好的做法
 export default defineWidget({
   render() {
-    const input = getViewData<any>();
-    // 没有检查 input.items 是否存在
+    const viewData = getViewData<any>();
+    // 没有检查 viewData.items 是否存在
     return (
       <view>
-        {input.items.map(item => <view>{item}</view>)}
+        {viewData.items.map(item => <view>{item}</view>)}
       </view>
     );
   }
@@ -321,24 +398,24 @@ export default definePage({
 // ❌ 错误
 export default defineWidget({
   render() {
-    const input = getViewData<any>();
+    const viewData = getViewData<any>();
     // @ts-ignore
-    return <view>{input.unknownProperty}</view>;
+    return <view>{viewData.unknownProperty}</view>;
   }
 });
 ```
 
 ```tsx
 // ✅ 正确
-interface Input {
+interface UserInfo {
   name: string;
   age: number;
 }
 
 export default defineWidget({
   render() {
-    const input = getViewData<Input>();
-    return <view>{input.name}</view>;
+    const viewData = getViewData<UserInfo>();
+    return <view>{viewData.name}</view>;
   }
 });
 ```

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

@@ -68,8 +68,8 @@ import { FC, definePage, getViewData, useEffect, useState } from '@doubao-apps/f
 import { request } from '@doubao-apps/framework/api';
 
 const DetailPage: FC = () => {
-  const input = getViewData() as { id?: string } | undefined;
-  const id = input?.id ?? '';
+  const viewData = getViewData() as { id?: string } | undefined;
+  const id = viewData?.id ?? '';
   const [detail, setDetail] = useState<any>(null);
 
   useEffect(() => {

package/dist/skills/quality-gate/screenshots/doubao-faq.md

@@ -67,7 +67,7 @@ adb -s "$DEVICE" shell am broadcast -a com.bytedance.applet.SET_APPLET_DEBUG_HOS
 典型例子：
 
 ```ts
-const { product, qty: initialQty = 1 } = getViewData<CheckoutInput>();
+const { product, qty: initialQty = 1 } = getViewData<CheckoutViewData>();
 ```
 
 如果对这类页面统一传 `'{}'`，很容易在测试阶段白屏，或者只渲染出宿主错误层。

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

@@ -70,14 +70,14 @@ export default {
 import { definePage, getViewData, useEffect } from '@doubao-apps/framework';
 
 function DetailPage() {
-  const input = getViewData() as { id?: string } | undefined;
+  const viewData = getViewData() as { id?: string } | undefined;
 
   useEffect(() => {
-    if (!input?.id) {
+    if (!viewData?.id) {
       return;
     }
-    // fetchDetail(input.id)
-  }, [input?.id]);
+    // fetchDetail(viewData.id)
+  }, [viewData?.id]);
 
   return <view />;
 }
@@ -122,14 +122,20 @@ uni-app 组件本质上是 Vue2 组件生命周期：
 ### 示例
 
 ```ts
-// After (Doubao Apps)
+// src/app.config.ts
+import { defineAppConfig } from '@doubao-apps/kit';
+
+export default defineAppConfig({
+  appId: 'uniapp-migrated-app',
+  name: 'uniapp-migrated-app'
+});
+```
+
+```ts
+// src/app.ts
 import { defineApp } from '@doubao-apps/framework';
 
 export default defineApp({
-  aiMeta: {
-    id: 'app',
-    name: 'uniapp-migrated-app'
-  },
   onLaunch() {
     console.log('app launched');
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@doubao-apps/ai",
-  "version": "0.0.28",
+  "version": "0.0.29",
   "description": "Doubao Apps SDK AI tools with context and skills management",
   "type": "module",
   "bin": {