187 lines
7.4 KiB
Markdown
187 lines
7.4 KiB
Markdown
# 历史归档：AgentEvalTool V1.1 版本说明
|
||
|
||
> **编号说明**：本文创建于 2026-07-16，当时代码包版本实际为 `0.2.0-dev`。这里的“V1.1”属于早期原型文档编号，不是当前项目 SemVer，也不晚于 2026-08-11 发布的 `v1.0.0`。当前发布说明见 [release-notes-v1.0.md](release-notes-v1.0.md)。
|
||
|
||
**版本**: v1.1
|
||
**日期**: 2026-07-10
|
||
**状态**: 历史编号归档
|
||
**作者**: AgentEval Team
|
||
|
||
---
|
||
|
||
## 一、版本概述
|
||
|
||
V1.1 在 V1.0 基础闭环（CLI CRUD + 基础 Web 查看）之上，完成了 MVP 功能补全和 Web 管理后台重构，并修复了生产环境中的关键稳定性问题。
|
||
|
||
## 二、主要变更
|
||
|
||
### 2.1 前端完全重构（Ant Design 5.x）
|
||
|
||
| 项目 | V1.0 | V1.1 |
|
||
|---|---|---|
|
||
| UI 库 | 无（手写 CSS） | Ant Design 5.x |
|
||
| 布局 | 手写 Flexbox 侧边栏 | ProLayout 专业布局 |
|
||
| 状态管理 | useState per page | 按需引入 |
|
||
| 代码编辑 | textarea | Monaco Editor |
|
||
| 图表 | 无 | @ant-design/charts |
|
||
| 构建优化 | 单 chunk | manualChunks 代码分割 |
|
||
|
||
**页面重构清单：**
|
||
|
||
- **仪表盘**：统计卡片（对象数/场景数/执行数/通过率）+ 最近评测记录表格 + 通过率趋势折线图
|
||
- **评测对象**：Table + 编辑抽屉 + 通道配置表单化（不再手写 JSON）+ 连通性测试 + 状态 Tag
|
||
- **评测场景**：Table + Monaco Editor 在线编辑 JSON 用例 + 预览弹窗 + 标签筛选
|
||
- **评测执行**：启动评测 + 执行列表 + 状态 Tag（running 有动画）+ WebSocket 实时进度时间线 + 运行详情抽屉
|
||
- **评测报告**：概览统计卡片 + 对话气泡样式展示 + 规则结果表格 + HTML 导出
|
||
|
||
### 2.2 后端功能增强
|
||
|
||
- **WebSocket 实时进度推送**：`/ws/runs/{run_id}` 端点，广播 `case_start`、`turn_end`、`rule_result` 等事件
|
||
- **Stats 聚合 API**：
|
||
- `GET /api/stats/dashboard`：仪表盘数据（对象数、场景数、执行数、平均通过率、最近 10 条记录）
|
||
- `GET /api/stats/trend`：通过率趋势数据（按天聚合，支持 `days` 参数）
|
||
- **Run Logs 增强**：返回 `sent_text` 和 `reply_text` 字段，供前端对话展示
|
||
- **EvalAgent 模块实现**：
|
||
- `EvalAgent` 抽象基类（`agents/base.py`）
|
||
- `SimpleAgent` 实现（`agents/simple.py`），委托给 EvalEngine
|
||
|
||
### 2.3 关键 Bug 修复
|
||
|
||
#### 2.3.1 SQLite 连接池耗尽（严重）
|
||
|
||
**问题**：默认 `QueuePool`（size 5, overflow 10）在 FastAPI 多线程环境下快速耗尽，导致页面超时。
|
||
|
||
**根因**：
|
||
1. 每个 `Repository()` 构造时调用 `get_session()` 创建新 Session，但从不关闭
|
||
2. 后台评测任务中的 Engine 也创建独立 Session
|
||
3. SQLite 不支持真正的连接池
|
||
|
||
**修复**：
|
||
- 引擎切换为 `StaticPool`（`check_same_thread=False` 模式下保持单连接共享）
|
||
- 所有 Router 使用 FastAPI `Depends(get_db)` 依赖注入管理 Session 生命周期
|
||
- 后台评测任务 `_run_evaluation` 使用 `try/finally` 确保 Session 释放
|
||
- `generate_report` 等报告函数支持传入外部 Session
|
||
|
||
#### 2.3.2 评测执行产生重复记录
|
||
|
||
**问题**：每次启动评测产生 2 条 run 记录（1 条 pending + 1 条 completed）。
|
||
|
||
**根因**：
|
||
1. API 端点 `start_run` 创建 run #1（pending）
|
||
2. `EvalEngine.run()` 内部又创建 run #2（running → completed）
|
||
|
||
**修复**：
|
||
- `EvalEngine.run()` 新增 `existing_run` 参数，传入时复用已有记录
|
||
- `_run_evaluation` 获取 API 创建的 run 并传给引擎
|
||
|
||
#### 2.3.3 代码部署未生效
|
||
|
||
**问题**：所有后端修复部署后未生效，页面持续超时。
|
||
|
||
**根因**：Docker 镜像通过 `COPY backend ./backend` 烘焙代码，rsync 只更新宿主机文件，`docker restart` 仍运行旧镜像。
|
||
|
||
**修复**：docker-compose.yml 新增后端代码 volume 挂载 `../../backend:/app/backend:ro`，后续代码变更通过 rsync + restart 即可生效，无需重建镜像。
|
||
|
||
## 三、部署架构变更
|
||
|
||
### 3.1 docker-compose.yml 更新
|
||
|
||
```yaml
|
||
volumes:
|
||
- ../../data:/app/data
|
||
- ../../config/config.json:/app/config/config.json:ro
|
||
- ../../frontend/web/dist:/app/frontend/web/dist:ro
|
||
- ../../backend:/app/backend:ro # V1.1 新增：代码热更新
|
||
```
|
||
|
||
### 3.2 Vite 构建优化
|
||
|
||
```typescript
|
||
build: {
|
||
rollupOptions: {
|
||
output: {
|
||
manualChunks: {
|
||
'vendor-antd': ['antd', '@ant-design/icons', '@ant-design/pro-components'],
|
||
'vendor-charts': ['@ant-design/charts'],
|
||
'vendor-monaco': ['@monaco-editor/react'],
|
||
},
|
||
},
|
||
},
|
||
}
|
||
```
|
||
|
||
## 四、新增文件
|
||
|
||
| 文件路径 | 说明 |
|
||
|---|---|
|
||
| `backend/agenteval/web/websocket.py` | WebSocket 连接管理器 |
|
||
| `backend/agenteval/web/routers/stats.py` | 统计聚合 API Router |
|
||
| `backend/agenteval/agents/base.py` | EvalAgent 抽象基类 |
|
||
| `backend/agenteval/agents/simple.py` | SimpleAgent 实现 |
|
||
| `data/scenarios/dept_navigation.yaml` | 科室导航评测场景（3 用例） |
|
||
|
||
## 五、修改文件
|
||
|
||
| 文件路径 | 变更说明 |
|
||
|---|---|
|
||
| `backend/agenteval/storage/db.py` | StaticPool + get_session_context |
|
||
| `backend/agenteval/web/app.py` | 新增 WebSocket 端点 + stats router |
|
||
| `backend/agenteval/web/routers/targets.py` | Depends(get_db) session 管理 |
|
||
| `backend/agenteval/web/routers/scenarios.py` | Depends(get_db) session 管理 |
|
||
| `backend/agenteval/web/routers/runs.py` | Depends(get_db) + existing_run 传递 |
|
||
| `backend/agenteval/web/routers/reports.py` | Depends(get_db) + session 传递 |
|
||
| `backend/agenteval/evaluation/engine.py` | existing_run 参数支持 |
|
||
| `backend/agenteval/evaluation/report.py` | session 参数传递 |
|
||
| `frontend/web/src/*` | 全部重构为 Ant Design 5.x |
|
||
| `deploy/t480/docker-compose.yml` | 新增 backend volume 挂载 |
|
||
|
||
## 六、技术栈更新
|
||
|
||
### 前端新增依赖
|
||
|
||
| 包名 | 版本 | 用途 |
|
||
|---|---|---|
|
||
| antd | 5.x | UI 组件库 |
|
||
| @ant-design/icons | - | 图标库 |
|
||
| @ant-design/pro-components | - | ProLayout、ProTable 等高级组件 |
|
||
| @ant-design/charts | - | 图表（Line、Bar 等） |
|
||
| @monaco-editor/react | - | YAML/JSON 在线编辑器 |
|
||
| zustand | - | 轻量状态管理（预留） |
|
||
| dayjs | - | 日期处理 |
|
||
|
||
### 后端新增依赖
|
||
|
||
无新增 Python 依赖。WebSocket 功能使用 FastAPI 内置的 `fastapi.WebSocket`。
|
||
|
||
## 七、已知问题与后续规划
|
||
|
||
### 7.1 已知问题
|
||
|
||
- Ant Design + Monaco Editor 打包产物较大（~2.8MB），后续可通过懒加载进一步优化
|
||
- WebSocket 断线后无自动重连机制（当前手动刷新）
|
||
- 评测执行期间 SQLite 写入可能阻塞读操作（StaticPool 单连接）
|
||
|
||
### 7.2 V1.2 规划方向
|
||
|
||
- 场景模板（预置单轮问答、多轮对话、压力测试模板）
|
||
- 场景在线校验 API（`POST /api/scenarios/validate`）
|
||
- 运行取消功能（`POST /api/runs/{id}/cancel`）
|
||
- 报告对比功能（选择两次运行进行 side-by-side 对比）
|
||
- WebSocket 自动重连 + 前端错误重试
|
||
- 前端路由懒加载优化包体积
|
||
|
||
## 八、验证标准
|
||
|
||
1. Web 后台使用 Ant Design 组件，界面专业、布局合理
|
||
2. 首页仪表盘展示统计数据和趋势图表
|
||
3. 评测对象和场景支持完整 CRUD（包含编辑）
|
||
4. 评测执行时可通过 WebSocket 实时看到进度和日志
|
||
5. 报告页面以对话气泡展示对话内容，规则结果清晰可读
|
||
6. 场景支持 JSON 在线编辑（Monaco Editor）
|
||
7. 所有操作有 loading 状态和错误提示
|
||
8. 部署到 t480 后可稳定使用（无连接池耗尽）
|
||
|
||
---
|
||
|
||
**最后更新**: 2026-07-10
|