# AgentEvalTool v0.5 版本发布说明

**版本**: v0.5.0-dev
**日期**: 2026-07-28 ~ 2026-07-29
**状态**: 已发布(t480 开发线)
**代号**: 「准」(Judgement semantics milestone)
**作者**: AgentEval Team

---

## 一、版本定位

v0.5 的主题是**把评测的"判定语义"从含糊变成准确**。起因是一次领域模型拷问（`/grill-with-docs`）：期望与规则的关系是什么？没配规则的用例算通过还是没测？动态生成的用例凭什么可以对比？这些问题在代码里都有隐含答案，但和产品意图不一致。本版本先把领域语言写成文档（CONTEXT.md 词汇表 + ADR），再按文档修正实现。

```
v0.1 (2026-07-09)  MVP 闭环
v0.2 (2026-07-14)  「稳」async 引擎 + 安全基线 + 部署规范化
v0.3 (2026-07-17)  「拓」多通道 + 规则扩展 + 模型配置中心
v0.4 (2026-07-28)  「联」AI 助手标准化 + 登录 + 仪表盘重构
v0.5 (2026-07-29)  ← 你在这里:「准」判定语义 + 场景版本化
```

## 二、领域模型文档化（新增基线）

- **`CONTEXT.md`**（仓库根）：14 个领域术语的唯一词汇表（评测对象/期望/评估规则/连通用例/场景版本/通过率/…）
- **`docs/adr/0001`**: 场景版本化保证可比性——仅"考纲"字段（cases / model_bindings / llm_config）变更时升版
- **`docs/adr/0002`**: 通过率**有意**包含执行失败（故障也是质量问题），不要当 bug"修掉"

## 三、主要功能（5 张 tracer-bullet 票）

### 3.1 期望与规则叠加生效（ticket 01）
- 旧行为：case 配了显式规则时 `expectation` 被忽略（互斥）；新行为：期望**始终**派生隐式 llm_score 规则，与显式规则**叠加**
- 隐式规则是 rule_logic 之外的硬约束：`case_passed = 显式规则组合结果 AND 所有隐式规则通过`
- 隐式规则的 reason 带 `[期望]` 前缀，报告中可区分

### 3.2 连通用例标注 + 判定通过率（ticket 02）
- 无规则且无期望的用例 = **连通用例**（合法的连通性验证，不是配置缺失）
- 报告层派生标注：`connectivity` 标记 + 🔗 徽章；全部轮次有回复即算通过
- 新增 `judged_pass_rate`：剔除连通用例后的判定通过率（分母为零时为 null）；原 `pass_rate` 口径不变（ADR-0002）

### 3.3 场景版本化（ticket 03）
- `Scenario.version` 系统维护，外部传入值忽略；新建=1，更新时对比考纲字段（JSON 序列化对比），变更才 +1
- 改名字/描述不升版；重存相同考纲不升版（有回归测试锁定）

### 3.4 运行快照场景版本（ticket 04）
- `EvalRun.scenario_version` 在运行创建时快照，场景后续升版不影响历史运行
- 迁移回填：存量 run 回填其场景当前版本（场景已删则为 1）

### 3.5 对比报告限同版本（ticket 05）
- 对比要求**同场景且同考纲版本**：API 400（提示双方版本）+ report 层 ValueError 双保险
- 前端：报告 B 下拉只列同场景同版本；场景筛选/富选项下拉/各页面全面展示 `v{n}` 版本标签

## 四、修复与体验

- **启动僵尸运行清理**：评测是进程内 asyncio 任务，重启即中断。现在启动时自动把遗留 running/pending 标记为 failed（`summary.error = interrupted`），尽力而为不阻断启动。起因：一次 `--skip-build` 部署重启打断了运行中的评测（run `cc15f6a9`）。教训：**重启部署前先查 running_count**
- **导出报告 401 修复**：登录鉴权启用后 `window.open` 直连导出接口不带 `X-Auth-Token`。三处导出（HTML/MD/JSON）改为经 axios 拉取 blob 后触发下载
- **触发来源标签全量展示**：手动/AI 助手/CLI 标签在列表、下拉、报告头、对比卡全部常显
- **仪表盘指标卡重设计**：固定高度三行布局（标题/数值/副行），修复"累计执行"换行导致卡片高度不一

## 五、测试与质量

| 指标 | v0.4 | v0.5 |
|---|---|---|
| 测试数量 | 232 | **259** |
| 新增 | — | 期望叠加矩阵×6、连通/判定通过率×7、场景版本 API×8、快照+迁移×3、对比校验×2、僵尸清理×2 等 |

流程上首次完整走通 `/grill-with-docs → /to-spec → /to-tickets → /implement(×5, TDD + 双轴 code-review)` 链路，spec 与票据在 `.scratch/v0.5/`。

## 六、部署与配置变更

- 两个新迁移：`c8e2f5a7b901`（scenarios.version）、`d5b8c2e4f617`（eval_runs.scenario_version + 回填），容器启动自动 `alembic upgrade head`
- 无新增环境变量
- t480 验证：迁移自动应用、存量 3 场景 v1 / 35 运行回填 v1、报告含 scenario_version / connectivity_cases / judged_pass_rate、启动清理日志生效

## 七、已知问题

1. t480 访问密码仍为临时值，需自行更换
2. volcengine-102 生产线停留在 v0.4 之前，差距扩大
3. 前端仍无自动化测试（仅 tsc）
4. 本地开发 `data/` DB 需手动 `alembic upgrade head`（启动清理靠 try/except 兜底跳过）

## 八、v0.6 候选方向

- volcengine-102 同步（优先）
- 前端测试基线（vitest）
- 报告趋势分析 / 多 run 聚合看板
- 多模态评测用例
- 配置同步自动化（消灭陷阱 #5）
