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, and this page is available as Markdown at /apps-plugin/docs/overview/quick-start.md.

快速开始

快速开始

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

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

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

开始前准备

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

在终端确认本机环境:

node --version
npm --version
pnpm --version

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

开发与调试流程

安装 Doubao Dev CLI

全局安装命令行工具:

npm install -g @doubao-dev/cli

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

初始化项目

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

dbx init my-app
cd my-app

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

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

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

完成标志:终端提示初始化成功,项目根目录存在 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。

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。

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 中的值一致。

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 时,可以运行:

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

具体字段可继续阅读配置实体与卡片绑定和编写 Skill。需要实现完整 MCP 协议时,可以直接让 AI Coding Agent 基于 DBX 内置提供的 Skill 完成开发。

配置实体与卡片绑定

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

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

完成标志:工具名、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. 工具失败时如实说明原因,不虚构商品、价格或卡片。

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

开发购物方案卡片

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

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

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

校验完整链路

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

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

dbx check --file manifest.yaml --json

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

完成标志:Manifest 校验通过,链路检查调用 create_shopping_plan 并命中 shopping-plan。

创建应用并上传

初始化和本地调试使用自动获取的沙箱 AppID。准备上传时,登录豆包开发者平台创建正式应用,并将项目配置切换为正式 AppID。

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

dbx check --file manifest.yaml
dbx build

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

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

完成标志:命令返回 version_tag、云构建成功,并展示版本详情页和后续调试指引。

真机预览

参考打包、提审与发布完成上传,在开发者平台选择对应版本,创建“应用插件 Debugger”测试链接并扫码进入端到端预览,详见「真机预览」。

提示

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


下一步

  • 体验完整示例:阅读“豆包应用插件 Demo”,了解应用插件端到端设计、Page、Widget 和调试方式。
  • 接入业务能力:阅读“MCP 工具与卡片”和“Skill 开发”,让模型调用业务工具并渲染卡片。
  • 上传与发布:完成本地验证后,阅读“打包、提审与发布”。