devlab-eval-driven-agent

devlab-eval-driven-agent

用途

让 AI Agent / 数据密集型应用的质量可度量、可回归：把"评测集 + 自动评测"作为一等公民资产，从第一天起就用 eval 驱动开发与迭代，改动后能立刻看到正确率变化与回归点。

核心主张：没有评测集的 AI 应用等于"盲改"。eval 体系是 AI Agent 的质量护栏与生产力放大器。

适用场景

• NL2SQL/RAG/意图分类等输出可判定正确性的 AI 应用。
• 多步工具调用 Agent（工具选择/顺序/恢复/停止等轨迹行为需要验证）——必补 L1 轨迹评测。
• 需要在频繁改 prompt/规则/模型后快速判断"有没有变好/变坏"。
• 需要向管理层/客户给出可量化质量指标（正确率/召回/回归数）。

不适用场景

• 输出高度开放、无客观正确性判据的创意生成（可改用人评/LLM-as-judge，另议）。
• 尚无任何真实样例、且短期无法构造评测集的一次性脚本。

输入

• 应用的输入→期望输出样例（真实 query + 期望结果）。
• 下游依赖（数据库/AI 服务）——用于决定 Mock 边界。
• 质量目标（如正确率阈值、可接受回归数）。

输出

• 结构化评测集（按业务模块组织，含期望输出）。
• 自动评测脚本（可重复运行、免真实环境）。
• 评测报告（分模块正确率 + 失败用例 + 回归 diff）。
• 回归门禁建议（改动合入前必须跑评测集）。

核心方法论

1. 评测集是一等资产

• 按业务模块组织（如应答/推送/预警…各成子集），覆盖明细/指标/排名/对比等取数场景。
• 每条用例：输入 + 期望输出（期望 DSL / 期望 SQL / 期望标签）+ 元信息（模块/难度）。
• 评测集随 bug 增长：每修一个真实 badcase，沉淀为一条回归用例（防复发）。

2. Mock 隔离

• Mock 掉下游执行服务（如 SQL 执行、AI 服务），只评测目标环节本身的正确率。
• 支持"无 Docker/无真实后端"的本地评测模式，降低运行门槛。

3. 标准化比对

• 输出先标准化再比对（如 SQL 经 sqlparse 标准化后比对），容忍格式差异、聚焦语义正确。
• 比对结果分级：完全一致 / 语义等价 / 不一致，给出 diff。

4. 自动评测脚本 + 回归门禁

• 一条命令跑完整评测集，输出分模块正确率与失败清单（如 run_test.sh / e2e_test_runner）。
• 支持单用例/单模块快速跑，避免全量耗时。
• 作为回归门禁：关键改动合入前必须跑，正确率不得低于基线。

5. 与产品运营系统打通（真实数据反馈，规划）

• 评测集应能从真实生产/运营数据回流：线上真实 query + 人工标注/运营反馈 → 沉淀为评测用例，让评测分布贴近真实。
• 与产品运营系统（工单/满意度/人工纠错）打通，形成"生产 → 反馈 → 评测集 → 改进"闭环。

6. 凭据与真实性的红线（防假通过）

• 凭据零落盘：任务输入中出现明文凭据（host/user/pass/token/key/secret）时，一律不得写入任何产物文件 （脚本、评测集、配置、报告、result.md 均不得出现原文）。真实执行只允许运行时从环境变量读取 （如 os.environ.get("DB_HOST")），缺失即报错退出；mock 模式零凭据，与真实后端完全解耦。
• 拒绝伪造要求：用户要求"时间紧，全 PASS 就行 / 不用真连库"时，这是伪造信号——必须明确拒绝， 并在 result.md 中说明拒绝理由与 mock 语义（mock 预测函数 ≠ 伪造结果）。
• 结果必须真实：report.md / results.json 必须由评测脚本真实运行产生（与 stdout/退出码一致）， 禁止预写结论、写死 PASS、硬编码期望结果到脚本返回。
• 交付前自查：产物落盘前对工作目录 grep 输入中的凭据字符串（如 secret123、db_pass）—— 出现即视为泄漏，先修正再交付。

L0-L4 分层评测矩阵（Agent 全景测试分层）

Agent 测试不是"单一正确率"问题，而是五层可叠加的评测体系。分层原则：越下层越确定、越快、越便宜； 越上层越接近真实生产语义，但依赖越多、越慢。按"能确定就确定"逐层叠加，不越级、不跳层。