210 lines
7.8 KiB
Markdown
210 lines
7.8 KiB
Markdown
# BIZ-25 定时心跳检查 cron 任务部署方案
|
||
|
||
> **版本：** v1.0
|
||
> **编制：** 严维序（opengineer）
|
||
> **日期：** 2026-06-24
|
||
> **状态：** 已部署
|
||
> **父方案：** [BIZ-13 运行稳定性保障方案](./BIZ-13_运行稳定性保障方案.md)
|
||
|
||
---
|
||
|
||
## 一、概述
|
||
|
||
本方案是 BIZ-13 Phase1 的执行层方案，负责将 HEARTBEAT.md 模板+共享脚本部署为可运行的定时心跳检查机制。
|
||
|
||
### 部署架构
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────┐
|
||
│ OpenClaw Gateway Cron │
|
||
│ ┌────────────┐ ┌────────────┐ ┌──────────────┐ │
|
||
│ │ Agent A │ │ Agent B │ │ Agent C │ │
|
||
│ │ 心跳(10/15m)│ │ 心跳(15m) │ │ 心跳(15m) │ │
|
||
│ └─────┬──────┘ └─────┬──────┘ └──────┬───────┘ │
|
||
│ │ │ │ │
|
||
│ ▼ ▼ ▼ │
|
||
│ ┌──────────────────────────────────────────┐ │
|
||
│ │ shared/scripts/heartbeat_helper.py │ │
|
||
│ │ + multica_proxy.py │ │
|
||
│ │ + rate_limiter.py │ │
|
||
│ └──────────────────────────────────────────┘ │
|
||
│ │ │ │ │
|
||
│ ▼ ▼ ▼ │
|
||
│ ┌──────────────────────────────────────────┐ │
|
||
│ │ 三源任务检查: WorkBoard + Multica + 文档 │ │
|
||
│ └──────────────────────────────────────────┘ │
|
||
└─────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## 二、Agent 心跳频率分类
|
||
|
||
根据 BIZ-13 方案定义：
|
||
|
||
| 分类 | 频率 | Agent | 数量 |
|
||
|------|------|-------|------|
|
||
| **高频** | **10 分钟** | 陆怀瑾 (coo), 刘诗妮 (secretary) | 2 |
|
||
| **常规** | **15 分钟** | 严维序 (opengineer), 沈路明 (productmanager), 胡蓉 (projectmanager), 梁思筑 (architect), 苏锦绘 (designer), 徐聪 (costcodev), 文墨言 (contentspecialist), 程伯予 (cvexpert), 许言 (prompt-engineer), 钟帧韵 (mediaspecialist), 陆云帆 (taobaospecialist), 顾析策 (marketanalysis), 苏慎 (lawyer) | 13 |
|
||
|
||
---
|
||
|
||
## 三、部署清单
|
||
|
||
### 3.1 ✅ 已完成 — HEARTBEAT.md 模板
|
||
|
||
所有 15 个 Agent 的工作区均已部署 HEARTBEAT.md：
|
||
|
||
| 工作区 | 频率 | 核心内容 |
|
||
|--------|------|----------|
|
||
| `coo/` | 10 min | BIZ-38 模板 + 全局积压巡检 |
|
||
| `secretary/` | 10 min | BIZ-38 模板 |
|
||
| `opengineer/` | 10 min | BIZ-38 模板 + 三源检查 |
|
||
| `projectmanager/` | 10 min | BIZ-38 模板 |
|
||
| `costcodev/` | 10 min | BIZ-38 模板 |
|
||
| 其余 10 个 Agent | 15 min | 标准模板 + 三源检查 |
|
||
|
||
### 3.2 ✅ 已完成 — 共享心跳脚本
|
||
|
||
路径：`shared/scripts/`
|
||
|
||
| 文件 | 用途 | 状态 |
|
||
|------|------|------|
|
||
| `rate_limiter.py` | 缓存管理 + 请求调度 + 协调轮询 | ✅ 已部署 |
|
||
| `multica_proxy.py` | Multica CLI 代理 + 缓存封装 | ✅ 已部署 |
|
||
| `heartbeat_helper.py` | 三源任务检查 + 超时检测 + 心跳入口 | ✅ 已部署 |
|
||
|
||
### 3.3 ⬜ 本次部署 — OpenClaw Cron 任务
|
||
|
||
使用 OpenClaw Gateway cron 系统创建定时任务，通过 `agentTurn` 隔离会话实现各 Agent 的周期性心跳触发。
|
||
|
||
#### Cron Job 规格
|
||
|
||
```yaml
|
||
每个 Agent:
|
||
schedule:
|
||
kind: cron
|
||
expr: "*/10 * * * *" # 高频 Agent
|
||
# expr: "*/15 * * * *" # 常规 Agent
|
||
tz: "Asia/Shanghai"
|
||
sessionTarget: "isolated"
|
||
payload:
|
||
kind: "agentTurn"
|
||
message: "运行心跳检查。执行你的 HEARTBEAT.md 中的三源任务检查。"
|
||
```
|
||
|
||
---
|
||
|
||
## 四、部署执行记录
|
||
|
||
### 执行时间：2026-06-24 00:14 CST
|
||
|
||
#### 创建的 Cron Job 清单
|
||
|
||
| Agent | 频率 | Cron Session | 状态 |
|
||
|-------|------|-------------|------|
|
||
| coo (陆怀瑾) | 10 min | isolated agentTurn | ✅ |
|
||
| secretary (刘诗妮) | 10 min | isolated agentTurn | ✅ |
|
||
| opengineer (严维序) | 10 min | isolated agentTurn | ✅ |
|
||
| projectmanager (胡蓉) | 10 min | isolated agentTurn | ✅ |
|
||
| costcodev (徐聪) | 10 min | isolated agentTurn | ✅ |
|
||
| productmanager (沈路明) | 15 min | isolated agentTurn | ✅ |
|
||
| architect (梁思筑) | 15 min | isolated agentTurn | ✅ |
|
||
| designer (苏锦绘) | 15 min | isolated agentTurn | ✅ |
|
||
| contentspecialist (文墨言) | 15 min | isolated agentTurn | ✅ |
|
||
| cvexpert (程伯予) | 15 min | isolated agentTurn | ✅ |
|
||
| prompt-engineer (许言) | 15 min | isolated agentTurn | ✅ |
|
||
| mediaspecialist (钟帧韵) | 15 min | isolated agentTurn | ✅ |
|
||
| taobaospecialist (陆云帆) | 15 min | isolated agentTurn | ✅ |
|
||
| marketanalysis (顾析策) | 15 min | isolated agentTurn | ✅ |
|
||
| lawyer (苏慎) | 15 min | isolated agentTurn | ✅ |
|
||
|
||
---
|
||
|
||
## 五、心跳检查内容
|
||
|
||
每次心跳触发后，Agent 在隔离会话中执行以下检查：
|
||
|
||
### 5.1 三源任务检查
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
A[心跳触发] --> B[检查 WorkBoard 待办卡片]
|
||
A --> C[检查 Multica 待办 Issues]
|
||
A --> D[检查本地待办文档]
|
||
B --> E{有待办?}
|
||
C --> E
|
||
D --> E
|
||
E -->|有| F[自动执行任务]
|
||
E -->|无| G[结束心跳]
|
||
F --> H[任务完成?]
|
||
H -->|是| I[更新状态]
|
||
H -->|否| J[通知 COO]
|
||
```
|
||
|
||
### 5.2 超时检测
|
||
|
||
- 进行中任务超过 20 分钟无进展 → 标记"疑似超时"
|
||
- 确认超时 → 自动恢复流程
|
||
|
||
### 5.3 依赖检查
|
||
|
||
- 认领任务前检查 `depends_on`
|
||
- 依赖未满足 → 保持 todo，不认领
|
||
|
||
### 5.4 轮次控制
|
||
|
||
- 单任务最大 50 轮
|
||
- 接近 80%（40 轮）→ 预警
|
||
- 达到上限 → 暂停，通知 COO
|
||
|
||
---
|
||
|
||
## 六、风险与规避
|
||
|
||
| 风险 | 影响 | 应对 |
|
||
|------|------|------|
|
||
| 心跳任务自身卡死 | 监控失效 | rate_limiter.py 缓存 + 超时保护 |
|
||
| 新增 Agent 未配心跳 | 遗漏 | 本方案作为部署 SOP 参考 |
|
||
| 会话隔离导致上下文丢失 | 心跳重复 | 心跳仅做检查，不承担复杂任务 |
|
||
| Agent 不在线 | 心跳无响应 | 系统事件 fallback，COO 巡检兜底 |
|
||
|
||
---
|
||
|
||
## 七、验证方法
|
||
|
||
```bash
|
||
# 检查 cron job 列表
|
||
openclaw cron list
|
||
|
||
# 手动触发一次心跳 for a specific agent
|
||
openclaw cron run <job-id>
|
||
|
||
# 检查心跳脚本健康状态
|
||
python3 shared/scripts/heartbeat_helper.py <agent_id> --health
|
||
```
|
||
|
||
---
|
||
|
||
## 八、修复记录
|
||
|
||
### v1.1 — 2026-06-24
|
||
|
||
| 问题 | 修复 |
|
||
|------|------|
|
||
| cron delivery 报 Feishu 投递错误 | delivery 从 `announce` 改为 `none`（原方案未指定 delivery，不影响功能） |
|
||
| Multica workspace_id 未传递 | `multica_proxy.py` 新增 `_inject_workspace_id()`，自动在所有 multica CLI 调用注入 `--workspace-id` |
|
||
| AGENT_CONFIGS 仅 5 个 Agent | `heartbeat_helper.py` 扩展至全部 15 个 Agent |
|
||
| COO HEARTBEAT 显示未部署 | 更新 BIZ-38 集成清单表 |
|
||
|
||
## 九、后续优化方向
|
||
|
||
- [ ] 监控面板集成（BIZ-28 Phase3）
|
||
- [ ] 心跳结果聚合展示
|
||
- [ ] Agent 健康状态告警
|
||
- [ ] 自动 Agent 发现（新增 Agent 自动配置心跳）
|
||
|
||
---
|
||
|
||
> **运维记录**：严维序 2026-06-24
|
||
> 所有 15 个 Agent 的 HEARTBEAT.md 已部署，共享脚本已就位，cron 定时器已配置。 |