@doubao-apps/create 0.0.25 → 0.0.27

package/dist/template-empty/.ai/rules/dos-and-donts.md

@@ -87,19 +87,6 @@ interface UserInfo {
 }
 
 export default defineWidget({
-  aiMeta: {
-    id: 'user-card',
-    name: '用户卡片',
-    input: {
-      type: 'object',
-      properties: {
-        name: { type: 'string', title: '姓名' },
-        age: { type: 'number', title: '年龄' },
-        avatar: { type: 'string', title: '头像' }
-      },
-      required: ['name', 'age']
-    }
-  },
   render() {
     const input = getViewData<UserInfo>();
     return <view>{input.name}</view>;
@@ -107,6 +94,21 @@ export default defineWidget({
 });
 ```
 
+```ts
+// ✅ 把 metadata 写到 src/app.config.ts
+import { defineAppConfig } from '@doubao-apps/kit';
+
+export default defineAppConfig({
+  widgets: {
+    'widgets/user-card': {
+      id: 'user-card',
+      name: '用户卡片',
+      description: '用户信息卡片'
+    }
+  }
+});
+```
+
 ```tsx
 // ❌ 不好的做法
 export default defineWidget({
@@ -247,20 +249,26 @@ export default definePage({
 ```
 
 ```tsx
-// ✅ 正确 - 在生命周期钩子中请求
-export default definePage({
-  data: {
-    userData: null
-  },
+// ✅ 推荐 - 使用 Hook 管理请求和状态
+import { useEffect, useState } from '@doubao-apps/framework';
 
-  onShow() {
-    fetch('/api/data').then(data => {
-      this.setData({ userData: data });
-    });
-  },
+function UserPage() {
+  const [userData, setUserData] = useState<{ name?: string } | null>(null);
+
+  useEffect(() => {
+    fetch('/api/data')
+      .then(res => res.json())
+      .then(data => {
+        setUserData(data);
+      });
+  }, []);
 
+  return <view>{userData?.name}</view>;
+}
+
+export default definePage({
   render() {
-    return <view>{this.data.userData?.name}</view>;
+    return <UserPage />;
   }
 });
 ```
@@ -351,21 +359,26 @@ export default defineWidget({
 ```
 
 ```tsx
-// ✅ 正确 - 使用实例状态
+// ✅ 推荐 - 使用组件内状态，实例之间互不影响
+import { useState } from '@doubao-apps/framework';
+
+function CounterWidget() {
+  const [count, setCount] = useState(0);
+
+  return (
+    <view
+      onClick={() => {
+        setCount(prev => prev + 1);
+      }}
+    >
+      Count: {count}
+    </view>
+  );
+}
+
 export default defineWidget({
-  data: {
-    count: 0
-  },
   render() {
-    return (
-      <view
-        onClick={() => {
-          this.setData({ count: this.data.count + 1 });
-        }}
-      >
-        Count: {this.data.count}
-      </view>
-    );
+    return <CounterWidget />;
   }
 });
 ```

package/dist/template-empty/AGENTS.md

@@ -1,4 +1,4 @@
-# AGENTS.md - Doubao Apps SDK AI 开发指南
+# Doubao Apps SDK AI 开发指南
 
 本文件专供 AI coding agents（如 Claude、Copilot、Cursor）和开发者使用，提供 Doubao Apps SDK 框架的快速入门、开发规则和文档导航。
 
@@ -31,7 +31,6 @@ pnpm install
 
 # 启动开发
 pnpm dev
-
 ```
 
 **开发服务器命令**：
@@ -66,9 +65,9 @@ my-doubao-app/
 
 - **优先使用 pnpm** 作为包管理器
 - **分离样式文件**：每个组件使用独立的 `.scss` 文件
-- **定义 aiMeta**：为 Page 和 Widget 提供完整的元数据
+- **在 `src/app.config.ts` 中配置 metadata**：为 App、Page 和 Widget 统一配置元数据
 - **使用生命周期钩子**：合理使用 `onShow`、`onMounted` 等
-- **TypeScript 类型**：为 props 和 state 提供类型定义
+- **TypeScript 类型**：使用 `getViewData<T>()`、为 props 和 state 提供类型定义
 - **错误处理**：处理边界情况和错误状态
 
 ### 禁止做法
@@ -92,22 +91,37 @@ my-doubao-app/
 
 Page 是全屏 UI 组件，支持九宫格、浮窗等变体。
 
-**基础结构**：
+**metadata 配置**：
+```ts
+import { defineAppConfig } from '@doubao-apps/kit';
+
+export default defineAppConfig({
+  pages: {
+    'pages/home': {
+      id: 'my-page',
+      title: '我的页面',
+      description: '页面功能描述'
+    }
+  }
+});
+```
+
+**页面实现**：
 ```tsx
 import { definePage, getViewData } from '@doubao-apps/framework';
 import './index.scss';
 
+interface HomePageData {
+  title: string;
+}
+
 export default definePage({
-  aiMeta: {
-    id: 'my-page',
-    title: '我的页面',
-  },
   onShow() {
     // 页面显示时触发
   },
   render() {
-    const input = getViewData();
-    return <view>页面内容</view>;
+    const input = getViewData<HomePageData>();
+    return <view>{input.title}</view>;
   }
 });
 ```
@@ -118,28 +132,38 @@ export default definePage({
 
 Widget 是聊天流中的卡片组件，在对话中展示。
 
-**基础结构**：
+**metadata 配置**：
+```ts
+import { defineAppConfig } from '@doubao-apps/kit';
+
+export default defineAppConfig({
+  widgets: {
+    'widgets/my-widget': {
+      id: 'my-widget',
+      name: '我的卡片',
+      description: '卡片功能描述',
+      boxType: 'inbox',
+      border: true
+    }
+  }
+});
+```
+
+**卡片实现**：
 ```tsx
 import { defineWidget, getViewData } from '@doubao-apps/framework';
 import './index.scss';
 
+interface MyWidgetData {
+  title: string;
+}
+
 export default defineWidget({
-  aiMeta: {
-    id: 'my-widget',
-    name: '我的卡片',
-    boxType: 'inbox',
-    input: {
-      type: 'object',
-      properties: {
-        title: { type: 'string', title: '标题' }
-      }
-    }
-  },
   onMounted() {
     // 卡片挂载后触发
   },
   render() {
-    const input = getViewData();
+    const input = getViewData<MyWidgetData>();
     return <view>{input.title}</view>;
   }
 });
@@ -171,7 +195,7 @@ export default defineWidget({
 完整的 Framework API（框架核心）和 Bridge API（系统能力）列表：
 
 - **[Framework API 快速参考](.ai/reference/framework-api-quick-ref.md)** - 核心 Framework API 速查
-- **[Open API 文档](.ai/reference/open-api.md)** - 公开可用的端能力（系统能力）定义
+- **[Open API 目录](.ai/reference/open-api/README.md)** - 公开可用的端能力（系统能力）目录与详细文档
 - **[组件库快速参考](.ai/reference/components-quick-ref.md)** - SDK 内置组件（Button、Switch、Swiper 等）
 
 包含：
@@ -206,8 +230,7 @@ API 参考文档
 
 - **[Framework API](.ai/reference/framework-api-quick-ref.md)** - 核心 Framework API 速查
 - **[组件库](.ai/reference/components-quick-ref.md)** - SDK 内置组件速查
-- **[Open API](.ai/reference/open-api.md)** - 系统能力 API
-
+- **[Open API](.ai/reference/open-api/README.md)** - 系统能力 API 目录与详细文档
 
 ### 依赖包
 
@@ -243,10 +266,10 @@ API 参考文档
 
 ```
 项目根目录/
-├── AGENTS.md   # 主入口文档（AI Agent 必读）
-└── .ai/                # 详细文档目录
-    ├── guides/         # 开发指南
-    ├── rules/          # 开发规则
-    ├── examples/       # 代码示例
-    └── reference/      # API 参考
+├── AGENTS.md            # 主入口文档（AI Agent 必读）
+└── .ai/                 # 详细文档目录
+    ├── guides/          # 开发指南
+    ├── rules/           # 开发规则
+    ├── examples/        # 代码示例
+    └── reference/       # API 参考
 ```

package/dist/template-empty/README.md

@@ -1,6 +1,6 @@
 # Empty Doubao Apps Template
 
-A minimal template for creating Doubao Apps without example pages.
+A minimal Doubao Apps template for starting from scratch.
 
 ## Getting Started
 
@@ -14,24 +14,71 @@ pnpm dev
 
 ## Project Structure
 
-```
+```text
 src/
-├── app.ts       # App entry point with lifecycle hooks
-└── pages/       # Add your pages here
+├── app.config.ts  # App, Page, and Widget metadata
+├── app.ts         # App lifecycle entry
+└── pages/         # Add your pages here
+```
+
+## Metadata Entry
+
+Use `src/app.config.ts` as the metadata source of truth.
+
+```ts
+import { defineAppConfig } from '@doubao-apps/kit';
+
+export default defineAppConfig({
+  appId: 'com.example.demo',
+  name: 'Demo App',
+  pages: {
+    'pages/home': {
+      id: 'home',
+      title: 'Home',
+      description: 'Home page'
+    }
+  }
+});
 ```
 
 ## Creating Pages
 
-Create a new file in `src/pages/` directory:
+1. Create a page file under `src/pages/`.
+2. Register its metadata in `src/app.config.ts`.
 
 ```tsx
-// src/pages/my-page/index.tsx
+// src/pages/home/index.tsx
 import { definePage } from '@doubao-apps/framework';
 
-export default definePage(() => {
-  return <view>
-    <text>Hello World!</text>
-  </view>;
+import './index.scss';
+
+function HomePage() {
+  return (
+    <view>
+      <text>Hello World!</text>
+    </view>
+  );
+}
+
+export default definePage({
+  render() {
+    return <HomePage />;
+  }
+});
+```
+
+```ts
+// src/app.config.ts
+import { defineAppConfig } from '@doubao-apps/kit';
+
+export default defineAppConfig({
+  pages: {
+    'pages/home': {
+      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.25"
+    "@doubao-apps/framework": "^0.0.27"
   },
   "devDependencies": {
-    "@doubao-apps/kit": "^0.0.25",
+    "@doubao-apps/kit": "^0.0.27",
     "typescript": "5.5.3"
   },
   "version": "0.0.16"

package/dist/template-empty/src/app.config.ts

@@ -0,0 +1,6 @@
+import { defineAppConfig } from '@doubao-apps/kit';
+
+export default defineAppConfig({
+  appId: '<%= appId %>',
+  name: '<%= name %>'
+});

package/dist/template-empty/src/app.ts

@@ -1,12 +1,6 @@
 import { defineApp } from '@doubao-apps/framework';
 
-// Define AI Metadata
 export default defineApp({
-  aiMeta: {
-    package: '<%= appId %>',
-    name: '<%= name %>'
-  },
-  // Watch life cycle
   onLaunch() {
     console.log('App launched');
   },

package/dist/template-empty/tsconfig.json

@@ -6,6 +6,8 @@
     "jsxImportSource": "@doubao-apps/framework",
     "esModuleInterop": true,
     "resolveJsonModule": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
     "lib": ["ES2020", "DOM"],
     "paths": {
       "@/*": ["./src/*"]

package/dist/template-starter/.ai/examples/common-patterns.md

@@ -388,62 +388,73 @@ function UserProfile({ userId }) {
 ### 1. 打开新页面
 
 ```tsx
-import { close, openPage, openPopup } from '@doubao-apps/framework/api';
+import { navigateTo, redirectTo, reLaunch } from '@doubao-apps/framework/api';
 
-// 打开全屏页面
+// 保留当前页面，打开详情页
 function openFullPage() {
-  openPage({
-    pageId: 'user-profile',
-    pageData: JSON.stringify({ userId: '12345' }),
-    context: {},
-    pageSettings: {
-      title: '用户资料'
-    }
+  navigateTo({
+    url: 'user-profile?userId=12345'
   });
 }
 
-// 打开弹窗页面
-function openSettingsPopup() {
-  openPopup({
-    pageId: 'settings',
-    context: {},
-    pageSettings: {
-      title: '设置',
-      heightPercent: 60 // 高度百分比，范围 (0, 100]
-    }
+// 替换当前页面
+function openSettingsPage() {
+  redirectTo({
+    url: 'settings'
+  });
+}
+
+// 清空页面栈并回到首页
+function relaunchHome() {
+  reLaunch({
+    url: 'home'
   });
 }
 ```
 
+这里的 `url` 直接使用目标页面的 `pageId`，与页面的 `aiMeta.id` 一致；如需传参，可继续拼接 query string。
+
 ### 2. 页面间传参
 
 ```tsx
+import { navigateTo } from '@doubao-apps/framework/api';
+
+function buildPageUrl(pageId: string, params: Record<string, string | number | boolean>) {
+  const query = Object.entries(params)
+    .map(([key, value]) => `${encodeURIComponent(key)}=${encodeURIComponent(String(value))}`)
+    .join('&');
+
+  return query ? `${pageId}?${query}` : pageId;
+}
+
 // 发送方
 function navigateWithParams() {
-  openPage({
-    pageId: 'detail-page',
-    pageData: JSON.stringify({
+  navigateTo({
+    url: buildPageUrl('detail-page', {
       id: '123',
       name: '商品名称',
       price: 99.99
-    }),
-    context: {}
+    })
   });
 }
 
 // 接收方 (detail-page)
 import { getViewData } from '@doubao-apps/framework';
 
+interface DetailPageInput {
+  id: string;
+  name: string;
+  price: number;
+}
+
 export default definePage({
   aiMeta: {
     id: 'detail-page',
     title: '详情页'
   },
   render() {
-    // 使用 getViewData 获取传递的参数
-    const viewData = getViewData();
-    const params = JSON.parse(viewData.pageData || '{}');
-    const { id, name, price } = params;
+    // getViewData() 直接返回传入页面的最终对象
+    const { id, name, price } = getViewData<DetailPageInput>();
 
     return (
       <view>
@@ -456,24 +467,29 @@ export default definePage({
 });
 ```
 
-### 3. 关闭页面
+### 3. 返回上一页
 
 ```tsx
-import { close } from '@doubao-apps/framework/api';
+import { navigateBack } from '@doubao-apps/framework/api';
 
 function closeCurrentPage() {
-  close(); // 关闭当前页面
+  navigateBack();
 }
 ```
 
 ### 4. 页面栈管理
 
 ```tsx
-import { close } from '@doubao-apps/framework/api';
+import { navigateBack } from '@doubao-apps/framework/api';
 
 // 场景 1: 返回上一页
 function goBack() {
-  close();
+  navigateBack();
+}
+
+// 场景 2: 返回多级页面
+function goBackTwoPages() {
+  navigateBack({ delta: 2 });
 }
 ```
 
@@ -509,13 +525,12 @@ export default definePage({
 ### 6. 九宫格页面导航
 
 ```tsx
+import { navigateTo } from '@doubao-apps/framework/api';
+
 // 打开九宫格页面
 function openGridPage() {
-  openPage({
-    pageId: 'app-grid',
-    pageSettings: {
-      title: '应用中心'
-    }
+  navigateTo({
+    url: 'app-grid'
   });
 }
 
@@ -538,12 +553,7 @@ export default definePage({
           <view
             key={app.id}
             className="grid-item"
-            onClick={() =>
-              openPage({
-                pageId: app.id,
-                context: {}
-              })
-            }
+            onClick={() => navigateTo({ url: app.id })}
           >
             <text className="icon">{app.icon}</text>
             <text className="name">{app.name}</text>

package/dist/template-starter/.ai/examples/component-basics.md

@@ -358,23 +358,6 @@ function WeatherCard({ city }: WeatherWidgetInput) {
 }
 
 export default defineWidget({
-  aiMeta: {
-    id: 'weather-card',
-    name: '天气卡片',
-    description: '显示指定城市的天气信息',
-    boxType: 'inbox',
-    input: {
-      type: 'object',
-      properties: {
-        city: {
-          type: 'string',
-          title: '城市名称',
-          description: '要查询天气的城市'
-        }
-      },
-      required: ['city']
-    }
-  },
   onMounted() {
     console.log('卡片挂载');
   },