# Evidence-only Evaluation 设计

本文描述当前 `evidence_only` evaluation mode 的评分规则。它是完整诊断 evaluation 的证据阶段拆分版，用于单独评估 multi-agent 是否能在停止诊断前收集到足够证据。

## 目标

`evidence_only` 不评价最终根因表述，也不要求 diagnosis-analyst 给出结论。它只回答三个问题：

- 编排是否按 evidence-only 边界停止，没有继续进入诊断阶段
- collector / evidence-agent 是否产出可供后续诊断使用的标准证据包
- 每个 case 定义的关键客观证据是否已经被收集到

这让我们可以分别优化 evidence 阶段和 diagnosis 阶段，避免一次完整诊断失败时无法判断问题出在证据不足还是推理错误。

## 与完整 evaluation 的关系

完整诊断 judge 的主链路是：

```text
workflow -> evidence_collection -> critical_evidence -> evidence_routing -> diagnosis
```

`evidence_only` 复用其中的两个核心证据 bucket：

- `judge.evidence_collection`
- `judge.critical_evidence`

因此 case 的关键证据规则不需要为 evidence-only 另写一份。后续按问题分类扩展 case 时，只要继续把“这个 case 必须捞到什么证据”写进 `judge.critical_evidence`，evidence-only 和完整诊断都会使用同一套标准。

## 执行边界

在 `case.yaml` 中设置：

```yaml
evaluation:
  mode: evidence_only
```

runner 会在原始用户 prompt 后附加 evidence-only 执行提示，要求 agent：

- 运行 collector / evidence-agent
- 写入 `evidences/agent-runs/evidence-agent.json`
- 写入 evidence summary 和 `workspace_evidence_report.json`
- 停止在 evidence 阶段
- 不调用 diagnosis-analyst
- 不输出最终根因诊断

这部分是 evaluation 专用执行约束，不改变普通 workspace 的主诊断流程。

## 评分结构

总分 100，分为三部分。

| Bucket | 分值 | 来源 | 目的 |
|---|---:|---|---|
| `mode_contract` | 10 | evidence-only 固定规则 | 确认阶段边界和下游 handoff artifact |
| `evidence_collection` | 30 | `judge.evidence_collection` | 确认证据包和基础 channel 覆盖 |
| `critical_evidence` | 60 | `judge.critical_evidence` | 确认 case 关键证据内容是否齐全 |

### mode_contract: 10 分

固定检查：

- `workspace_evidence_report_valid`：`workspace_evidence_report.json` 存在且是合法 JSON
- `evidence_agent_artifact_present`：`evidences/agent-runs/evidence-agent.json` 存在且是合法 JSON
- `summary_artifact_present`：evidence summary 存在
- `diagnosis_agent_not_invoked`：不能写入 `diagnosis-analyst.json`

这些检查全部是 required。失败代表 run 没有遵守 evidence-only 执行边界，通常判为 `invalid`。

### evidence_collection: 30 分

复用 case 的 `judge.evidence_collection`。典型检查包括：

- core evidence bundle 是否存在，例如 `metrics.json`、`queries.json`、`collection_errors.json`、`logs.json`
- 是否观察到日志、metric/query、event 等必要 channel
- event 查询已尝试时是否落盘对应 artifact

该 bucket 关注“证据包形态和覆盖面”，不直接判断这些证据能否支撑最终结论。

### critical_evidence: 60 分

复用 case 的 `judge.critical_evidence`。这是 evidence-only 的主要质量分。

这里应该写每个 case 必须收集到的客观证据，例如：

- GC 问题：GC pause / duration / count/sum/bucket 等指标
- restart 问题：restart metric、component health、panic 日志
- expensive query 问题：slow query / TopSQL / decoded plan / scan 行数
- capacity 问题：incident 与 baseline 的节点数、规格或负载对比

如果 collector 产物齐全，但关键证据没捞到，run 应该是 `fail`，不是 `invalid`。这表示它是一次可比较的运行，只是 evidence 质量不够。

## Verdict 规则

`evidence_only` 的 verdict precedence：

1. artifact resolution 失败 -> `invalid`
2. `diagnosis_agent_not_invoked` 失败 -> `invalid`, `evidence_only_stage_boundary_failed`
3. `mode_contract` 其他 required 失败 -> `invalid`, `evidence_only_artifacts_missing`
4. `evidence_collection` fail -> `invalid`, `evidence_collection_incomplete`
5. `evidence_collection` partial -> `fail`, `evidence_collection_partial`
6. `critical_evidence` fail -> `fail`, `critical_evidence_missing`
7. `critical_evidence` partial -> `fail`, `critical_evidence_partial`
8. 全部通过 -> `pass`

`invalid` 表示本次运行不完整或不可比，不适合用于质量趋势比较；`fail` 表示运行可比，但证据质量不达标。

## 分数 band

最终分数沿用完整 evaluation 的 hard-gate band：

- `invalid` 固定为 0
- hard gate 全部通过时，最终分数至少为 70
- hard gate 未通过但 run 可比时，最终分数最高为 69

因此 evidence-only 的分数含义是：

- `100`：证据阶段完整，关键证据齐全，且没有越界进入诊断
- `70-99`：当前规则下通过，但可以通过 optional checks 继续区分质量
- `1-69`：run 可比，但证据不足
- `0`：run 不可比或执行边界失败

## Case 编写建议

新增或细化 case 时，优先把规则放到已有 bucket：

- artifact / channel / collector shape 放 `judge.evidence_collection`
- 能否支撑正确诊断的客观证据放 `judge.critical_evidence`
- 诊断结论、误诊防护、建议质量仍放 `judge.diagnosis`

不要让 evidence-agent 自己判断“证据是否足够”。它只负责收集、整理和引用证据；证据是否足够支撑 diagnosis，由 evaluation 的 deterministic judge 和后续 diagnosis 阶段判断。

## 输出位置

一次 evidence-only run 的 judge packet 会包含：

- `packet.mode_contract`
- `packet.evidence_collection`
- `packet.critical_evidence`
- `packet.scoring`

这些字段可以直接用于对比优化前后的 evidence 阶段质量，也可以在分类优化时只观察某一类 case 的 `critical_evidence` 得分变化。