@doubao-apps/ai 0.0.25 → 0.0.27

package/dist/contexts/doubao-apps-dev/.ai/rules/dos-and-donts.md

@@ -0,0 +1,390 @@
+# 开发规则 - Do's and Don'ts
+
+Doubao Apps SDK 框架的开发规则和最佳实践。
+
+---
+
+## ✅ 推荐做法（Do's）
+
+### 项目管理
+
+#### ✅ 使用 pnpm 包管理器
+```bash
+# 推荐
+pnpm install
+pnpm add @doubao-apps/framework
+
+# 不推荐（除非项目已使用 npm）
+npm install
+npm install @doubao-apps/framework
+```
+
+
+### 组件开发
+
+#### ✅ 定义完整的 aiMeta
+```tsx
+// ✅ 好的做法
+export default definePage({
+  aiMeta: {
+    id: 'user-profile',
+    title: '用户资料',
+    description: '展示和编辑用户个人资料'
+  },
+  // ...
+});
+```
+
+```tsx
+// ❌ 不好的做法
+export default definePage({
+  aiMeta: {
+    id: 'page1'  // 缺少 title、description 等信息
+  },
+  // ...
+});
+```
+
+#### ✅ 分离样式文件
+```tsx
+// ✅ 好的做法
+// index.tsx
+import './index.scss';
+
+export default definePage({
+  // ...
+});
+```
+
+```scss
+// index.scss
+.container {
+  padding: 16px;
+  background: #fff;
+}
+```
+
+```tsx
+// ❌ 不好的做法
+export default definePage({
+  render() {
+    return (
+      <view style={{ padding: '16px', background: '#fff' }}>
+        内容
+      </view>
+    );
+  }
+});
+```
+
+#### ✅ 使用 TypeScript 类型定义
+```tsx
+// ✅ 好的做法
+interface UserInfo {
+  name: string;
+  age: number;
+  avatar?: string;
+}
+
+export default defineWidget({
+  render() {
+    const input = getViewData<UserInfo>();
+    return <view>{input.name}</view>;
+  }
+});
+```
+
+```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({
+  render() {
+    const input = getViewData<any>();  // 使用 any 类型，失去类型检查
+    return <view>{input.name}</view>;
+  }
+});
+```
+
+#### ✅ 使用生命周期钩子
+```tsx
+// ✅ 好的做法
+export default definePage({
+  aiMeta: { /* ... */ },
+
+  onShow() {
+    console.log('Page shown');
+  },
+
+  onHide() {
+    console.log('Page hidden');
+  },
+
+  onDestroy() {
+    console.log('Page destroyed');
+  },
+
+  render() {
+    return <view>内容</view>;
+  }
+});
+```
+
+
+#### ✅ 错误处理和边界情况
+```tsx
+// ✅ 好的做法
+export default defineWidget({
+  render() {
+    const input = getViewData<{ items: string[] }>();
+    // 处理空数据
+    if (!input.items || input.items.length === 0) {
+      return <view>暂无数据</view>;
+    }
+
+    return (
+      <view>
+        {input.items.map((item, index) => (
+          <view key={index}>{item}</view>
+        ))}
+      </view>
+    );
+  }
+});
+```
+
+```tsx
+// ❌ 不好的做法
+export default defineWidget({
+  render() {
+    const input = getViewData<any>();
+    // 没有检查 input.items 是否存在
+    return (
+      <view>
+        {input.items.map(item => <view>{item}</view>)}
+      </view>
+    );
+  }
+});
+```
+
+
+
+## ❌ 禁止做法（Don'ts）
+
+### 样式相关
+
+#### ❌ 内联样式长度值必须带单位
+
+Lynx CSS encoder 要求：**所有 CSS 长度值必须显式带单位**，裸数字（无单位）会触发运行时错误 `CSS length need units (except 0)`。
+
+```tsx
+// ❌ 错误：裸数字（无单位）
+<view style={{ width: 100, height: 56, fontSize: 14 }} />
+
+// ✅ 正确：带单位字符串
+<view style={{ width: '100px', height: '56px', fontSize: '14px' }} />
+
+// ✅ 例外：以下属性可以使用裸数字（无单位）
+// flex, opacity, zIndex, fontWeight, aspectRatio
+<view style={{ flex: 1, opacity: 0.5, zIndex: 10 }} />
+```
+
+#### ❌ 不写内联样式
+```tsx
+// ❌ 错误
+export default definePage({
+  render() {
+    return (
+      <view style={{ padding: 16, background: '#fff' }}>
+        内容
+      </view>
+    );
+  }
+});
+```
+
+```tsx
+// ✅ 正确
+import './index.scss';
+
+export default definePage({
+  render() {
+    return (
+      <view className="container">
+        内容
+      </view>
+    );
+  }
+});
+```
+
+### 异步操作
+
+#### ❌ 不在 render 中发起请求
+```tsx
+// ❌ 错误 - 每次渲染都会发请求
+export default definePage({
+  render() {
+    fetch('/api/data').then(data => {
+      // 处理数据
+    });
+
+    return <view>内容</view>;
+  }
+});
+```
+
+```tsx
+// ✅ 推荐 - 使用 Hook 管理请求和状态
+import { useEffect, useState } from '@doubao-apps/framework';
+
+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 <UserPage />;
+  }
+});
+```
+
+### 组件结构
+
+#### ❌ 不过度嵌套组件
+```tsx
+// ❌ 错误 - 过度嵌套
+export default definePage({
+  render() {
+    return (
+      <view>
+        <view>
+          <view>
+            <view>
+              <view>
+                <view>
+                  内容
+                </view>
+              </view>
+            </view>
+          </view>
+        </view>
+      </view>
+    );
+  }
+});
+```
+
+```tsx
+// ✅ 正确 - 扁平结构
+export default definePage({
+  render() {
+    return (
+      <view className="page">
+        <view className="header">头部</view>
+        <view className="content">内容</view>
+        <view className="footer">底部</view>
+      </view>
+    );
+  }
+});
+```
+
+### 类型使用
+
+#### ❌ 不忽略 TypeScript 类型
+```tsx
+// ❌ 错误
+export default defineWidget({
+  render() {
+    const input = getViewData<any>();
+    // @ts-ignore
+    return <view>{input.unknownProperty}</view>;
+  }
+});
+```
+
+```tsx
+// ✅ 正确
+interface Input {
+  name: string;
+  age: number;
+}
+
+export default defineWidget({
+  render() {
+    const input = getViewData<Input>();
+    return <view>{input.name}</view>;
+  }
+});
+```
+
+### 状态管理
+
+#### ❌ 不在全局作用域定义状态
+```tsx
+// ❌ 错误 - 全局变量会在多个实例间共享
+let count = 0;
+
+export default defineWidget({
+  render() {
+    count++;  // 所有实例共享这个 count
+    return <view>Count: {count}</view>;
+  }
+});
+```
+
+```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({
+  render() {
+    return <CounterWidget />;
+  }
+});
+```
+
+## 📚 相关文档
+
+- [组件开发指南](../guides/component-development.md)
+- [最佳实践](../guides/best-practices.md)
+- [性能优化](../guides/performance-optimization.md)

package/dist/{skills → contexts}/doubao-apps-dev/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
-
 ```
 
 **开发服务器命令**：
@@ -67,9 +66,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 提供类型定义
 - **错误处理**：处理边界情况和错误状态
 
 ### 禁止做法
@@ -93,22 +92,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>;
   }
 });
 ```
@@ -119,28 +133,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>;
   }
 });
@@ -172,7 +196,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 等）
 
 包含：
@@ -207,8 +231,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 目录与详细文档
 
 ### 依赖包
 
@@ -244,10 +267,10 @@ API 参考文档
 
 ```
 项目根目录/
-├── AGENTS.md   # 主入口文档（AI Agent 必读）
-└── .ai/                # 详细文档目录
-    ├── guides/         # 开发指南
-    ├── rules/          # 开发规则
-    ├── examples/       # 代码示例
-    └── reference/      # API 参考
+├── AGENTS.md            # 主入口文档（AI Agent 必读）
+└── .ai/                 # 详细文档目录
+    ├── guides/          # 开发指南
+    ├── rules/           # 开发规则
+    ├── examples/        # 代码示例
+    └── reference/       # API 参考
 ```

package/dist/{skills → contexts}/doubao-apps-dev/CLAUDE.md

@@ -16,7 +16,7 @@
 | 性能优化 | [.ai/guides/performance-optimization.md](.ai/guides/performance-optimization.md) |
 | 问题排查 | [.ai/guides/troubleshooting.md](.ai/guides/troubleshooting.md) |
 | Framework API | [.ai/reference/framework-api-quick-ref.md](.ai/reference/framework-api-quick-ref.md) |
-| Bridge API / 系统能力 | [.ai/reference/open-api.md](.ai/reference/open-api.md) |
+| Bridge API / 系统能力 | [.ai/reference/open-api/README.md](.ai/reference/open-api/README.md) |
 
 ## 知识库结构
 

package/dist/manifest.json

@@ -0,0 +1,45 @@
+{
+  "packageName": "@byted-doubao-apps/ai-assets",
+  "version": "0.0.27",
+  "generatedAt": "2026-05-12T09:32:17.292Z",
+  "skills": [
+    {
+      "name": "doubao-apps-dev",
+      "entry": "skills/doubao-apps-dev/SKILL.md",
+      "hasAiDir": true
+    },
+    {
+      "name": "douyin-to-doubao",
+      "entry": "skills/douyin-to-doubao/SKILL.md",
+      "hasAiDir": false
+    },
+    {
+      "name": "h5-to-doubao",
+      "entry": "skills/h5-to-doubao/SKILL.md",
+      "hasAiDir": false
+    },
+    {
+      "name": "quality-gate",
+      "entry": "skills/quality-gate/SKILL.md",
+      "hasAiDir": false
+    },
+    {
+      "name": "uniapp-to-doubao",
+      "entry": "skills/uniapp-to-doubao/SKILL.md",
+      "hasAiDir": false
+    },
+    {
+      "name": "weixin-to-doubao",
+      "entry": "skills/weixin-to-doubao/SKILL.md",
+      "hasAiDir": false
+    }
+  ],
+  "contexts": [
+    {
+      "name": "doubao-apps-dev",
+      "entry": "contexts/doubao-apps-dev/AGENTS.md",
+      "claudeEntry": "contexts/doubao-apps-dev/CLAUDE.md",
+      "hasAiDir": true
+    }
+  ]
+}