# AgentEvalTool v0.4.0 「联」开发计划

**开发版本**: v0.4.0-dev
**制定日期**: 2026-07-27
**代码基线**: `92f98c3`（v0.3.0-dev 已发布 t480）
**核心目标**: AI 助手评测链路标准化 + 报告查询体验优化
**状态**: ✅ 已发布(t480, 2026-07-28)，发布说明见 [release-notes-v0.4.md](release-notes-v0.4.md)

---

## 一、背景：run 95ee8738 "消失"事故排查

用户通过 AI 助手触发评测（run `95ee8738-11e7-4959-a3cf-45e3536b28eb`），但在"评测执行"和"评测报告"页面均查不到。

**排查结论（2026-07-27）**：

| 检查项 | 结果 |
|---|---|
| t480 数据库 `eval_runs` | ✅ run 存在，status=completed |
| `GET /api/runs` | ✅ 正常返回，列表第一条 |
| t480 SKILL.md（openclaw 工作区） | ✅ 走标准 `POST /api/runs` |
| 前端展示 | ❌ **根因所在** |

**根因**：前端采用 keep-alive 标签页架构（页面挂载后永不卸载），Runs / Reports 页只在**首次挂载**时加载一次列表，切回标签页不刷新。AI 助手评测发生在页面已挂载之后 → 两个页面全是旧数据。叠加因素：Runs 页默认时间过滤为"今天"、Reports 页只显示 completed 状态。

**数据与 API 完全正常，纯前端展示层问题。**

## 二、需求与实现

### 需求 1：触发来源标记 + AI 助手标准化链路

- `EvalRun.triggered_by` 枚举字段（`manual` / `ai_assistant` / `cli`，默认 manual），全链路透传：models → EvalRunDB → repository → engine → CLI → API
- 迁移 `b7d4e6f81c22`：`eval_runs` 加列，存量回填 `manual`
- `POST /api/runs` 接受可选 `triggered_by`（非法值 422）
- 标准 skill 纳入版本管理：`backend/plugins/openclaw/skills/agenteval-run/SKILL.md`（要求带 `triggered_by: "ai_assistant"`），deploy 脚本自动同步到 openclaw 工作区
- `plugins/openclaw/README.md` 移除 CLI subprocess 模式（CLI 写孤立库，禁止 OpenClaw 使用）
- 前端：RunList 与 Reports 下拉显示来源 Tag（AI 助手=紫色 / CLI=蓝色 / 手动不显示）

### 需求 1.5（排查衍生，本次事故的直接修复）：标签页激活刷新

- 新 hook `useOnTabActive(path, cb)`：监听 tabStore.activeKey，标签页重新激活时触发刷新（跳过首次挂载）
- Runs、Reports 两页接入

### 需求 2：报告页查询体验优化

- 后端 `GET /api/runs` 返回冗余 `scenario_name` / `target_name`
- Reports 页选择区重做：
  - 场景筛选器（含各场景 run 数量统计）
  - run 下拉富选项：场景名 · 对象名 · 时间 · 通过率 · 来源 Tag，支持关键字搜索
  - 修复旧版 `.reverse()` 导致最旧记录排最前的问题

### 需求 3：对比报告限制同场景

- 后端 `GET /api/reports/compare`：场景不同返回 `400 对比报告要求两个运行使用相同场景`
- `generate_compare_report` 入口双保险（ValueError）
- 顺带修复：case 无规则结果时 `all([]) == True` 被误判为通过 → 改为 None
- 前端：报告 B 下拉只列同场景 run；A 变更后 B 场景不符自动清空

## 三、测试

- 新增 6 个测试：triggered_by 默认值/透传持久化/非法值 422、list 含名称字段、compare 跨场景 400/ValueError
- 全量 224 通过（v0.3 基线 218 → 224）

## 四、发布验证清单（t480）

1. `scripts/deploy-t480.sh` 部署（自动同步 SKILL.md 到 openclaw 工作区）
2. `/api/health` 返回 version=0.4.0-dev
3. 手动触发一次评测 → Runs 页显示无来源 Tag（manual）
4. 让 AI 助手触发一次评测 → 切回 Runs/Reports 页**不刷新浏览器**即可看到新记录，带"AI 助手"标记
5. 对比报告：跨场景 run 不可选、同场景可正常对比