deaeabcf74
All checks were successful
CI / test (push) Successful in 3m54s
- .scratch/v111-architecture-scan.md: mark §6.1, §6.2, §6.4 as RESOLVED (commits38e3817,f85eca1,6d32653); add §6.5 for T8 decision-log dedupe (commit4bcab06). - docs/release-notes-v1.1.0.md: add section ten listing the four post-release fixes shipped to main after v1.1.1 was deployed, so the release page documents what v1.1.1 production actually contains (and what the v1.1.1 image does NOT contain).
256 lines
11 KiB
Markdown
256 lines
11 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 开发和测试的团队成员！
|
||
|
||
---
|
||
|
||
## 十、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 段)
|