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

package/dist/contexts/doubao-apps-dev/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`

package/dist/contexts/doubao-apps-dev/references/reference/open-api/10-/350/256/276/345/244/207-/350/256/276/345/244/207/346/226/271/345/220/221.md

@@ -10,6 +10,7 @@
 | --- | --- |
 | [startDeviceMotionListening](#startdevicemotionlistening) | 开始监听设备方向变化。<br><br>需配对调用 stopDeviceMotionListening。 |
 | [stopDeviceMotionListening](#stopdevicemotionlistening) | 停止监听设备方向变化。 |
+| [onDeviceMotionChange](#ondevicemotionchange) | 监听设备方向变化事件。<br><br>返回取消监听函数。 |
 
 ## API 详情
 
@@ -47,6 +48,39 @@
 
 `Promise`\<`object`\>
 
+<a id="ondevicemotionchange"></a>
+### onDeviceMotionChange()
+
+> **onDeviceMotionChange**(`handler`): () => `void`
+
+监听设备方向变化事件。
+
+#### Parameters
+
+• **handler**
+
+#### Returns
+
+`Function`
+
+返回取消当前监听函数的函数。
+
+##### Returns
+
+`void`
+
+#### Example
+
+```ts
+import { onDeviceMotionChange } from '@doubao-apps/framework/api';
+
+const off = onDeviceMotionChange(({ alpha, beta, gamma }) => {
+  console.log(alpha, beta, gamma);
+});
+
+off();
+```
+
 ## 相关类型
 
 <a id="startdevicemotionlisteningparams"></a>

package/dist/contexts/doubao-apps-dev/references/reference/open-api/README.md

@@ -15,7 +15,7 @@
 | 设备 / 加速度计 | 加速度计监听能力。 | 3 | [查看](./07-设备-加速度计.md) |
 | 设备 / iBeacon | iBeacon 搜索和结果读取能力。 | 3 | [查看](./08-设备-ibeacon.md) |
 | 设备 / 罗盘 | 罗盘监听能力。 | 3 | [查看](./09-设备-罗盘.md) |
-| 设备 / 设备方向 | 设备方向监听能力。 | 2 | [查看](./10-设备-设备方向.md) |
+| 设备 / 设备方向 | 设备方向监听能力。 | 3 | [查看](./10-设备-设备方向.md) |
 | 设备 / 陀螺仪 | 陀螺仪监听能力。 | 3 | [查看](./11-设备-陀螺仪.md) |
 | UI / 输入 | 键盘和输入框选区能力。 | 1 | [查看](./12-ui-输入.md) |
 | 设备 / 网络 | 网络类型和本机局域网 IP。 | 3 | [查看](./13-设备-网络.md) |

package/dist/contexts/doubao-apps-dev/references/reference/open-api.md

@@ -2,7 +2,7 @@
 
 > 公开可用的端能力 API。默认从 `@doubao-apps/framework/api` 导入；本文件根据 `packages/open-api/src` 的导出结构自动生成，按模块列出 API 名称和说明。
 
-覆盖 124 个函数。详细参数、返回值、示例和相关类型请查看 [Open API 目录](open-api/README.md)，精确字段也可按参数/结果类型名查看 IDE 类型提示或 `@doubao-apps/framework/api` 类型定义。
+覆盖 125 个函数。详细参数、返回值、示例和相关类型请查看 [Open API 目录](open-api/README.md)，精确字段也可按参数/结果类型名查看 IDE 类型提示或 `@doubao-apps/framework/api` 类型定义。
 
 ## 使用方式
 
@@ -176,6 +176,7 @@ iBeacon 搜索和结果读取能力。
 | --- | --- |
 | [startDeviceMotionListening](open-api/10-设备-设备方向.md#startdevicemotionlistening) | 开始监听设备方向变化。<br><br>需配对调用 stopDeviceMotionListening。 |
 | [stopDeviceMotionListening](open-api/10-设备-设备方向.md#stopdevicemotionlistening) | 停止监听设备方向变化。 |
+| [onDeviceMotionChange](open-api/10-设备-设备方向.md#ondevicemotionchange) | 监听设备方向变化事件。<br><br>返回取消监听函数。 |
 
 ## 设备 / 陀螺仪
 

package/dist/contexts/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/manifest.json

@@ -1,7 +1,7 @@
 {
   "packageName": "@byted-doubao-apps/ai-assets",
-  "version": "0.0.28",
-  "generatedAt": "2026-05-19T13:02:35.901Z",
+  "version": "0.0.29-rc.0",
+  "generatedAt": "2026-05-22T07:24:40.145Z",
   "skills": [
     {
       "name": "doubao-apps-dev",

package/dist/skills/doubao-apps-dev/SKILL.md

@@ -71,7 +71,7 @@ my-doubao-app/
 
 - **优先使用 pnpm** 作为包管理器
 - **分离样式文件**：每个组件使用独立的 `.scss` 文件
-- **在 `src/app.config.ts` 中配置 metadata**：为 App、Page 和 Widget 统一配置元数据
+- **配置 App 元信息**：`src/app.config.ts` 需要配置 `appId` 和 `name`；`pages` / `widgets` 是可选的显式入口配置
 - **使用生命周期钩子**：合理使用 `onShow`、`onMounted` 等
 - **TypeScript 类型**：使用 `getViewData<T>()`、为 props 和 state 提供类型定义
 - **错误处理**：处理边界情况和错误状态
@@ -97,21 +97,48 @@ my-doubao-app/
 
 Page 是全屏 UI 组件，支持九宫格、浮窗等变体。
 
-**metadata 配置**：
+**可选 pages 配置**：
 ```ts
 import { defineAppConfig } from '@doubao-apps/kit';
 
 export default defineAppConfig({
-  pages: {
-    'pages/home': {
+  appId: 'com.example.my-doubao-app',
+  name: '我的豆包应用',
+  pages: [
+    {
+      entry: 'pages/home/index',
       id: 'my-page',
       title: '我的页面',
       description: '页面功能描述'
     }
-  }
+  ]
+});
+```
+
+`src/app.config.ts` 是应用配置文件，需要配置 `appId` 和 `name`。`pages` 数组是可选配置；`src/pages/home/index.tsx`
+这类一级目录即使不写进 `pages` 也会被自动发现，默认 `pageId` 是目录名 `home`，但 `title`、`description`
+等页面 metadata 为空。
+
+**什么时候需要配置**：需要设置标题/描述等 metadata、稳定首页入口、或声明多级目录时，使用 `pages` 数组。`pages`
+第一项会作为应用首页（最终 manifest 的 `appletEntry`）。如果希望 `home` 作为默认打开页面，把
+`pages/home/index` 放在第一项；多页面应用继续按顺序声明其他页面。
+
+如果只是声明入口、不补 metadata，可以直接写字符串：
+
+```ts
+export default defineAppConfig({
+  appId: 'com.example.my-doubao-app',
+  name: '我的豆包应用',
+  pages: ['pages/home/index', 'pages/account/demo/index']
 });
 ```
 
+**不配置 `pages` 时**：一级页面仍会产出；如果没有显式 `pages` 顺序，首页入口会走构建兜底/历史默认 `index`。
+首页不是 `index` 时，建议显式配置 `pages` 第一项。
+
+**多级目录**：`src/pages/account/demo/index.tsx` 不会被一级目录扫描自动发现，需要写
+`entry: 'pages/account/demo/index'`。如果不写 `id`，默认 `pageId` 是最后一级目录名 `demo`。
+
 **页面实现**：
 ```tsx
 import { definePage, getViewData } from '@doubao-apps/framework';
@@ -126,8 +153,8 @@ export default definePage({
     // 页面显示时触发
   },
   render() {
-    const input = getViewData<HomePageData>();
-    return <view>{input.title}</view>;
+    const viewData = getViewData<HomePageData>();
+    return <view>{viewData.title}</view>;
   }
 });
 ```
@@ -138,20 +165,37 @@ export default definePage({
 
 Widget 是聊天流中的卡片组件，在对话中展示。
 
-**metadata 配置**：
+**可选 widgets 配置**：
 ```ts
 import { defineAppConfig } from '@doubao-apps/kit';
 
 export default defineAppConfig({
-  widgets: {
-    'widgets/my-widget': {
+  appId: 'com.example.my-doubao-app',
+  name: '我的豆包应用',
+  widgets: [
+    {
+      entry: 'widgets/my-widget/index',
       id: 'my-widget',
       name: '我的卡片',
       description: '卡片功能描述',
       boxType: 'inbox',
       border: true
     }
-  }
+  ]
+});
+```
+
+`src/widgets/my-widget/index.tsx` 这类一级目录即使不配置也会被自动发现，默认 `widgetId` 是目录名
+`my-widget`，`name`、`description` 等 metadata 为空。多级目录如 `src/widgets/order/detail/index.tsx`
+需要在 `widgets` 数组中显式写 `entry: 'widgets/order/detail/index'`。
+
+如果只是声明入口、不补 metadata，可以直接写字符串：
+
+```ts
+export default defineAppConfig({
+  appId: 'com.example.my-doubao-app',
+  name: '我的豆包应用',
+  widgets: ['widgets/my-widget/index', 'widgets/order/detail/index']
 });
 ```
 
@@ -169,8 +213,8 @@ export default defineWidget({
     // 卡片挂载后触发
   },
   render() {
-    const input = getViewData<MyWidgetData>();
-    return <view>{input.title}</view>;
+    const viewData = getViewData<MyWidgetData>();
+    return <view>{viewData.title}</view>;
   }
 });
 ```

package/dist/skills/doubao-apps-dev/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/skills/doubao-apps-dev/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` - 普通卡片