@doubao-apps/ai 0.0.26 → 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

@@ -7,7 +7,7 @@ description:
   当用户开发豆包应用、创建页面或卡片组件、调用端能力 API 时使用此技能。
 ---
 
-# SKILL.md - Doubao Apps SDK AI 开发指南
+# Doubao Apps SDK AI 开发指南
 
 本文件专供 AI coding agents（如 Claude、Copilot、Cursor）和开发者使用，提供 Doubao Apps SDK 框架的快速入门、开发规则和文档导航。
 
@@ -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>;
   }
 });
@@ -218,7 +247,6 @@ API 参考文档
 - **[组件库](.ai/reference/components-quick-ref.md)** - SDK 内置组件速查
 - **[Open API](.ai/reference/open-api/README.md)** - 系统能力 API 目录与详细文档
 
-
 ### 依赖包
 
 - **Framework**：`@doubao-apps/framework` - 核心框架
@@ -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.26",
+  "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",

package/dist/skills/doubao-apps-dev/.ai/reference/open-api/05-ui-/350/276/223/345/205/245.md

@@ -1,95 +0,0 @@
-# Open API: UI / 输入
-
-键盘和输入框选区能力。
-
-[返回目录](./README.md) | [返回速查](../open-api.md)
-
-## 速查
-
-| API | 签名 | 用途 | 参数类型 | 结果类型 | 注意点 |
-| --- | --- | --- | --- | --- | --- |
-| [`onKeyboardHeightChange`](#onkeyboardheightchange) | `onKeyboardHeightChange(handler): () => void` | 监听键盘高度变化事件 | `handler` | `() => void` | 返回取消监听函数 |
-| [`hideKeyboard`](#hidekeyboard) | `hideKeyboard(params?): Promise<object>` | 收起键盘 | `params?` | `Promise<object>` | - |
-| [`getSelectedTextRange`](#getselectedtextrange) | `getSelectedTextRange(params?): Promise<GetSelectedTextRangeResult>` | 获取当前输入框的选区范围 | `params?` | `Promise<GetSelectedTextRangeResult>` | - |
-
-## API 详情
-
-<a id="onkeyboardheightchange"></a>
-### onKeyboardHeightChange()
-
-> **onKeyboardHeightChange**(`handler`): () => `void`
-
-监听键盘高度变化事件。
-
-#### Parameters
-
-• **handler**
-
-#### Returns
-
-`Function`
-
-##### Returns
-
-`void`
-
-#### Example
-
-```typescript
-import { onKeyboardHeightChange } from '@doubao-apps/framework/api';
-
-const unsubscribe = onKeyboardHeightChange(({ height }) => {
-  console.log('Keyboard height change event:', { height });
-});
-```
-
-<a id="hidekeyboard"></a>
-### hideKeyboard()
-
-> **hideKeyboard**(`params`?): `Promise`\<`object`\>
-
-收起键盘。
-
-#### Parameters
-
-• **params?**
-
-#### Returns
-
-`Promise`\<`object`\>
-
-<a id="getselectedtextrange"></a>
-### getSelectedTextRange()
-
-> **getSelectedTextRange**(`params`?): `Promise`\<[`GetSelectedTextRangeResult`](#getselectedtextrangeresult)\>
-
-获取当前输入框的选区范围。
-
-#### Parameters
-
-• **params?**
-
-#### Returns
-
-`Promise`\<[`GetSelectedTextRangeResult`](#getselectedtextrangeresult)\>
-
-## 相关类型
-
-<a id="getselectedtextrangeresult"></a>
-### GetSelectedTextRangeResult
-
-获取输入框选区范围的返回结果。
-
-#### Properties
-
-##### end
-
-> **end**: `number`
-
-选区结束位置。
-
-##### start
-
-> **start**: `number`
-
-选区起始位置。