docs(release): add v1.1.0 release notes

Document the intelligent evaluation cron pool architecture: - Cron pool management (5-20 workers) - Task queue with priority scheduling - Worker skill with autonomous decision logic - Config snapshot management and comparison - Decision process tracking and visualization - Monitoring and alerting system - Fault tolerance and recovery mechanisms - Frontend UI for config history, decision process, and cron pool monitoring Rename legacy v1.1 release notes to v1.1-legacy.md.
2026-08-12 11:11:34 +08:00 · 2026-08-12 11:11:34 +08:00 · 6f2be0e68f
commit 6f2be0e68f
parent 15699e0dd0
2 changed files with 421 additions and 0 deletions
--- a/docs/release-notes-v1.1-legacy.md
+++ b/docs/release-notes-v1.1-legacy.md
@ -0,0 +1,186 @@
+# 历史归档：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
--- a/docs/release-notes-v1.1.0.md
+++ b/docs/release-notes-v1.1.0.md
@ -0,0 +1,235 @@
+# AgentEvalTool v1.1.0 发布说明
+
+**版本**：v1.1.0
+**发布日期**：2026-08-12
+**状态**：已发布
+**作者**：AgentEval Team
+
+---
+
+## 一、版本概述
+
+v1.1.0 在 v1.0.0 智能评估基础上，引入 **Cron 池架构**，解决了"一个智能评估对应一个 OpenClaw session"导致的上下文割裂和 cron 爆炸问题。新版本通过池化管理、任务队列、自主决策和完整的可观测性，实现了真正可扩展的智能评估体系。
+
+## 二、核心能力
+
+### 2.1 Cron 池管理
+
+- **池化 Worker**：5-20 个 OpenClaw cron 任务组成工作池，自动扩缩容
+- **任务队列**：平台维护待处理评估，按优先级排序（时段到期 > 欠账多 > 等待时间长）
+- **Worker Skill**：OpenClaw 工作单元，每分钟唤醒，自主决策执行/等待/分析
+- **状态持久化**：Cron state 和任务队列都持久化在 SQLite，重启可恢复
+
+### 2.2 自主决策逻辑
+
+- **时段判断**：根据当前时间偏移判断处于哪个时段（早高峰/午间/晚间）
+- **欠账检测**：计算当前时段应有多少会话，实际有多少，决定是否需要执行
+- **严重度分析**：检测已完成会话中的高严重度问题，决定是否需要深入挖掘
+- **决策类型**：execute_session（执行会话）/ wait（等待）/ start_analysis（开始分析）
+
+### 2.3 配置快照管理
+
+- **自动保存**：创建评估、提交计划、修改配置时自动保存快照
+- **快照对比**：选择两个快照，显示差异字段（goal、seeds、plan 等）
+- **快照导出**：一键导出为 JSON 文件
+- **前端 UI**：配置历史页面，支持列表、详情、对比、导出
+
+### 2.4 决策过程追踪
+
+- **决策时间线**：Timeline 视图展示每次决策，颜色区分决策类型
+- **决策日志列表**：表格形式展示，支持展开查看完整上下文
+- **类型筛选**：按决策类型筛选（execute_session / wait / start_analysis）
+- **日志导出**：一键导出为 JSON 文件
+- **前端 UI**：决策过程页面，支持时间线、列表、筛选、导出
+
+### 2.5 监控和告警
+
+- **关键指标**：
+  - 池使用率（busy/total）
+  - 任务积压（pending 任务数）
+  - 卡死率（stuck/total）
+  - 平均处理时间（秒）
+  - 评估完成率
+- **告警规则**：
+  - 池使用率 > 90% 持续 10 分钟（warning）
+  - 任务积压 > 50（warning）
+  - 卡死率 > 10%（critical）
+- **告警通知**：日志 + webhook
+- **告警历史**：支持查看和解决告警
+- **前端 UI**：Cron 池监控页面，实时刷新（5 秒轮询）
+
+### 2.6 故障恢复
+
+- **卡死检测**：10 分钟未活跃的 cron 标记为 stuck
+- **任务重新入队**：cron 卡死后，任务重新分配给其他 cron
+- **状态对账**：检查平台 DB 与 OpenClaw state 一致性
+- **平台重启恢复**：扫描 assigned 任务，检查 cron 是否还活跃
+- **OpenClaw 重启恢复**：同步 cron state 到平台 DB
+
+## 三、架构变更
+
+### 3.1 数据模型
+
+新增 5 个表：
+
+| 表名 | 说明 |
+|------|------|
+| `intelligent_eval_task_queue` | 任务队列（pending/assigned/completed/failed） |
+| `openclaw_cron_pool` | Cron 池状态（idle/busy/stuck） |
+| `intelligent_eval_config_snapshots` | 配置快照（created/plan_submitted/config_updated） |
+| `intelligent_eval_decision_logs` | 决策日志（execute_session/wait/start_analysis） |
+| `cron_pool_alert_history` | 告警历史（warning/critical） |
+
+### 3.2 API 端点
+
+新增 15+ 个 API 端点：
+
+**任务队列**：
+- `GET /api/intelligent-evals/tasks/next` — 获取下一个任务
+- `POST /api/intelligent-evals/tasks/{id}/assign` — 分配任务
+- `POST /api/intelligent-evals/tasks/{id}/complete` — 完成任务
+
+**决策日志**：
+- `POST /api/intelligent-evals/{id}/decision-logs` — 创建决策日志
+- `GET /api/intelligent-evals/{id}/decision-logs` — 获取决策日志列表
+
+**配置快照**：
+- `GET /api/intelligent-evals/{id}/config-snapshots` — 列出快照
+- `GET /api/intelligent-evals/{id}/config-snapshots/{snapshot_id}` — 获取单个快照
+- `POST /api/intelligent-evals/{id}/config-snapshots/compare` — 对比快照
+
+**Cron 池管理**：
+- `GET /api/openclaw/cron-pool` — 查询池状态
+- `POST /api/openclaw/cron-pool/scale` — 手动扩缩容
+- `POST /api/openclaw/cron-pool/sync` — 同步状态
+- `POST /api/openclaw/cron-pool/auto-scale` — 自动扩缩容
+- `POST /api/openclaw/crons/{id}/heartbeat` — 上报心跳
+
+**监控告警**：
+- `GET /api/openclaw/cron-pool/metrics` — 查询指标
+- `POST /api/openclaw/cron-pool/check-alerts` — 检查告警规则
+- `GET /api/openclaw/cron-pool/alerts` — 查询告警历史
+- `POST /api/openclaw/cron-pool/alerts/{id}/resolve` — 解决告警
+
+### 3.3 OpenClaw Skill
+
+新增 `agenteval-intelligent-worker` skill：
+
+- **工作流程**：取任务 → 决策 → 执行 → 上报
+- **状态管理**：idle/busy 状态切换，cron state 持久化
+- **决策逻辑**：分析时段、欠账、严重度，决定执行/等待/分析
+- **错误处理**：API 失败重试，连续失败放弃任务
+
+### 3.4 前端页面
+
+新增 3 个页面：
+
+1. **配置历史页面**（EvalDetail 内）
+   - 快照列表（时间、类型、创建者）
+   - 快照详情（四件套、粗计划）
+   - 快照对比（diff 视图）
+   - 快照导出（JSON）
+
+2. **决策过程页面**（EvalDetail 内）
+   - 决策时间线（Timeline 视图）
+   - 决策日志列表（表格视图）
+   - 类型筛选（execute_session / wait / start_analysis）
+   - 日志导出（JSON）
+
+3. **Cron 池监控页面**（独立页面 `/cron-pool`）
+   - 池状态卡片（总数/空闲/忙碌/卡死）
+   - 监控指标卡片（使用率、积压、卡死率等）
+   - 告警历史表格（支持解决告警）
+   - 实时刷新（5 秒轮询）
+   - 手动扩缩容
+
+## 四、质量基线
+
+- **后端测试**：853 项测试通过
+  - 单元测试：任务入队、池管理、决策逻辑、配置快照、告警规则、故障恢复
+  - 集成测试：API 端点、端到端流程、迁移往返
+- **前端测试**：TypeScript 类型检查通过
+- **数据库迁移**：Alembic upgrade/downgrade 往返通过，head 为 `c8f3e9a2b4d1`
+
+## 五、兼容性与配置
+
+- **版本号**：从 1.0.0 升级到 1.1.0（MINOR 版本，向后兼容）
+- **数据库**：新增 5 个表，通过 Alembic 迁移自动创建
+- **API**：所有现有 API 保持兼容，新增 API 为额外端点
+- **配置**：无需修改现有配置，OpenClaw 自动同步新 skill
+- **部署**：升级时容器入口自动执行 Alembic；正式发布前仍必须备份数据 volume
+
+## 六、迁移指南
+
+### 6.1 从 v1.0.0 升级到 v1.1.0
+
+1. **备份数据**：
+   ```bash
+   cp data/agenteval.db data/agenteval.db.backup
+   ```
+
+2. **拉取新代码**：
+   ```bash
+   git pull origin main
+   ```
+
+3. **运行迁移**：
+   ```bash
+   alembic upgrade head
+   ```
+
+4. **同步版本号**：
+   ```bash
+   python3 scripts/sync_version.py
+   ```
+
+5. **重启服务**：
+   ```bash
+   docker-compose restart
+   ```
+
+6. **验证**：
+   - 访问 `/cron-pool` 页面，确认 Cron 池监控页面正常
+   - 创建智能评估，确认配置历史和决策过程页面正常
+   - 检查日志，确认 Worker skill 正常唤醒
+
+### 6.2 配置检查
+
+- **OpenClaw skill**：部署脚本会自动同步 `agenteval-intelligent-worker` skill
+- **环境变量**：无需新增环境变量
+- **API Key**：现有 API Key 继续有效
+
+## 七、已知问题与后续规划
+
+### 7.1 已知问题
+
+- Cron 池最大 20 个 worker，超过 100 个并发评估需要排队
+- 决策日志未自动清理，长期运行后需要定期清理历史数据
+- 告警 webhook 失败后不会重试
+
+### 7.2 v1.2.0 规划方向
+
+- **多对象对比**：支持多个评测对象的横向对比
+- **事件驱动唤醒**：平台状态变更时主动触发 OpenClaw，减少 cron 轮询压力
+- **决策日志自动清理**：定期清理超过 30 天的决策日志
+- **告警 webhook 重试**：失败后自动重试 3 次
+- **前端性能优化**：决策日志和告警历史分页加载
+
+## 八、验证标准
+
+1. Cron 池监控页面正常显示池状态、指标和告警
+2. 创建智能评估后，配置历史页面自动显示创建快照
+3. 提交计划后，配置历史页面自动显示计划提交快照
+4. 决策过程页面显示完整的决策时间线和日志
+5. 手动扩缩容功能正常工作
+6. 告警触发后能在告警历史中看到
+7. 所有 API 端点正常响应
+8. 853 个测试全部通过
+
+## 九、致谢
+
+感谢所有参与 v1.1.0 开发和测试的团队成员！
+
+---
+
+**最后更新**: 2026-08-12