> For AI agents: the complete documentation index is available at /apps-plugin/docs/llms.txt, the full documentation bundle is available at /apps-plugin/docs/llms-full.txt.

# 快速开始

## 快速开始

本指南带你运行一个完整的购物方案应用插件。用户输入“请为 2 个人准备一份 200 元的火锅购物方案”，服务会调用 MCP Tool，并用初始化模板中的 Widget 展示购物方案。这条链路包含四个运行时产物：

```text
用户请求
  → skill/SKILL.md：判断何时调用工具并整理参数
  → MCP Server：执行 create_shopping_plan
  → manifest.yaml：声明购物方案实体并绑定 Widget
  → Widget：渲染购物方案并跳转详情页
```

初始化项目默认连接共享远程 MCP，可以直接运行示例。如果需要接入自己的业务逻辑，再将它替换为本地 MCP Server。

## 开始前准备

- Node.js `22.13.1` 或更高版本。
- npm 可正常访问 npmjs.org。
- 建议安装 pnpm，用于安装和运行项目依赖。
- 一个已完成主体认证的豆包开发者平台账号。

在终端确认本机环境：

```bash
node --version
npm --version
pnpm --version
```

**完成标志：**`node --version` 输出 `v22.13.1` 或更高版本，且 npm 能正常输出版本号。

## 开发与调试流程

### 安装 Doubao Dev CLI

全局安装命令行工具：

```bash
npm install -g @doubao-dev/cli
```

**完成标志：**`dbx --version` 输出 dbx 的版本号。如果提示找不到 `dbx`，重新打开终端；仍未恢复时，检查 npm 全局 bin 目录是否已加入 `PATH`。

### 初始化项目

进入准备存放项目的文件夹，运行下面的命令。CLI 会新建 `my-app` 目录，请确保没有同名目录：

```bash
dbx init my-app
cd my-app
```

按终端提示完成登录，并选择需要安装开发 Skills 的 Agent。初始化过程会自动获取沙箱 AppID、创建前端 Starter、写入 Manifest 和运行态 Skill，并安装前端依赖。

初始化完成后，项目通常包含以下内容：

```text
.
├── README.md
├── AGENTS.md
├── manifest.yaml
├── package.json
├── skill
│   └── SKILL.md
├── src
│   ├── app.config.ts
│   ├── pages
│   └── widgets
└── tsconfig.json
```

**完成标志：**&#x7EC8;端提示初始化成功，项目根目录存在 `manifest.yaml`、`skill/SKILL.md`、`src/` 和 `AGENTS.md`。

### 使用 MCP Server

`dbx init` 生成的工程默认连接共享远程 MCP Server。运行 `dbx dev`，在控制台输入 `web`，再输入“帮我生成一份 2 人火锅购物方案，预算 200 元”，即可查看完整效果。

如果要替换为自己的 MCP Server，可以按下面三步开发。Server 可以先返回 Mock 数据，跑通后再接入真实业务接口。

**第一步：实现 MCP 工具**

使用官方 MCP TypeScript SDK 注册 `create_shopping_plan`，并返回 `shopping_plan_entity`。下面只展示关键代码；`/mcp` 路由和启动方式见 [Server Guide](https://ts.sdk.modelcontextprotocol.io/server)。

```typescript
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import * as z from 'zod/v4';

const server = new McpServer({
  name: 'shopping-plan',
  version: '1.0.0'
});

server.registerTool(
  'create_shopping_plan',
  { inputSchema: { scene: z.string() } },
  async ({ scene }) => ({
    content: [{ type: 'text', text: '已生成购物方案' }],
    structuredContent: {
      entities: [{
        entity_type: 'shopping_plan_entity',
        plan_id: 'plan_001',
        title: scene + '购物方案'
      }]
    }
  })
);
```

**第二步：配置 manifest.yaml**

把 MCP 地址、工具、实体和 Widget 绑定写入工程根目录的 `manifest.yaml`。其中 `tools.create_shopping_plan` 对应第一步注册的工具名；`entities.shopping_plan_entity` 对应工具返回的 `entity_type`；`tool_card_binding` 中的 `shopping-plan` 是下一步要注册的 Widget ID。

```yaml
manifest_version: 1
app_key: db_app_xxxxxx
name: 购物方案

mcp_server:
  end_point: https://example.com/mcp
  description: 购物方案 MCP Server
  mcp_config:
    protocol: Streamable

tools:
  create_shopping_plan:
    login_type: no_login
    description: 根据购物场景、人数和预算生成购物方案
    output:
      kind: entities
      entity_types: [shopping_plan_entity]

entities:
  shopping_plan_entity:
    schema:
      plan_id:
        type: string
        is_entity_id: true
      entity_type:
        type: string
        llm_visible: false
      title:
        type: string
    tool_card_binding:
      create_shopping_plan: shopping-plan
```

**第三步：注册 Widget 并联调**

在 `src/app.config.ts` 中注册购物方案 Widget。注册路径 `widgets/shopping-plan/index` 对应的 Widget ID 是 `shopping-plan`，需要与第二步 `tool_card_binding` 中的值一致。

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

export default defineAppConfig({
  appId: 'db_app_xxxxxx',
  name: '购物方案',
  pages: ['pages/home/index'],
  widgets: ['widgets/shopping-plan/index']
});
```

完成后运行 `dbx dev`。默认使用 `manifest.yaml` 中的 MCP 地址；临时调试本地 Server 时，可以运行：

```bash
dbx dev --mcp-endpoint http://127.0.0.1:8000/mcp
```

具体字段可继续阅读[配置实体与卡片绑定](/apps-plugin/docs/overview/quick-start.md)和[编写 Skill](/apps-plugin/docs/overview/quick-start.md)。需要实现完整 MCP 协议时，可以直接让 AI Coding Agent 基于 DBX 内置提供的 Skill 完成开发。

### 配置实体与卡片绑定

在 `manifest.yaml` 中声明工具输出和 `shopping_plan_entity`，并将 `create_shopping_plan` 绑定到 `shopping-plan`：

```yaml
tools:
  create_shopping_plan:
    login_type: no_login
    output:
      kind: entities
      entity_types: [shopping_plan_entity]

entities:
  shopping_plan_entity:
    schema:
      plan_id:
        type: string
        is_entity_id: true
      entity_type:
        type: string
        llm_visible: false
      title:
        type: string
      people_count:
        type: int
      budget:
        type: float
      subtotal:
        type: float
    tool_card_binding:
      create_shopping_plan: shopping-plan
```

**完成标志：**&#x5DE5;具名、`entity_type` 和 Widget ID 分别在 MCP Server、Manifest 与前端注册配置中完全一致。

### 编写 Skill

编辑 `skill/SKILL.md`，告诉模型何时调用工具，以及缺少参数时如何处理。默认模板包含以下规则：

1. 用户提出火锅、早餐、露营等场景化购物需求时，调用 `create_shopping_plan`。
2. 调用前确认购物场景、人数和预算；缺少任一项时先向用户询问。
3. 将“两个人”“预算 200 元”等表达转换为合法 JSON 数字。
4. 用户没有说明辣度时，使用 `preferences.spicy_level="low"`。
5. 工具失败时如实说明原因，不虚构商品、价格或卡片。

**完成标志：**&#x53;kill 同时写明触发场景、工具选择、参数来源、默认规则和结果边界，没有把安装步骤或接口字段表写进运行态说明。

### 开发购物方案卡片

在 `src/app.config.ts` 中确认 Widget ID 为 `shopping-plan`。初始化模板中的 Widget 使用 `useViewData` 读取购物方案实体，展示标题、人数、件数、金额和部分商品分组；用户点击“查看方案”后进入详情页。

如果修改了业务实体字段，需要同步修改 MCP ToolResult、Manifest schema，以及 Widget 和 Page 使用的类型与渲染逻辑。

**完成标志：**&#x8D2D;物方案卡片正常显示标题、人数、商品数量和金额；点击“查看方案”能够打开详情页；缺少关键字段时显示空态，而不是白屏。

### 校验完整链路

先校验 Manifest，再使用 `dbx check --query` 验证 MCP result、Manifest、`tool_card_binding` 和卡片增量：

运行 `check` 前，确认 `manifest.yaml` 中的 MCP 地址指向本次要测试的服务。`dev --mcp-endpoint` 只影响调试服务，不会修改 `check` 使用的地址；需要使用另一份配置时，给 `check` 添加 `--manifest <path>`。

```bash
dbx check --file manifest.yaml --json

dbx check \
  --query "请为 2 个人准备一份 200 元的火锅购物方案" \
  --expect-card required \
  --verbose \
  --json
```

**完成标志：**&#x4D;anifest 校验通过，链路检查调用 `create_shopping_plan` 并命中 `shopping-plan`。

### 创建应用并上传

初始化和本地调试使用自动获取的沙箱 AppID。准备上传时，登录[豆包开发者平台](https://developer.doubao.com/dashboard?state=)创建正式应用，并将项目配置切换为正式 AppID。

本地地址 `127.0.0.1` 只能用于本机调试。上传前，需要将本地 MCP 部署为公网可访问的 HTTPS endpoint，并更新 `manifest.mcp_server.end_point`。

```bash
dbx check --file manifest.yaml
dbx build
```

不要在 Manifest、Skill 或源码中保存 AppSecret、访问令牌或其他长期密钥。

`dbx build` 会创建测试版本并默认等待云构建完成。如需直接创建正式、可提审版本，执行 `dbx build --release`，版本号由后端生成；也可用 `dbx build --release 1.2.3` 显式指定 `x.y.z` 格式的版本号。该命令不会自动提审或发布。

**完成标志：**&#x547D;令返回 `version_tag`、云构建成功，并展示版本详情页和后续调试指引。

### 真机预览

参考[打包、提审与发布](/apps-plugin/docs/release/package-and-submit.md)完成上传，在开发者平台选择对应版本，创建“应用插件 Debugger”测试链接并扫码进入端到端预览，详见[「真机预览」](/apps-plugin/docs/development-tools/device-debugging.md)。

:::info 提示

真机预览前需在“开发 - 开发配置 - 白名单配置”中添加豆包 UID，再扫码体验。

<div hidden data-lark-callout-end></div>

:::

***

## 下一步

- 体验完整示例：阅读“[豆包应用插件 Demo](/apps-plugin/docs/overview/demo.md)”，了解应用插件端到端设计、Page、Widget 和调试方式。
- 接入业务能力：阅读“MCP 工具与卡片”和“Skill 开发”，让模型调用业务工具并渲染卡片。
- 上传与发布：完成本地验证后，阅读“[打包、提审与发布](/apps-plugin/docs/release/package-and-submit.md)”。
