# HEARTBEAT.md 增强模板

> 版本：v2.0
> 来源：BIZ-13 运行稳定性保障方案
> 用途：为所有 Agent HEARTBEAT.md 增加运行稳定性保障能力

---

## 全局增强规则（所有 Agent 必须包含）

### 1. 🛡️ 超时检测与自动恢复

```markdown
## 🛡️ 超时检测与自动恢复

> **核心规则：每次心跳，检查自己是否有任务超时未完成。**

### 超时阈值

| Agent 类型 | 心跳频率 | 单任务超时 |
|------------|----------|------------|
| 高频（secretary/coo） | 10 分钟 | 60 分钟 |
| 开发（costcodev/architect/opengineer/designer） | 15 分钟 | 120 分钟 |
| 业务（其他 Agent） | 15 分钟 | 90 分钟 |

### 检测流程

每次心跳执行：
1. 获取自己的 `status=in_progress` 的 WorkBoard 卡片
2. 计算 `当前时间 - started_at`
3. 如果超过超时阈值 → 进入自动恢复流程

### 自动恢复流程

```
检测到任务超时
    ↓
检查最近日志（是否有实质性进展）
    ↓
┌──────────┴──────────┐
│                     │
有进展（< 3轮无产出）  无进展（>= 3轮无产出）
│                     │
延长超时 + 记录日志    自动恢复：
│                     ├─ 尝试重新执行当前步骤
更新 heartbeat         ├─ 仍失败 → 释放卡片
                      └─ 通知 COO 介入
```

### ⚠️ 超时告警

- 第 1 次超时：自动恢复，不告警
- 第 2 次超时：通知 COO
- 第 3 次超时：通知 Vincent，卡片标为 blocked
```

### 2. 🔗 依赖检查前置

```markdown
## 🔗 依赖检查前置

> **核心规则：认领任务前，必须检查所有依赖是否已完成。**

### 检查流程

1. 获取任务的 `depends_on` 列表
2. 对每个依赖，查询其状态
3. 如果任一依赖未完成 → 不认领该任务，等待下次心跳
4. 如果所有依赖已完成 → 正常认领并执行

### 异常处理

- 依赖任务已取消 → 向上报告，由 COO 决策
- 依赖任务超时无响应 → 通知依赖方和 COO
- 循环依赖 → 自动检测并报告给 COO
```

### 3. 🔄 最大轮次限制

```markdown
## 🔄 最大轮次限制

> **核心规则：单任务不能无限循环执行。**

| Agent 类型 | 最大对话轮次 | 超限处理 |
|------------|-------------|----------|
| 高频（secretary/coo） | 50 | 自动暂停，通知创建者 |
| 开发（costcodev/architect/opengineer） | 100 | 自动暂停，记录日志摘要 |
| 业务（其他 Agent） | 30 | 自动暂停，通知创建者 |

### 检测方式

每次心跳检查 `in_progress` 任务的会话轮次：
- 接近上限（80%）→ 在心跳日志中标记警告
- 达到上限 → 自动暂停任务，保存当前状态
```

### 4. 📊 上下文控制

```markdown
## 📊 上下文控制（Token 管理）

> **核心规则：避免上下文溢出导致任务中断。**

### 策略

1. **引用代替填塞**：Agent 配置文件中只保留核心规则，详细信息存 docs/ 目录
2. **分块读取**：超大文件分块读取，避免一次性加载
3. **清理过期信息**：每轮对话前清理上一轮的工具输出（仅保留关键结果）
4. **合并查询**：多个 Agent 相同查询由 COO 统一执行后广播
```

---

## 心跳频率分级

```markdown
## ⏱️ 心跳触发频率

- **高频 Agent（secretary / coo）**: 每 10 分钟
- **开发 Agent（costcodev / architect / opengineer / designer）**: 每 15 分钟
- **业务 Agent（projectmanager / productmanager / taobaospecialist / contentspecialist / mediaspecialist / cvexpert / marketanalysis / lawyer）**: 每 15 分钟
```

---

## 全局关键规则（增强版）

```markdown
## ⚠️ 全局关键规则

1. **心跳不打断对话** — 如果用户正在与 Agent 对话，心跳逻辑延后执行
2. **非紧急事项延后汇报** — 等下一轮心跳或用户主动询问时再汇报
3. **发现任务立即执行，不得请示** — 用户在大多数时候不在线，请示=任务卡死
4. **依赖检查前置** — 认领任务前必须检查所有依赖是否已完成
5. **超时自动恢复** — 任务超时自动尝试恢复，3 次失败后升级
6. **轮次限制** — 单任务达上限后自动暂停，防止无限循环
7. **上下文控制** — 引用代替填塞，避免 Token 溢出
```

---

## 各 Agent 类型模板

### 高频 Agent 模板（secretary/coo）

在原有专属心跳清单基础上，增加：
```markdown
### 🛡️ 稳定性保障清单

1. ✅ 超时检测：检查 in_progress 任务是否超时（阈值 60 分钟）
2. ✅ 依赖检查：新任务认领前检查所有 depends_on
3. ✅ 轮次检查：当前任务是否接近 50 轮上限
4. ✅ 上下文检查：HEARTBEAT.md/AGENTS.md 文件大小是否 < 5KB
```

### 开发 Agent 模板（costcodev/architect/opengineer/designer）

```markdown
### 🛡️ 稳定性保障清单

1. ✅ 超时检测：检查 in_progress 任务是否超时（阈值 120 分钟）
2. ✅ 依赖检查：新任务认领前检查所有 depends_on
3. ✅ 轮次检查：当前任务是否接近 100 轮上限
4. ✅ 编译/测试检查：如有自动化测试，确认通过
```

### 业务 Agent 模板（其他 Agent）

```markdown
### 🛡️ 稳定性保障清单

1. ✅ 超时检测：检查 in_progress 任务是否超时（阈值 90 分钟）
2. ✅ 依赖检查：新任务认领前检查所有 depends_on
3. ✅ 轮次检查：当前任务是否接近 30 轮上限
4. ✅ 输出质量检查：确认最近产出符合质量标准
```

---

## 实施说明

1. 此模板由 COO（陆怀瑾）编制，经 Vincent 审阅批准后实施
2. 模板中的 agent_id 需替换为各 Agent 的实际标识
3. 无需移除各 Agent 原有的专属心跳清单，只需追加稳定性保障清单
4. 修改后的文件需提交到 EnterpriseArchitect git 仓库