# 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