BIZ-25: Phase1 cron部署方案 - 15个Agent心跳定时任务配置

Co-authored-by: multica-agent <github@multica.ai>

plans/BIZ-25_定时心跳检查cron任务部署方案.md

@@ -0,0 +1,199 @@
+# 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 定时器已配置。