# AgentEvalTool v0.4 版本发布说明

**版本**: v0.4.0-dev
**日期**: 2026-07-27 ~ 2026-07-28
**状态**: 已发布(t480 开发线)
**代号**: 「联」(Integration milestone)
**作者**: AgentEval Team

---

## 一、版本定位

v0.4 的主题是**打通 AI 助手与平台的标准化联动**，并完成生产化前的最后两块拼图：访问控制与运营视图。起因是一次真实事故：用户通过 AI 助手触发的评测（run `95ee8738`）在页面上"消失"。

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

## 二、事故排查：run 95ee8738 "消失"

| 检查项 | 结果 |
|---|---|
| t480 数据库 / API | ✅ run 存在、completed、列表第一条 |
| OpenClaw skill 调用链 | ✅ 走标准 POST /api/runs |
| 前端展示 | ❌ **根因** |

**根因**：keep-alive 标签页架构下页面永不重新挂载，Runs / Reports 只在首次挂载时加载列表，切回标签页不刷新；叠加 Runs 页默认"今天"时间过滤、Reports 页只显示 completed。**纯前端展示层问题，数据无损**。

**修复**：新增 `useOnTabActive` hook — 标签页重新激活时自动刷新，已接入仪表盘 / Runs / Reports 三页。

## 三、主要功能

### 3.1 触发来源标记（triggered_by）
- `EvalRun.triggered_by` 枚举（manual / ai_assistant / cli）全链路：模型 → DB（迁移 `b7d4e6f81c22`，存量回填 manual）→ API → CLI → 引擎
- `POST /api/runs` 接受可选 `triggered_by`，非法值 422
- 前端 Runs 列表、Reports 下拉、仪表盘显示来源 Tag（AI 助手=紫 / CLI=蓝）

### 3.2 AI 助手链路标准化
- 标准 skill `backend/plugins/openclaw/skills/agenteval-run/SKILL.md` 纳入版本管理，deploy 脚本自动同步到 openclaw 工作区
- skill 自动从 `~/.openclaw/agenteval-api-key` 读取 API Key（deploy 脚本从远端 .env 提取生成），启用鉴权后 AI 助手不受影响
- `plugins/openclaw/README.md` 废除 CLI subprocess 模式（CLI 直写本地 SQLite 孤立库，是"记录消失"类事故的高危路径）

### 3.3 评测报告页体验重做
- `GET /api/runs` 返回冗余 `scenario_name` / `target_name`
- 两行表头（模式+场景筛选+重置/刷新 | 报告选择+操作），对比模式不再换行
- 场景筛选器（含计数）、富选项下拉（场景·对象·时间·通过率·来源）、全下拉 allowClear、一键重置
- **对比报告限同场景**：后端 400 + generate 层双保险 + 前端 B 下拉只列同场景；顺带修复空 results 被 `all([])` 误判通过

### 3.4 简单登录（访问控制）
- `.env` 配 `AGENTEVAL_ADMIN_PASSWORD` 即启用；未配置零打扰
- `POST /api/auth/login` 换取无状态 HMAC 会话 token（sessionStorage，关浏览器失效）；401 自动踢回登录页；菜单头部图标退出
- `require_api_key` 升级 `require_auth`：X-API-Key（机器）与 X-Auth-Token（浏览器）双凭据并行

### 3.5 仪表盘全面重构
- `/api/stats/dashboard` 扩展：模型配置数、今日执行、运行中、触发来源分布、场景聚合统计、富化最近记录
- 三行布局：6 指标卡 / 趋势图+场景表现排行 / 最近记录+快捷操作+来源分布
- 页面请求从 3 个全量列表收敛为 2 个聚合接口

### 3.6 UI 与工程优化
- 模型配置页 12 列 → 6 列合并，取消横向滚动（Endpoint/完整 Token 数移入悬浮提示）
- 仪表盘滚动修复（flex:1 在非 flex 父容器失效 → height:100%）
- vite `chunkSizeWarningLimit: 2200`：注释记录 vendor 2.12MB 不可拆分原因（@antv 强拆触发 TDZ 崩溃、rollup 拒绝 async 归并的实测结论），阈值仅在真实回归时报警

## 四、测试与质量

| 指标 | v0.3 | v0.4 |
|---|---|---|
| 测试数量 | 218 | **232** |
| 新增 | — | triggered_by×4、compare 场景限制×2、auth×5、stats×3 |

CI 三件套（v0.3 收尾时补齐）在本版本首次实战：pre-push hook 拦截推送前跑版本一致性 + ruff + pytest。

## 五、部署与配置变更

- **t480 `.env` 新增**（需手动维护，陷阱 #5）：`AGENTEVAL_ADMIN_PASSWORD`、`AGENTEVAL_API_KEY`
- deploy-t480.sh 新增：SKILL.md 同步 + API Key 文件注入 openclaw 工作区
- t480 验证：登录门 401/200 全链路、AI 助手带 key 调用 200、仪表盘聚合数据正确

## 六、已知问题

1. t480 访问密码为临时值，需自行更换
2. 前端仍无自动化测试（仅 tsc）
3. `.env` 远端手动维护未根治（陷阱 #5）
4. volcengine-102 生产线尚未同步 v0.4（含登录配置）

## 七、v0.5 候选方向

- 前端测试基线（vitest）
- 报告趋势分析 / 多 run 聚合看板
- OpenClaw 深度集成二期（插件双向调用）
- 多模态评测用例
- 配置同步自动化（消灭陷阱 #5）