1aa453ef0a
Implement Ticket 01 of intelligent eval cron pool architecture (ADR-0007): - Add 4 new tables: task_queue, cron_pool, config_snapshots, decision_logs - Implement task enqueueing logic with priority calculation - Implement task assignment and completion APIs - Add unit tests (9) and integration tests (7) - Update CONTEXT.md with new vocabulary - Add ADR-0007 documenting cron pool architecture decision All 760 tests passing.
119 lines
4.8 KiB
Markdown
119 lines
4.8 KiB
Markdown
# ADR-0007: 智能评估 OpenClaw 集成采用 Cron 池模式
|
||
|
||
**状态**: 已接受
|
||
**日期**: 2026-08-11
|
||
**决策者**: 架构团队
|
||
**相关**: ADR-0003（评估活动分期）、CONTEXT.md（智能评估词汇）
|
||
|
||
## Context
|
||
|
||
智能评估（Intelligent Evaluation）需要 OpenClaw 作为"虚拟用户大脑"自主规划和执行评测任务。关键争议在于：**一个智能评估如何与 OpenClaw 的执行单元关联**。
|
||
|
||
### 核心矛盾
|
||
|
||
1. **自主性 vs 可扩展性**：
|
||
- 保持 OpenClaw 自主性（每个评估独立决策）→ 一个评估一个 cron → cron 爆炸
|
||
- 解决 cron 爆炸（共享 cron）→ OpenClaw 失去自主性
|
||
|
||
2. **耐久性 vs 灵活性**：
|
||
- 长 session（上下文连续）→ OpenClaw 重启丢失
|
||
- 多 session（耐久）→ 上下文割裂
|
||
|
||
3. **平台控制 vs OpenClaw 自治**：
|
||
- 平台调度（精确控制）→ OpenClaw 退化为执行器
|
||
- OpenClaw 自治（灵活）→ 平台失去控制
|
||
|
||
### 已否决的方案
|
||
|
||
- **一个评估 = 一个 OpenClaw Agent**：OpenClaw 不支持持久 agent 概念
|
||
- **一个评估 = 一个长 Session**：长 session 超时，重启丢失
|
||
- **平台调度 + Webhook 触发**：OpenClaw 失去自主性，退化为静态评估
|
||
- **全局单 Cron + 批量处理**：单次唤醒耗时长，无并发
|
||
- **事件驱动 + Cron 兜底**：OpenClaw 无法自主规划
|
||
|
||
## Decision
|
||
|
||
采用 **Cron 池模式**：
|
||
|
||
1. **OpenClaw 维护 Cron 池**（5-20 个，动态扩容/缩容）
|
||
- 每个 cron 是"工作单元"，可以处理任意评估
|
||
- Cron state 存储 `{"status": "idle/busy", "eval_id": "..."}`
|
||
- 每分钟唤醒，自主决策"现在该做什么"
|
||
|
||
2. **平台维护任务队列**（持久化在 DB）
|
||
- 扫描所有 executing 评估
|
||
- 判断哪些需要立即处理（时段到期、有欠账）
|
||
- 按优先级排序，提供给 OpenClaw
|
||
|
||
3. **Cron 每次唤醒时**：
|
||
- 如果 idle → 从平台队列取一个任务
|
||
- 如果 busy → 继续处理当前评估
|
||
- 处理完 → 归还 cron 到池中
|
||
|
||
4. **池管理**：
|
||
- 平台负责创建/删除 cron（通过 OpenClaw CLI 或 Gateway API）
|
||
- 负载高时扩容（busy/total > 0.8）
|
||
- 负载低时缩容（idle > min_size * 2）
|
||
|
||
## Consequences
|
||
|
||
### 优点
|
||
|
||
1. **保持 OpenClaw 自主性**：每个 cron 有完整的决策权（规划、执行、调整）
|
||
2. **可扩展性**：池化复用，最多 20 个 cron，支持 100+ 并发评估（排队）
|
||
3. **耐久性好**：Cron state + 任务队列都持久化，重启可恢复
|
||
4. **资源可控**：限制并发评估数量（最多 20 个）
|
||
5. **弹性伸缩**：根据负载自动扩容/缩容
|
||
6. **技术可行**：OpenClaw 支持动态创建/删除 cron（CLI + Gateway API）
|
||
|
||
### 缺点
|
||
|
||
1. **复杂度高**：需要实现池管理、任务队列、超时检测、故障恢复
|
||
2. **状态同步**：Cron state 与平台状态需要保持一致
|
||
3. **调试困难**：需要追踪 cron 分配历史和决策日志
|
||
|
||
### 风险与缓解
|
||
|
||
| 风险 | 缓解措施 |
|
||
|------|---------|
|
||
| Cron 卡死 | 平台检测 10 分钟未活跃 → 标记评估 stuck → 分配新 cron |
|
||
| 池满（20 个都在用） | 新评估排队等待，前端提示"排队中" |
|
||
| OpenClaw 重启 | Cron state 持久化在 SQLite，重启后恢复 |
|
||
| 平台重启 | 任务队列持久化在 DB，重启后恢复 |
|
||
| 状态不一致 | 平台定期对账（每 5 分钟），发现不一致自动修复 |
|
||
|
||
### 性能影响
|
||
|
||
- **响应延迟**：分钟级（cron 每分钟触发），对于 24 小时窗口的评估可接受
|
||
- **资源消耗**：最多 20 个 cron 同时运行，每分钟 20 次唤醒
|
||
- **数据库压力**：任务队列查询每分钟 20 次，需要索引优化
|
||
|
||
## Implementation Notes
|
||
|
||
### 技术验证
|
||
|
||
OpenClaw 支持动态创建/删除 cron：
|
||
- CLI: `openclaw automations create/remove`
|
||
- Gateway API: 文档明确支持（具体端点待验证）
|
||
- State 持久化: SQLite，16KB 自定义 JSON
|
||
|
||
### 关键设计决策
|
||
|
||
1. **池管理归属**：平台负责创建/删除 cron，OpenClaw 负责执行
|
||
2. **状态权威**：平台 DB 是任务状态的权威，cron state 是执行上下文
|
||
3. **超时机制**：评估 2 小时未完成 → 强制归还 cron；cron 10 分钟未活跃 → 标记卡死
|
||
4. **公平性**：任务队列按优先级排序（时段到期 > 欠账多 > 等待时间长）
|
||
|
||
### 后续优化
|
||
|
||
- **事件驱动**：平台状态变更时主动触发 OpenClaw（webhook），减少 cron 轮询压力
|
||
- **优先级队列**：支持用户手动提升某个评估的优先级
|
||
- **监控告警**：池使用率、任务积压、cron 卡死率
|
||
|
||
## References
|
||
|
||
- [OpenClaw Cron Jobs Documentation](https://docs.openclaw.ai/automation/cron-jobs)
|
||
- [OpenClaw CLI Cron Commands](https://docs.openclaw.ai/cli/cron)
|
||
- CONTEXT.md「智能评估」章节
|
||
- ADR-0003「评估活动分期」
|