SuperBizAgent-java/mvp/eval/schema.md

Diagnosis Eval Data Schema

这份文档记录评测基准里的数据结构。口语化理解就是：

用例文件说“我要考什么”
trace 文件说“Agent 实际做了什么”
评测结果说“这次有没有跑偏”
汇总报告说“整体稳定性怎么样”

当前这套评测是代码规则判断，不是再调用一个 LLM 来打分。

1. 用例定义

文件：mvp/eval/cases/diagnosis-cases.json

每一条 case 是一个固定考题，告诉评测器“这个问题应该看哪些点、需要哪些证据、哪些结论可以接受”。

{
  "id": "payment-timeout",
  "title": "Payment API timeout",
  "question": "支付接口最近出现超时，请结合知识库、日志和指标判断可能原因，并给出修复建议。",
  "traceFixture": "payment-timeout-pass.json",
  "expectedRootCauseKeywords": ["支付", "超时", "连接池"],
  "minKeywordMatches": 2,
  "requiredEvidenceTools": ["lookup_knowledge", "query_logs", "query_metrics"],
  "allowedVerdicts": ["PASS", "LOW_CONFID"],
  "forbiddenAnswerKeywords": ["无证据确定"]
}

字段说明：

字段	意思	评测器怎么用
id	这条用例的唯一名字	出现在报告里，方便定位是哪条 case 挂了
title	给人看的标题	出现在结果里，方便快速理解场景
question	要问 Agent 的问题	fixture 模式下不会真的发送给 Agent，但它记录了这条 case 的原始输入
traceFixture	对应的 trace 文件名	评测器会去 fixtures/ 目录加载这个文件
expectedRootCauseKeywords	最终回答里希望看到的关键点	评测器会在 session.answer 里做关键词命中检查
minKeywordMatches	至少要命中几个关键词	命中数低于这个值，就认为根因覆盖不够
requiredEvidenceTools	这条 case 至少应该用到哪些证据工具	评测器会检查 trace 里是否出现这些工具
allowedVerdicts	Verifier 允许给出的结论	比如 PASS 或 LOW_CONFID，不在列表里就失败
forbiddenAnswerKeywords	回答里不应该出现的危险说法	命中这些词，说明回答可能过度自信或不符合降级策略

2. Trace Fixture

目录：mvp/eval/fixtures/*.json

trace fixture 是一次 Agent 运行后的“留痕快照”。评测器不会关心整个 trace 的所有字段，只读取当前能支撑基准判断的字段。

当前会读取这些字段：

Trace 字段	意思	评测器怎么用
session.answer	Agent 最终给用户的回答	用来检查根因关键词和禁用词
session.totalDurationMs	这次运行耗时	进入报告，帮助观察性能是否明显变差
session.selfEvaluation.verifier_evaluation.verdict	Verifier 对最终回答的判断	必须存在，并且要落在 case 的 allowedVerdicts 里
session.selfEvaluation.verifier_evaluation.tool_trace_summary[*].tool_name	Verifier 总结里看到的工具证据	用来补充判断证据工具是否出现
toolInvocations[*].toolName	Agent 实际调用过的工具名	用来检查 requiredEvidenceTools 是否满足
toolInvocations[*].success	工具调用是否成功	当前主要保留在 trace 里，后续可以升级成更严格的成功率检查

简单说，trace 里最重要的是三类信息：

最终回答：它说了什么
工具证据：它查了什么
Verifier：它自己有没有承认这个结论可靠

3. 单条评测结果

Java 类型：DiagnosisEvalResult

这是每条 case 跑完之后的判断结果。

字段	意思
caseId	对应的 case id
title	case 标题
passed	这条 case 是否通过
failedChecks	没通过的具体原因，比如缺工具、关键词不够、verdict 不允许
verdict	从 trace 里读出来的 Verifier verdict
matchedKeywordCount	最终回答命中的关键词数量
requiredKeywordCount	case 定义里一共有多少个关键词
evidenceCoverage	每个必需工具是否出现，例如 { "query_logs": true }
toolCallCount	本次 trace 里工具调用总数
durationMs	本次 trace 的耗时

判断通过的口语化规则：

回答要说到关键点
该查的证据工具要查到
Verifier 的结论要在可接受范围内
回答不能出现危险的过度自信表达
如果是 REJECT，就必须走降级模板

4. 汇总报告

Java 类型：DiagnosisEvalReport

这是整个基准集跑完之后的总结果。

字段	意思
totalCases	总共评测了多少条 case
passedCases	通过了多少条
passRate	通过率，范围是 0.0 到 1.0
verdictDistribution	Verifier verdict 的分布，比如有几个 PASS、几个 LOW_CONFID
averageToolCallCount	平均每条 case 调用了多少次工具
averageDurationMs	平均耗时
results	每条 case 的详细结果列表

5. 怎么看这个基准

这套结构不是为了证明 Agent 永远正确，而是为了在每次改 prompt、工具、检索、Verifier 之后，有一个固定尺子能回答：

以前能过的诊断题，现在还过不过？
它是不是少查了某些证据？
它是不是变得更自信但证据不足？
它是不是开始输出不该说的话？
它是不是明显变慢了？

所以面试里可以这样讲：

我没有只看一次 demo 效果，而是把典型诊断场景固化成 case。
每条 case 都定义预期关键点、必需证据工具和可接受的 verifier 结论。
Agent 每次运行会留下 trace，评测器用代码规则读取 trace，输出结构化报告。
这样我改 Agent 的时候，可以用同一套基准判断有没有行为回退。

6. Baseline Diff

Baseline diff 是拿两份 report 做对比：

baseline report：以前认可的基准结果
current report：这次改动后跑出来的新结果
diff report：告诉你哪里变好了、哪里变差了、哪里只是变了

Java 类型：

• DiagnosisEvalDiffReport
• DiagnosisEvalDiffItem

DiagnosisEvalDiffReport 字段：

字段	意思
baselineTotalCases	baseline 里有多少条 case
currentTotalCases	current 里有多少条 case
baselinePassedCases	baseline 通过了多少条
currentPassedCases	current 通过了多少条
baselinePassRate	baseline 通过率
currentPassRate	current 通过率
regressionCount	退化项数量
improvementCount	改善项数量
changedCount	普通变化项数量
hasRegression	是否存在退化
items	具体 diff 明细

DiagnosisEvalDiffItem 字段：

字段	意思
type	REGRESSION、IMPROVEMENT 或 CHANGED
scope	aggregate 表示整体指标，case 表示单条 case
caseId	如果是单条 case 变化，这里记录 case id
metric	哪个指标变了，比如 passRate 或 evidenceCoverage.query_logs
baselineValue	baseline 里的值
currentValue	current 里的值
delta	数值变化量；非数值变化为空
message	给人看的变化说明

口语化判断规则：

pass rate 下降：退化
case 从通过变失败：退化
证据工具从有变没有：退化
关键词命中变少：退化
工具调用或耗时升高：成本上升，记为退化信号
verdict 分布变化：记录变化，供人工判断是否符合预期

面试里可以这样讲：

我把 baseline report 和当前 report 做结构化 diff。
它不是再问 LLM，而是用代码比较固定字段。
如果某个 case 从 PASS 变 FAIL，或者 query_logs 证据没了，
diff 会直接标成 regression。
这样 Agent 改动可以用固定基准做回归判断。