@doubao-apps/create 0.0.25 → 0.0.27

package/dist/template-starter/.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-starter/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-starter/README.md

@@ -45,7 +45,8 @@ pnpm run analyze
 ├── package.json          # 依赖管理
 ├── tsconfig.json         # TypeScript 配置
 ├── src/
-│   ├── app.ts            # 应用入口
+│   ├── app.config.ts     # App / Page / Widget metadata
+│   ├── app.ts            # 应用生命周期入口
 │   ├── pages/            # 页面组件目录
 │   │   └── home/
 │   │       ├── index.tsx
@@ -57,6 +58,10 @@ pnpm run analyze
 └── debug-scene/          # 调试场景配置
 ```
 
+### metadata 配置
+
+项目中的 App、Page 和 Widget metadata 统一写在 `src/app.config.ts`，`src/app.ts` 和各页面/卡片入口只负责生命周期与渲染逻辑。
+
 ---
 
 ## 🤖 AI 开发支持

package/dist/template-starter/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-starter/src/app.config.ts

@@ -0,0 +1,35 @@
+import { defineAppConfig } from '@doubao-apps/kit';
+
+export default defineAppConfig({
+  appId: '<%= appId %>',
+  name: '<%= name %>',
+  pages: {
+    'pages/home': {
+      id: 'home',
+      title: 'Doubao Apps SDK',
+      description: 'Doubao Apps SDK 欢迎页面'
+    },
+    'pages/react-lynx': {
+      id: 'react-lynx',
+      title: 'React Lynx',
+      description: '基于 React 的 UI 开发框架介绍'
+    },
+    'pages/lynx': {
+      id: 'lynx',
+      title: 'Lynx',
+      description: '高性能跨平台 UI 引擎介绍'
+    },
+    'pages/applet': {
+      id: 'applet',
+      title: 'Applet',
+      description: '小程序开发模板介绍'
+    }
+  },
+  widgets: {
+    'widgets/weather-card': {
+      id: 'weather-card',
+      name: 'Weather Card',
+      description: '显示当前天气信息的卡片组件'
+    }
+  }
+});

package/dist/template-starter/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-starter/src/pages/applet/index.tsx

@@ -66,11 +66,6 @@ function AppletPage() {
 }
 
 export default definePage({
-  aiMeta: {
-    id: 'applet',
-    title: 'Applet',
-    description: '小程序开发模板介绍'
-  },
   onShow() {
     console.log('Applet page shown');
   },

package/dist/template-starter/src/pages/home/index.tsx

@@ -87,11 +87,6 @@ function HomePage() {
 }
 
 export default definePage({
-  aiMeta: {
-    id: 'home',
-    title: 'Doubao Apps SDK',
-    description: 'Doubao Apps SDK 欢迎页面'
-  },
   onShow() {
     console.log('Home page shown');
   },

package/dist/template-starter/src/pages/lynx/index.tsx

@@ -66,10 +66,6 @@ function LynxPage() {
 }
 
 export default definePage({
-  aiMeta: {
-    id: 'lynx',
-    description: '高性能跨平台 UI 引擎介绍'
-  },
   onShow() {
     console.log('Lynx page shown');
   },

package/dist/template-starter/src/pages/react-lynx/index.tsx

@@ -120,11 +120,6 @@ function ReactLynxPage() {
 }
 
 export default definePage({
-  aiMeta: {
-    id: 'react-lynx',
-    title: 'React Lynx',
-    description: '基于 React 的 UI 开发框架介绍'
-  },
   onShow() {
     console.log('React Lynx page shown');
   },

package/dist/template-starter/src/widgets/weather-card/index.tsx

@@ -175,10 +175,6 @@ function WeatherCard() {
 }
 
 export default defineWidget({
-  aiMeta: {
-    id: 'weather-card',
-    description: '显示当前天气信息的卡片组件'
-  },
   onShow() {
     console.log('Weather card shown');
   },

package/dist/template-starter/tsconfig.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@doubao-apps/create",
-  "version": "0.0.25",
+  "version": "0.0.27",
   "description": "Create Doubao Apps projects with a single command",
   "type": "module",
   "bin": {