@doubao-apps/ai 0.0.25 → 0.0.27

package/dist/skills/doubao-apps-dev/.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/skills/doubao-apps-dev/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: doubao-apps-dev
-description: >
+description:
   Doubao Apps SDK (框架/framework) 开发指南。用于开发豆包小程序应用，
   包含 Page（页面）、Widget（卡片）组件开发、Bridge API 系统能力调用、生命周期管理等。
   基于 React Lynx 框架，使用 TSX/JSX 语法和 React Hooks 开发模式，并且提供了内置 UI 组件开箱即用。
@@ -35,12 +35,17 @@ Doubao Apps SDK 是豆包应用开发框架，基于 React Lynx 框架提供完
 ### 3. 创建项目
 
 ```bash
+# 使用 create 创建一个 empty 工程，注意，使用正式的项目文件夹名
+npm create @byted-doubao-apps my-doubao-app -- --template empty -y
+
+# 进入项目目录
+cd my-doubao-app
+
 # 安装依赖
 pnpm install
 
 # 启动开发
 pnpm dev
-
 ```
 
 **开发服务器命令**：
@@ -53,7 +58,6 @@ pnpm dev
 
 ```
 my-doubao-app/
-├── doubao.config.ts      # 项目配置
 ├── package.json          # 依赖管理
 ├── pnpm-lock.yaml        # 依赖锁定
 └── src/
@@ -76,9 +80,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 提供类型定义
 - **错误处理**：处理边界情况和错误状态
 
 ### 禁止做法
@@ -102,22 +106,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>;
   }
 });
 ```
@@ -128,28 +147,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>;
   }
 });
@@ -181,7 +210,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 等）
 
 包含：
@@ -216,8 +245,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 目录与详细文档
 
 ### 依赖包
 
@@ -253,7 +281,7 @@ API 参考文档
 
 ```
 <skill-directory>/
-├── SKILL.md    # 主入口文档（AI Agent 必读）
+├── SKILL.md            # 主入口文档（AI Agent 必读）
 └── .ai/                # 详细文档目录
     ├── guides/         # 开发指南
     ├── rules/          # 开发规则

package/dist/skills/douyin-to-doubao/SKILL.md

@@ -108,8 +108,8 @@ npx @doubao-apps/ai skills add doubao-apps-dev --agent codex
 依次检测以下路径，取第一个存在的作为 `$SKILLS_BASE`：
 
 ```bash
-ls .agents/skills/doubao-apps-dev/AGENTS.md 2>/dev/null && echo "SKILLS_BASE=.agents/skills/doubao-apps-dev"
-ls .claude/skills/doubao-apps-dev/AGENTS.md 2>/dev/null && echo "SKILLS_BASE=.claude/skills/doubao-apps-dev"
+ls .agents/skills/doubao-apps-dev/SKILL.md 2>/dev/null && echo "SKILLS_BASE=.agents/skills/doubao-apps-dev"
+ls .claude/skills/doubao-apps-dev/SKILL.md 2>/dev/null && echo "SKILLS_BASE=.claude/skills/doubao-apps-dev"
 ```
 
 **2. 如未安装，执行安装**

package/dist/skills/h5-to-doubao/SKILL.md

@@ -140,10 +140,10 @@ view {
 
 ```bash
 # Claude Code 优先
-ls .claude/skills/doubao-apps-dev/AGENTS.md 2>/dev/null && echo "SKILLS_BASE=.claude/skills/doubao-apps-dev"
+ls .claude/skills/doubao-apps-dev/SKILL.md 2>/dev/null && echo "SKILLS_BASE=.claude/skills/doubao-apps-dev"
 
 # 其他 Agent（Cursor 等）
-ls .agent/skills/doubao-apps-dev/AGENTS.md 2>/dev/null && echo "SKILLS_BASE=.agent/skills/doubao-apps-dev"
+ls .agent/skills/doubao-apps-dev/SKILL.md 2>/dev/null && echo "SKILLS_BASE=.agent/skills/doubao-apps-dev"
 ```
 
 **2. 如未安装，执行安装**：

package/dist/skills/uniapp-to-doubao/SKILL.md

@@ -109,8 +109,8 @@ npx @doubao-apps/ai skills add doubao-apps-dev --agent codex
 依次检测以下路径，取第一个存在的作为 `$SKILLS_BASE`：
 
 ```bash
-ls .agents/skills/doubao-apps-dev/AGENTS.md 2>/dev/null && echo "SKILLS_BASE=.agents/skills/doubao-apps-dev"
-ls .claude/skills/doubao-apps-dev/AGENTS.md 2>/dev/null && echo "SKILLS_BASE=.claude/skills/doubao-apps-dev"
+ls .agents/skills/doubao-apps-dev/SKILL.md 2>/dev/null && echo "SKILLS_BASE=.agents/skills/doubao-apps-dev"
+ls .claude/skills/doubao-apps-dev/SKILL.md 2>/dev/null && echo "SKILLS_BASE=.claude/skills/doubao-apps-dev"
 ```
 
 **2. 如未安装，执行安装**

package/dist/skills/weixin-to-doubao/SKILL.md

@@ -78,10 +78,10 @@ description: Migrate WeChat Mini Program (微信小程序) projects to Doubao Ap
 
 ```bash
 # Claude Code 优先
-ls .claude/skills/doubao-apps-dev/AGENTS.md 2>/dev/null && echo "SKILLS_BASE=.claude/skills/doubao-apps-dev"
+ls .claude/skills/doubao-apps-dev/SKILL.md 2>/dev/null && echo "SKILLS_BASE=.claude/skills/doubao-apps-dev"
 
 # 其他 Agent（Cursor 等）
-ls .agent/skills/doubao-apps-dev/AGENTS.md 2>/dev/null && echo "SKILLS_BASE=.agent/skills/doubao-apps-dev"
+ls .agent/skills/doubao-apps-dev/SKILL.md 2>/dev/null && echo "SKILLS_BASE=.agent/skills/doubao-apps-dev"
 ```
 
 **2. 如未安装，执行安装**：

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@doubao-apps/ai",
-  "version": "0.0.25",
+  "version": "0.0.27",
   "description": "Doubao Apps SDK AI tools with context and skills management",
   "type": "module",
   "bin": {
@@ -16,7 +16,9 @@
       "import": "./dist/cli.js",
       "types": "./dist/cli.d.ts"
     },
-    "./skills/*": "./dist/skills/*"
+    "./manifest": "./dist/manifest.json",
+    "./skills/*": "./dist/skills/*",
+    "./contexts/*": "./dist/contexts/*"
   },
   "files": [
     "bin.js",