快速开始
快速开始
本指南带你运行一个完整的购物方案应用插件。用户输入“请为 2 个人准备一份 200 元的火锅购物方案”,服务会调用 MCP Tool,并用初始化模板中的 Widget 展示购物方案。这条链路包含四个运行时产物:
初始化项目默认连接共享远程 MCP,可以直接运行示例。如果需要接入自己的业务逻辑,再将它替换为本地 MCP Server。
开始前准备
- Node.js
22.13.1或更高版本。 - npm 可正常访问 npmjs.org。
- 建议安装 pnpm,用于安装和运行项目依赖。
- 一个已完成主体认证的豆包开发者平台账号。
在终端确认本机环境:
完成标志:node --version 输出 v22.13.1 或更高版本,且 npm 能正常输出版本号。
开发与调试流程
安装 Doubao Dev CLI
全局安装命令行工具:
完成标志:dbx --version 输出 dbx 的版本号。如果提示找不到 dbx,重新打开终端;仍未恢复时,检查 npm 全局 bin 目录是否已加入 PATH。
初始化项目
进入准备存放项目的文件夹,运行下面的命令。CLI 会新建 my-app 目录,请确保没有同名目录:
按终端提示完成登录,并选择需要安装开发 Skills 的 Agent。初始化过程会自动获取沙箱 AppID、创建前端 Starter、写入 Manifest 和运行态 Skill,并安装前端依赖。
初始化完成后,项目通常包含以下内容:
完成标志:终端提示初始化成功,项目根目录存在 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。
第二步:配置 manifest.yaml
把 MCP 地址、工具、实体和 Widget 绑定写入工程根目录的 manifest.yaml。其中 tools.create_shopping_plan 对应第一步注册的工具名;entities.shopping_plan_entity 对应工具返回的 entity_type;tool_card_binding 中的 shopping-plan 是下一步要注册的 Widget ID。
第三步:注册 Widget 并联调
在 src/app.config.ts 中注册购物方案 Widget。注册路径 widgets/shopping-plan/index 对应的 Widget ID 是 shopping-plan,需要与第二步 tool_card_binding 中的值一致。
完成后运行 dbx dev。默认使用 manifest.yaml 中的 MCP 地址;临时调试本地 Server 时,可以运行:
具体字段可继续阅读配置实体与卡片绑定和编写 Skill。需要实现完整 MCP 协议时,可以直接让 AI Coding Agent 基于 DBX 内置提供的 Skill 完成开发。
配置实体与卡片绑定
在 manifest.yaml 中声明工具输出和 shopping_plan_entity,并将 create_shopping_plan 绑定到 shopping-plan:
完成标志:工具名、entity_type 和 Widget ID 分别在 MCP Server、Manifest 与前端注册配置中完全一致。
编写 Skill
编辑 skill/SKILL.md,告诉模型何时调用工具,以及缺少参数时如何处理。默认模板包含以下规则:
- 用户提出火锅、早餐、露营等场景化购物需求时,调用
create_shopping_plan。 - 调用前确认购物场景、人数和预算;缺少任一项时先向用户询问。
- 将“两个人”“预算 200 元”等表达转换为合法 JSON 数字。
- 用户没有说明辣度时,使用
preferences.spicy_level="low"。 - 工具失败时如实说明原因,不虚构商品、价格或卡片。
完成标志: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>。
完成标志:Manifest 校验通过,链路检查调用 create_shopping_plan 并命中 shopping-plan。
创建应用并上传
初始化和本地调试使用自动获取的沙箱 AppID。准备上传时,登录豆包开发者平台创建正式应用,并将项目配置切换为正式 AppID。
本地地址 127.0.0.1 只能用于本机调试。上传前,需要将本地 MCP 部署为公网可访问的 HTTPS endpoint,并更新 manifest.mcp_server.end_point。
不要在 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 开发”,让模型调用业务工具并渲染卡片。
- 上传与发布:完成本地验证后,阅读“打包、提审与发布”。