用例格式与复现指南

每个用例页对应仓库里的一个 markdown 文件，文档和测试是同一个文件： CI 每天执行的就是你看到的这一页，不存在”文档说的”和”实际测的”两份。

一页怎么读

元素	含义
考什么	这个用例存在的理由——它度量的能力面
题面（```prompt 块）	逐字节发给 agent 的用户消息，$today/$today+7d 是运行时求值的日期占位符
验收（```yaml 块）	判定断言。final_state 由测试框架直接查引擎打真值，不信 agent 的话
验收（```js 块）	代码验收——声明式表达不了的差分/结构断言
基础项目	用例的初始数据环境，版本化不可变（crm-basic@1 发布后永不修改）

多步用例（标了步骤数的）：多个题面在同一个会话里连续执行，每步跑完 立即判定，某步失败即停并报告”第几步”。它考的是连续作业——比如第二步只说 “把刚才那家改回去”，agent 必须记得第一步改的是谁。

验收的设计原则

断言写意图，不写路径。 我们只规定”答案必须正确、状态必须改对、不许暴力 翻表”（工具调用上限），不规定 agent 必须用哪个工具、按什么顺序。聪明的解法 不该被考卷惩罚——这条原则是用真实事故换来的：曾有断言强制要求走聚合工具， 结果把”从值分布直接拿现成计数”的更优解判成失败，越强的模型挂得越多。

写类用例查引擎终态。 agent 说”已改好”不算数：跑完后直接查数据引擎， 行数、存储形态（选项引用而非文本）都要对得上。

在本地复现

三步：起容器 → 配模型 key → 跑。

# ① 起一个星汉容器（默认 8090 端口）
sh tools/docker/workspace/run.sh up 8090

# ② + ③ 用你的大模型 API key 一键种 provider 并开跑
cd packages/agent-eval
EVAL_SEED_PROVIDER=1 \
EVAL_PROVIDER_KEY=sk-你的key \
EVAL_PROVIDER_TYPE=openai-compatible \
EVAL_PROVIDER_BASEURL=https://api.你的服务商.com/v1 \
EVAL_MODEL=某模型id \
pnpm eval --only <用例id> --runs 3

全部参数（都走环境变量）：

变量	必填	说明
EVAL_PROVIDER_KEY	二选一	大模型 API key。配合 EVAL_SEED_PROVIDER=1 自动在容器里创建/更新 provider
EVAL_PROVIDER_ID	二选一	容器里已配好的 provider id（产品设置页配过模型就有）。与上面一组二选一
EVAL_PROVIDER_TYPE	否	anthropic（默认）/ openai / openai-compatible
EVAL_PROVIDER_BASEURL	否	服务商 API 地址（OpenRouter、DeepSeek 等中转必填）
EVAL_MODEL	否	模型 id，不填用 provider 默认
EVAL_BASE_URL	否	容器地址，默认 http://localhost:8090
EVAL_FIXTURE_DIR	否	基础项目缓存目录，默认 .fixtures-cache/（首跑自动从 OSS 下载并 sha256 校验）
EVAL_TRANSCRIPTS	否	对话凭证：failures（默认，只留失败样本）/ all / none

命令行参数：--only <用例id前缀> 只跑匹配的用例；--runs N 覆盖每例次数。 用了任意一个就跳过基线门禁比对（样本和基线不同，比了没意义）。

报告在哪看

每次跑完，终端直接打印 markdown 报告，同时落盘：

packages/agent-eval/reports/
  <时间戳>.html                # 双击即开的可视化报告（结论/分域/逐用例/失败剖析）
  <时间戳>.md                  # 终端/PR 里贴的纯文本版
  <时间戳>.json                # CI 比基线用的结构化数据
  <时间戳>-transcripts/        # 失败样本的完整对话凭证（题面/工具轨迹/回答/评分）

报告双指标：pass@k（k 次里至少对一次——能不能做到）与 pass^k（k 次 全对——稳不稳定，基线门禁盯它）；网络/环境 error 不进成功率分母但单独报 错误率。想深挖某个失败：打开对应 transcripts 目录里的 JSON，工具调用序列、 每次调用的参数和返回值、模型完整回答都在里面。

想贡献用例？

用例格式的完整规范（含五条纪律与 fixture 版本化规则）在仓库 packages/agent-eval/cases/README.md。公开集之外还有一组永不公开 的 holdout 用例做防过拟合对照——公开分数刷上去、holdout 分数没跟上，说明 优化过拟合了公开集，这是我们自己也要遵守的红线。