> 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.

# 打包与提审

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

完整流程如下：

```mermaid
flowchart LR
    A[检查项目配置] --> B[校验 manifest.yaml]
    B --> C[打包并上传]
    C --> D[等待云构建]
    D --> E{构建结果}
    E -->|失败| F[修复问题并重新上传]
    F --> C
    E -->|成功| G[打包与云构建完成]
```

## 开始前

请先完成以下准备：

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

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

```text
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 会在上传过程中创建临时包，并在命令结束后自动删除。

## 检查项目配置

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

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

如需确认当前登录状态，可执行：

```bash
dbx auth status
```

## 校验 Manifest

先校验 `manifest.yaml`：

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

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

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

## 创建版本并触发云构建

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

```bash
dbx build
```

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

```bash
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` 获取结构化输出。

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

```bash
dbx build --env .env.production --secret-env .env.secret
```

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

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

## 查询云构建状态

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

```bash
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` 中声明。

### 提审操作流程

进入应用插件版本详情页（路径：我的应用插件 → 应用插件详情 → 配置预览），点击右上角的「提交审核」。

提交审核这一步需要**由应用插件管理员在开发者平台上操作，**&#x5F00;发成员可以查看版本状态与审核报告，但提审、提交内测、上线这些流转动作统一由管理员把关。

![应用插件版本的配置预览界面，展示版本号、提交审核入口、Manifest 信息和 Skill 设置](//lf-flow-web-cdn.doubao.com/obj/flow-doubao/goofy_deploy_edenx/flow/doubao-apps--plugin-doc/static/image/TR6DwiE3MiKRCEkGMkncmybVnKb-01.989bca68bd.png)
<!-- lark-image-display-size width="3790" height="1944" -->

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

| 结论 | 含义                              | 你该做什么                   |
| -- | ------------------------------- | ----------------------- |
| 通过 | 各项检查达标，版本进入 `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>` 再次查询；如果构建最终失败，根据输出的错误信息修复并重新构建。
