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/evaluation/automated-evaluation.md.

自动化评测

提示

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

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

适用场景

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

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

开始前

开始评测前,请确认:

  • Node.js 版本不低于 22.13.0。
  • 已按照《CLI 安装与配置》完成 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 检查项目、收集缺失配置、选择正确命令、跟踪运行状态、读取证据文件,并在失败后完成修复与回归。

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

dbx eval skill

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

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

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

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,然后直接说明目标。

完整评测:

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

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

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

分析已有失败报告:

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

修复后回归:

请根据刚才的 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

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

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

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

--skip-render

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

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

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

最小示例:

# 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.manifestManifest 路径,通常是 ./manifest.yaml。
app.skill被测 Skill 目录,通常为 ./skill;递归加载其中的 SKILL.md。
app.app_idApp Key,应与 Manifest 中的 app_key 一致。
mcp.urlMCP 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_concurrencyChecklist 生成并发,默认 1,最大 2。
run.scoring_concurrencyCase 评分并发,默认 1,最大 2。
run.judge_concurrencyJudge 请求并发,默认 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:

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

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

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

配置优先级从高到低:

显式 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. 查看报告

默认输出目录形如:

<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.jsonCase 校验失败时的诊断产物。
cases.raw.json原始生成 Case,排查 Case 数完整性失败时使用。
skill-review.jsonSkill 质量评分、问题和建议。
veto.jsonRelease Veto 是否命中及原因。
developer-summary.json面向开发者的问题聚类和整改建议。
posthook-summary.jsonSimulator 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 原因。
Evaluatorrule 检查确定性规则,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_INCOMPLETEmissing_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 或 timeouthttp_status、error_type、log_id、retryable通常可稍后使用 --resume 继续。
渲染或截图失败前端、Widget、Chrome、文件描述符限制先修复环境;只有接受无卡或无截图评测时才用 --skip-render。
单个 Case 失败report.json、scores/、trajectories/按 Case 分数、Hard Failure、归因和 LogID 汇报,不要说整个 Eval 执行失败。
Release 是 NOT PASSveto.json、report.json这是准出失败,不是 CLI 崩溃;说明具体 Veto 原因。

8. 修复与回归

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

推荐闭环:

确认失败阶段和证据
-> 判断代码、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 时,默认创建新任务。

继续一个中断的运行:

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

不需要实时页面时:

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

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

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:

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 的后端链路自检:

dbx check --demo milk-tea --verbose

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

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,说明具体原因。
什么时候应该创建新 RunManifest、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 冒烟。