陆怀瑾 (COO)
242 lines
6.1 KiB
Markdown
242 lines
6.1 KiB
Markdown
# 智能体运行稳定性保障规范 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（陆怀瑾）。 |