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

# 自动化评测

:::info 提示

DBX Eval 用于评估豆包应用插件的 Agent、MCP Server、Skill 与卡片渲染的端到端表现。一次完整评测会完成项目检查、MCP 探索、用例生成、多轮轨迹、评分、失败归因、准出判定和 HTML 报告。

建议从项目根目录打开 Coding Agent，让它使用 `dbx-eval` Skill 运行评测、分析报告，并在修复后重新验证。你也可以按下文的 CLI 示例自己运行，或将命令接入 CI。

<div hidden data-lark-callout-end></div>

:::

## 适用场景

当你需要确认一个豆包应用插件是否具备可发布质量时，可以使用自动化评测。它主要回答以下问题：

- Agent 是否能完成真实用户的多轮任务。
- MCP Tool 是否可访问，工具名、参数和返回值是否与 Manifest 对齐。
- `SKILL.md` 是否能指导 Agent 在正确时机调用正确工具。
- 卡片或 Widget 是否能渲染，并在需要时生成截图。
- 失败时是否能定位到平台环境、工具、Skill、Case 质量或路由边界问题。

## 开始前

开始评测前，请确认：

- Node.js 版本不低于 `22.13.0`。
- 已按照[《CLI 安装与配置》](/apps-plugin/docs/development-tools/installation.md)完成 DBX CLI 安装和登录。
- 当前 CLI 版本具备 Eval 能力，`dbx eval --help` 能看到评测相关命令。
- 本地已有豆包应用插件项目，并包含 `manifest.yaml` 和完整 `SKILL.md`。
- `manifest.yaml` 中有非空 `app_key`。默认 Gateway 依赖它做请求归因；`dbx auth login` 不会生成或补齐 `app_key`。
- MCP Endpoint 可访问。Manifest 中声明的 Tool 名称必须与 MCP `tools/list` 返回逐项一致，大小写也必须一致。
- 如果需要验证卡片截图，项目需要具备可启动的前端、对应 Widget 和本机 Chrome 或 Chromium 环境。

不要把 API Key、AppSecret、模型凭证或登录凭证写入对话、日志、截图或代码仓库。

## 1. 安装评测 Skill

`dbx-eval` Skill 是 Coding Agent 使用 DBX Eval 的操作说明。它会指导 Agent 检查项目、收集缺失配置、选择正确命令、跟踪运行状态、读取证据文件，并在失败后完成修复与回归。

在豆包应用插件项目根目录执行：

```bash
dbx eval skill
```

也可以显式指定项目路径：

```bash
dbx eval skill --project-path /absolute/path/to/project
```

如果项目尚未初始化任何 Agent Skill 目录，可以指定目标 Agent：

```bash
dbx eval skill --agent trae
dbx eval skill --agent codex
dbx eval skill --agent claude-code
```

根据项目当前的安装情况，命令会执行以下操作：

- 如果项目已经安装过开发 Skill，会在所有检测到的 Skill 目录中更新或补装 `dbx-eval`；此时指定 `--agent` 也不会只更新某一个 Agent。
- 如果项目还没有安装过开发 Skill，会为你选择的 Agent 安装 CLI 内置 Skills。通过脚本或非交互终端运行时，需要用 `--agent <id>` 指定 Agent。
- 该命令只安装 Skill，不执行登录、脚手架、MCP 启动或 Git 初始化。

安装完成后，重新打开项目或刷新 Coding Agent 会话，使新 Skill 被加载。

## 2. 让 Coding Agent 发起评测

推荐从豆包应用插件项目根目录打开 Coding Agent，然后直接说明目标。

完整评测：

```text
请使用 dbx-eval Skill 测评当前应用插件。
```

只验证一个已知业务场景：

```text
请使用 dbx-eval Skill 测评当前应用插件，只评测“查询当前订单并展示订单状态”这个场景。
请启动实时评测页面。评测完成后按证据解释失败原因，不要直接修改代码；先给我最小修复方案。
```

分析已有失败报告：

```text
请使用 dbx-eval Skill 分析这次评测失败：<运行目录或 report.json 的完整路径>。
请读取 failure.json（如存在）、state.json、run.log、report.json、轨迹和评分文件，按 Case 列出失败步骤、工具调用、错误原文、LogID、归因和建议。先不要重跑。
```

修复后回归：

```text
请根据刚才的 Eval 证据做最小修复。修复后先使用原失败场景回归，再运行正式评测，并对比修复前后的通过率、Release 决策和失败项。不要用新的场景替代原失败场景。
```

提示词中最重要的是说明项目、目标场景、是否允许改代码，以及期望 Agent 返回哪些证据。

## 3. 手动 CLI 命令

第一次运行时，先选一个业务场景，确认配置、MCP 和卡片渲染都正常，再增加用例数和并发数。

| 目标                | 命令                                                                   |
| ----------------- | -------------------------------------------------------------------- |
| 启动实时评测页面          | `dbx eval server --project-path /absolute/path/to/project`           |
| 启动实时评测页面但不自动打开浏览器 | `dbx eval server --project-path /absolute/path/to/project --no-open` |
| 只在终端跑一次评测         | `dbx eval run --project-path /absolute/path/to/project`              |
| 查看历史报告            | `dbx eval report --project-path /absolute/path/to/project`           |
| 以 JSON 查看历史报告     | `dbx eval report --project-path /absolute/path/to/project --json`    |

先用一个场景检查评测是否能正常运行：

```bash
dbx eval run \
  --project-path /absolute/path/to/project \
  --intent "查询当前订单，并展示订单状态" \
  --intent-count 1 \
  --pass-k 1 \
  --concurrency 1
```

使用 `dbx eval run` 可以直接在终端运行评测，卡片渲染和截图仍会执行。如果这次不需要检查卡片，或运行环境缺少前端、Widget 或浏览器，可以添加以下选项跳过渲染和截图：

```bash
--skip-render
```

## 4. 配置 `node_modules/.doubao-dev/eval.yaml`

项目的评测配置保存在 `node_modules/.doubao-dev/eval.yaml`。首次运行时，可以用 `-c <temporary-config.yaml>` 指定准备好的配置文件；校验通过后，CLI 会将本次使用的配置保存到项目的默认位置，方便下次继续使用。

配置可能包含明文模型凭证，不应提交到代码仓库。

最小示例：

```yaml
# node_modules/.doubao-dev/eval.yaml
# Contains plaintext LLM credentials if custom endpoints are configured. Do not commit or share this file.
app:
  manifest: ./manifest.yaml
  skill: ./skill
  app_id: db_xxxx
mcp:
  url: http://127.0.0.1:3200/mcp
run:
  mode: full_pipeline
  rollout_mode: ua_driven
  intent_count: 20
  pass_k: 1
  concurrency: 1
  checklist_concurrency: 1
  scoring_concurrency: 1
  judge_concurrency: 1
  pass_threshold: 0.6
  max_rounds: 10
  max_step: 8
  output_dir: ./data
  skip_render: false
```

常用字段：

| 字段                          | 说明                                                                  |
| --------------------------- | ------------------------------------------------------------------- |
| `app.manifest`              | Manifest 路径，通常是 `./manifest.yaml`。                                  |
| `app.skill`                 | 被测 Skill 目录，通常为 `./skill`；递归加载其中的 `SKILL.md`。                       |
| `app.app_id`                | App Key，应与 Manifest 中的 `app_key` 一致。                                |
| `mcp.url`                   | MCP Server 地址；未显式配置时，CLI 会尝试从 Manifest 的 `mcp_server.end_point` 读取。 |
| `run.intent_count`          | 自动生成 Case 数，默认 20，最大 100。                                           |
| `run.pass_k`                | 每个 Case 最大尝试次数，默认 1；大于 2 会触发准出拦截。                                   |
| `run.concurrency`           | 轨迹并发，默认 1，最大 2。                                                     |
| `run.checklist_concurrency` | Checklist 生成并发，默认 1，最大 2。                                           |
| `run.scoring_concurrency`   | Case 评分并发，默认 1，最大 2。                                                |
| `run.judge_concurrency`     | Judge 请求并发，默认 1，最大 2。                                               |
| `run.pass_threshold`        | 单 Case 通过阈值，默认 0.6。                                                 |
| `run.max_rounds`            | 单条轨迹最大对话轮数，默认 10，最大 20。                                             |
| `run.max_step`              | 每轮最大工具步骤，默认 8。                                                      |
| `run.output_dir`            | 运行产物与报告输出目录，默认 `./data`。                                            |
| `run.skip_render`           | 是否跳过前端发现、渲染运行时和截图，默认 `false`。                                       |

使用自定义 OpenAI-compatible endpoint 时，才需要配置 `ua`：

```yaml
ua:
  base_url: https://example.com/v1
  api_key: sk-xxxx
  model: your-model
```

Judge 未配置时继承 UA。若要单独覆盖 Judge：

```yaml
judge:
  base_url: https://example.com/v1
  api_key: sk-xxxx
  model: judge-model
```

配置优先级从高到低：

```text
显式 CLI 参数
> -c/--config 指定 YAML（替换项目 YAML 层，不与项目 YAML 逐字段合并）
> <projectPath>/node_modules/.doubao-dev/eval.yaml
> ~/.dbx/config.yaml
> Manifest 推导
> 非 endpoint 默认值
```

`dbx eval server --resume` 和 `dbx eval run --resume` 使用运行目录中的状态快照，不修改项目配置。

## 5. 用例生成与评测流程

未指定 `--intent` 时，Eval 会优先使用业务流驱动生成：

- 从 API 依赖和 Skill 文档推导业务流 FlowMap。
- 由确定性计划分配每条流的主干、分支和异常用例。
- 为用例回填 `flow_id`、`case_kind`、`flow_variant` 等来源字段。

这是 best-effort 策略。FlowMap 生成失败或无有效业务流时，会回退到既有 seed 规划，不影响评测继续。产物 `generation-coverage.json` 的 `strategy` 字段会标记本次策略，例如 `flow_v2` 或 `legacy_seed`。

显式传入 `--intent` 时，始终走指定场景路径，用例数与 Intent 数严格一致。

如果生成并通过校验的用例少于计划数量，评测会在用例生成阶段停止，后续的 Checklist、轨迹、评分和报告都不会执行，也不会生成正式的 `report.json` 或 `report.html`。这表示评测尚未完成，需要先排查用例生成失败的原因。

## 6. 查看报告

默认输出目录形如：

```text
<projectPath>/<run.output_dir>/eval-run-<run-id>/
```

让 Coding Agent 给出报告的完整路径，并说明：评测是否完成、用例通过率、是否满足发布条件（Release 决策）、哪些用例失败，以及对应的 LogID 和修复建议。

重点产物：

| 产物                         | 用途                                     |
| -------------------------- | -------------------------------------- |
| `report.html`              | 默认轻量报告，依赖同目录下的 `screenshots/`。         |
| `report-standalone.html`   | 截图内联的自包含报告，适合单文件转发或部署。                 |
| `report.json`              | 机器可读最终结果。                              |
| `run.log`                  | 全链路日志、错误和 LogID。                       |
| `state.json`               | 阶段状态、续跑状态和配置快照。                        |
| `failure.json`             | 提前终止时的诊断摘要。                            |
| `case-validation.json`     | Case 校验失败时的诊断产物。                       |
| `cases.raw.json`           | 原始生成 Case，排查 Case 数完整性失败时使用。           |
| `skill-review.json`        | Skill 质量评分、问题和建议。                      |
| `veto.json`                | Release Veto 是否命中及原因。                  |
| `developer-summary.json`   | 面向开发者的问题聚类和整改建议。                       |
| `posthook-summary.json`    | Simulator PostHook 独立诊断汇总，不参与评分和 Veto。 |
| `flow-map.json`            | 业务流驱动生成时的 FlowMap。                     |
| `generation-coverage.json` | 业务流和 API 覆盖告警。                         |
| `trajectories/`            | 对话、工具调用、工具结果、Trace 和 LogID。            |
| `scores/`                  | Attempt 级评分和归因。                        |
| `screenshots/`             | 卡片 PNG 截图；`skip_render` 时可为空或不存在。      |

核心结论的含义：

| 结论           | 说明                                                              |
| ------------ | --------------------------------------------------------------- |
| 运行状态         | 区分运行中、提前终止、已完成但未通过、已完成并通过。没有生成最终报告时，不应只报“0 分”。                  |
| Case 通过率     | 表示多少业务场景达到当前通过阈值；它不是最终准出结论。                                     |
| Release 决策   | `PASS` 表示未触发准出拦截；`NOT PASS` 应同时给出 Veto 原因。                      |
| Evaluator    | `rule` 检查确定性规则，`behavior` 检查 Tool、参数与调用行为，`rubric` 判断业务步骤和成功条件。 |
| Hard Failure | 核心任务、最大轮次、用户体验一票否决等关键失败。即使总分不低，也可能导致 Case 或 Release 不通过。        |
| LogID        | 用于关联云端或链路日志。发生网络、模型、模拟器或平台错误时，应原样保留。                            |

常见 Release Veto 触发条件：

- 通过率低于 `run.pass_threshold`。
- 存在被评测基础设施或 Case 冲突阻塞的 Case。
- 存在 Hard Failure。
- 存在 `L1_platform` 归因项。
- Skill Review 总分低于 0.5，或 Skill 描述与实际 Tool 行为不匹配。
- `pass_k` 实际最大尝试次数大于 2。

## 7. 失败排障

不要只根据终端最后一行下结论。运行中或失败后，按以下顺序读取证据：

1. 确认输出目录和 run ID。`run.log` 开头包含 `Starting new run ... at <outputDir>`，`server` 模式还会输出 localhost 页面 URL。
2. 如果存在 `failure.json`，优先读取它。它包含 `stage`、`message`、`hint`、`error_type`、`http_status`、`log_id`、`retryable`、`completed_phases` 和下一步命令。
3. 读取 `state.json`。重点看 `failure.stage/message/logId/retryable`、各阶段状态，以及每个 Case 的 attempts。
4. 读取 `run.log` 尾部和失败阶段附近日志。优先检索 `FATAL`、`ERROR`、`WARN`、`FAILED`、`Failure diagnostic saved`、`log_id=`、`logid` 和失败阶段名。
5. 如果已生成 `report.json`，说明 Pipeline 已进入报告阶段；这类 `NOT PASS` 通常不是执行提前终止。
6. 如果已生成 `veto.json` 但没有 `report.json`，优先说明准出判定已完成但报告写入失败，再结合 `state.json` 和 `run.log` 判断是否可重跑或续跑。

归因口径：

| 归因             | 含义                                    | 常见修复方向                                            |
| -------------- | ------------------------------------- | ------------------------------------------------- |
| `L1_platform`  | 平台、环境、状态隔离、工具可用性或能力模拟异常。              | 检查环境、网络、测试数据、状态和服务稳定性。                            |
| `L2_tool`      | 工具执行、返回结果、协议转换、参数传递或时间处理异常。           | 修复 MCP Tool 实现、Schema、协议或返回数据。                    |
| `L3_skill`     | 任务理解、Skill 召回与遵循、结果核验、推理或 Skill 定义不足。 | 补充 Skill 规则与示例，或修复模型侧规划与核验。                       |
| `case_quality` | 测试用例的前置条件、剧本或成功标准存在冲突。                | 人工复核 Case 与 Checklist；确认不是业务实现问题后，可按 Case 质量问题处理。 |
| `other_intent` | 请求不属于当前 Skill 能力范围，或被路由到错误能力。         | 明确 Skill 边界、路由和拒答策略。                              |

常见问题与优先处理：

| 现象                               | 优先检查                                                   | 处理建议                                                     |
| -------------------------------- | ------------------------------------------------------ | -------------------------------------------------------- |
| `EVAL_PROJECT_CONFIG_INCOMPLETE` | `missing_fields`、`node_modules/.doubao-dev/eval.yaml`  | 逐项补齐 Manifest、Skill、App ID、MCP URL 等字段，不要猜测。             |
| Manifest `app_key` 缺失            | `manifest.yaml`                                        | 在 Manifest 写入非空 `app_key`；`dbx auth login` 不会补上。         |
| `AppID mismatch`                 | `--app-id` 与 Manifest `app_key`                        | 以 Manifest 为唯一事实来源，保持二者一致。                               |
| MCP 无法连接                         | `mcp.url`、`manifest.mcp_server.end_point`、MCP 服务日志     | 启动 MCP Server，或修正 `--mcp-url` 与配置。                       |
| Tool 对不上                         | Manifest tools、MCP `tools/list`                        | 工具名逐项对齐，大小写必须一致。                                         |
| Case 数完整性失败                      | `failure.json`、`case-validation.json`、`cases.raw.json` | 这类失败不可用 `--resume` 补齐；修复 Skill、业务流或生成约束后创建新 Run。         |
| 默认 Gateway 登录态失效                 | `failure.json`、`run.log` 中的 401/403 或登录失效提示            | 执行 `dbx auth login`，成功后按明确 run ID 或 `resume_command` 续跑。 |
| LLM 429、5xx 或 timeout            | `http_status`、`error_type`、`log_id`、`retryable`        | 通常可稍后使用 `--resume` 继续。                                   |
| 渲染或截图失败                          | 前端、Widget、Chrome、文件描述符限制                               | 先修复环境；只有接受无卡或无截图评测时才用 `--skip-render`。                   |
| 单个 Case 失败                       | `report.json`、`scores/`、`trajectories/`                | 按 Case 分数、Hard Failure、归因和 LogID 汇报，不要说整个 Eval 执行失败。     |
| Release 是 `NOT PASS`             | `veto.json`、`report.json`                              | 这是准出失败，不是 CLI 崩溃；说明具体 Veto 原因。                           |

## 8. 修复与回归

先结合日志和失败用例，确认问题出在平台、工具还是 Skill，再修改对应部分。归因标签可以帮助排查，但不能单凭标签就重写 Skill 或工具。

推荐闭环：

```text
确认失败阶段和证据
-> 判断代码、MCP、Skill、Manifest、Case、配置或环境责任
-> 提出最小修复并等待确认
-> 修改后使用原失败 Intent 回归
-> 再运行正式评测
-> 对比修复前后的通过率、Release 决策、失败项和 LogID
```

常见修复策略：

| 证据现象                                     | 优先修复                                   | 回归方式                         |
| ---------------------------------------- | -------------------------------------- | ---------------------------- |
| Manifest 漏 Tool、名称或大小写与 `tools/list` 不一致 | 对齐 Manifest 与 MCP Tool 声明。             | 重新检查工具列表，再跑原失败场景。            |
| 参数缺失、类型不符，或 Tool 无法表达业务需求                | 修复 Tool Schema、参数来源或补充工具能力。            | 检查实际 Tool Call 参数与返回值。       |
| Tool 有能力，但 Agent 没有正确选择或不知道参数从哪里获得       | 在 `SKILL.md` 中补充调用时机、前置查询、参数来源和示例。     | 使用同一 Intent 检查 Tool 选择与调用顺序。 |
| 工具返回空数据、状态不稳定或测试前置条件不存在                  | 补充测试数据并固定必要状态流转。                       | 在相同数据快照下重跑失败 Case。           |
| 工具链路正确，但卡片缺失或渲染失败                        | 检查 Widget 注册、实体协议、前端和浏览器环境。            | 同时核对 Tool 结果与截图。             |
| Case 与 Skill、Tool 或用户指令相互冲突              | 修正 Case 或 Checklist，不要修改正确业务实现去迎合错误用例。 | 重新生成或修正用例后再评测。               |

## 9. 续跑边界

只有开发者明确要求续跑具体 run ID 或运行目录时，才使用 `--resume`。开发者只说“继续评测”“再跑一次”“续跑刚才失败的任务”，但没有提供 run ID 时，默认创建新任务。

继续一个中断的运行：

```bash
dbx eval server --resume <run-id-or-run-dir>
```

不需要实时页面时：

```bash
dbx eval run --resume <run-id-or-run-dir>
```

只重试失败 Case、复用已通过 Case：

```bash
dbx eval server --resume <run-id-or-run-dir> --rerun-failed
```

`--resume` 会使用原运行目录里的状态快照，拒绝其他运行参数。不要从 `dbx eval report` 的报告列表或 `~/.dbx/eval-runs/index.json` 中自行推断续跑目标。

### 使用原 Case 验证 Skill 或 Tool 修复

如果只修改了当前项目的 `SKILL.md`、Tool 内部业务逻辑、测试数据或运行返回效果，可以保留原 Case 和 Checklist，从 rollout 阶段重新执行全部 Case：

```bash
dbx eval server --resume <run-id-or-run-dir> --from-phase rollout
```

不需要实时页面时改用 `dbx eval run`。该命令会重新读取当前 `SKILL.md`，保留分析、实体池、业务流、Intent、Case 和 Checklist，并重新执行 Skill Review、全部轨迹、评分、归因、准出和报告。

以下能力契约必须保持不变：

- Manifest。
- Tool 名称。
- Tool 描述。
- Tool 输入和输出 Schema。

这些契约发生变化时，原 Case 和 Checklist 可能已经失效，应创建新的完整评测。`--from-phase rollout` 不支持 `score_only`，也不能与 `--rerun-failed` 同时使用。执行前如需对比修复前后结果，应先记录原通过率、失败项、归因和 Release 决策。

## 10. 可选 Demo 自检

CLI 内置了 `taxi` 和 `milk-tea` 两个 MCP Demo，适合验证本机 CLI、MCP 握手和工具名对齐能力。它不是三方项目正式 Eval 的必经步骤，也不能替代真实项目的 `dbx eval`。

运行内置 Demo 的后端链路自检：

```bash
dbx check --demo milk-tea --verbose
```

该命令会自动启动所需的 Demo MCP Server，并在检查结束后关闭，无需另开终端。若只想独立启动 Demo MCP Server 供其他客户端连接，运行：

```bash
dbx mcp demo milk-tea
```

服务默认选择空闲端口，连接地址以终端输出的 `streamable_http` 为准；按 Ctrl+C 停止服务。

Demo 中 `milk-tea` 暴露 `MilkTea_search`、`MilkTea_order`，`taxi` 暴露 `Taxi_search`、`Taxi_order`。Manifest tools 与 MCP `tools/list` 必须精确匹配，大小写不一致会被 preflight 拦截。

## 常见问题

| 问题                                  | 处理方法                                                                                            |
| ----------------------------------- | ----------------------------------------------------------------------------------------------- |
| Coding Agent 没有识别到 `dbx-eval` Skill | 确认项目级 Skill 目录中已经安装 `dbx-eval`，然后重新打开项目或刷新 Agent 会话。提示词中明确写“请使用 dbx-eval Skill”。                |
| 不需要实时页面时用什么命令                       | 使用 `dbx eval run`，卡片渲染和截图仍会执行。只有不需要这两项检查时，才添加 `--skip-render`。                                  |
| 报告没有截图是否一定失败                        | 不一定。先确认本次是否启用了 `skip_render`；如果没有，再检查 Widget 注册、工具结果中的实体数据、前端启动和浏览器环境。                          |
| 浏览器或渲染运行时失败                         | 检查本机 Chrome 或 Chromium、前端依赖和系统文件描述符限制。macOS 上遇到文件打开数量不足时，可在启动评测的终端先执行 `ulimit -n 65536`。        |
| 登录状态失效                              | 出现 401、403 或 DBX 登录失效提示时，执行 `dbx auth login`。成功后让 Agent 使用明确 run ID 或运行目录继续。                    |
| 评测执行结束，但 Release 是 `NOT PASS`       | 这通常不是 CLI 崩溃，而是准出规则被触发。读取 `veto.json` 和 `report.json`，说明具体原因。                                   |
| 什么时候应该创建新 Run                       | Manifest、Tool 名称、Tool 描述或输入输出 Schema 发生变化，Case 数完整性失败，未提供明确续跑 run ID，或旧状态版本与配置快照不兼容时，都应创建新 Run。 |

## 评测前检查清单

发起正式评测前，建议确认：

- `dbx eval --help` 能看到 `server`、`run`、`report`、`gen-explore`、`gen-trajectory`、`skill`。
- Node.js 版本不低于 `22.13.0`。
- `dbx auth status` 有效，或已完成 `dbx auth login`。
- `manifest.yaml` 中有非空 `app_key`。
- `node_modules/.doubao-dev/eval.yaml` 的 `app.app_id` 与 Manifest `app_key` 一致。
- `app.manifest`、`app.skill`、`mcp.url` 均可解析。
- Manifest tools 与 MCP `tools/list` 精确一致。
- 需要截图时，前端、Widget 和 Chrome 或 Chromium 可用。
- 大规模评测前先跑单 Intent 冒烟。
