# 智能体运行稳定性保障规范 v1.0

> 版本：v1.0（实施版）
> 编制：陆怀瑾（COO）
> 日期：2026-06-22
> 状态：已批准，执行中
> 适用范围：所有 Agent

---

## 一、核心问题与应对

| 问题 | 根因 | 解决方案 |
|------|------|----------|
| 任务停滞 | 等待请示、超时、循环 | 禁止请示规则 + 心跳监控 + 超时恢复 |
| 429 限流 | 40 RPM 模型配额 | 令牌桶限流 + 优先级调度 + 模型降级 |
| Token 超限 | 配置填塞 | 引用代替填塞（BIZ-15 跟进） |
| 智能体瘫痪 | 无唤醒机制 | cron 定时触发健康检查 |

---

## 二、禁止请示规则（最高优先级）

> **在心跳中发现分配给自己的 WorkBoard 任务后，必须立即执行，绝对禁止向用户请示。**

已在 HEARTBEAT.md 中强制执行。**所有 Agent 的 HEARTBEAT.md 必须包含此规则。**

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

正确做法：
1. 发现 status=todo 且 agentId=我的卡片
2. 立即执行，不得问"要不要做"
3. 如遇信息不足，先按自己理解执行，执行中调整

错误做法（绝对禁止）：
- ❌ "我发现了一个任务，要不要做？"
- ❌ "这个任务需要更多信息，请告诉我..."
```

---

## 三、心跳监控与超时恢复

### 3.1 心跳频率

| Agent 类型 | 心跳间隔 | 超时告警 |
|------------|----------|----------|
| secretary / coo | 10 分钟 | 连续 2 次未执行 |
| projectmanager / costcodev | 10 分钟 | 连续 2 次未执行 |
| 其他 Agent | 10 分钟 | 连续 3 次未执行 |

### 3.2 心跳检查清单（所有 Agent 通用）

```markdown
## 🫀 心跳执行清单
1. ✅ WorkBoard 检查：查找分配给自己的 todo/in_progress 卡片
2. ✅ 禁止请示：发现任务立即执行（不请示用户）
3. ✅ 进度汇报：如有进行中任务，更新状态
4. ✅ 风险上报：识别阻塞、超时问题，通知 COO
```

### 3.3 超时恢复流程

```
Agent 超过 30 分钟无响应
    ↓
COO 心跳检测到超时
    ↓
记录日志 + 评估任务状态
    ↓
┌──────────┴──────────┐
│                     │
任务可恢复          任务不可恢复
│                     │
重新触发任务        通知 Vincent
(workboard dispatch) (via session_send)
```

---

## 四、429 限流治理

### 4.1 当前配额与监控

| 模型 | RPM 限制 | 建议预留 |
|------|----------|----------|
| 主模型 | 40 | 保留 10 RPM 给紧急任务 |
| 备用模型 | 40 | 满 35 RPM 时切换 |

### 4.2 令牌桶限流策略

```
每个 Agent 独立的令牌桶:
- 容量：按 Agent 优先级分配
- COO/secretary: 8 RPM
- 开发 Agent: 6 RPM  
- 业务 Agent: 4 RPM
- 预留池: 10 RPM (紧急任务)

令牌桶耗尽 → 自动降级到备用模型或排队
```

### 4.3 优先级调度

| 优先级 | 适用场景 | 处理方式 |
|--------|----------|----------|
| P1 紧急 | Vincent 直接指令 | 立即可用预留池 |
| P2 高 | 阻塞性任务、风险告警 | 优先分配令牌 |
| P3 正常 | 日常任务 | 正常排队 |
| P4 低 | 后台优化、报告生成 | 低峰期执行 |

### 4.4 模型降级链

```
主模型 (qwen3.5-397b) RPM 不足
    ↓
备用模型 (deepseek-v4-pro)
    ↓
等待 + 指数退避重试 (1s → 2s → 4s → 8s)
    ↓
3 次重试后仍失败 → 记录日志，通知 COO
```

### 4.5 请求合并优化

| 优化项 | 当前做法 | 优化后 |
|--------|----------|--------|
| WorkBoard 轮询 | 每个 Agent 独立轮询 | COO 统一轮询，广播结果 |
| 重复检索 | 多个 Agent 重复查同一文档 | 缓存关键查询结果（5 分钟 TTL） |
| 连续调用 | 无间隔连续调用 API | 最小间隔 500ms |

---

## 五、唤醒机制

### 5.1 Cron 定时唤醒

```yaml
# COO 健康检查唤醒
cron:
  schedule: "*/5 * * * *"  # 每 5 分钟
  action: health_check
  targets:
    - 检查所有 Agent 最后活跃时间
    - 超过 15 分钟无活动 → 触发唤醒消息
    - 超过 30 分钟无活动 → 通知 Vincent
```

### 5.2 唤醒消息模板

```markdown
## 🔔 唤醒检查

距上次活跃时间：{elapsed} 分钟
当前任务状态：{status}
是否存在阻塞：{blocked}

系统自动唤醒，请确认状态。
```

### 5.3 自唤醒规则

每个 Agent 在 HEARTBEAT.md 中配置：

```
如果距上次心跳超过 2 个周期（20 分钟）：
→ 自动重新评估任务状态
→ 如有待办，立即执行
→ 如无待办，确认存活
```

---

## 六、上下文/Token 溢出防护

### 6.1 配置文件大小限制

| 文件 | 最大行数 | 超标处理 |
|------|----------|----------|
| AGENTS.md | 200 | 移到 docs/agent-roster.md |
| SOUL.md | 80 | 提取模块化引用 |
| TOOLS.md | 100 | 索引化（不填塞参数） |
| HEARTBEAT.md | 60 | 精简检查清单 |
| MEMORY.md | 150 | 定期归档旧条目 |

### 6.2 运行时监控

```
Token 使用量达到 80%
    ↓
自动清理上下文
    ↓
仍超 90%
    ↓
重启会话
```

---

## 七、监控告警矩阵

| 指标 | 警告阈值 | 严重阈值 | 通知对象 |
|------|----------|----------|----------|
| Agent 无响应 | > 15 min | > 30 min | 警告 → COO，严重 → Vincent |
| 429 错误率 | > 5% | > 20% | COO |
| Token 使用量 | > 80% | > 95% | 该 Agent |
| 任务积压 | > 5 pending | > 10 pending | COO |
| 任务超时 | > 24h in_progress | > 48h | 警告 → Agent，严重 → Vincent |

---

## 八、实施步骤

### 阶段 1：即刻生效（今日）
- [x] 禁止请示规则 → 已在各 Agent HEARTBEAT.md 中落实
- [ ] 心跳频率统一为 10 分钟
- [ ] COO 端健康检查 cron 配置

### 阶段 2：本周完成
- [ ] 令牌桶限流配置（按 Agent 分配 RPM）
- [ ] 模型降级链配置
- [ ] 告警规则上线

### 阶段 3：持续优化
- [ ] 监控面板搭建
- [ ] 自动重启恢复
- [ ] 请求合并优化

---

## 九、交付物清单

- [x] 运行稳定性保障规范（本文档）
- [ ] HEARTBEAT.md 模板更新（含禁止请示 + 自唤醒规则）
- [ ] COO 端 cron 健康检查任务
- [ ] 令牌桶限流配置
- [ ] 告警规则配置

---

> 本规范自批准之日起生效。执行中如遇问题，联系 COO（陆怀瑾）。