EnterpriseArchitect/plans/BIZ-24_HEARTBEAT增强模板方案.md

BIZ-24 HEARTBEAT.md 增强模板方案

Phase 1 of BIZ-13 运行稳定性保障方案
版本：v1.0
编制：陆怀瑾（COO）
日期：2026-06-22
状态：待审阅
关联：BIZ-13 运行稳定性保障方案

---

一、目标

为所有 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 发现任务后向用户请示"要不要做"，用户不在线时任务卡死数小时。

规则文本：

## ⚠️ 禁止请示规则（最高优先级）

你在心跳中发现 WorkBoard 任务后，必须立即执行，绝对禁止向用户请示！

原因：
- 用户在大多数时候并不在线，请示会导致任务卡死数小时
- 心跳是后台自动行为，用户没有义务实时响应你的请示
- 你的职责是"主动完成交付"，而不是"等待指令"

正确做法：
1. 发现 status=todo 且 agentId=你的卡片
2. 立即认领并执行
3. 如遇信息不足，先按自己的最佳理解执行，执行中再调整
4. 任务完成后，通知任务创建者

错误做法（绝对禁止）：
- ❌ "我发现了一个任务，要不要做？"
- ❌ "这个任务需要更多信息，请告诉我..."
- ❌ "任务已完成，请确认是否符合要求"

规则 2：超时检测规则

问题：Agent 执行到某一步后卡住，长时间无输出，无任何监告。

规则文本：

高频 Agent 版：

## ⏱️ 超时检测规则

### 心跳频率：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 版（差异部分）：

### 心跳频率：15 分钟
每次心跳执行以下检测：
1. 检查所有进行中任务的最新更新时间
2. 如超过 30 分钟无进展 → 标记为"疑似超时"

业务 Agent 版（差异部分）：

### 心跳频率：15 分钟
每次心跳执行以下检测：
1. 检查所有进行中任务的最新更新时间
2. 如超过 30 分钟无进展 → 标记为"疑似超时"

规则 3：自动恢复规则

问题：检测到无进展后没有自动恢复手段，任务永久停滞。

规则文本：

## 🔄 自动恢复规则

### 恢复流程

检测到超时（无进展超阈值） ↓ 步骤 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 时间，且可能导致循环等待。

规则文本：

## 🔗 依赖检查前置规则

### 任务启动前强制检查
每次认领或启动任务前，必须执行依赖检查：

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 版：

## 🛑 最大轮次限制

### 限制值：50 轮
单次任务执行不得超过 50 个对话轮次。

### 检测机制
- 每次心跳记录已消耗轮次
- 接近上限（80%）时发出预警
- 达到上限时自动暂停

### 超限处理

达到最大轮次 ↓

1. 暂停任务执行
2. 记录已完成的步骤和未完成的部分
3. 通知 COO，附当前进度
4. COO 决定：重新分配 / 拆分任务 / 人工介入

### 计数器维护
\```bash
# 每次心跳更新轮次计数
# 轮次数据存储在任务 metadata 或 comment 中
\```

开发 Agent 版（差异部分）：

### 限制值：100 轮
单次任务执行不得超过 100 个对话轮次。

业务 Agent 版（差异部分）：

### 限制值：30 轮
单次任务执行不得超过 30 个对话轮次。

---

四、HEARTBEAT.md 完整增强模板

4.1 高频 Agent 完整模板（secretary / coo）

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

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

# 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. 验证 — 等待一轮完整心跳，检查是否有任务停滞告警

---

六、交付物

• HEARTBEAT.md 增强模板方案（本文档）
• 14 个 Agent 的独立 HEARTBEAT.md 文件（待审阅后生成）
• 心跳 cron 配置脚本
• 部署验证报告

---

七、风险与注意事项

风险	影响	缓解措施
心跳自身卡死	所有监控失效	独立的 watchdog 进程监控心跳 cron 执行
自动恢复过于激进	正常长任务被中断	仅对超阈值且无进展的任务执行恢复
禁止请示导致错误执行	Agent 自行决定后出错	关键决策（涉及外部资源、金钱）仍需暂停并通知
轮次限制过严	复杂任务被截断	接近上限时提前预警，COO 可手动扩展

---

⚠️ 本方案需 Vincent 审阅后方可部署到各 Agent workspace。当前为模板方案，存放于 EnterpriseArchitect/plans/ 目录。