# 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「评估活动分期」