# 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
```

---

## 八、后续优化方向

- [ ] 监控面板集成（BIZ-28 Phase3）
- [ ] 心跳结果聚合展示
- [ ] Agent 健康状态告警
- [ ] 自动 Agent 发现（新增 Agent 自动配置心跳）

---

> **运维记录**：严维序 2026-06-24  
> 所有 15 个 Agent 的 HEARTBEAT.md 已部署，共享脚本已就位，cron 定时器已配置。