AgentEvalTool/docs/release-notes-v1.1-legacy.md

# 历史归档：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