Eval Panel (`/i/dev/eval`)

Eval Panel 是内置 devtools 页面，用来直接对本地运行中的 agent 执行 live evaluation cases。这些 cases 是固定提示和确定性期望的小样本，会走真实 LLM、真实 tools 和真实 prompt assembly，但不会污染正常会话历史。

当 devtools UI 通过 mushroom-agent start 或 mushroom-agent serve --ui 启用时，该页面可用。普通生产 serve 模式不会挂载它。

适合场景

场景	用 Eval Panel	用 `mushroom-agent eval-live`
修改 system prompt / 工具后，本地交互验证	✅ Eval Panel	⚠️ 也可以，但没有 UI
在 CI / 脚本中运行 live regression	❌	✅ `eval-live` + `eval-live.yml`
验证某条 instruction 在当前模型下是否仍被遵守	✅	✅

Live runs 会共享 agent 的 ctx.think 和 ctx.tools，因此会调用你配置的 LLM provider 并消耗真实 token。运行前请确认预算。

打开页面

mushroom-agent start
打开 http://127.0.0.1:7860/i/dev/eval，或从 chat 顶部栏点击 "Eval ->"

运行 suite

从左侧列表选择一个或多个 cases，可用 All / None 快速切换。所有 bundled cases 都会 live 执行。
设置 Samples（1-5）。每个 sample 都是一次独立 LLM 调用。
可选：勾选 Enable LLM-as-judge，用 judge.instruction_following 为输出打分，也可以在 Advanced 中增加 judge.task_completion。如果未设置 EVAL_JUDGE_MODEL，该选项会禁用。
点击 Run。确认弹窗会显示预计 LLM 调用次数：cases x samples x (1 + judge_metrics)。
查看 live progress bar 和 per-sample 表格。可用 Cancel 取消运行中的任务。
底部 summary 会显示 pass/fail 计数和 host-context drift warnings。

每次运行会保存到 <workspace>/eval_runs/run_<hex>.json；如果没有 workspace，则保存到 ~/.mushroom_agent/eval_runs/。系统会保留最新的 dev.eval.keep_runs 个文件，清理更旧的 runs。

Token 预算

典型调用量为：

calls = N_cases x N_samples x (1 + N_judge_metrics)

例如 bundled 10 个 live cases、1 个 sample、0 个 judges，约为 10 次 LLM 调用。如果启用两个 judges 且 samples 为 3，则约为 90 次调用。点击确认前请查看弹窗里的估算。

LLM-as-judge 配置

Judge 使用独立 LLM credentials，不能复用生产 OPENAI_API_KEY。这是刻意限制，原因见 mushroom-evals/mushroom_evals/judge.py：

export EVAL_JUDGE_MODEL=gpt-4o-mini
export EVAL_JUDGE_API_KEY=sk-eval-...
# optional
export EVAL_JUDGE_BASE_URL=https://your-proxy/v1

未配置时，judge metric 行会显示 status="skipped"，且不会计为失败。配置错误时，行会显示 status="error"，但 run 会继续。

配置（`config.yaml`）

dev:
  eval:
    enabled: true            # 设为 false 会隐藏 /i/dev/eval
    max_concurrency: 1       # 同时运行的 run 数量，硬上限为 4
    keep_runs: 20            # 磁盘保留数量
    default_enable_judge: false  # UI judge checkbox 的默认勾选状态

如果 dev.eval.enabled = false，register_eval_routes 会返回 None，页面会变成 404。

和 `mushroom-agent eval-live` 的区别

两个入口共享同一条执行路径：mushroom_evals.runners.agent_runner.run_case_live。差异主要是运行方式：

	`mushroom-agent eval-live` (CLI)	Eval Panel (`/i/dev/eval`)
LLM 成本	真实	真实
运行位置	CI / scripts，无 UI	dev process 内
触发方式	shell 命令	手动点击
Memory	真实 `ctx.memory`；runner 会设置 `turn_ctx.extras['is_eval']=True`，memory 实现决定是否短路	相同
Trace IDs	`eval-{run_id}-{case.id}-s{sample}`	相同
适合用途	定时或按需 live regression	探索式验证

CI / scripts 入口见 mushroom-agent eval-live 以及 .github/workflows/eval-live.yml workflow。

`mushroom-agent eval-live`

和 dev panel 使用同一条 live 执行路径，但提供非交互 CLI，适合 CI / scripts。

# 真实运行 live LLM，需要可用的 ~/.mushroom_agent/config.yaml 和 llm.api_key
mushroom-agent eval-live --suite all --samples 2

# dry-run：发现 cases、构建 agent，但不调用 LLM
mushroom-agent eval-live --dry-run

关键 flags：

Flag	默认值	说明
`--suite`	`all`	`smoke` 或 `all`
`--samples`	`1`	每个 case 的独立运行次数
`--capability` / `--case-id`	未设置	过滤条件
`--enable-judge` / `--no-enable-judge`	auto	需要 `EVAL_JUDGE_MODEL` + `EVAL_JUDGE_API_KEY`
`--judge-metrics`	`judge.instruction_following`	逗号分隔
`--case-timeout`	`120`	秒；每个 case 使用 asyncio.wait_for
`--write-baseline NAME`	未设置	写入 candidate baseline 到 `mushroom-evals/mushroom_evals/baselines/`
`--dry-run`	关闭	schema / agent 校验后退出 0，不调用 LLM
`--silence`	关闭	静默 per-case progress lines

Reports：

mushroom-evals/reports/live-{suite}-{ts}-detail.jsonl：每个 case x sample 一行，包含所有 metrics
mushroom-evals/reports/live-{suite}-{ts}-summary.jsonl：按 case 聚合，包含 pass@1、avg_score
exit code：0 全绿 / 1 regression / 2 setup error，例如缺少 llm.api_key

GitHub Action .github/workflows/eval-live.yml 是 canonical scheduled / on-demand runner，只通过 workflow_dispatch 触发。

参见

Implementation walk-through: docs/design/agent-eval-framework.md §9.3
Schema: mushroom-evals/mushroom_evals/schema.py
Dev console: /web

适合场景​

打开页面​

运行 suite​

Token 预算​

LLM-as-judge 配置​

配置（config.yaml）​

和 mushroom-agent eval-live 的区别​

mushroom-agent eval-live​

参见​