diff --git a/AGENT.md b/AGENT.md index c26e6f2..219ef6b 100644 --- a/AGENT.md +++ b/AGENT.md @@ -6,7 +6,7 @@ **AgentEvalTool** 是智能体质量评估工具集平台，评估 AI 数字员工（大模型 + RAG）和 AI 助手（OpenClaw）的服务质量。核心闭环：定义评估 → 执行评估 → 分析结果 → 改进优化。 -- **当前版本**: v0.3.0-dev（2026-07-17 发布至 t480，里程碑「拓」） +- **当前版本**: v0.4.0-dev（2026-07-28 发布至 t480，里程碑「联」） - **运行环境**: t480 测试服务器（192.168.8.145:8001） - **语言**: Python 3.11（后端） + TypeScript/React 18（前端） @@ -16,10 +16,11 @@ |---|---|---|---|---| | v0.1 | MVP | 2026-07-09 | 核心闭环跑通 | ✅ 已发布 | | v0.2 | 「稳」 | 2026-07-14 | async 引擎 + 安全基线 + 测试 + 部署规范化 | ✅ 已发布(t480) | -| **v0.3** | **「拓」** | **2026-07-17** | **多通道 + 规则扩展 + 模型配置中心** | **✅ 已发布(t480)** | -| v0.4 | — | 规划中 | 前端测试 / 报告增强 / OpenClaw 深度集成二期 / 多模态用例 | 📋 待规划 | +| v0.3 | 「拓」 | 2026-07-17 | 多通道 + 规则扩展 + 模型配置中心 | ✅ 已发布(t480) | +| **v0.4** | **「联」** | **2026-07-28** | **AI 助手标准化(triggered_by) + 登录 + 仪表盘重构** | **✅ 已发布(t480)** | +| v0.5 | — | 规划中 | 前端测试 / 报告聚合看板 / OpenClaw 二期 / 多模态 | 📋 待规划 | -详细内容见 [docs/release-notes-v0.3.md](docs/release-notes-v0.3.md)。 +详细内容见 [docs/release-notes-v0.4.md](docs/release-notes-v0.4.md)。 ## 技术栈 @@ -138,6 +139,12 @@ curl http://192.168.8.145:8001/api/health - `backend/` → `/app/backend:ro`（代码热更新） - `.env` → `/app/.env:ro`（Pydantic Settings 配置, 见 `.env.example`） +### 鉴权（v0.4 起） +- `AGENTEVAL_ADMIN_PASSWORD`：设置后 Web UI 需登录（会话 token, 关浏览器失效）；不设则无登录门 +- `AGENTEVAL_API_KEY`：机器调用凭据（X-API-Key）；deploy 脚本会把它写入 openclaw 工作区 + `data/openclaw/agenteval-api-key`, agenteval-run skill 自动读取 +- 两个凭据任一匹配即放行（`web/deps.py: require_auth`）；`/api/health` 与 `/api/auth/*` 始终开放 + ### 镜像 tag 约定 - `t480-agenteval:` — 不可变, 对应某次具体构建 - `t480-agenteval:latest` — 可变, 总是指向最新部署 diff --git a/README.md b/README.md index 071adf9..06e8eb5 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # AgentEvalTool -> **当前开发版本**: v0.3.0-dev 「拓」 · 已发布至 t480 · 发布说明见 [docs/release-notes-v0.3.md](docs/release-notes-v0.3.md) +> **当前开发版本**: v0.4.0-dev 「联」 · 已发布至 t480 · 发布说明见 [docs/release-notes-v0.4.md](docs/release-notes-v0.4.md) 智能体质量评估工具集平台。 @@ -11,19 +11,23 @@ - 异步评测执行引擎（真并发 / 真取消 / 可配置超时 / WS 实时进度） - 评测通道：tutu-api / HTTP / OpenClaw - 评估规则：关键词、响应时间、LLM 评分、语义相似度、JSON Schema、安全检测 + all/any/weighted 组合 -- 模型配置中心（统一凭据管理 + 加密落库 + OpenAI/Anthropic/DashScope/Gemini 协议） -- 报告生成（JSON / HTML / Markdown / 对比报告）+ Webhook 通知 +- 模型配置中心（统一凭据管理 + Fernet 加密 + OpenAI/Anthropic/DashScope/Gemini 协议） +- 报告生成（JSON / HTML / Markdown / 同场景对比报告）+ Webhook 通知 +- 触发来源标记（手动 / AI 助手 / CLI）+ AI 助手标准化评测链路 +- 简单登录（访问密码 + 会话 token，未配置零打扰） +- 运营仪表盘（指标卡 / 趋势 / 场景表现 / 触发来源分布） - 文件管理（分类树 + 上传下载） -- OpenClaw 免登录 iframe 集成 + HTTP Skill +- OpenClaw 免登录 iframe 集成 + 标准 agenteval-run 技能 - Web 管理后台（FastAPI + React） -## v0.3 亮点 +## v0.4 亮点 -- **模型配置中心**：模型连接统一管理，场景只引用配置 ID，API Key 加密落库、响应零泄露 -- **ModelGateway**：chat / embed / moderate 统一入口，4 种协议适配器 -- **3 通道 + 6 规则**：工厂/注册表模式，插件式扩展 -- **测试基线**：218 个测试，82% 覆盖率 -- **报告增强**：Markdown 导出、run 对比、Webhook 通知 +- **AI 助手标准化**：`triggered_by` 全链路标记 + 标准 SKILL.md 版本管理与自动同步 + API Key 自动注入 +- **简单登录**：`AGENTEVAL_ADMIN_PASSWORD` 一键启用访问控制，机器调用（X-API-Key）不受影响 +- **仪表盘重构**：6 指标卡 + 趋势 + 场景表现排行 + 触发来源分布 +- **报告页重做**：场景筛选、富选项下拉、一键重置、对比报告限同场景 +- **keep-alive 刷新修复**：标签页激活自动刷新，根治"评测记录消失"问题 +- **测试基线**：232 个测试 ## 快速开始 diff --git a/docs/plan-v0.4.md b/docs/plan-v0.4.md new file mode 100644 index 0000000..d3aca5f --- /dev/null +++ b/docs/plan-v0.4.md @@ -0,0 +1,70 @@ +# 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 不可选、同场景可正常对比 diff --git a/docs/release-notes-v0.4.md b/docs/release-notes-v0.4.md new file mode 100644 index 0000000..f5d957a --- /dev/null +++ b/docs/release-notes-v0.4.md @@ -0,0 +1,95 @@ +# 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）