打包与提审
本文介绍如何使用 dbx 校验项目、创建测试或正式版本,以及如何查询云构建结果。
完整流程如下:
开始前
请先完成以下准备:
- 已安装
dbx,并通过dbx auth login登录有权管理目标应用插件的开发者账号。 - 已取得目标应用插件的 AppID。
- 已完成 Manifest、Skill 和应用插件前端开发,并通过本地调试验证主要功能。
- MCP Server 已部署到可从公网访问的地址。
localhost、127.0.0.1和仅在局域网中可访问的地址不能用于云构建后的版本。
进入豆包应用插件项目目录后再执行本文中的命令。典型目录如下:
了解打包范围
dbx build 会从下表列出的项目位置读取文件。请将文件放在对应位置,命令不支持分别指定各类文件的路径:
MCP Server 不会被打进版本包;版本中只保存 manifest.yaml 配置的 MCP 地址和协议参数,因此服务端必须提前部署并保持可访问。
无需提前手动制作 ZIP 文件。CLI 会在上传过程中创建临时包,并在命令结束后自动删除。
检查项目配置
上传前至少检查以下内容:
如需确认当前登录状态,可执行:
校验 Manifest
先校验 manifest.yaml:
校验失败时,命令会返回问题对应的 code、字段路径和说明。修改所有错误后重新执行,直到显示校验通过。警告不会直接阻止校验,但仍应确认其是否影响当前版本。
该命令只校验 Manifest。Skill 文件结构、前端构建和项目内容之间的一致性会在构建时继续检查,因此 Manifest 校验通过不代表整个项目一定能够构建成功。
创建版本并触发云构建
在项目根目录创建测试版本:
创建正式、可提审版本,以下两种用法任选其一:
使用 --release 创建可提审的正式版本。可以让平台自动生成版本号,也可以像第二条命令一样指定 x.y.z 格式的版本号。创建成功后,还需要到开发者平台提审和发布。如果当前不在项目根目录,用 --project <project-path> 指定项目即可。
命令会依次完成以下操作:
- 运行应用插件前端构建检查;传入
--env或--secret-env时跳过本地预编译。 - 再次校验 Manifest,并检查 MCP 地址是否适合云端访问。
- 校验并同步项目中发现的应用级平台配置;同步失败时不提交版本。
- 上传 Manifest。
- 打包并上传
skill/下所有SKILL.md。 - 打包并上传应用插件前端源码。
- 创建版本并等待云构建完成。
命令默认等待云构建完成,最多等待 300 秒。需要等待更久时,用 --timeout-seconds <n> 调整时长;想提交后立即返回,则使用 --no-wait,此时不能同时指定 --timeout-seconds。即使等待超时,云端仍会继续构建。
命令完成后,请保存输出中的以下信息:
需要在脚本中读取这些字段时,可添加全局选项 --json 获取结构化输出。
需要为云构建指定变量时:
将普通变量放在 --env 指定的文件中,秘密变量放在 --secret-env 指定的文件中。相对路径从项目根目录算起,实际文件名须以 .env 开头。如果两个文件有同名变量,会使用秘密变量文件中的值。
秘密变量的名称不能以 PUBLIC_ 开头;如果设置了 NODE_ENV,值必须为 production。指定任一变量文件后,CLI 会跳过本地预编译,由云端使用这些变量完成构建。
查询云构建状态
使用构建命令返回的 version_tag 查询一次状态:
在项目根目录运行时,命令会从 manifest.yaml 读取 AppID;在其他目录运行时,请加上 --project <project-path>。每次运行只查询一次状态。如果构建还没结束,可以稍后再查;创建版本时希望同时等待构建结果,可以直接使用默认等待的 dbx build。
构建状态如下:
等待超时不表示构建失败。可以使用同一 version_tag 再次执行状态查询。
dbx build 等待到构建失败时退出 1,JSON 中的 error.code 为 DBX_BUILD_FAILED,构建详情位于 details。dbx build status <version> --json 成功查询到失败构建时仍退出 0,通过 state: "failed" 和 build_error 表达远端失败,并尽可能提供 error_info_file 和 log_id;查询到失败状态本身不产生错误 JSON。根据错误内容修复项目后重新构建,并以新一次构建返回的 version_tag 为准。
提审
提审包结构
开发调试完成后,开发者必须通过 dbx 打包并提交一套完整的提审包供审核与上线。审核系统在四类审核触发前,会先对提审包做完整性 + 结构校验:校验 MCP Server / Skill / Widget / Full Page / Announcement / Multi-task 的完整性与结构合法性;必选项(Skill)缺失或结构非法将直接拒审,提示开发者补件,不进入后续审核。
提审包由以下六类内容加 manifest 构成。
MCP Server
- MCP Server 适合提供原子工具,是 Skill 背后能力的实际执行方。
- 豆包只支持 Remote MCP Server,传输方式为 HTTP / SSE,不支持本地 stdio。
- MCP Server 不会被打进版本包,版本中只保存
manifest.yaml配置的 MCP 地址和协议参数,因此服务端必须提前部署并保持公网可访问。localhost、127.0.0.1及仅在局域网 / 公司网络内可访问的地址均不可用。 - Manifest 中声明的工具名称必须与 MCP Server 返回的工具名称一致。
Skill
- Skill 是 MCP Tool schema 的暴露载体,也是整个接入与审核流程的一等公民输入。开发者通过自然语言 + 一定的标准格式,描述模型应如何使用其背后的能力。
- 豆包采用渐进式加载,不会在会话启动时把所有 Tool schema 一次性塞进上下文。
skill/可以直接放一份SKILL.md,也可以在子目录中分别放置多份。CLI 会递归打包所有文件名完全一致的SKILL.md,保留相对目录结构;不会打包其他文件,因此不要依赖references、scripts等辅助文件。- Skill 中不得包含密钥、测试数据或本地路径等不应发布的内容。
- Skill 通常涵盖:声明能力范围与触发条件、声明私有工具 schema / 鉴权 / 索权需求、声明所用公共工具(如
general_search、local_search、route_plan等)、定义主要场景与工具调用规范、定义不同场景下的 UI(Widget → Full Page → 支付键)、声明工具调用失败时的降级兜底策略等。
Widget(卡片)
- Widget 即卡片,用于将 MCP Server 返回的部分字段以视觉更友好且可交互的形式返回给用户。
- 受 UI 与基础产品设计审核(C10)约束,需满足视觉规范:卡片高度(含标题)≤ 500dp、主标题 ≤ 16 字、CTA 按钮 ≤ 3 个、KV 字段 ≤ 6 行(超出折叠)、主色 ≤ 3 种、圆角(卡片 12dp / 按钮 8dp)、必须适配暗色模式。
- 须完成三态设计:正常态、空态、错误态。
- 卡片固定字段绑定在
manifest.yaml中声明,可交互按钮是进入全页的入口。
Full Page(全页)
- Full Page 即全页,用于承载卡片难以承载的复杂信息与交互,如长列表查看、编辑修改等动作。
- 需满足结构与跳转规范:全页须为 5 区固定结构、入口必须从卡片来、禁止全页再跳全页、
deep_link只传资源 id、卡片 ↔ 全页状态双向同步、跳转须带conversation_id。 - 同样需完成三态设计(正常态、空态、错误态),并与绑定 Skill 中的出卡逻辑与 UI 交互描述保持一致。
Announcement(服务通知)
- Announcement 即服务通知,用于服务类应用插件在必要时刻主动向用户发送通知,例如车辆到达通知等。
- 服务通知需求需在
manifest.yaml中声明;对外文案与素材需通过内容合规扫描(涉黄涉政、违禁、虚假宣传、诱导等)。
Multi-task(多任务栏)
- Multi-task 即多任务栏,用于异步应用插件为用户持续提供服务,例如音乐 / 音频播放、地图导航等。
- 多任务管理需求需在
manifest.yaml中声明。
提审操作流程
进入应用插件版本详情页(路径:我的应用插件 → 应用插件详情 → 配置预览),点击右上角的「提交审核」。
提交审核这一步需要由应用插件管理员在开发者平台上操作,开发成员可以查看版本状态与审核报告,但提审、提交内测、上线这些流转动作统一由管理员把关。

审核完成后,审核系统会输出一份结构化报告,给出总体结论和一份可整改的问题清单。
整改清单里的每一条都会给出问题定位、严重等级和建议动作,照着改即可。修复完成后重新走一遍"打包 → 提交审核"流程,系统会重新检查。
常见问题
Manifest 校验通过,但构建仍然失败
独立校验只检查 Manifest。构建时还会检查前端是否能够构建、Skill 目录及其子目录中是否至少包含一份 SKILL.md、平台配置能否同步、各类文件能否成功打包,以及平台是否能创建版本。请根据命令返回的错误阶段逐项处理。
提示 MCP 地址不能从云端访问
将 manifest.yaml 中的 MCP 地址替换为已经部署、可从公网访问的地址。不要使用本机地址、局域网地址或只能通过公司网络访问的地址。修改后重新校验并构建。
提示 Skill 目录中没有 SKILL.md
确认项目根目录的 skill/ 存在,且其中至少有一份文件名完全一致的 SKILL.md,可放在根目录或子目录中。CLI 不会加载符号链接指向的文件。
等待构建超时
超时只表示本次 dbx build 停止等待,不会取消远端构建。使用原 version_tag 执行 dbx build status <version> 再次查询;如果构建最终失败,根据输出的错误信息修复并重新构建。