6f2be0e68f
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.
236 lines
8.5 KiB
Markdown
236 lines
8.5 KiB
Markdown
# 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
|