sinohqb 1aa453ef0a feat(intelligent-eval): add cron pool data model and task queue API

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.

2026-08-12 02:13:21 +08:00

4.8 KiB

Raw Permalink Blame History

ADR-0007: 智能评估 OpenClaw 集成采用 Cron 池模式

状态: 已接受日期: 2026-08-11 决策者: 架构团队相关: ADR-0003（评估活动分期）、CONTEXT.md（智能评估词汇）

Context

智能评估（Intelligent Evaluation）需要 OpenClaw 作为"虚拟用户大脑"自主规划和执行评测任务。关键争议在于：一个智能评估如何与 OpenClaw 的执行单元关联。

核心矛盾

自主性 vs 可扩展性：
- 保持 OpenClaw 自主性（每个评估独立决策）→ 一个评估一个 cron → cron 爆炸
- 解决 cron 爆炸（共享 cron）→ OpenClaw 失去自主性
耐久性 vs 灵活性：
- 长 session（上下文连续）→ OpenClaw 重启丢失
- 多 session（耐久）→ 上下文割裂
平台控制 vs OpenClaw 自治：
- 平台调度（精确控制）→ OpenClaw 退化为执行器
- OpenClaw 自治（灵活）→ 平台失去控制

已否决的方案

一个评估 = 一个 OpenClaw Agent：OpenClaw 不支持持久 agent 概念
一个评估 = 一个长 Session：长 session 超时，重启丢失
平台调度 + Webhook 触发：OpenClaw 失去自主性，退化为静态评估
全局单 Cron + 批量处理：单次唤醒耗时长，无并发
事件驱动 + Cron 兜底：OpenClaw 无法自主规划

Decision

采用 Cron 池模式：

OpenClaw 维护 Cron 池（5-20 个，动态扩容/缩容）
- 每个 cron 是"工作单元"，可以处理任意评估
- Cron state 存储 {"status": "idle/busy", "eval_id": "..."}
- 每分钟唤醒，自主决策"现在该做什么"
平台维护任务队列（持久化在 DB）
- 扫描所有 executing 评估
- 判断哪些需要立即处理（时段到期、有欠账）
- 按优先级排序，提供给 OpenClaw
Cron 每次唤醒时：
- 如果 idle → 从平台队列取一个任务
- 如果 busy → 继续处理当前评估
- 处理完 → 归还 cron 到池中
池管理：
- 平台负责创建/删除 cron（通过 OpenClaw CLI 或 Gateway API）
- 负载高时扩容（busy/total > 0.8）
- 负载低时缩容（idle > min_size * 2）

Consequences

优点

保持 OpenClaw 自主性：每个 cron 有完整的决策权（规划、执行、调整）
可扩展性：池化复用，最多 20 个 cron，支持 100+ 并发评估（排队）
耐久性好：Cron state + 任务队列都持久化，重启可恢复
资源可控：限制并发评估数量（最多 20 个）
弹性伸缩：根据负载自动扩容/缩容
技术可行：OpenClaw 支持动态创建/删除 cron（CLI + Gateway API）

缺点

复杂度高：需要实现池管理、任务队列、超时检测、故障恢复
状态同步：Cron state 与平台状态需要保持一致
调试困难：需要追踪 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

关键设计决策

池管理归属：平台负责创建/删除 cron，OpenClaw 负责执行
状态权威：平台 DB 是任务状态的权威，cron state 是执行上下文
超时机制：评估 2 小时未完成 → 强制归还 cron；cron 10 分钟未活跃 → 标记卡死
公平性：任务队列按优先级排序（时段到期 > 欠账多 > 等待时间长）

后续优化

事件驱动：平台状态变更时主动触发 OpenClaw（webhook），减少 cron 轮询压力
优先级队列：支持用户手动提升某个评估的优先级
监控告警：池使用率、任务积压、cron 卡死率

References

OpenClaw Cron Jobs Documentation
OpenClaw CLI Cron Commands
CONTEXT.md「智能评估」章节
ADR-0003「评估活动分期」

4.8 KiB Raw Permalink Blame History Unescape Escape