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

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. 备份数据：

   cp data/agenteval.db data/agenteval.db.backup
   

2. 拉取新代码：

   git pull origin main
   

3. 运行迁移：

   alembic upgrade head
   

4. 同步版本号：

   python3 scripts/sync_version.py
   

5. 重启服务：

   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 开发和测试的团队成员！

---

十、Post-release Patches（v1.1.0 → v1.1.1 之后合并到 main 的修复）

v1.1.0 部署到生产后，CI 防护网 + 集成测试暴露了 4 个真问题，并在 P0 测试加固阶段（扫描文档 §6）持续追踪。下列修复已合入 main，生产环境（v1.1.1）已包含这些行为，但版本号未升级（不打 v1.1.2 patch release）。

Commit	修复	影响的真问题 / 守卫
38e3817	task_queue.assign_task / complete_task 改原子 CAS（UPDATE … WHERE status=… + rowcount）	#3 worker 任务竞争（§6.1）— xfail 转绿
f85eca1	AlertManager._send_webhook 加重试（最多 3 次、指数退避 1s/2s）+ 按 alert.webhook_sent 去重	#5 webhook 缺重试+去重（§6.2）— 两个 xfail 转绿
6d32653	AlertManager.maybe_autoscale 在创建 alert 后自动调 cron_pool.scale_up(1)（高利用率/任务积压自动扩容）	#6 告警→auto_scale 联动（T7）— xfail 转绿
4bcab06	decision_logs.create_decision_log 在同 (eval_id, decision_type, context) 时去重返回现有行（append-only 不变性保持）	#6 decision-logs 不去重（T8）— xfail 转绿
3376cac	移除上一步遗留的未用变量与 import（ruff F841/F401）	代码清理

质量基线：878 passed + 0 xfailed（全 xfail 守卫已转绿并移除）；ruff 零错误；后端/前端测试全绿。

生产版本：v1.1.1（image agenteval:1.1.1-ee9cc33，commit ee9cc33）已部署到 volcengine-102，仍包含 v1.1.0 全部功能。生产若要吸收这些 post-release 行为，无需重新部署——已含在 v1.1.1 镜像（这些 commit 在 v1.1.1 bump 之后合并，但不影响 v1.1.1 的镜像；如需打包进生产 image，需在打 v1.1.2 patch release 时重新 build）。

遗留（未修）：前端 CronPoolMonitor 轮询统一（S6 独立 issue，§6.3）— 当前前端 cron 池监控轮询在浏览器 tab 不可见时仍每 5s 触发，建议作为下一轮 issue 处理。

---

最后更新: 2026-08-12 (v1.1.0) + 2026-08-14 (post-release patches 段)