From f793da91f0cfd5ba5b8a2d125a87b36e0e28cb89 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=99=86=E6=80=80=E7=91=BE=20=28COO=29?= Date: Mon, 22 Jun 2026 21:46:03 +0800 Subject: [PATCH] =?UTF-8?q?BIZ-13:=20=E8=BF=90=E8=A1=8C=E7=A8=B3=E5=AE=9A?= =?UTF-8?q?=E6=80=A7=E4=BF=9D=E9=9A=9C=E8=A7=84=E8=8C=83=20v1.0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 涵盖：禁止请示规则、心跳监控超时恢复、429限流令牌桶、唤醒机制、Token溢出防护、监控告警矩阵 --- specs/BIZ-13_运行稳定性保障规范_v1.0.md | 242 ++++++++++++++++++++++++ 1 file changed, 242 insertions(+) create mode 100644 specs/BIZ-13_运行稳定性保障规范_v1.0.md diff --git a/specs/BIZ-13_运行稳定性保障规范_v1.0.md b/specs/BIZ-13_运行稳定性保障规范_v1.0.md new file mode 100644 index 0000000..f64ae39 --- /dev/null +++ b/specs/BIZ-13_运行稳定性保障规范_v1.0.md @@ -0,0 +1,242 @@ +# 智能体运行稳定性保障规范 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（陆怀瑾）。 \ No newline at end of file