@doubao-apps/create 0.0.28 → 0.0.29-rc.0

package/dist/template-starter/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-starter/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-starter/references/guides/performance-optimization.md

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

package/dist/template-starter/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');
   },

package/dist/template-starter/references/reference/framework-api-quick-ref.md

@@ -7,8 +7,8 @@
 
 | API | 用途 | 示例 |
 |-----|------|------|
-| `definePage()` | 定义 Page 组件 | `definePage({ aiMeta: {...}, render() {...} })` |
-| `defineWidget()` | 定义 Widget 组件 | `defineWidget({ aiMeta: {...}, render() {...} })` |
+| `definePage()` | 定义 Page 组件 | `definePage({ render() {...} })` |
+| `defineWidget()` | 定义 Widget 组件 | `defineWidget({ render() {...} })` |
 | `defineApp()` | 定义 App 入口 | `defineApp({ onLaunch() {...} })` |
 
 ---
@@ -77,8 +77,8 @@ interface MyData {
   title: string;
   count: number;
 }
-const data = getViewData<MyData>();
-console.log(data.title, data.count);
+const viewData = getViewData<MyData>();
+console.log(viewData.title, viewData.count);
 ```
 
 **AIViewContext 类型**：
@@ -206,7 +206,7 @@ const phone = await getPhoneNumber();
 
 > `close()` 已废弃，公开路由场景请优先使用 `navigateBack()`。
 >
-> 常规页面跳转场景下，`url` 直接使用目标页面的 `pageId`，该值一般与页面的 `aiMeta.id` 一致；需要传参时可直接拼接 query string。
+> 常规页面跳转场景下，`url` 直接使用目标页面的 `pageId`。显式配置时取 `src/app.config.ts` 中对应 page 的 `id`；不配置时取入口目录名，例如 `src/pages/detail/index.tsx` 默认为 `detail`。需要传参时可直接拼接 query string。
 
 ### showToast
 
@@ -461,36 +461,41 @@ const phone = await getPhoneNumber();
 
 # 常用类型
 
-```typescript
-// Page Input
-interface PageInput {
-  [key: string]: any;  // URL 参数
-}
-
-// src/app.config.ts 中的 metadata 配置
-interface PageAIMeta {
-  id: string;                      // 页面唯一标识
-  title?: string;                  // 页面标题
-  description?: string;            // 页面描述
-}
-
-interface WidgetAIMeta {
-  id: string;                      // 卡片唯一标识
-  name?: string;                   // 卡片名称
-  description?: string;            // 卡片描述
-  boxType?: 'inbox' | 'full_box';  // 卡片类型
-  border?: boolean;                // 是否显示边框
-  keywords?: string[];             // 搜索关键词
-  titleType?: 'none' | 'normal' | 'float';
-}
+`src/app.config.ts` 需要配置 `appId` 和 `name`。Page / Widget metadata 使用可选的 `pages`、`widgets` 数组声明：
 
-// Widget 渲染数据类型
-interface WidgetViewData {
-  title: string;
-  content?: string;
-}
+```typescript
+import { defineAppConfig } from '@doubao-apps/kit';
+
+export default defineAppConfig({
+  appId: 'com.example.my-doubao-app',
+  name: '我的豆包应用',
+  pages: [
+    'pages/home/index',
+    {
+      entry: 'pages/account/demo/index',
+      id: 'account-demo',
+      title: '账号示例页',
+      description: '多级目录页面示例'
+    }
+  ],
+  widgets: [
+    'widgets/user-card/index',
+    {
+      entry: 'widgets/order/detail/index',
+      id: 'order-detail',
+      name: '订单详情卡片',
+      description: '多级目录卡片示例',
+      boxType: 'inbox',
+      border: true,
+      keywords: ['order'],
+      titleType: 'normal'
+    }
+  ]
+});
 ```
 
+字符串数组项只声明入口，不补 metadata；对象数组项用于同时声明入口和 metadata。
+
 ---
 
 # 快速示例
@@ -498,17 +503,25 @@ interface WidgetViewData {
 
 ## 最小 App
 
+### src/app.config.ts
+
+```ts
+import { defineAppConfig } from '@doubao-apps/kit';
+
+export default defineAppConfig({
+  appId: 'com.doubao.react-lynx-template',
+  name: 'Doubao Apps SDK Template',
+  description: 'React Lynx 开发模板',
+  keywords: ['react', 'lynx', 'template', 'doubao']
+});
+```
+
+### src/app.ts
+
 ```tsx
 import { defineApp } from "@doubao-apps/framework";
 
-// Define AI Metadata
 export default defineApp({
-  aiMeta: {
-    package: "com.doubao.react-lynx-template",
-    name: "Doubao Apps SDK Template",
-    description: "React Lynx 开发模板",
-    keywords: ["react", "lynx", "template", "doubao"],
-  },
   onLaunch() {
     console.log("App launched");
   },

package/dist/template-starter/references/reference/open-api/01-/345/237/272/347/241/200-/350/264/246/345/217/267-/347/263/273/347/273/237.md

@@ -482,7 +482,7 @@ showToast({
 ```ts
 expiredWidget({
   widgetInstanceId: 'instance_123',
-  schema: '${pageId}?key=value'
+  url: '${pageId}?key=value'
 });
 ```
 
@@ -1851,18 +1851,28 @@ mcp入参，如果expectedAction里预期要调用工具，需要在这里写明
 
 点击失效卡要跳转的页面 detailText
 
-##### schema?
+##### ~~schema?~~
 
 > `optional` **schema**: `string`
 
 点击失效卡要跳转的页面 schema，格式与 navigateTo 的 url 相同
 
+###### Deprecated
+
+使用 url 字段替代 schema 字段，后续版本将移除 schema 字段，请尽快迁移到 url 字段
+
 ##### title?
 
 > `optional` **title**: `string`
 
 点击失效卡要跳转的页面 title
 
+##### url?
+
+> `optional` **url**: `string`
+
+点击失效卡要跳转的页面 url 或 sslocal schema
+
 ##### widgetInstanceId
 
 > **widgetInstanceId**: `string`