@doubao-apps/create 0.0.33 → 0.0.34

package/dist/template-starter/README.md

@@ -1,204 +1,83 @@
-# Doubao Apps SDK 项目
+# Doubao Apps SDK Starter
 
-豆包应用开发项目。
+这是一个 Doubao Apps SDK 起始模板，包含一个 Page、一个 Widget 和最小入口配置。
 
----
-
-## 🚀 快速开始
-
-### 安装依赖
+## 快速开始
 
 ```bash
 pnpm install
-```
-
-### 启动开发
-
-```bash
-# 启动开发服务器
 pnpm run dev
 ```
 
-开发服务器启动后，可以使用以下命令：
-- 输入 `d` - 选择场景/页面/卡片运行
-- 输入 `<scene-name>` - 运行指定场景
-- 输入 `<page-id>` - 运行指定页面
-- 输入 `<widget-id>` - 运行指定卡片
+开发服务器启动后，可以输入页面或卡片 id 运行指定视图。
 
-### 构建部署
+## 构建
 
 ```bash
-# 构建项目
 pnpm run build
-
-
-# 分析构建产物
-pnpm run analyze
 ```
 
----
-
-## 📂 项目结构
+## 项目结构
 
-```
+```text
 .
 ├── package.json          # 依赖管理
 ├── tsconfig.json         # TypeScript 配置
-├── src/
-│   ├── app.config.ts     # App / Page / Widget metadata
-│   ├── app.ts            # 应用生命周期入口
-│   ├── pages/            # 页面组件目录
-│   │   └── home/
-│   │       ├── index.tsx
-│   │       └── index.scss
-│   └── widgets/          # 卡片组件目录
-│       └── hello-world/
-│           ├── index.tsx
-│           └── index.scss
-└── debug-scene/          # 调试场景配置
+└── src/
+    ├── app.ts            # 应用入口
+    ├── app.config.ts     # 应用配置
+    ├── mcp-ui/           # 可选登录、隐私等协议页面
+    ├── pages/            # 页面目录
+    │   └── home/
+    │       ├── index.tsx
+    │       └── index.scss
+    └── widgets/          # 卡片目录
+        └── hello-world/
+            ├── index.tsx
+            └── index.scss
 ```
 
-### metadata 配置
-
-项目中的 App、Page 和 Widget metadata 统一写在 `src/app.config.ts`，`src/app.ts` 和各页面/卡片入口只负责生命周期与渲染逻辑。
-
----
+## App 配置
 
-## 🤖 AI 开发支持
+`src/app.config.ts` 默认只声明 App 信息和 Page / Widget 入口。标题、描述、自定义 id 等业务 metadata 按需再补。
 
-本项目已集成 AI 开发知识库，帮助 AI 工具（Claude、Copilot、Cursor）更好地理解框架并辅助开发。
+```ts
+import { defineAppConfig } from '@doubao-apps/kit';
 
-### 📖 知识库文档
-
-项目包含以下 AI 友好的文档：
-
-- **AGENTS.md** - AI Agent 主入口，包含框架概览和导航
-- **references/** - 详细开发文档目录
-  - `guides/` - 开发指南和最佳实践
-  - `examples/` - 代码示例
-  - `rules/` - 开发规范
-  - `reference/` - API 快速参考
-
-### 🎯 使用 AI 工具开发
-
-#### 1. 安装 AI 上下文与 Skills（推荐）
-
-如果你希望在项目中配套安装 Doubao Apps 的 AI 知识库与技能，可使用 CLI：
-
-```bash
-npm install -g @doubao-apps/ai
-
-# 安装到指定 Agent 的 skill
-doubao-cli skills add doubao-apps-dev --agent codex
+export default defineAppConfig({
+  appId: 'db_xxxxxx',
+  name: '我的豆包应用',
+  pages: ['pages/home/index'],
+  widgets: ['widgets/hello-world/index']
+});
 ```
 
-其中 `doubao-cli skills add <skill1> [skill2...] --agent <agent>` 用于将一个或多个 skills 安装到指定 AI Agent 的 skills 目录中，适合补充项目开发规范、最佳实践和 API 参考。
+需要页面标题、卡片名称、描述、多级目录或稳定入口顺序时，再把字符串入口改成对象写法。
 
-- `--agent`：指定目标 Agent，例如 `codex`、`cursor`、`claude-code`
-- `--global`：全局安装到用户目录，而不是当前项目目录
-- `doubao-cli skills list`：查看当前可用的 skills
-- `doubao-cli skills update [--global]`：更新已安装的 skills
+## AI 开发支持
 
-常见示例：
+创建项目时如果选择 AI 支持，Create CLI 会在当前项目目录自动安装 `doubao-apps-dev` Skill 到所选 AI Agent。
 
-```bash
-# 给 Codex 安装 Doubao Apps 开发 skill
-doubao-cli skills add doubao-apps-dev --agent codex
+如果创建时没有选择 AI 支持，或需要给其他 Agent 补装 Skill，可以在当前项目目录执行：
 
-# 一次安装多个 skills
-doubao-cli skills add doubao-apps-dev quality-gate --agent claude-code
+```bash
+# 给指定 Agent 安装 Doubao Apps 开发 Skill
+npx @doubao-apps/ai skills add doubao-apps-dev --agent claude-code
 
 # 全局安装到用户目录
-doubao-cli skills add doubao-apps-dev --agent claude-code --global
-```
+npx @doubao-apps/ai skills add doubao-apps-dev --agent claude-code --global
 
-安装后会生成 Agent 对应的 skills 目录，用于提供开发规则、示例和 API 参考。
-
-#### 2. 高效提问技巧
-
-**✅ 清晰明确的问题**：
-- "创建一个天气卡片 Widget，展示温度和天气图标"
-- "如何在 Page 中调用 Bridge API 获取用户信息？"
-- "优化这个组件的渲染性能"
-- "添加错误处理和加载状态"
-
-**❌ 模糊的问题**：
-- "帮我写个页面"
-- "这个怎么做"
-- "优化代码"
-- "修复 bug"
-
-#### 3. AI 辅助开发流程
-
-1. **明确需求** - 清楚描述要实现的功能和预期效果
-2. **查阅文档** - 参考 `AGENTS.md` 和 `references/` 目录下的文档
-3. **请求 AI 生成** - 使用清晰的提示词让 AI 生成代码
-4. **测试验证** - 运行 `pnpm run dev` 查看效果
-5. **迭代优化** - 根据结果调整需求，继续与 AI 协作
-
-#### 4. 常用 AI 开发任务
-
-| 任务 | 文档参考 | AI 提示词示例 |
-|------|---------|--------------|
-| 创建新页面 | `references/guides/component-development.md` | "创建一个用户资料页面，包含头像、姓名、邮箱和统计数据" |
-| 创建新卡片 | `references/guides/component-development.md` | "创建一个天气卡片 Widget，接收城市名称并展示天气信息" |
-| API 集成 | `references/examples/common-patterns.md` | "调用 Bridge API 获取用户位置信息并展示在地图上" |
-| 状态管理 | `references/examples/common-patterns.md` | "使用 Context 管理全局主题状态（亮色/暗色模式）" |
-| 页面导航 | `references/examples/common-patterns.md` | "打开详情页面并传递商品 ID 参数" |
-| 性能优化 | `references/guides/performance-optimization.md` | "优化列表渲染性能，减少不必要的重新渲染" |
-| 问题排查 | `references/guides/troubleshooting.md` | "调试页面加载缓慢的问题" |
-
-### 📚 快速导航
-
-**入门学习**：
-- 📖 [AGENTS.md](./AGENTS.md) - 从这里开始
-- 🎯 [组件开发](./references/guides/component-development.md) - Page 和 Widget 完整指南
-- 💡 [组件基础](./references/examples/component-basics.md) - Page vs Widget 对比示例
-
-**实战参考**：
-- 🔧 [常用模式](./references/examples/common-patterns.md) - API 集成、状态管理、页面导航
-- 📋 [最佳实践](./references/guides/best-practices.md) - 代码规范和架构设计
-- ⚡ [性能优化](./references/guides/performance-optimization.md) - 渲染优化和内存管理
-
-**问题解决**：
-- 🔍 [故障排查](./references/guides/troubleshooting.md) - 调试技巧和常见问题
-- 📖 [API 参考](./references/reference/open-api.md) - Framework + Bridge 完整 API
-
----
-
-## 🔧 开发工具
-
-### HDT（Hybrid DevTool）
-
-推荐使用 HDT 进行调试和预览：
-
-**下载地址**：
-- macOS Apple Silicon: [下载 DMG](https://cdn-tos-cn.bytedance.net/obj/hdt2/HybridDevtool3.0/latest/darwin-universal/hdt3-darwin-universal.dmg)
-- macOS Intel: [下载 DMG](https://cdn-tos-cn.bytedance.net/obj/hdt2/HybridDevtool3.0/latest/darwin-x64/hdt3-darwin-x64.dmg)
-- Windows: [下载 EXE](https://cdn-tos-cn.bytedance.net/obj/archi/tiktok/hdt-for-windows/hdt3/latest/x64/HybridDevtool3.0-Setup-x64.exe)
-
-**功能**：
-- 实时预览应用效果
-- 调试工具和日志查看
-- 网络请求监控
-- 性能分析
-
----
-
-## 📖 相关链接
-
-- **框架文档**: [Doubao Apps SDK 文档](https://example.com/docs)
-- **Lynx 官方文档**: [https://lynx.bytedance.net/next/llms.txt](https://lynx.bytedance.net/next/llms.txt)
-- **API 参考**: 查看项目内 `references/reference/open-api.md`
-- **示例代码**: 查看项目内 `references/examples/` 目录
-
----
+# 查看和更新可用 Skills
+npx @doubao-apps/ai skills list
+npx @doubao-apps/ai skills update
+```
 
-## 🆘 获取帮助
+- `skills add` 会把指定 Skill 安装到目标 Agent 的 skills 目录。
+- `--agent` 可填写 `codex`、`cursor`、`claude-code`、`opencode`、`github-copilot` 等。
+- `--global` 表示安装到用户目录；不加时安装到当前项目目录。
 
-遇到问题？
+使用 AI 辅助开发时，建议把目标视图类型、入口路径、viewData 字段、metadata 和需要调用的端能力说清楚，例如：
 
-1. 查看 **[故障排查指南](./references/guides/troubleshooting.md)**
-2. 查阅 **[AGENTS.md](./AGENTS.md)** 获取完整文档导航
-3. 使用 AI 工具并参考 **系统提示词**配置
-4. 联系团队获取支持
+- “创建一个订单摘要 Widget，入口为 `src/widgets/order-summary/index.tsx`，从 `getViewData<T>()` 读取订单号、金额和状态。”
+- “创建一个账号设置 Page，注册到 `src/app.config.ts`，包含 `switch` 和 `slider` 的受控状态。”
+- “在页面按钮点击时调用 `showToast`，并处理 loading、success、error 状态。”

package/dist/template-starter/package.json

@@ -6,10 +6,10 @@
     "build": "doubao build"
   },
   "dependencies": {
-    "@doubao-apps/framework": "^0.0.33"
+    "@doubao-apps/framework": "^0.0.34"
   },
   "devDependencies": {
-    "@doubao-apps/kit": "^0.0.33",
+    "@doubao-apps/kit": "^0.0.34",
     "typescript": "6.0.3"
   },
   "version": "0.0.16"

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

@@ -3,7 +3,6 @@ import { defineAppConfig } from '@doubao-apps/kit';
 export default defineAppConfig({
   appId: '<%= appId %>',
   name: '<%= name %>',
-  pages: [
-    'pages/home/index' // 首页入口
-  ]
+  pages: ['pages/home/index'],
+  widgets: ['widgets/hello-world/index']
 });

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

@@ -1,197 +1,63 @@
-:root {
-  --primary-bg: #0a0a0a;
-  --secondary-bg: #1a1a1a;
-  --card-bg: #161616;
-  --primary-text: #ffffff;
-  --secondary-text: #a0a0a0;
-  --accent-text: #00d4ff;
-  --border-color: #2a2a2a;
-  --success-color: #00ff88;
-  --warning-color: #ffaa00;
-  --error-color: #ff4444;
-  
-  --space-xs: 8rpx;
-  --space-sm: 16rpx;
-  --space-md: 24rpx;
-  --space-lg: 32rpx;
-  --space-xl: 48rpx;
-  --space-xxl: 64rpx;
-  --space-xxxl: 96rpx;
-  
-  --border-radius-sm: 12rpx;
-  --border-radius-md: 16rpx;
-  --border-radius-lg: 24rpx;
-  --border-radius-xl: 32rpx;
-  
-  --shadow-sm: 0 2rpx 8rpx rgba(0, 0, 0, 0.4);
-  --shadow-md: 0 4rpx 16rpx rgba(0, 0, 0, 0.6);
-  --shadow-lg: 0 8rpx 32rpx rgba(0, 0, 0, 0.8);
-  --shadow-xl: 0 16rpx 48rpx rgba(0, 0, 0, 0.9);
-}
-
-.home {
+.home-page {
   min-height: 100vh;
-  background: var(--primary-bg);
-  position: relative;
-
-  &__background-pattern {
-    position: fixed;
-    top: 0;
-    left: 0;
-    right: 0;
-    bottom: 0;
-    background-image: 
-      radial-gradient(circle at 20% 20%, rgba(102, 126, 234, 0.1) 0%, transparent 50%),
-      radial-gradient(circle at 80% 80%, rgba(118, 75, 162, 0.1) 0%, transparent 50%),
-      radial-gradient(circle at 40% 60%, rgba(240, 147, 251, 0.05) 0%, transparent 50%);
-    z-index: 0;
-  }
-
-  &__container {
-    position: relative;
-    z-index: 1;
-    min-height: 100vh;
-    padding: var(--space-xl) var(--space-lg);
-    box-sizing: border-box;
-  }
+  padding: 48rpx 32rpx;
+  box-sizing: border-box;
+  background: #f7f8fc;
+  color: #171a24;
 
   &__header {
-    text-align: center;
-    margin-bottom: var(--space-xxxl);
-  }
-
-  &__logo {
-    margin-bottom: var(--space-lg);
+    margin-bottom: 40rpx;
   }
 
-  &__logo-icon {
-    font-size: 80rpx;
-    line-height: 1;
+  &__eyebrow {
+    display: block;
+    margin-bottom: 16rpx;
+    color: #3d67ff;
+    font-size: 24rpx;
+    font-weight: 600;
   }
 
   &__title {
-    font-size: 64rpx;
-    font-weight: 700;
-    color: var(--primary-text);
-    margin-bottom: var(--space-sm);
     display: block;
-    letter-spacing: 2rpx;
-    text-shadow: 0 2rpx 8rpx rgba(0, 0, 0, 0.3);
+    margin-bottom: 20rpx;
+    color: #171a24;
+    font-size: 44rpx;
+    font-weight: 700;
+    line-height: 1.2;
   }
 
-  &__subtitle {
-    font-size: 28rpx;
-    color: var(--secondary-text);
+  &__description {
     display: block;
-    font-weight: 400;
-    letter-spacing: 1rpx;
-  }
-
-  &__divider {
-    width: 120rpx;
-    height: 4rpx;
-    background: linear-gradient(90deg, var(--accent-text), transparent);
-    margin: var(--space-xl) 0;
-    border-radius: 2rpx;
-  }
-
-  &__list {
-    display: flex;
-    flex-direction: column;
-    gap: var(--space-lg);
-    margin-bottom: var(--space-xxl);
-    box-sizing: border-box;
-    
-    .card {
-      min-height: 160rpx;
-    }
+    color: #5d6475;
+    font-size: 28rpx;
+    line-height: 1.5;
   }
 
-  &__footer {
-    text-align: center;
-    padding-top: var(--space-lg);
-    border-top: 1rpx solid var(--border-color);
+  &__section {
+    padding: 28rpx;
+    border: 1rpx solid #dfe3ef;
+    border-radius: 16rpx;
+    background: #ffffff;
   }
 
-  &__copyright {
-    font-size: 20rpx;
-    color: var(--secondary-text);
+  &__section-title {
     display: block;
-    opacity: 0.7;
-  }
-}
-
-.card {
-  position: relative;
-  border-radius: var(--border-radius-xl);
-  overflow: hidden;
-  min-height: 160rpx;
-  cursor: pointer;
-  transition: all 0.4s cubic-bezier(0.4, 0, 0.2, 1);
-  box-sizing: border-box;
-
-  &:active {
-    transform: translateY(-4rpx) scale(0.98);
-  }
-
-  &__inner {
-    height: 100%;
-    padding: var(--space-lg);
-    display: flex;
-    flex-direction: row;
-    align-items: center;
-    text-align: left;
-    position: relative;
-    border-radius: var(--border-radius-xl);
-    background: var(--card-bg);
-    border: 1rpx solid rgba(255, 255, 255, 0.1);
-    transition: all 0.4s cubic-bezier(0.4, 0, 0.2, 1);
-    box-shadow: var(--shadow-lg);
-    box-sizing: border-box;
-  }
-
-  &:active &__inner {
-    box-shadow: var(--shadow-xl);
-    transform: translateY(-4rpx) scale(0.98);
-  }
-
-  &__icon-wrapper {
-    margin-right: var(--space-lg);
-    position: relative;
-    flex-shrink: 0;
-  }
-
-  &__icon {
-    font-size: 48rpx;
-    line-height: 1;
+    margin-bottom: 20rpx;
+    color: #171a24;
+    font-size: 30rpx;
+    font-weight: 600;
   }
 
-  &__content {
-    flex: 1;
+  &__list {
     display: flex;
     flex-direction: column;
-    justify-content: center;
-    z-index: 2;
-    min-width: 0;
-  }
-
-  &__title {
-    font-size: 28rpx;
-    font-weight: 600;
-    color: #ffffff;
-    margin-bottom: var(--space-xs);
-    display: block;
-    text-shadow: 0 1rpx 4rpx rgba(0, 0, 0, 0.3);
-    letter-spacing: 0.5rpx;
+    gap: 16rpx;
   }
 
-  &__description {
-    font-size: 20rpx;
-    color: rgba(255, 255, 255, 0.8);
-    line-height: 1.4;
+  &__item {
     display: block;
-    font-weight: 400;
-    text-shadow: 0 1rpx 2rpx rgba(0, 0, 0, 0.3);
+    color: #3c4252;
+    font-size: 24rpx;
+    line-height: 1.5;
   }
-
-}
+}

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

@@ -1,87 +1,32 @@
-import { definePage } from '@doubao-apps/framework';
-
+import { definePage, getViewData } from '@doubao-apps/framework';
 import './index.scss';
 
-interface CardProps {
-  title: string;
-  description: string;
-  icon: string;
-  gradient?: string;
-  onTap: () => void;
-}
-
-function Card({ title, description, icon, gradient, onTap }: CardProps) {
-  return (
-    <view className="card" bindtap={onTap}>
-      <view className="card__inner" style={gradient ? { background: gradient } : {}}>
-        <view className="card__icon-wrapper">
-          <text className="card__icon">{icon}</text>
-        </view>
-        <view className="card__content">
-          <text className="card__title">{title}</text>
-          <text className="card__description">{description}</text>
-        </view>
-        <view className="card__glow" />
-      </view>
-    </view>
-  );
+interface HomePageData {
+  title?: string;
+  description?: string;
 }
 
 function HomePage() {
-  const handleNavigateToReactLynx = () => {
-    console.log('Navigate to React Lynx');
-  };
-
-  const handleNavigateToLynx = () => {
-    console.log('Navigate to Lynx');
-  };
-
-  const handleNavigateToApplet = () => {
-    console.log('Navigate to Applet');
-  };
+  const viewData = getViewData<HomePageData>();
 
   return (
-    <view className="home">
-      <view className="home__background-pattern" />
-
-      <scroll-view className="home__container" scroll-orientation="vertical" enable-scroll={true}>
-        <view className="home__header">
-          <view className="home__logo">
-            <text className="home__logo-icon">🔷</text>
-          </view>
-          <text className="home__title">Doubao Apps SDK</text>
-          <text className="home__subtitle">豆包小程序开发框架</text>
-          <view className="home__divider" />
-        </view>
-
-        <view className="home__list">
-          <Card
-            title="React Lynx"
-            description="现代化的 React UI 开发框架，基于 Lynx 渲染引擎，提供熟悉的 React 开发体验"
-            icon="⚛️"
-            gradient="linear-gradient(135deg, #667eea 0%, #764ba2 100%)"
-            onTap={handleNavigateToReactLynx}
-          />
-          <Card
-            title="Lynx"
-            description="高性能跨平台渲染引擎，提供原生级别的渲染性能和流畅体验"
-            icon="🚀"
-            gradient="linear-gradient(135deg, #f093fb 0%, #f5576c 100%)"
-            onTap={handleNavigateToLynx}
-          />
-          <Card
-            title="Applet"
-            description="小程序运行环境，提供完整的小程序开发、构建、部署能力"
-            icon="📱"
-            gradient="linear-gradient(135deg, #4facfe 0%, #00f2fe 100%)"
-            onTap={handleNavigateToApplet}
-          />
-        </view>
+    <view className="home-page">
+      <view className="home-page__header">
+        <text className="home-page__eyebrow">Doubao Apps SDK</text>
+        <text className="home-page__title">{viewData.title || '欢迎使用豆包应用'}</text>
+        <text className="home-page__description">
+          {viewData.description || '这是 starter 模板中的首页，你可以从这里开始开发 Page 和 Widget。'}
+        </text>
+      </view>
 
-        <view className="home__footer">
-          <text className="home__copyright">© 2024 ByteDance</text>
+      <view className="home-page__section">
+        <text className="home-page__section-title">下一步</text>
+        <view className="home-page__list">
+          <text className="home-page__item">1. 编辑 src/pages/home/index.tsx 创建页面内容</text>
+          <text className="home-page__item">2. 编辑 src/widgets/hello-world/index.tsx 创建卡片内容</text>
+          <text className="home-page__item">3. 在 src/app.config.ts 中维护入口和 metadata</text>
         </view>
-      </scroll-view>
+      </view>
     </view>
   );
 }
@@ -90,9 +35,6 @@ export default definePage({
   onShow() {
     console.log('Home page shown');
   },
-  onHide() {
-    console.log('Home page hidden');
-  },
   render() {
     return <HomePage />;
   }

package/dist/template-starter/src/widgets/hello-world/index.scss

@@ -0,0 +1,23 @@
+.hello-world-widget {
+  padding: 28rpx;
+  border: 1rpx solid #dfe3ef;
+  border-radius: 16rpx;
+  background: #ffffff;
+  color: #171a24;
+
+  &__title {
+    display: block;
+    margin-bottom: 12rpx;
+    color: #171a24;
+    font-size: 32rpx;
+    font-weight: 700;
+    line-height: 1.3;
+  }
+
+  &__message {
+    display: block;
+    color: #5d6475;
+    font-size: 24rpx;
+    line-height: 1.5;
+  }
+}

package/dist/template-starter/src/widgets/hello-world/index.tsx

@@ -0,0 +1,29 @@
+import { defineWidget, getViewData } from '@doubao-apps/framework';
+import './index.scss';
+
+interface HelloWorldData {
+  title?: string;
+  message?: string;
+}
+
+function HelloWorldWidget() {
+  const viewData = getViewData<HelloWorldData>();
+
+  return (
+    <view className="hello-world-widget">
+      <text className="hello-world-widget__title">{viewData.title || 'Hello World'}</text>
+      <text className="hello-world-widget__message">
+        {viewData.message || '这是 starter 模板中的示例卡片。'}
+      </text>
+    </view>
+  );
+}
+
+export default defineWidget({
+  onShow() {
+    console.log('Hello World widget shown');
+  },
+  render() {
+    return <HelloWorldWidget />;
+  }
+});