@doubao-apps/create 0.0.28 → 0.0.29

package/dist/template-empty/README.md

@@ -31,13 +31,14 @@ import { defineAppConfig } from '@doubao-apps/kit';
 export default defineAppConfig({
   appId: 'com.example.demo',
   name: 'Demo App',
-  pages: {
-    'pages/home': {
+  pages: [
+    {
+      entry: 'pages/home/index',
       id: 'home',
       title: 'Home',
       description: 'Home page'
     }
-  }
+  ]
 });
 ```
 
@@ -72,13 +73,14 @@ export default definePage({
 import { defineAppConfig } from '@doubao-apps/kit';
 
 export default defineAppConfig({
-  pages: {
-    'pages/home': {
+  pages: [
+    {
+      entry: 'pages/home/index',
       id: 'home',
       title: 'Home',
       description: 'Home page'
     }
-  }
+  ]
 });
 ```
 

package/dist/template-empty/package.json

@@ -6,10 +6,10 @@
     "build": "doubao build"
   },
   "dependencies": {
-    "@doubao-apps/framework": "^0.0.28"
+    "@doubao-apps/framework": "^0.0.29"
   },
   "devDependencies": {
-    "@doubao-apps/kit": "^0.0.28",
+    "@doubao-apps/kit": "^0.0.29",
     "typescript": "5.5.3"
   },
   "version": "0.0.16"

package/dist/template-empty/references/examples/common-patterns.md

@@ -412,7 +412,8 @@ function relaunchHome() {
 }
 ```
 
-这里的 `url` 直接使用目标页面的 `pageId`，与页面的 `aiMeta.id` 一致；如需传参，可继续拼接 query string。
+这里的 `url` 直接使用目标页面的 `pageId`。显式配置时取 `src/app.config.ts` 中对应 page 的 `id`；不配置时取入口目录名，例如
+`src/pages/detail/index.tsx` 默认为 `detail`。如需传参，可继续拼接 query string。
 
 ### 2. 页面间传参
 
@@ -441,20 +442,16 @@ function navigateWithParams() {
 // 接收方 (detail-page)
 import { getViewData } from '@doubao-apps/framework';
 
-interface DetailPageInput {
+interface DetailPageData {
   id: string;
   name: string;
   price: number;
 }
 
 export default definePage({
-  aiMeta: {
-    id: 'detail-page',
-    title: '详情页'
-  },
   render() {
     // getViewData() 直接返回传入页面的最终对象
-    const { id, name, price } = getViewData<DetailPageInput>();
+    const { id, name, price } = getViewData<DetailPageData>();
 
     return (
       <view>
@@ -497,10 +494,6 @@ function goBackTwoPages() {
 
 ```tsx
 export default definePage({
-  aiMeta: {
-    id: 'my-page',
-    title: '我的页面'
-  },
   onShow() {
     // 页面显示时调用（包括从其他页面返回）
     console.log('页面显示');
@@ -536,10 +529,6 @@ function openGridPage() {
 
 // 九宫格页面定义
 export default definePage({
-  aiMeta: {
-    id: 'app-grid',
-    title: '应用中心'
-  },
   render() {
     const apps = [
       { id: 'app1', name: '应用1', icon: '🎯' },

package/dist/template-empty/references/examples/component-basics.md

@@ -28,6 +28,28 @@ src/pages/user-profile/
 └── index.scss      # 组件样式
 ```
 
+### app.config.ts
+
+`app.config.ts` 需要配置 `appId` 和 `name`。这里额外配置 `pages` 是为了补充标题和描述，并确保
+`user-profile` 作为页面 ID 使用。
+
+```ts
+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: '显示用户个人信息和统计数据'
+    }
+  ]
+});
+```
+
 ### index.tsx
 
 ```tsx
@@ -139,11 +161,6 @@ function UserProfilePage() {
 }
 
 export default definePage({
-  aiMeta: {
-    id: 'user-profile',
-    title: '用户资料',
-    description: '显示用户个人信息和统计数据'
-  },
   onShow() {
     console.log('页面显示');
   },
@@ -261,11 +278,11 @@ interface WeatherData {
   icon: string;
 }
 
-interface WeatherWidgetInput {
+interface WeatherWidgetData {
   city: string;
 }
 
-function WeatherCard({ city }: WeatherWidgetInput) {
+function WeatherCard({ city }: WeatherWidgetData) {
   const [weather, setWeather] = useState<WeatherData | null>(null);
   const [loading, setLoading] = useState(true);
   const [error, setError] = useState<string | null>(null);
@@ -365,8 +382,8 @@ export default defineWidget({
     console.log('卡片销毁');
   },
   render() {
-    const input = getViewData<WeatherWidgetInput>();
-    return <WeatherCard city={input.city} />;
+    const viewData = getViewData<WeatherWidgetData>();
+    return <WeatherCard city={viewData.city} />;
   }
 });
 ```
@@ -466,10 +483,10 @@ export default defineWidget({
    - `onHide()` - 页面隐藏时调用
    - `onDestroy()` - 页面销毁时调用
 
-2. **页面配置 (aiMeta)**
-   - `id` - 页面唯一标识
-   - `title` - 页面标题
-   - `description` - 页面描述
+2. **页面配置（可选 pages）**
+   - 一级目录不写进 `pages` 也会自动发现，默认 `id` 是目录名
+   - 需要 `title`、`description`、固定首页或多级目录时再配置
+   - 多级目录需要显式写 `entry`
 
 3. **状态管理**
    - 使用 React Hooks（useState, useEffect）
@@ -486,10 +503,10 @@ export default defineWidget({
    - `onForeground()` / `onBackground()` - 应用前后台切换
    - `onMounted()` / `onDestroy()` - 挂载/销毁
 
-2. **输入数据定义 (input schema)**
-   - 使用 JSON Schema 定义输入格式
-   - AI 根据 schema 生成结构化数据
-   - 必须字段使用 `required` 数组
+2. **ViewData 定义**
+   - 使用 TypeScript 类型定义 `getViewData<T>()` 的 viewData 结构
+   - 对可选字段和空数据做兜底处理
+   - 避免直接使用 `any`
 
 3. **卡片类型 (boxType)**
    - `inbox` - 普通卡片

package/dist/template-empty/references/guides/component-development.md

@@ -6,6 +6,42 @@ Page（页面）和 Widget（卡片）组件的完整开发指南。
 
 ## 🎯 Page 开发指南
 
+### App 配置、可选入口与多级目录
+
+`src/app.config.ts` 是应用配置文件，需要配置 `appId` 和 `name`。`pages` / `widgets` 是可选的显式入口配置。
+一级页面目录会自动发现，例如 `src/pages/home/index.tsx` 会产出 `pageId: 'home'`；不配置到 `pages` 时仍可构建，
+但 `title`、`description` 等页面 metadata 为空。
+
+需要补 metadata、固定首页顺序或声明多级目录时，再配置 `pages` 数组。`pages` 是有序数组，第一项会作为应用首页
+（最终 manifest 的 `appletEntry`）；如果希望 `home` 是默认打开页面，把 `pages/home/index` 放在第一项。
+数组项可以是字符串，也可以是 `{ entry, ...metadata }` 对象：只声明入口时用字符串；需要补 metadata 时用对象。
+
+如果不配置 `pages` / `widgets`，一级 Page / Widget 仍会按目录产出；Page / Widget 的默认 ID 取入口最后一级目录名，
+页面/卡片 metadata 字段为空，Widget 的 `boxType` 默认为 `inbox`。没有显式 `pages` 顺序时，首页入口会走构建兜底/历史默认
+`index`；首页不是 `index` 时建议配置 `pages` 第一项。
+
+多级目录不会被一级扫描自动发现，例如 `src/pages/account/demo/index.tsx` 需要显式写
+`entry: 'pages/account/demo/index'`。如果不配置 `id`，默认 `pageId` 是最后一级目录名 `demo`。
+
+```ts
+import { defineAppConfig } from '@doubao-apps/kit';
+
+export default defineAppConfig({
+  appId: 'com.example.my-doubao-app',
+  name: '我的豆包应用',
+  pages: [
+    'pages/home/index',
+    'pages/account/demo/index',
+    {
+      entry: 'pages/profile/index',
+      id: 'profile',
+      title: '资料页',
+      description: '补充 metadata 的页面示例'
+    }
+  ]
+});
+```
+
 ### 基本结构
 
 ```tsx
@@ -13,14 +49,7 @@ import { definePage, getViewData, useState, useEffect } from '@doubao-apps/frame
 import './index.scss';
 
 export default definePage({
-  // 1. AI 元数据配置
-  aiMeta: {
-    id: 'my-page',                    // 页面唯一标识
-    title: '我的页面',                 // 页面标题
-    description: '页面功能描述'         // 页面描述
-  },
-
-  // 2. 生命周期钩子
+  // 1. 生命周期钩子
   onShow() {
     // 页面显示时调用（包括从其他页面返回）
     console.log('页面显示');
@@ -36,12 +65,12 @@ export default definePage({
     console.log('页面销毁');
   },
 
-  // 3. 渲染函数
+  // 2. 渲染函数
   render() {
     // 使用 getViewData() 和 getViewContext() 获取数据和上下文
-    const input = getViewData();
+    const viewData = getViewData();
 
-    return <MyPageComponent {...input} />;
+    return <MyPageComponent {...viewData} />;
   }
 });
 ```
@@ -52,10 +81,6 @@ export default definePage({
 
 ```tsx
 export default definePage({
-  aiMeta: {
-    id: 'full-page',
-    title: '全屏页面'
-  },
   render() {
     return (
       <view className="full-page">
@@ -72,10 +97,6 @@ export default definePage({
 
 ```tsx
 export default definePage({
-  aiMeta: {
-    id: 'grid-page',
-    title: '九宫格'
-  },
   render() {
     const items = [
       { id: '1', title: '应用1', icon: '🎯' },
@@ -100,19 +121,15 @@ export default definePage({
 ### 页面参数接收
 
 ```tsx
-interface PageInput {
+interface PageViewData {
   userId: string;
   tab?: string;
 }
 
 export default definePage({
-  aiMeta: {
-    id: 'user-detail',
-    title: '用户详情'
-  },
   render() {
-    const input = getViewData<PageInput>();
-    const { userId, tab = 'profile' } = input;
+    const viewData = getViewData<PageViewData>();
+    const { userId, tab = 'profile' } = viewData;
 
     return (
       <view>
@@ -145,9 +162,10 @@ reLaunch({
 });
 ```
 
-`url` 在常规页面跳转里填写页面的 `pageId`，与该页面的 `aiMeta.id` 一致；需要传参时可直接在后面拼接 query string。
+`url` 在常规页面跳转里填写页面的 `pageId`。显式配置时取 `src/app.config.ts` 中对应 page 的 `id`；不配置时取入口目录名，例如
+`src/pages/detail/index.tsx` 默认为 `detail`。
 
-页面内可继续通过 `getViewData<PageInput>()` 读取 URL 中传入的参数。
+页面内可继续通过 `getViewData<PageViewData>()` 读取 URL 中传入的参数。
 
 ### 常用模式
 
@@ -243,14 +261,26 @@ function FormPage() {
 
 ## 🎴 Widget 开发指南
 
-### Metadata 配置
+### 可选 Widgets 配置
+
+一级 Widget 目录会自动发现，例如 `src/widgets/my-widget/index.tsx` 会产出 `widgetId: 'my-widget'`。不配置
+`widgets` 时仍可构建，但 `name`、`description` 等 metadata 为空，`boxType` 默认是 `inbox`。
+
+需要补 metadata 或声明多级目录时，再配置 `widgets` 数组。多级目录如 `src/widgets/order/detail/index.tsx`
+需要显式写 `entry: 'widgets/order/detail/index'`；如果不配置 `id`，默认 `widgetId` 是最后一级目录名 `detail`。
+数组项可以是字符串，也可以是 `{ entry, ...metadata }` 对象：只声明入口时用字符串；需要补 metadata 时用对象。
 
 ```ts
 import { defineAppConfig } from '@doubao-apps/kit';
 
 export default defineAppConfig({
-  widgets: {
-    'widgets/my-widget': {
+  appId: 'com.example.my-doubao-app',
+  name: '我的豆包应用',
+  widgets: [
+    'widgets/simple-card/index',
+    'widgets/order/detail/index',
+    {
+      entry: 'widgets/my-widget/index',
       id: 'my-widget',                 // 卡片唯一标识
       name: '我的卡片',                 // 卡片名称
       description: '卡片功能描述',       // 卡片描述
@@ -259,7 +289,7 @@ export default defineAppConfig({
       keywords: ['demo', 'widget'],
       titleType: 'normal'
     }
-  }
+  ]
 });
 ```
 
@@ -301,8 +331,8 @@ export default defineWidget({
   },
 
   render() {
-    const input = getViewData<MyWidgetData>();
-    return <MyWidgetComponent {...input} />;
+    const viewData = getViewData<MyWidgetData>();
+    return <MyWidgetComponent {...viewData} />;
   }
 });
 ```
@@ -323,25 +353,28 @@ export default defineWidget({
 import { defineAppConfig } from '@doubao-apps/kit';
 
 export default defineAppConfig({
-  widgets: {
-    'widgets/info-card': {
+  appId: 'com.example.my-doubao-app',
+  name: '我的豆包应用',
+  widgets: [
+    {
+      entry: 'widgets/info-card/index',
       id: 'info-card',
       name: '信息卡片',
       boxType: 'inbox'
     }
-  }
+  ]
 });
 ```
 
 ```tsx
 export default defineWidget({
   render() {
-    const input = getViewData<{ title: string; content: string }>();
+    const viewData = getViewData<{ title: string; content: string }>();
 
     return (
       <view className="info-card">
-        <text className="title">{input.title}</text>
-        <text className="content">{input.content}</text>
+        <text className="title">{viewData.title}</text>
+        <text className="content">{viewData.content}</text>
       </view>
     );
   }
@@ -357,33 +390,36 @@ export default defineWidget({
 import { defineAppConfig } from '@doubao-apps/kit';
 
 export default defineAppConfig({
-  widgets: {
-    'widgets/user-action-card': {
+  appId: 'com.example.my-doubao-app',
+  name: '我的豆包应用',
+  widgets: [
+    {
+      entry: 'widgets/user-action-card/index',
       id: 'user-action-card',
       name: '全宽卡片示例',
       boxType: 'full_box'
     }
-  }
+  ]
 });
 ```
 
 ```tsx
 export default defineWidget({
   render() {
-    const input = getViewData<{ action: string; result: string }>();
+    const viewData = getViewData<{ action: string; result: string }>();
     return (
       <view className="user-action-card">
-        <text>操作: {input.action}</text>
-        <text>结果: {input.result}</text>
+        <text>操作: {viewData.action}</text>
+        <text>结果: {viewData.result}</text>
       </view>
     );
   }
 });
 ```
 
-### 输入数据类型
+### ViewData 类型
 
-Widget 输入数据通过 `getViewData<T>()` 的泛型参数和 TypeScript 接口表达。
+Widget viewData 通过 `getViewData<T>()` 的泛型参数和 TypeScript 接口表达。
 
 ```tsx
 interface ProductCardData {
@@ -400,20 +436,20 @@ interface ProductCardData {
 
 export default defineWidget({
   render() {
-    const input = getViewData<ProductCardData>();
+    const viewData = getViewData<ProductCardData>();
     return (
       <view className="product-card">
-        <text className="name">{input.name}</text>
-        <text className="price">¥{input.price}</text>
-        {input.images && (
+        <text className="name">{viewData.name}</text>
+        <text className="price">¥{viewData.price}</text>
+        {viewData.images && (
           <view className="images">
-            {input.images.map((img, idx) => (
+            {viewData.images.map((img, idx) => (
               <image key={idx} src={img} />
             ))}
           </view>
         )}
-        <text className="category">{input.category}</text>
-        {!input.inStock && <text className="out-of-stock">缺货</text>}
+        <text className="category">{viewData.category}</text>
+        {!viewData.inStock && <text className="out-of-stock">缺货</text>}
       </view>
     );
   }
@@ -671,18 +707,16 @@ interface TodoData {
 }
 
 export default defineWidget({
-  aiMeta: { ... },
-
   onMounted() {
     // 在生命周期钩子中访问数据
-    const data = getViewData<TodoData>();
-    console.log('任务列表:', data.tasks);
+    const viewData = getViewData<TodoData>();
+    console.log('任务列表:', viewData.tasks);
   },
 
   render() {
     // render 函数中使用 getViewData() 获取数据
-    const input = getViewData<TodoData>();
-    return <view>{input.tasks.length} 个任务</view>;
+    const viewData = getViewData<TodoData>();
+    return <view>{viewData.tasks.length} 个任务</view>;
   }
 });
 ```
@@ -696,8 +730,8 @@ interface WeatherData {
 
 function WeatherWidget() {
   const loadWeatherIcon = () => {
-    const data = getViewData<WeatherData>();
-    return data.temperature > 25 ? '☀️' : '❄️';
+    const viewData = getViewData<WeatherData>();
+    return viewData.temperature > 25 ? '☀️' : '❄️';
   };
 
   return (
@@ -715,27 +749,27 @@ function WeatherWidget() {
 
 ### 使用 `getViewData()` 和 `getViewContext()`
 
-render 函数不再接收 input 和 context 参数，请使用以下方法获取数据和上下文：
+render 函数不再通过参数接收 viewData 和 context，请使用以下方法获取数据和上下文：
 
 **推荐做法**：
 ```tsx
 // ✅ 推荐：render 函数中使用 getViewData()
 render() {
-  const input = getViewData<WeatherData>();
-  return <text>{input.city}: {input.temperature}°C</text>;
+  const viewData = getViewData<WeatherData>();
+  return <text>{viewData.city}: {viewData.temperature}°C</text>;
 }
 
 // ✅ 推荐：生命周期钩子中使用 getViewData()
 onMounted() {
-  const data = getViewData<WeatherData>();
+  const viewData = getViewData<WeatherData>();
   // 处理数据...
 }
 
 // ✅ 推荐：同时获取数据和上下文
 render() {
-  const input = getViewData<WeatherData>();
+  const viewData = getViewData<WeatherData>();
   const context = getViewContext();
-  return <text>{input.city} - {context.lang}</text>;
+  return <text>{viewData.city} - {context.lang}</text>;
 }
 ```
 

package/dist/template-empty/references/guides/performance-optimization.md

@@ -348,8 +348,6 @@ function HeavyFeature() {
 ```tsx
 // ✅ 好的做法 - 优先渲染关键内容
 export default definePage({
-  aiMeta: { /* ... */ },
-
   onShow() {
     // 先显示页面骨架
     this.showSkeleton = true;

package/dist/template-empty/references/guides/troubleshooting.md

@@ -120,8 +120,6 @@ const handleClick = useCallback(() => {
 ```tsx
 // ❌ 错误写法 - 没有在正确位置定义
 export default definePage({
-  aiMeta: { /* ... */ },
-
   render() {
     // ❌ 不能在这里定义
     const onShow = () => {
@@ -134,8 +132,6 @@ export default definePage({
 
 // ✅ 正确写法
 export default definePage({
-  aiMeta: { /* ... */ },
-
   onShow() {
     console.log('Page shown');
   },