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

AgentEvalTool V1.1 版本发布说明

版本: 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 更新

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 构建优化

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