# Doubao Apps SDK Starter

这是一个 Doubao Apps SDK 起始模板，包含一个购物方案 Widget 和一个方案详情 Page。

## 快速开始

```bash
pnpm install
pnpm run dev
```

开发服务器启动后，可以输入 Page URL 或 Widget ID 运行指定视图。

## 构建

```bash
pnpm run build
pnpm run deploy
```

## 测试

模板内置了一个购物方案摘要的 Rstest 单元测试示例：

```bash
pnpm test
```

## 项目结构

```text
.
├── doubao.config.ts      # 项目配置文件
├── package.json          # 依赖管理
├── rstest.config.ts      # Rstest 配置
├── tsconfig.json         # TypeScript 配置
├── src/
    ├── app.ts            # 应用入口
    ├── app.config.ts     # 应用配置
    ├── auth/             # 可选登录、隐私等协议页面
    ├── pages/            # 页面目录
    │   └── home/
    │       ├── index.tsx
    │       └── index.scss
    ├── shared/
    │   ├── shopping-plan.ts
    │   └── shopping-plan-summary.ts
    └── widgets/          # 卡片目录
        └── shopping-plan/
            └── index.tsx
└── tests/
    └── shopping-plan-summary.test.ts
```

## App 配置

`src/app.config.ts` 默认只声明 App 信息和 Page / Widget 入口。标题、描述、自定义 id 等业务 metadata 按需再补。

```ts
import { defineAppConfig } from '@byted-doubao-apps/framework/config';

export default defineAppConfig({
  appId: 'db_app_xxxxxxx',
  name: '我的豆包应用',
  pages: ['pages/home/index'],
  widgets: ['widgets/shopping-plan/index']
});
```

`shopping-plan` Widget 读取购物方案数据并展示摘要；用户点击卡片按钮后，会进入 Home Page
查看商品分组和金额。

## AI 开发支持

创建项目时如果选择 AI 支持，Create CLI 会在当前项目目录自动安装 `doubao-apps-dev` Skill 到所选 AI Agent。

如果创建时没有选择 AI 支持，或需要给其他 Agent 补装 Skill，可以在当前项目目录执行：

```bash
# 给指定 Agent 安装 Doubao Apps 开发 Skill
npx @byted-doubao-apps/ai skills add doubao-apps-dev --agent claude-code

# 全局安装到用户目录
npx @byted-doubao-apps/ai skills add doubao-apps-dev --agent claude-code --global

# 查看和更新可用 Skills
npx @byted-doubao-apps/ai skills list
npx @byted-doubao-apps/ai skills update
```

- `skills add` 会把指定 Skill 安装到目标 Agent 的 skills 目录。
- `--agent` 可填写 `codex`、`cursor`、`claude-code`、`opencode`、`github-copilot` 等。
- `--global` 表示安装到用户目录；不加时安装到当前项目目录。

使用 AI 辅助开发时，建议把目标视图类型、入口路径、viewData 字段、metadata 和需要调用的端能力说清楚，例如：

- “创建一个订单摘要 Widget，入口为 `src/widgets/order-summary/index.tsx`，从 `getViewData<T>()` 读取订单号、金额和状态。”
- “创建一个账号设置 Page，注册到 `src/app.config.ts`，包含 `switch` 和 `slider` 的受控状态。”
- “在页面按钮点击时调用 `showToast`，并处理 loading、success、error 状态。”