重试策略 - Zeus

Zeus 在消息处理的各个环节提供错误捕获和重试机制，确保流式传输的可靠性和用户体验的连续性。

Backend Error Handling

错误分类

错误类型	检测条件	SSE 事件	用户提示
认证错误	身份验证失败	`error` (Unauthorized)	重定向到登录
速率限制	Rate limit exceeded	`error` (RateLimited)	提示稍后重试
输入长度超限	Range of input length / InvalidParameter	`error`	建议缩短输入
上下文窗口溢出	context length / token limit	`error`	建议开启新会话
通用异常	其他所有 Exception	`error`	包含 traceback 详情

所有错误均通过 SSE 的 error 事件类型返回给前端，包含 error_code 和 details 字段。

Frontend Error Handling

HTTP 状态码处理

HTTP 状态码	含义	处理方式
401	未授权	重定向到登录页
403	信用额度不足	Toast 提示充值
503	后端未启动	连接错误提示
504	请求超时	超时提示

流错误处理

错误类型	触发条件	处理方式
AbortError	用户主动取消	静默处理，不显示错误
网络断开	连接中断	提示网络错误
解析错误	SSE 数据格式异常	记录日志，尝试恢复

Retry Strategy

自动重试

当遇到可恢复错误时，系统使用指数退避策略自动重试：

配置	值
最大重试次数	3 次
初始等待	1s
退避倍数	2x
最大等待	8s

不重试的错误

以下错误类型不会触发自动重试：

认证错误（401）— 需要用户重新登录
信用额度不足（403）— 需要用户充值
用户主动取消（AbortError）— 用户意图明确

Fallback & Degradation

Event Persistence 降级

RealtimeEventSaver 在持久化失败时的降级策略：

阶段	行为
正常	批量写入 PostgreSQL（3 个事件/批，100ms 间隔）
重试	指数退避重试，最多 3 次
降级	写入 LocalStorage 备份
恢复	下次加载时从 LocalStorage 回写服务器

Timeout 保护

超时项	默认值	说明
Agent 最大执行时长	7200s (2h)	FastAPI 单次调用上限
MCP 服务器	1800s (30min)	每个 MCP 服务器的连接超时
HITL 工具审批	可配置	每个工具独立设置
LangGraph 递归限制	999	Agent 循环的最大迭代次数