feat: BIZ-24 HEARTBEAT.md enhancement template for all agents

- 禁止请示规则：发现任务立即执行，禁止向用户请示 - 超时检测规则：高频 10min / 开发 15min / 业务 15min - 自动恢复规则：超时无进展自动重新调度 - 依赖检查前置：任务启动前强制检查依赖 - 最大轮次限制：高频 50轮 / 开发 100轮 / 业务 30轮 Phase 1 of BIZ-13 运行稳定性保障方案 Co-authored-by: multica-agent <github@multica.ai>
2026-06-22 23:11:59 +08:00
1 changed files with 586 additions and 0 deletions
@@ -0,0 +1,586 @@
+# BIZ-24 HEARTBEAT.md 增强模板方案
+
+> Phase 1 of BIZ-13 运行稳定性保障方案  
+> 版本：v1.0  
+> 编制：陆怀瑾（COO）  
+> 日期：2026-06-22  
+> 状态：待审阅  
+> 关联：[BIZ-13 运行稳定性保障方案](BIZ-13_运行稳定性保障方案.md)
+
+---
+
+## 一、目标
+
+为所有 Agent 的 HEARTBEAT.md 文件统一增强以下 5 项机制，解决任务停滞与运行异常问题：
+
+1. **禁止请示规则** — 消除"等待用户确认"导致的任务卡死
+2. **超时检测规则** — 按 Agent 类型差异化配置心跳频率
+3. **自动恢复规则** — 检测无进展时自动重新调度
+4. **依赖检查前置** — 任务启动前强制检查所有依赖
+5. **最大轮次限制** — 防止无限循环或资源耗尽
+
+---
+
+## 二、Agent 分类与参数配置
+
+### 2.1 分类标准
+
+| 分类 | 特征 | Agent |
+|------|------|-------|
+| 高频 Agent | 需频繁检查任务状态、全局监控 | secretary, coo |
+| 开发 Agent | 执行开发/设计/部署等长周期任务 | projectmanager, productmanager, architect, costcodev, designer, opengineer |
+| 业务 Agent | 执行专项业务任务 | taobaospecialist, contentspecialist, mediaspecialist, cvexpert, marketanalysis, lawyer |
+
+### 2.2 参数配置矩阵
+
+| 参数 | 高频 Agent | 开发 Agent | 业务 Agent |
+|------|-----------|-----------|-----------|
+| 心跳频率 | 10 分钟 | 15 分钟 | 15 分钟 |
+| 最大轮次 | 50 轮 | 100 轮 | 30 轮 |
+| 超时告警阈值 | 20 分钟无进展 | 30 分钟无进展 | 30 分钟无进展 |
+| 自动恢复等待 | 30 分钟后重新调度 | 45 分钟后重新调度 | 45 分钟后重新调度 |
+| 告警通知对象 | COO | COO + 创建者 | 创建者 |
+
+---
+
+## 三、五项增强规则详解
+
+### 规则 1：禁止请示规则
+
+**问题**：Agent 发现任务后向用户请示"要不要做"，用户不在线时任务卡死数小时。
+
+**规则文本**：
+```markdown
+## ⚠️ 禁止请示规则（最高优先级）
+
+你在心跳中发现 WorkBoard 任务后，必须立即执行，绝对禁止向用户请示！
+
+原因：
+- 用户在大多数时候并不在线，请示会导致任务卡死数小时
+- 心跳是后台自动行为，用户没有义务实时响应你的请示
+- 你的职责是"主动完成交付"，而不是"等待指令"
+
+正确做法：
+1. 发现 status=todo 且 agentId=你的卡片
+2. 立即认领并执行
+3. 如遇信息不足，先按自己的最佳理解执行，执行中再调整
+4. 任务完成后，通知任务创建者
+
+错误做法（绝对禁止）：
+- ❌ "我发现了一个任务，要不要做？"
+- ❌ "这个任务需要更多信息，请告诉我..."
+- ❌ "任务已完成，请确认是否符合要求"
+```
+
+### 规则 2：超时检测规则
+
+**问题**：Agent 执行到某一步后卡住，长时间无输出，无任何监告。
+
+**规则文本**：
+
+高频 Agent 版：
+```markdown
+## ⏱️ 超时检测规则
+
+### 心跳频率：10 分钟
+每次心跳执行以下检测：
+1. 检查所有进行中任务的最新更新时间
+2. 如超过 20 分钟无进展 → 标记为"疑似超时"
+3. 疑似超时 → 立即追加一次完整心跳，尝试推进
+4. 如确认超时 → 进入自动恢复流程
+
+### 检测脚本
+\```bash
+# 检查进行中任务是否超时
+openclaw workboard list --json 2>/dev/null | python3 -c "
+import sys, json, time
+data = json.load(sys.stdin)
+inprogress = [c for c in data.get('cards', []) if c.get('status') == 'in_progress']
+now = time.time()
+for c in inprogress:
+    updated = c.get('updated_at', '')
+    if updated:
+        age = now - time.mktime(time.strptime(updated[:19], '%Y-%m-%dT%H:%M:%S'))
+        if age > 1200:  # 20 分钟
+            print(f'⏰ TIMEOUT: {c[\"id\"][:8]} [{c.get(\"agentId\",\"?\")}] {c[\"title\"]}')
+"
+\```
+```
+
+开发 Agent 版（差异部分）：
+```markdown
+### 心跳频率：15 分钟
+每次心跳执行以下检测：
+1. 检查所有进行中任务的最新更新时间
+2. 如超过 30 分钟无进展 → 标记为"疑似超时"
+```
+
+业务 Agent 版（差异部分）：
+```markdown
+### 心跳频率：15 分钟
+每次心跳执行以下检测：
+1. 检查所有进行中任务的最新更新时间
+2. 如超过 30 分钟无进展 → 标记为"疑似超时"
+```
+
+### 规则 3：自动恢复规则
+
+**问题**：检测到无进展后没有自动恢复手段，任务永久停滞。
+
+**规则文本**：
+```markdown
+## 🔄 自动恢复规则
+
+### 恢复流程
+```
+检测到超时（无进展超阈值）
+    ↓
+步骤 1：追加一次完整心跳，尝试推进任务
+    ↓
+步骤 2：检查任务状态
+    ↓
+┌─────────────┴─────────────┐
+│                           │
+有进展                     仍无进展
+    │                           │
+重置超时计数器              步骤 3：通知 COO/创建者
+    │                           │
+继续执行                    步骤 4：标记为 blocked
+                                │
+                           步骤 5：重新调度（分配备用 Agent 或
+                                   等待人工介入）
+```
+
+### 自动恢复触发条件
+- 高频 Agent：超 30 分钟无进展 → 自动重新调度
+- 开发 Agent：超 45 分钟无进展 → 自动重新调度  
+- 业务 Agent：超 45 分钟无进展 → 自动重新调度
+
+### 恢复操作
+1. 停止当前任务执行
+2. 在任务中添加评论说明超时原因
+3. 释放 Agent 认领（release claim）
+4. 通知 COO 重新分配
+5. 如任务可重试 → 创建重新调度标记
+
+### 恢复脚本示例
+\```bash
+# 自动恢复：重新调度超时任务
+openclaw workboard list --json 2>/dev/null | python3 -c "
+import sys, json, time
+data = json.load(sys.stdin)
+timed_out = [c for c in data.get('cards', [])
+              if c.get('status') == 'in_progress' 
+              and c.get('agentId') in ['agent_id_list']]
+for c in timed_out:
+    # 检查是否超过自动恢复阈值
+    # 如超过 → 释放认领，通知 COO
+    print(f'RECOVER: {c[\"id\"][:8]}')
+"
+\```
+```
+
+### 规则 4：依赖检查前置
+
+**问题**：任务开始后才发现依赖未满足，浪费 Agent 时间，且可能导致循环等待。
+
+**规则文本**：
+```markdown
+## 🔗 依赖检查前置规则
+
+### 任务启动前强制检查
+每次认领或启动任务前，必须执行依赖检查：
+
+1. 读取任务的 depends_on 字段
+2. 逐一检查每个依赖任务的状态
+3. 所有依赖 ready → 可以启动
+4. 任一依赖未完成 → 禁止启动，标记为 blocked
+
+### 检查脚本
+\```bash
+# 依赖检查
+openclaw workboard read <card-id> --json 2>/dev/null | python3 -c "
+import sys, json
+card = json.load(sys.stdin)
+deps = card.get('dependsOn', [])
+if deps:
+    for dep in deps:
+        print(f'依赖: {dep[\"id\"]} → 状态: {dep.get(\"status\", \"?\")}')
+        if dep.get('status') != 'done':
+            print(f'⛔ 依赖未满足，禁止启动任务 {card[\"id\"][:8]}')
+            sys.exit(1)
+    print('✅ 所有依赖已满足')
+else:
+    print('✅ 无依赖，可以启动')
+"
+\```
+
+### 依赖未满足时的处理
+1. 不认领任务（保持 todo 状态）
+2. 不在该任务上浪费心跳时间
+3. 如超过等待阈值（高频 1h / 开发/业务 2h），通知依赖任务的执行者
+```
+
+### 规则 5：最大轮次限制
+
+**问题**：Agent 陷入无限循环，反复执行相同逻辑无进展，持续消耗 API 配额。
+
+**规则文本**：
+
+高频 Agent 版：
+```markdown
+## 🛑 最大轮次限制
+
+### 限制值：50 轮
+单次任务执行不得超过 50 个对话轮次。
+
+### 检测机制
+- 每次心跳记录已消耗轮次
+- 接近上限（80%）时发出预警
+- 达到上限时自动暂停
+
+### 超限处理
+```
+达到最大轮次
+    ↓
+1. 暂停任务执行
+2. 记录已完成的步骤和未完成的部分
+3. 通知 COO，附当前进度
+4. COO 决定：重新分配 / 拆分任务 / 人工介入
+```
+
+### 计数器维护
+\```bash
+# 每次心跳更新轮次计数
+# 轮次数据存储在任务 metadata 或 comment 中
+\```
+```
+
+开发 Agent 版（差异部分）：
+```markdown
+### 限制值：100 轮
+单次任务执行不得超过 100 个对话轮次。
+```
+
+业务 Agent 版（差异部分）：
+```markdown
+### 限制值：30 轮
+单次任务执行不得超过 30 个对话轮次。
+```
+
+---
+
+## 四、HEARTBEAT.md 完整增强模板
+
+### 4.1 高频 Agent 完整模板（secretary / coo）
+
+```markdown
+# HEARTBEAT.md - [Agent Name] 的心跳配置
+
+## ⚠️ 禁止请示规则（最高优先级，自动执行）
+
+> **核心规则：发现分配给自己的任务 → 立即执行，不得向用户请示！**
+> 心跳是后台自动行为，用户在大多数时候并不在线，请示会导致任务卡死。
+
+### 执行流程（严格执行，无需确认）
+1. **检查待办卡片** — 查找 agent_id 为自己且 status=todo 的卡片
+2. **立即执行，不得请示** — 发现待办卡片后直接执行
+3. **检查进行中卡片** — 确认认领的任务状态
+4. **完成任务** — 完成后通知任务创建者
+
+### ⚠️ 绝对禁止行为
+- ❌ 不得问"要不要做这个任务"
+- ❌ 不得等用户确认再执行
+- ❌ 不得以"需要更多信息"为由拒绝执行
+
+---
+
+## ⏱️ 超时检测规则
+
+### 心跳频率：10 分钟
+每次心跳执行以下检测：
+1. 检查进行中任务的最新更新时间
+2. 超过 20 分钟无进展 → 标记为"疑似超时"
+3. 疑似超时 → 追加一次完整心跳尝试推进
+4. 确认超时 → 进入自动恢复流程
+
+---
+
+## 🔄 自动恢复规则
+
+### 触发条件
+- 超 30 分钟无进展 → 自动重新调度
+
+### 恢复操作
+1. 停止当前任务执行
+2. 添加评论说明超时原因
+3. 释放 Agent 认领
+4. 通知 COO 重新分配
+5. 创建重新调度标记
+
+---
+
+## 🔗 依赖检查前置规则
+
+### 强制检查流程
+1. 认领任务前，读取 depends_on 字段
+2. 逐一检查每个依赖任务的状态
+3. 依赖未满足 → 不认领（保持 todo）
+4. 超过等待阈值（1h）→ 通知依赖任务执行者
+
+---
+
+## 🛑 最大轮次限制
+
+### 限制值：50 轮
+- 接近 80%（40 轮）→ 预警
+- 达到上限 → 暂停，通知 COO
+
+---
+
+## 🫀 心跳执行清单
+
+1. ✅ WorkBoard 任务检查
+2. ✅ 进行中任务超时检测
+3. ✅ 依赖检查
+4. ✅ 轮次计数器更新
+5. ✅ [Agent 专属检查项]
+
+---
+
+## ⚠️ 全局关键规则
+
+1. **心跳不打断对话** — 用户正在对话时延后执行
+2. **非紧急事项延后汇报** — 等下一轮心跳或用户询问
+3. **发现任务立即执行，不得请示**
+4. **超时任务按自动恢复流程处理**
+5. **依赖未满足不启动**
+6. **达到轮次上限自动暂停**
+```
+
+### 4.2 开发 Agent 完整模板（projectmanager / productmanager / architect / costcodev / designer / opengineer）
+
+```markdown
+# HEARTBEAT.md - [Agent Name] 的心跳配置
+
+## ⚠️ 禁止请示规则（最高优先级，自动执行）
+
+> **核心规则：发现分配给自己的任务 → 立即执行，不得向用户请示！**
+> 心跳是后台自动行为，用户在大多数时候并不在线，请示会导致任务卡死。
+
+### 执行流程（严格执行，无需确认）
+1. **检查待办卡片** — 查找 agent_id 为自己且 status=todo 的卡片
+2. **立即执行，不得请示** — 发现待办卡片后直接执行
+3. **检查进行中卡片** — 确认认领的任务状态
+4. **完成任务** — 完成后通知任务创建者
+
+### ⚠️ 绝对禁止行为
+- ❌ 不得问"要不要做这个任务"
+- ❌ 不得等用户确认再执行
+- ❌ 不得以"需要更多信息"为由拒绝执行
+
+---
+
+## ⏱️ 超时检测规则
+
+### 心跳频率：15 分钟
+每次心跳执行以下检测：
+1. 检查进行中任务的最新更新时间
+2. 超过 30 分钟无进展 → 标记为"疑似超时"
+3. 疑似超时 → 追加一次完整心跳尝试推进
+4. 确认超时 → 进入自动恢复流程
+
+---
+
+## 🔄 自动恢复规则
+
+### 触发条件
+- 超 45 分钟无进展 → 自动重新调度
+
+### 恢复操作
+1. 停止当前任务执行
+2. 添加评论说明超时原因
+3. 释放 Agent 认领
+4. 通知 COO 和任务创建者
+5. 创建重新调度标记
+
+---
+
+## 🔗 依赖检查前置规则
+
+### 强制检查流程
+1. 认领任务前，读取 depends_on 字段
+2. 逐一检查每个依赖任务的状态
+3. 依赖未满足 → 不认领（保持 todo）
+4. 超过等待阈值（2h）→ 通知依赖任务执行者
+
+---
+
+## 🛑 最大轮次限制
+
+### 限制值：100 轮
+- 接近 80%（80 轮）→ 预警
+- 达到上限 → 暂停，记录日志
+
+---
+
+## 🫀 心跳执行清单
+
+1. ✅ WorkBoard 任务检查
+2. ✅ 进行中任务超时检测
+3. ✅ 依赖检查
+4. ✅ 轮次计数器更新
+5. ✅ [Agent 专属检查项]
+
+---
+
+## ⚠️ 全局关键规则
+
+1. **心跳不打断对话** — 用户正在对话时延后执行
+2. **非紧急事项延后汇报** — 等下一轮心跳或用户询问
+3. **发现任务立即执行，不得请示**
+4. **超时任务按自动恢复流程处理**
+5. **依赖未满足不启动**
+6. **达到轮次上限自动暂停**
+```
+
+### 4.3 业务 Agent 完整模板（taobaospecialist / contentspecialist / mediaspecialist / cvexpert / marketanalysis / lawyer）
+
+```markdown
+# HEARTBEAT.md - [Agent Name] 的心跳配置
+
+## ⚠️ 禁止请示规则（最高优先级，自动执行）
+
+> **核心规则：发现分配给自己的任务 → 立即执行，不得向用户请示！**
+> 心跳是后台自动行为，用户在大多数时候并不在线，请示会导致任务卡死。
+
+### 执行流程（严格执行，无需确认）
+1. **检查待办卡片** — 查找 agent_id 为自己且 status=todo 的卡片
+2. **立即执行，不得请示** — 发现待办卡片后直接执行
+3. **检查进行中卡片** — 确认认领的任务状态
+4. **完成任务** — 完成后通知任务创建者
+
+### ⚠️ 绝对禁止行为
+- ❌ 不得问"要不要做这个任务"
+- ❌ 不得等用户确认再执行
+- ❌ 不得以"需要更多信息"为由拒绝执行
+
+---
+
+## ⏱️ 超时检测规则
+
+### 心跳频率：15 分钟
+每次心跳执行以下检测：
+1. 检查进行中任务的最新更新时间
+2. 超过 30 分钟无进展 → 标记为"疑似超时"
+3. 疑似超时 → 追加一次完整心跳尝试推进
+4. 确认超时 → 进入自动恢复流程
+
+---
+
+## 🔄 自动恢复规则
+
+### 触发条件
+- 超 45 分钟无进展 → 自动重新调度
+
+### 恢复操作
+1. 停止当前任务执行
+2. 添加评论说明超时原因
+3. 释放 Agent 认领
+4. 通知任务创建者
+5. 创建重新调度标记
+
+---
+
+## 🔗 依赖检查前置规则
+
+### 强制检查流程
+1. 认领任务前，读取 depends_on 字段
+2. 逐一检查每个依赖任务的状态
+3. 依赖未满足 → 不认领（保持 todo）
+4. 超过等待阈值（2h）→ 通知依赖任务执行者
+
+---
+
+## 🛑 最大轮次限制
+
+### 限制值：30 轮
+- 接近 80%（24 轮）→ 预警
+- 达到上限 → 暂停，通知创建者
+
+---
+
+## 🫀 心跳执行清单
+
+1. ✅ WorkBoard 任务检查
+2. ✅ 进行中任务超时检测
+3. ✅ 依赖检查
+4. ✅ 轮次计数器更新
+5. ✅ [Agent 专属检查项]
+
+---
+
+## ⚠️ 全局关键规则
+
+1. **心跳不打断对话** — 用户正在对话时延后执行
+2. **非紧急事项延后汇报** — 等下一轮心跳或用户询问
+3. **发现任务立即执行，不得请示**
+4. **超时任务按自动恢复流程处理**
+5. **依赖未满足不启动**
+6. **达到轮次上限自动暂停**
+```
+
+---
+
+## 五、部署清单
+
+### 5.1 各 Agent HEARTBEAT.md 更新状态
+
+| Agent | 分类 | 模板版本 | 部署状态 | 部署人 |
+|-------|------|---------|---------|--------|
+| secretary (刘诗妮) | 高频 | 高频 Agent 模板 | 待部署 | COO |
+| coo (陆怀瑾) | 高频 | 高频 Agent 模板 | 待部署 | COO |
+| projectmanager (胡蓉) | 开发 | 开发 Agent 模板 | 待部署 | COO |
+| productmanager (沈路明) | 开发 | 开发 Agent 模板 | 待部署 | COO |
+| architect (梁思筑) | 开发 | 开发 Agent 模板 | 待部署 | COO |
+| costcodev (徐聪) | 开发 | 开发 Agent 模板 | 待部署 | COO |
+| designer (苏绘锦) | 开发 | 开发 Agent 模板 | 待部署 | COO |
+| opengineer (严维序) | 开发 | 开发 Agent 模板 | 待部署 | COO |
+| taobaospecialist (陆云帆) | 业务 | 业务 Agent 模板 | 待部署 | COO |
+| contentspecialist (文墨言) | 业务 | 业务 Agent 模板 | 待部署 | COO |
+| mediaspecialist (钟帧韵) | 业务 | 业务 Agent 模板 | 待部署 | COO |
+| cvexpert (程伯予) | 业务 | 业务 Agent 模板 | 待部署 | COO |
+| marketanalysis (顾析策) | 业务 | 业务 Agent 模板 | 待部署 | COO |
+| lawyer (苏慎) | 业务 | 业务 Agent 模板 | 待部署 | COO |
+
+### 5.2 部署步骤
+
+1. **Vincent 审阅本方案** — 确认参数配置
+2. **创建 HEARTBEAT.md 文件** — 按模板为每个 Agent 创建（以 [Agent Name] 替换占位符）
+3. **配置心跳 cron** — 按分类配置定时任务
+4. **部署到各 Agent workspace** — 将 HEARTBEAT.md 分发到对应 Agent 工作区
+5. **验证** — 等待一轮完整心跳，检查是否有任务停滞告警
+
+---
+
+## 六、交付物
+
+- [x] HEARTBEAT.md 增强模板方案（本文档）
+- [ ] 14 个 Agent 的独立 HEARTBEAT.md 文件（待审阅后生成）
+- [ ] 心跳 cron 配置脚本
+- [ ] 部署验证报告
+
+---
+
+## 七、风险与注意事项
+
+| 风险 | 影响 | 缓解措施 |
+|------|------|----------|
+| 心跳自身卡死 | 所有监控失效 | 独立的 watchdog 进程监控心跳 cron 执行 |
+| 自动恢复过于激进 | 正常长任务被中断 | 仅对超阈值且无进展的任务执行恢复 |
+| 禁止请示导致错误执行 | Agent 自行决定后出错 | 关键决策（涉及外部资源、金钱）仍需暂停并通知 |
+| 轮次限制过严 | 复杂任务被截断 | 接近上限时提前预警，COO 可手动扩展 |
+
+---
+
+> ⚠️ 本方案需 Vincent 审阅后方可部署到各 Agent workspace。当前为模板方案，存放于 EnterpriseArchitect/plans/ 目录。