自动化评测
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 检查项目、收集缺失配置、选择正确命令、跟踪运行状态、读取证据文件,并在失败后完成修复与回归。
在豆包应用插件项目根目录执行:
也可以显式指定项目路径:
如果项目尚未初始化任何 Agent Skill 目录,可以指定目标 Agent:
根据项目当前的安装情况,命令会执行以下操作:
- 如果项目已经安装过开发 Skill,会在所有检测到的 Skill 目录中更新或补装
dbx-eval;此时指定--agent也不会只更新某一个 Agent。 - 如果项目还没有安装过开发 Skill,会为你选择的 Agent 安装 CLI 内置 Skills。通过脚本或非交互终端运行时,需要用
--agent <id>指定 Agent。 - 该命令只安装 Skill,不执行登录、脚手架、MCP 启动或 Git 初始化。
安装完成后,重新打开项目或刷新 Coding Agent 会话,使新 Skill 被加载。
2. 让 Coding Agent 发起评测
推荐从豆包应用插件项目根目录打开 Coding Agent,然后直接说明目标。
完整评测:
只验证一个已知业务场景:
分析已有失败报告:
修复后回归:
提示词中最重要的是说明项目、目标场景、是否允许改代码,以及期望 Agent 返回哪些证据。
3. 手动 CLI 命令
第一次运行时,先选一个业务场景,确认配置、MCP 和卡片渲染都正常,再增加用例数和并发数。
先用一个场景检查评测是否能正常运行:
使用 dbx eval run 可以直接在终端运行评测,卡片渲染和截图仍会执行。如果这次不需要检查卡片,或运行环境缺少前端、Widget 或浏览器,可以添加以下选项跳过渲染和截图:
4. 配置 node_modules/.doubao-dev/eval.yaml
项目的评测配置保存在 node_modules/.doubao-dev/eval.yaml。首次运行时,可以用 -c <temporary-config.yaml> 指定准备好的配置文件;校验通过后,CLI 会将本次使用的配置保存到项目的默认位置,方便下次继续使用。
配置可能包含明文模型凭证,不应提交到代码仓库。
最小示例:
常用字段:
使用自定义 OpenAI-compatible endpoint 时,才需要配置 ua:
Judge 未配置时继承 UA。若要单独覆盖 Judge:
配置优先级从高到低:
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. 查看报告
默认输出目录形如:
让 Coding Agent 给出报告的完整路径,并说明:评测是否完成、用例通过率、是否满足发布条件(Release 决策)、哪些用例失败,以及对应的 LogID 和修复建议。
重点产物:
核心结论的含义:
常见 Release Veto 触发条件:
- 通过率低于
run.pass_threshold。 - 存在被评测基础设施或 Case 冲突阻塞的 Case。
- 存在 Hard Failure。
- 存在
L1_platform归因项。 - Skill Review 总分低于 0.5,或 Skill 描述与实际 Tool 行为不匹配。
pass_k实际最大尝试次数大于 2。
7. 失败排障
不要只根据终端最后一行下结论。运行中或失败后,按以下顺序读取证据:
- 确认输出目录和 run ID。
run.log开头包含Starting new run ... at <outputDir>,server模式还会输出 localhost 页面 URL。 - 如果存在
failure.json,优先读取它。它包含stage、message、hint、error_type、http_status、log_id、retryable、completed_phases和下一步命令。 - 读取
state.json。重点看failure.stage/message/logId/retryable、各阶段状态,以及每个 Case 的 attempts。 - 读取
run.log尾部和失败阶段附近日志。优先检索FATAL、ERROR、WARN、FAILED、Failure diagnostic saved、log_id=、logid和失败阶段名。 - 如果已生成
report.json,说明 Pipeline 已进入报告阶段;这类NOT PASS通常不是执行提前终止。 - 如果已生成
veto.json但没有report.json,优先说明准出判定已完成但报告写入失败,再结合state.json和run.log判断是否可重跑或续跑。
归因口径:
常见问题与优先处理:
8. 修复与回归
先结合日志和失败用例,确认问题出在平台、工具还是 Skill,再修改对应部分。归因标签可以帮助排查,但不能单凭标签就重写 Skill 或工具。
推荐闭环:
常见修复策略:
9. 续跑边界
只有开发者明确要求续跑具体 run ID 或运行目录时,才使用 --resume。开发者只说“继续评测”“再跑一次”“续跑刚才失败的任务”,但没有提供 run ID 时,默认创建新任务。
继续一个中断的运行:
不需要实时页面时:
只重试失败 Case、复用已通过 Case:
--resume 会使用原运行目录里的状态快照,拒绝其他运行参数。不要从 dbx eval report 的报告列表或 ~/.dbx/eval-runs/index.json 中自行推断续跑目标。
使用原 Case 验证 Skill 或 Tool 修复
如果只修改了当前项目的 SKILL.md、Tool 内部业务逻辑、测试数据或运行返回效果,可以保留原 Case 和 Checklist,从 rollout 阶段重新执行全部 Case:
不需要实时页面时改用 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 的后端链路自检:
该命令会自动启动所需的 Demo MCP Server,并在检查结束后关闭,无需另开终端。若只想独立启动 Demo MCP Server 供其他客户端连接,运行:
服务默认选择空闲端口,连接地址以终端输出的 streamable_http 为准;按 Ctrl+C 停止服务。
Demo 中 milk-tea 暴露 MilkTea_search、MilkTea_order,taxi 暴露 Taxi_search、Taxi_order。Manifest tools 与 MCP tools/list 必须精确匹配,大小写不一致会被 preflight 拦截。
常见问题
评测前检查清单
发起正式评测前,建议确认:
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与 Manifestapp_key一致。app.manifest、app.skill、mcp.url均可解析。- Manifest tools 与 MCP
tools/list精确一致。 - 需要截图时,前端、Widget 和 Chrome 或 Chromium 可用。
- 大规模评测前先跑单 Intent 冒烟。