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/release/package-and-submit.md.

打包与提审

本文介绍如何使用 dbx 校验项目、创建测试或正式版本,以及如何查询云构建结果。

完整流程如下:

开始前

请先完成以下准备:

  • 已安装 dbx,并通过 dbx auth login 登录有权管理目标应用插件的开发者账号。
  • 已取得目标应用插件的 AppID。
  • 已完成 Manifest、Skill 和应用插件前端开发,并通过本地调试验证主要功能。
  • MCP Server 已部署到可从公网访问的地址。localhost、127.0.0.1 和仅在局域网中可访问的地址不能用于云构建后的版本。

进入豆包应用插件项目目录后再执行本文中的命令。典型目录如下:

my-doubao-service/
├── manifest.yaml
├── skill/
│   └── SKILL.md
├── business-templates.yaml   # 可选
├── events.json               # 可选
├── tools.json                # 可选
├── package.json
└── src/                      # 前端源码

了解打包范围

dbx build 会从下表列出的项目位置读取文件。请将文件放在对应位置,命令不支持分别指定各类文件的路径:

内容默认位置打包方式
Manifest<project>/manifest.yaml读取 app_key 作为唯一 AppID 来源,完成严格校验后上传。
Skill<project>/skill/递归打包所有 SKILL.md 为 ZIP,保留相对目录结构。根目录或子目录中至少需要一份 SKILL.md,其他文件不会打包。
应用插件前端项目根目录的 package.json、src/ 等默认先执行前端构建检查,再将源码打包上传;指定构建变量文件时跳过本地预编译,由云端完成正式构建。
平台配置项目根目录约定文件构建前校验并同步发现的应用级配置;当前支持 business-templates.yaml。

MCP Server 不会被打进版本包;版本中只保存 manifest.yaml 配置的 MCP 地址和协议参数,因此服务端必须提前部署并保持可访问。

无需提前手动制作 ZIP 文件。CLI 会在上传过程中创建临时包,并在命令结束后自动删除。

检查项目配置

上传前至少检查以下内容:

检查项要求
AppIDmanifest.yaml 中的 app_key 必须是目标应用插件的真实 AppID,不能保留示例值。
MCP Servermcp_server_url 必须为云端可访问的服务地址,协议配置应与实际服务一致。
工具Manifest 中声明的工具名称必须与 MCP Server 返回的工具名称一致。
Skillskill/ 根目录或子目录中至少包含一份 SKILL.md,内容不得包含密钥、测试数据或本地路径。
前端源码依赖可正常安装,构建脚本可执行,并已通过本地调试验证。
敏感信息源码、Manifest 和 Skill 中不得包含 AppSecret、Access Token、私钥或其他不应公开的凭证。

如需确认当前登录状态,可执行:

dbx auth status

校验 Manifest

先校验 manifest.yaml:

dbx check --file ./manifest.yaml

校验失败时,命令会返回问题对应的 code、字段路径和说明。修改所有错误后重新执行,直到显示校验通过。警告不会直接阻止校验,但仍应确认其是否影响当前版本。

该命令只校验 Manifest。Skill 文件结构、前端构建和项目内容之间的一致性会在构建时继续检查,因此 Manifest 校验通过不代表整个项目一定能够构建成功。

创建版本并触发云构建

在项目根目录创建测试版本:

dbx build

创建正式、可提审版本,以下两种用法任选其一:

dbx build --release
dbx build --release 1.2.3

使用 --release 创建可提审的正式版本。可以让平台自动生成版本号,也可以像第二条命令一样指定 x.y.z 格式的版本号。创建成功后,还需要到开发者平台提审和发布。如果当前不在项目根目录,用 --project <project-path> 指定项目即可。

命令会依次完成以下操作:

  1. 运行应用插件前端构建检查;传入 --env 或 --secret-env 时跳过本地预编译。
  2. 再次校验 Manifest,并检查 MCP 地址是否适合云端访问。
  3. 校验并同步项目中发现的应用级平台配置;同步失败时不提交版本。
  4. 上传 Manifest。
  5. 打包并上传 skill/ 下所有 SKILL.md。
  6. 打包并上传应用插件前端源码。
  7. 创建版本并等待云构建完成。

命令默认等待云构建完成,最多等待 300 秒。需要等待更久时,用 --timeout-seconds <n> 调整时长;想提交后立即返回,则使用 --no-wait,此时不能同时指定 --timeout-seconds。即使等待超时,云端仍会继续构建。

命令完成后,请保存输出中的以下信息:

字段说明
app_id本次构建对应的应用插件 AppID。
version_tag本次版本的唯一标识,后续查询构建状态时需要使用。
log_id本次请求的标识,出现问题时用于定位;可通过命令的 JSON 输出获取。
version_detail_url版本详情页,可查看真机调试二维码。
app_detail_url应用详情页,可配置体验白名单。
doubao_debug_conversation_url豆包调试会话入口。

需要在脚本中读取这些字段时,可添加全局选项 --json 获取结构化输出。

需要为云构建指定变量时:

dbx build --env .env.production --secret-env .env.secret

将普通变量放在 --env 指定的文件中,秘密变量放在 --secret-env 指定的文件中。相对路径从项目根目录算起,实际文件名须以 .env 开头。如果两个文件有同名变量,会使用秘密变量文件中的值。

秘密变量的名称不能以 PUBLIC_ 开头;如果设置了 NODE_ENV,值必须为 production。指定任一变量文件后,CLI 会跳过本地预编译,由云端使用这些变量完成构建。

查询云构建状态

使用构建命令返回的 version_tag 查询一次状态:

dbx build status <version>

在项目根目录运行时,命令会从 manifest.yaml 读取 AppID;在其他目录运行时,请加上 --project <project-path>。每次运行只查询一次状态。如果构建还没结束,可以稍后再查;创建版本时希望同时等待构建结果,可以直接使用默认等待的 dbx build。

构建状态如下:

状态说明
queued等待云构建开始。
building云端正在构建或上传结果。
succeeded云构建成功。
failed云构建失败。
unknown服务端返回了当前 CLI 无法识别的状态。

等待超时不表示构建失败。可以使用同一 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 构成。

组成必选性作用打包 / 交付方式
Skill✅ 必选MCP Tool schema 的暴露载体,用自然语言 + 标准格式描述模型应如何使用其背后的能力。将 Skill 目录及其子目录中的所有 SKILL.md 打包为 ZIP,保留相对目录结构,其他文件不会打包。
MCP Server✅ 必选适合提供原子工具,供 Skill 声明与调用。不打进版本包,版本中仅保存 manifest.yaml 中配置的 MCP 地址和协议参数,服务端须提前部署并保持可访问。
Widget(卡片)✅ 必选将 MCP Server 返回的部分字段以视觉更友好且可交互的形式返回给用户。前端产物随前端源码一起打包上传,云端完成正式构建。
Full Page(全页)可选承载卡片难以承载的复杂信息与交互(如长列表查看、编辑修改等动作)。同前端源码一起打包,需满足全页结构与跳转规范。
Announcement(服务通知)可选服务类应用插件在必要时刻主动向用户发送通知,如车辆到达通知等。需求在 manifest.yaml 中声明。
Multi-task(多任务栏)可选异步应用插件为用户持续提供服务,如音乐 / 音频播放、地图导航等。需求在 manifest.yaml 中声明。
manifest✅ 必选承载 meta(含隐私协议)、卡片固定字段绑定、鉴权 / 索权需求声明、服务通知 / 多任务需求声明等确定性配置。读取 manifest.yaml,完成严格校验后上传。

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 信息和 Skill 设置

审核完成后,审核系统会输出一份结构化报告,给出总体结论和一份可整改的问题清单。

结论含义你该做什么
通过各项检查达标,版本进入 reviewed。可以进入下一步"提交内测"。
驳回存在必改项(如 Skill 缺失、结构非法、高危安全风险等)。按报告里的"整改清单"逐条修复,然后重新提审。

整改清单里的每一条都会给出问题定位、严重等级和建议动作,照着改即可。修复完成后重新走一遍"打包 → 提交审核"流程,系统会重新检查。

常见问题

Manifest 校验通过,但构建仍然失败

独立校验只检查 Manifest。构建时还会检查前端是否能够构建、Skill 目录及其子目录中是否至少包含一份 SKILL.md、平台配置能否同步、各类文件能否成功打包,以及平台是否能创建版本。请根据命令返回的错误阶段逐项处理。

提示 MCP 地址不能从云端访问

将 manifest.yaml 中的 MCP 地址替换为已经部署、可从公网访问的地址。不要使用本机地址、局域网地址或只能通过公司网络访问的地址。修改后重新校验并构建。

提示 Skill 目录中没有 SKILL.md

确认项目根目录的 skill/ 存在,且其中至少有一份文件名完全一致的 SKILL.md,可放在根目录或子目录中。CLI 不会加载符号链接指向的文件。

等待构建超时

超时只表示本次 dbx build 停止等待,不会取消远端构建。使用原 version_tag 执行 dbx build status <version> 再次查询;如果构建最终失败,根据输出的错误信息修复并重新构建。