--- name: dbx-eval description: 运行和配置 DBX Eval 自动化评测。用户要求执行 dbx eval、评估 MCP 或 Skill、启动实时评测页面、查看历史评测报告、生成轨迹评分报告、配置或续跑评测时使用。 --- # DBX Eval 使用 `dbx eval` 执行豆包小程序 Agent 的自动化评测。完整流水线包括 MCP 探索、用例生成、轨迹、评分、归因和 HTML 报告。 ## 命令选择 - `dbx eval server`：本地交互式评测，同时提供 localhost 实时进度和报告页。 - `dbx eval run`：纯终端评测，适合 CI、无浏览器环境或用户明确不要 Web 页面。 - `dbx eval report`：列出当前项目已有报告并选择一个使用默认浏览器打开。 - `dbx eval gen-explore`：只探索 MCP 工具并生成实体池。 - `dbx eval gen-trajectory`：只生成指定 Intent 的多轮轨迹。 - `dbx eval skill`：为存量项目补装 `dbx-eval` Skill；未初始化时按选择的 Agent 安装全部内置 Skills。 发起完整评测时，默认使用 `dbx eval server`，让用户同时看到终端日志和 localhost 实时进度 / 报告页。只有用户明确说“不需要页面 / 只要终端 / CI / 无浏览器环境”， 或页面依赖无法满足且用户同意降级时，才使用 `dbx eval run`。 `server` 完成 Pipeline 后会继续驻留供用户查看报告。记录并反馈页面 URL，用户不再 需要页面时再通过 `Ctrl+C` 关闭；使用 `--no-open` 可禁止自动打开浏览器。 不要把“不要页面”自动等同于 `--skip-render`。`dbx eval run` 只是没有实时 Web 页面；`--skip-render` 只在用户明确不要卡片渲染 / 截图，或运行环境没有前端、 Widget、Chrome、截图能力时使用。 `report` 按 run 创建时间从新到旧展示，每页 10 条，只列出存在 `report.html` 的 当前项目 run。使用 `--project-path` 指定其他项目；使用全局 `--json` 时只返回摘要 列表，不打开浏览器。该命令不发起评测，不要求登录、MCP 可达或项目 Eval 配置完整。 ## 为存量项目补装 Skill 存量项目在早期 `dbx init` 后可能缺少 `dbx-eval` 的项目级入口，而 `dbx upgrade` 只刷新全局托管目录，不会新增项目软链接。此时使用： ```bash dbx eval skill --project-path ``` 命令根据项目当前状态执行两种行为： - 已存在任一内置 Skill 入口（软链接、目录或断链）时，向全部已发现的项目级 Skill 目录只补装 / 刷新 `dbx-eval`，此时 `--agent` 不生效。 - 完全没有初始化痕迹时，复用 `dbx init` 的 Agent 选择安装全部内置 Skills。非交互 环境必须用 `--agent ` 指定目标（可重复，`universal` 自动包含）。 `--skills-mode link|copy`（默认 `link`）与 `-y, --yes`（覆盖非软链目录前自动备份） 沿用安装器既有语义。该命令只安装 Skill，不执行认证、脚手架、MCP 或 Git 初始化。 ## 新建与续跑 默认创建新任务，并默认执行不带 `--resume` 的 `dbx eval server`。除非用户明确说 不需要页面、只要终端、CI 或无浏览器环境，否则不要把首次运行或新任务切到 `dbx eval run`。用户只说“继续评测”“再跑一次”“续跑刚才失败的任务”，但没有提供 run ID 时，也创建新任务。 只有用户明确要求续跑具体 run ID 时，才续跑；默认仍使用实时页面： ```bash dbx eval server --resume ``` 用户明确要求不要页面、只要终端、CI 或无浏览器环境时，续跑才使用： ```bash dbx eval run --resume ``` 如果用户完成一轮评测后，根据报告修改了当前项目的 `SKILL.md` 或 Tool 内部实现， 并明确要求使用原 Case 和 Checklist 验证修复效果，先记录或复制修复前报告，再使用： ```bash dbx eval server --resume --from-phase rollout ``` 不需要实时页面时改用 `dbx eval run`。该命令重新读取项目当前的 `SKILL.md`，保留 分析、实体池、业务流、Intent、Case 和 Checklist，重新执行 Skill Review、全部轨迹、 评分、归因、准出和报告。Tool 内部实现和返回效果可以变化，但 Manifest、Tool 名称、 描述和 Schema 必须与原评测一致；这些能力契约发生变化时创建新的完整评测。 该命令会覆盖原运行目录中的轨迹、评分、截图和报告，不可与 `--rerun-failed` 同时使用，也不支持 `score_only`。如需对比修复前后结果，执行前复制原报告或记录 原通过率、失败项、归因和 Release 决策。 用户只提供 run ID、但没有表达续跑意图时，不自动续跑。不得从最近任务、失败记录、 `dbx eval report` 的报告列表或 `~/.dbx/eval-runs/index.json` 中推断或补全续跑 目标；`report` 仅用于查看历史报告。 ## 项目配置门禁 执行会发起评测的 Eval 命令前： 1. 明确用户要评测的项目绝对路径 `projectPath`，不要默认猜测其他项目。 2. **确认 App Key（强制，不可跳过）**：发起任何会发起评测的命令（`dbx eval server` / `dbx eval run` / `gen-explore` / `gen-trajectory`）之前，必须先向 用户确认本次评测使用的 `app_key`。读取解析出的 `manifest.yaml` 的 `app_key`， 把该值展示给用户并要求其明确确认「就用这个 app_key」；`manifest.yaml` 缺失 `app_key`、值为空或用户不确认时，用 `AskUserQuestion` 追问，拿到后写入 `manifest.yaml` 的 `app_key` 字段（Manifest 是唯一事实来源，不要只写进 `.dbx/eval.yaml`）。使用 `--app-id` 时其值必须与 Manifest 的 `app_key` 一致， 否则 `resolveAppKey` 会报 `AppID mismatch`。未获得用户对 `app_key` 的确认， 不得发起评测。这一步与登录无关：`dbx auth login` 只提供 SSO 登录态，不提供 `app_key`。仅当用户明确使用自定义 OpenAI-compatible endpoint（不走 Gateway） 时，`app_key` 才非必需。 3. 检查 `/.dbx/eval.yaml`。 4. 文件存在时读取并检查必需字段，不要重复询问已有信息。 5. 文件不存在或字段不完整时，必须使用 `AskUserQuestion` 一次询问一个问题， 收集缺失信息后再运行。 6. 执行命令默认选择 `dbx eval server`。不要询问“是否需要实时页面”；只有用户已 表达不要页面 / 只要终端 / CI / 无浏览器环境，或页面依赖检查失败时，才切换到 `dbx eval run` 或向用户确认降级。 使用自定义 LLM endpoint 时，项目配置会包含明文 API Key。不得在回复、日志摘要或 错误信息中输出完整 Key，不得建议用户提交或分享 `.dbx/eval.yaml`。 ## 必需信息 优先从项目文件和已有上下文获取，只询问无法确定的字段： - LLM 默认使用登录后的远端 Gateway，不要求用户提供 endpoint、API Key 或 model。 - 仅当用户明确要求自定义模型服务时，收集完整的 `ua.base_url`、`ua.api_key` 和 `ua.model`。 - Judge 未配置的 endpoint、API Key 和 model 分别继承 UA，只询问用户要覆盖的字段。 - MCP URL：`mcp.url` - Manifest：`app.manifest` - Skill：`app.skill` - App Key：默认 Gateway 后端下必需。发起评测前必须向用户确认 `manifest.yaml` 的 `app_key`（见「项目配置门禁」第 2 步）；缺失或未确认时追问并写回 Manifest。 - 运行默认值：`run.intent_count` 默认 20，可配置范围 1–100；超过 100 时 CLI 按 100 执行。`run.max_rounds` 默认 10，可配置范围 1–20；超过 20 时 CLI 按 20 执行。其余包括 pass@k、阈值、最大步数、输出目录 - 正式评测可分别配置 `run.concurrency`（轨迹）、`run.scoring_concurrency` （Case 评分）、`run.judge_concurrency`（Judge 请求）和 `run.checklist_concurrency`（Checklist 请求）。四项均默认 1，可配置范围 1–2； 超过 2 时 CLI 按 2 执行 - `skip_render` 默认 `false`。只有用户明确不要卡片渲染 / 截图，或确认环境没有 前端、Widget、Chrome、截图能力时，才询问或设置为 `true` 如果找到多个 Manifest、Skill 或 Eval YAML 候选，必须让用户选择，不得自行 决定。 推荐的 `run` 配置如下，按需要修改即可： ```yaml run: intent_count: 20 concurrency: 1 checklist_concurrency: 1 scoring_concurrency: 1 judge_concurrency: 1 max_rounds: 10 ``` ## 首次配置 不要直接写最终的 `/.dbx/eval.yaml`。在本地临时目录生成 YAML， 将收集的信息写入后通过 `-c` 交给 CLI。默认使用实时页面： ```bash dbx eval server \ --project-path \ -c ``` 如果用户明确不要页面或当前环境只能终端运行，改用： ```bash dbx eval run \ --project-path \ -c ``` 如果只是不要实时页面但仍要验证卡片渲染，不要添加 `--skip-render`；只有明确 无卡 / 无截图评测时才加 `--skip-render` 或把 `run.skip_render` 写入临时 YAML。 CLI 校验成功后会把最终生效配置原子写入： ```text /.dbx/eval.yaml ``` 显式 `-c` 会更新项目默认配置。后续运行可省略 `-c`： ```bash dbx eval server --project-path ``` 如果 CLI 报 `EVAL_PROJECT_CONFIG_INCOMPLETE`，根据 `missing_fields` 继续通过 `AskUserQuestion` 收集，不要臆造值。 ## 配置优先级 ```text 显式 CLI 参数 > -c 指定 YAML（替换项目 YAML 层，不与项目 YAML 合并） > /.dbx/eval.yaml（未指定 -c 时） > ~/.dbx/config.yaml > Manifest 推导 > 非 endpoint 默认值 ``` 四个命令共用项目配置： - `dbx eval server` - `dbx eval run` - `dbx eval gen-explore` - `dbx eval gen-trajectory` `dbx eval server --resume` 和 `dbx eval run --resume` 使用运行目录中的状态快照， 不修改项目配置。 ## 运行前检查 - Node.js 版本至少为 `22.13.0`。 - 默认推荐先执行 `dbx auth status`；未登录时提示执行 `dbx auth login`。 - 默认 LLM 通过 SSO 调用 `{apiBaseUrl}/app_developer/api/v1/chat/completions`。仅完整配置自定义 OpenAI-compatible endpoint 时，LLM 调用不依赖 SSO。 - 默认 Gateway 登录态过期时，Eval 应提前终止并提示 `dbx auth login`； 不要把 `Login token has expired` 解释为 MCP、业务工具或卡片渲染错误。 - 默认 Gateway 后端下，`manifest.yaml` 必须包含非空 `app_key`。DBX Gateway 依赖 它对每次 LLM 调用做归因，缺失时 preflight 的 `Manifest app_key` 检查会致命失败， Eval 不会启动。此时提示在 `manifest.yaml` 写入 `app_key`（或用 `--app-id` 指定，且需与 Manifest 一致）。仅完整配置自定义 OpenAI-compatible endpoint 时不 强制 `app_key`。`dbx auth login` 只提供 SSO 登录态，不提供 `app_key`，两者相互 独立。 - `skip_render` 只跳过前端、浏览器和截图，不豁免默认 Gateway 的登录要求。 - MCP URL 可达，且 Manifest tools 与 `tools/list` 一致。 - 未使用 `skip_render` 时，前端依赖、浏览器和文件描述符限制满足要求。 - 使用 `skip_render` 时，不要求前端、Widget、Chrome 或截图运行时。 ## 快速冒烟 ```bash dbx eval run \ --project-path \ --intent '<明确场景>' \ --intent-count 1 \ --pass-k 1 \ --concurrency 1 ``` 无卡评测增加： ```bash --skip-render ``` ## 用例生成策略 自动模式（未指定 `--intent`）下，用例生成优先走业务流驱动： - 从 API 依赖和 Skill 文档推导业务流 FlowMap，再由确定性计划分配每条流的主干、 分支和异常用例，最后为每条用例回填来源字段 `flow_id`、`case_kind`、`flow_variant`。 - 这是 best-effort：FlowMap 生成失败或无有效业务流时，自动回退到既有的 seed 规划， 不影响评测继续。产物 `generation-coverage.json` 的 `strategy` 字段标记本次策略 （`flow_v2` 或 `legacy_seed`）。 - 覆盖率只告警不阻断：`generation-coverage.json` 记录未覆盖的业务流和 API，缺口不会 使评测失败，也不会自动补生成。 - 显式 `--intent` 恒走既有路径，不生成来源字段，用例数与 Intent 数严格一致。 - Case 数完整性是硬门禁：实际通过校验的 Case 少于计划数时，Pipeline 在用例生成阶段 立即停止，不进入 Checklist、Trajectory、评分或报告阶段，也不生成正式 `report.json` / `report.html`。不得把部分 Case 结果描述为完整评测。 向用户解释用例或排查问题时，可用 `flow_id`/`case_kind` 说明某条用例覆盖的业务链路 与类型；不要把覆盖率告警当作评测失败。 ## 运行观察与失败排障 运行 `dbx eval server` 时，同时关注 localhost 页面和终端输出。页面用于看阶段进度， 终端用于保留可复制的错误摘要；最终诊断仍以输出目录中的文件为准。 运行中或失败后，按以下顺序读取产物，不要只根据终端最后一行下结论： 1. 先确认输出目录和 run ID。`run.log` 开头包含 `Starting new run ... at `， `server` 模式还会在终端输出 localhost 页面 URL。 2. 如果存在 `failure.json`，优先读取它。它是提前终止的诊断摘要，包含 `stage`、 `title`、`message`、`hint`、`error_type`、`http_status`、`log_id`、`retryable`、 `completed_phases` 和下一步命令。普通可续跑失败提供 `resume_command`；Case 数 完整性失败提供 `failure_kind=case_generation_incomplete`、 `next_action=new_run`、`case_generation` 和 `new_run_command`，不提供 `resume_command`。 3. 读取 `state.json`。重点看 `failure.stage/message/logId/retryable`、各 `phases` 的 `pending/partial/done` 状态，以及 `cases.*.attempts[].status/error`，用来判断 卡在哪个阶段、哪些 case 已完成、是否适合 `--resume`。 4. 读取 `run.log` 的尾部和失败阶段附近日志。优先检索 `FATAL`、`ERROR`、`WARN`、 `FAILED`、`Failure diagnostic saved`、`log_id=`、`logid` 和失败阶段名。 5. 如果已生成 `report.json`，说明 Pipeline 已进入报告阶段；按报告里的 `summary`、 `veto`、`attribution_summary`、`skill_review_view` 和各 case 分数解释质量问题。 这类 `NOT PASS` 不是“执行提前终止”。 6. 如果已生成 `veto.json` 但没有 `report.json`，优先说明准出判定已完成但报告写入失败； 继续结合 `state.json` 和 `run.log` 判断是否可重跑或续跑。 常见失败归因规则： - Case 数完整性失败：当 `failure_kind=case_generation_incomplete` 时，向用户展示 `case_generation.planned_cases`、`valid_cases`、`missing_cases`、 `missing_case_ids` 和每个 `invalid_cases[].reasons`。同时读取 `case-validation.json` 与 `cases.raw.json` 解释生成或校验问题。此类失败不可用 `--resume` 补齐；修复 Skill、业务流或生成约束后，按 `new_run_command` 创建 replacement Run。 - `preflight` 失败：通常是登录态、MCP 可达性、Manifest/tools 合约、Node/浏览器/文件 描述符等运行前置条件问题。先复述失败检查项和 hint，再给修复命令或配置项。 - `preflight` 的 `Manifest app_key` 失败：`manifest.yaml` 缺少非空 `app_key`。提示在 Manifest 写入 `app_key`（或用 `--app-id` 指定并与 Manifest 一致）后重跑；这与登录 无关，`dbx auth login` 不会补上 `app_key`。 - `dev_runtime` 或渲染相关失败：说明前端、Widget、Chrome、截图环境或本地调试运行时 问题。不要建议直接 `--skip-render`，除非用户接受无卡 / 无截图评测。 - 默认 LLM Gateway 登录态失效：如果 `failure.json` / `state.json` / `run.log` 出现 `Login token has expired`、`登录状态已失效`、`http_status=401/403` 且后端为 `gateway`，根因是 DBX SSO 登录态过期；必须提示先执行 `dbx auth login`，登录成功后再按 `resume_command` 或 `--resume ` 继续。不要建议直接重跑，也不要归因为 MCP Server、业务工具或 `http://127.0.0.1:/mcp`。 - LLM/Gateway 失败：报告 `http_status`、`error_type`、`transport`、`log_id` 和是否 `retryable`。401/403 先建议 `dbx auth login`；429/5xx/timeout 通常可稍后 `--resume`。 - MCP/工具调用失败：检查 `mcp.url`、Manifest 的 `mcp_server.end_point`、`tools/list` 和 `run.log` 中具体工具名；不要把工具返回业务空结果直接判成平台故障。 - `rollout` 中单 case 失败：如果 Pipeline 继续生成了报告，按 case 分数、hard failure、 attribution 和 LogID 汇报；不要把个别 case 不通过描述成整个 Eval 执行失败。 - `veto` 不通过：说明评测完成但准出失败，优先引用 `veto.json` 和 `report.json` 的 reasons，给出影响面和整改方向。 向用户反馈失败时，必须包含： - 当前状态：运行中 / 已提前终止 / 已完成但未通过 / 已完成并通过。 - 失败阶段或准出结论，以及一行根因判断。 - 证据路径：`failure.json`（存在时）、`state.json`、`run.log`、`report.json` 或 `veto.json` 的绝对路径。 - Case 数完整性失败还必须提供 `case-validation.json` 和 `cases.raw.json` 的绝对路径， 并明确说明未生成 Checklist、Trajectory、评分和正式报告。 - LogID：有则原样给出；没有则明确“未发现 LogID”。 - 下一步：可直接重跑、可用 `--resume `、需要先登录、需要启动 MCP、需要修复 Skill/工具/渲染环境等。不要承诺已经修复尚未验证的问题。 ## 产物与反馈 反馈时必须提供完整绝对路径： - 输出目录 - `report.html`（默认轻量报告，依赖同目录下的 `screenshots/`） - `report-standalone.html`（截图内联的自包含报告，适合单文件转发或部署） - `report.json` - `run.log` - `state.json` - `failure.json`（提前终止时存在） - `case-validation.json` 和 `cases.raw.json`（Case 数完整性失败时的诊断产物） - `.dbx/eval.yaml` - `skill-review.json` 和 `veto.json` - `flow-map.json` 和 `generation-coverage.json`（业务流驱动生成时存在） - `trajectories/`、`scores/` 和 `screenshots/`（存在时） 同时列出： - 通过率和通过数/总数 - Release 决策 - 各 evaluator 得分 - Case 数、pass@k 和总耗时 - 失败阶段、关键错误和 LogID（失败时） - localhost 页面 URL（使用 `server` 且仍驻留时） 不得把缺少截图描述成评测失败；`skip_render` 模式下无截图是预期行为。