初始提交：多智能体协作体系总体方案及各子项目详细方案

- BIZ-11: 组织架构与岗位职责体系建设方案 - BIZ-12: 文档存储、命名与索引规范方案 - BIZ-13: 运行稳定性保障方案（任务停滞与429速率限制） - BIZ-14: 知识库体系建设方案 - BIZ-15: 配置文件持续优化机制方案所有方案均为初稿，待刘总审阅。
2026-06-22 02:45:51 +08:00
commit 38b21d7adb
6 changed files with 1966 additions and 0 deletions
@@ -0,0 +1,345 @@
+# BIZ-13 智能体运行稳定性保障方案
+
+> 版本：v1.0  
+> 编制：陆怀瑾（COO）  
+> 日期：2026-06-22  
+> 状态：待审阅
+
+---
+
+## 一、目标
+
+解决智能体运行中的两大核心问题：
+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：心跳机制落地（本周）
+- [ ] 更新所有 Agent 的 HEARTBEAT.md
+- [ ] 配置定时任务（10 分钟）
+- [ ] 测试超时检测
+
+### 阶段 2：限流优化（下周）
+- [ ] 实现请求队列
+- [ ] 配置多模型负载均衡
+- [ ] 实现智能重试
+
+### 阶段 3：监控体系（持续）
+- [ ] 搭建监控面板
+- [ ] 配置告警规则
+- [ ] 定期健康检查
+
+---
+
+## 八、风险与对策
+
+| 风险 | 影响 | 对策 |
+|------|------|------|
+| 心跳任务本身卡死 | 监控失效 | 独立监控进程 |
+| 请求队列过长 | 延迟增加 | 动态扩容 |
+| 缓存数据过期 | 决策错误 | 设置 TTL + 主动刷新 |
+
+---
+
+## 九、交付物清单
+
+- [ ] HEARTBEAT.md 更新模板
+- [ ] 请求队列实现代码
+- [ ] 多模型负载均衡配置
+- [ ] 智能重试机制实现
+- [ ] 监控面板 URL
+- [ ] 告警规则配置
+
+---
+
+> ⚠️ 本方案需 Vincent 审阅后方可实施。审阅前不修改任何 Agent 配置文件。