# BIZ-13 智能体运行稳定性保障方案

> 版本：v1.1  
> 编制：陆怀瑾（COO）  
> 日期：2026-06-22  
> 状态：Phase 1 执行中（Vincent 已审阅同意）

---

## 一、目标

解决智能体运行中的两大核心问题：
1. **任务停滞**：智能体未完成任务便停滞不前
2. **429 限流**：API 速率限制（当前 40 RPM）导致任务延迟

确保智能体系统稳定、可靠、持续运行。

---

## 二、任务停滞问题分析

### 2.1 根因分析

| 根因 | 表现 | 发生频率 |
|------|------|----------|
| 超时无响应 | 执行到某一步后卡住，无输出 | 高 |
| 依赖缺失 | 等待前置条件，但条件永不满足 | 中 |
| 无限循环 | 反复执行相同逻辑，无进展 | 中 |
| 上下文溢出 | Token 超限，无法继续 | 低 |
| 工具调用失败 | 工具返回错误，未处理 | 中 |
| 等待用户确认 | 错误地等待人类输入 | 高 |

### 2.2 典型案例

```
案例 1：等待用户确认
问题：Agent 发现任务后，向用户请示"要不要做"
影响：用户不在线时，任务卡死数小时
对策：HEARTBEAT.md 明确规定"禁止请示"

案例 2：依赖循环等待
问题：Agent A 等 Agent B，Agent B 等 Agent A
影响：双方永远无法推进
对策：依赖图检测 + 超时自动降级

案例 3：工具调用失败未处理
问题：工具返回错误，Agent 未检查，继续执行
影响：后续步骤全部失败
对策：强制错误检查 + 重试机制
```

---

## 三、任务停滞解决方案

### 3.1 心跳超时检测

**机制**：每个 Agent 配置 HEARTBEAT.md，定期执行检查清单

**超时阈值**：
- 高频 Agent（secretary/coo）：10 分钟
- 开发 Agent：15 分钟
- 业务 Agent：15 分钟

**超时处理**：
```
检测到超时
    ↓
检查任务状态
    ↓
┌─────┴─────┐
│           │
有进展     无进展
    │           │
延长超时   自动恢复
(通知 COO)  (重新调度)
```

### 3.2 依赖检查前置

**规则**：任务开始前，检查所有依赖是否满足

```python
def check_dependencies(task):
    for dep in task.depends_on:
        if not is_complete(dep):
            return False, f"依赖 {dep} 未完成"
    return True, "依赖满足"

# 任务启动前强制检查
ready, reason = check_dependencies(task)
if not ready:
    set_status(task, "blocked", reason)
    notify_co()
```

### 3.3 最大轮次限制

**规则**：单任务最大执行轮次限制

| Agent 类型 | 最大轮次 | 超限处理 |
|------------|----------|----------|
| 高频 Agent | 50 | 自动暂停，通知 COO |
| 开发 Agent | 100 | 自动暂停，记录日志 |
| 业务 Agent | 30 | 自动暂停，通知创建者 |

### 3.4 上下文控制

**策略**：引用代替填塞

```
错误做法：
- AGENTS.md 中嵌入全部 Agent 信息（3000+ tokens）

正确做法：
- AGENTS.md 只保留核心协作协议
- 详细信息存 docs/agent-roster.md
- 通过引用链接访问
```

**上下文清理**：
- 每轮对话前清理过期信息
- 工具调用结果仅保留必要部分
- 长文档分块读取

---

## 四、429 限流问题分析

### 4.1 当前限制

| 模型 | RPM 限制 | 当前使用 | 风险等级 |
|------|----------|----------|----------|
| 主模型 (qwen3.5-397b) | 40 | ~30 | 中 |
| 备用模型 (deepseek-v4-pro) | 40 | ~10 | 低 |

### 4.2 限流影响

```
触发 429 限流
    ↓
任务延迟执行
    ↓
┌─────┴─────┐
│           │
等待恢复   任务失败
(分钟级)   (小时级)
```

---

## 五、429 限流解决方案

### 5.1 请求队列 + 优先级调度

**队列设计**：
```
请求队列（FIFO + 优先级）
┌─────────────────────────────────────┐
│ 优先级 1 (紧急): Vincent 直接任务    │
│ 优先级 2 (高):   阻塞性任务          │
│ 优先级 3 (正常): 常规任务            │
│ 优先级 4 (低):   后台优化任务        │
└─────────────────────────────────────┘
         ↓
    令牌桶限流
         ↓
    模型 API
```

**调度算法**：
```python
def schedule_request(request):
    # 1. 加入优先级队列
    priority_queue.add(request)
    
    # 2. 检查令牌桶
    if token_bucket.has_tokens():
        token_bucket.consume()
        send_to_api(request)
    else:
        # 3. 等待或降级
        if request.priority >= 2:
            wait_for_token()
        else:
            fallback_to_backup_model(request)
```

### 5.2 多模型负载均衡

**模型池**：
| 模型 | 用途 | 优先级 |
|------|------|--------|
| qwen3.5-397b | 主模型，复杂推理 | 高 |
| deepseek-v4-pro | 备用模型，常规任务 | 中 |
| 本地模型 | 简单任务，成本优化 | 低 |

**负载均衡策略**：
```
主模型可用且 RPM 充裕
    ↓
使用主模型
    ↓
主模型 RPM 不足
    ↓
切换到备用模型
    ↓
备用模型也不足
    ↓
降级到本地模型或等待
```

### 5.3 智能重试机制

**指数退避 + Jitter**：
```python
def retry_with_backoff(api_call, max_retries=3):
    for i in range(max_retries):
        try:
            return api_call()
        except RateLimitError:
            delay = (2 ** i) * 1000 + random(0, 1000)  # ms
            sleep(delay)
    
    raise Exception("重试失败")
```

**重试策略**：
| 重试次数 | 延迟时间 | 说明 |
|----------|----------|------|
| 第 1 次 | 1-2 秒 | 快速重试，应对短暂波动 |
| 第 2 次 | 2-4 秒 | 指数退避 |
| 第 3 次 | 4-8 秒 | 切换备用模型 |

### 5.4 请求合并与缓存

**合并策略**：
```
错误做法：
- 每个 Agent 独立轮询 WorkBoard（40 RPM × N Agent）

正确做法：
- COO 统一轮询，广播结果
- 减少轮询频率（10 分钟 → 15 分钟）
- 合并相似查询
```

**缓存策略**：
```
查询请求
    ↓
检查缓存
    ↓
┌─────┴─────┐
│           │
缓存命中   缓存未命中
    │           │
返回缓存   调用 API → 更新缓存
```

**缓存有效期**：
| 数据类型 | 有效期 | 说明 |
|----------|--------|------|
| WorkBoard 状态 | 5 分钟 | 高频变化 |
| Agent 配置 | 1 小时 | 低频变化 |
| 知识库内容 | 1 天 | 基本不变 |
| 用户信息 | 1 天 | 基本不变 |

---

## 六、监控与告警

### 6.1 监控指标

| 指标 | 阈值 | 告警级别 |
|------|------|----------|
| 任务停滞时长 | > 1h | 警告 |
| 任务停滞时长 | > 4h | 严重 |
| 429 错误率 | > 5% | 警告 |
| 429 错误率 | > 20% | 严重 |
| Agent 响应延迟 | > 30s | 警告 |

### 6.2 告警流程

```
监控系统检测到异常
    ↓
记录日志
    ↓
┌─────┴─────┐
│           │
警告        严重
    │           │
通知 COO   通知 Vincent
```

### 6.3 监控工具

- Prometheus + Grafana（基础设施监控）
- 自定义 Agent 健康检查脚本
- WorkBoard 诊断工具

---

## 七、实施步骤

### 阶段 1：心跳机制落地（本周）
- [x] 更新所有 Agent 的 HEARTBEAT.md（15/15 Agent 已完成）
- [x] 已创建分步实施子任务（BIZ-24 ~ BIZ-28，5个子任务）
- [ ] 配置定时任务（10/15 分钟）→ BIZ-25，已分派 opengineer 严维序
- [ ] 测试超时检测 → BIZ-24 执行中

### 阶段 2：限流优化（下周）
- [ ] 实现请求队列
- [ ] 配置多模型负载均衡
- [ ] 实现智能重试

### 阶段 3：监控体系（持续）
- [ ] 搭建监控面板
- [ ] 配置告警规则
- [ ] 定期健康检查

---

## 八、风险与对策

| 风险 | 影响 | 对策 |
|------|------|------|
| 心跳任务本身卡死 | 监控失效 | 独立监控进程 |
| 请求队列过长 | 延迟增加 | 动态扩容 |
| 缓存数据过期 | 决策错误 | 设置 TTL + 主动刷新 |

---

## 九、交付物清单

- [ ] HEARTBEAT.md 更新模板
- [ ] 请求队列实现代码
- [ ] 多模型负载均衡配置
- [ ] 智能重试机制实现
- [ ] 监控面板 URL
- [ ] 告警规则配置

---

> ⚠️ 本方案需 Vincent 审阅后方可实施。审阅前不修改任何 Agent 配置文件。