问题域/PD-03

容错与重试

Fault Tolerance & Retry

LLM 调用失败、响应截断、格式错误时如何检测、恢复、重试。Agent 系统的鲁棒性取决于容错设计。

子问题

1.API 调用失败：网络超时、速率限制、服务不可用

2.响应格式错误：JSON 解析失败、缺少必要字段

3.响应截断：输出超过 max_tokens 被截断

4.幻觉检测：LLM 生成不存在的工具名或参数

5.级联失败：一个 Agent 失败导致整个流程崩溃

6.多 Provider tool_calls.arguments 返回 JSON 字符串而非字典导致框架解析失败

7.双层重试嵌套的最大重试次数需要预算意识（外层×内层可能指数膨胀）

8.交易日会话重试时需要重建 system_prompt（含当日价格），不能复用失败会话的上下文

9.外部金融数据 API 的批量请求需要批次间延迟防止速率限制

10.LLM连续生成无效代码导致Agent陷入错误→重试→再错误的死循环

11.LLM反复返回观察而不执行动作导致Agent停滞消耗token无进展

12.错误爆发守卫解除后立即重新触发需要冷却期保护

13.无动作跟进的签名停滞检测：相同返回值+日志重复说明LLM陷入循环

14.事件队列中低优先级自循环事件阻塞高优先级玩家输入

15.Reaction tracker 状态转换时的清除时机：过早清除导致重试计数丢失，过晚清除导致误升级

16.轮询间隔与 escalateAfter 精度不匹配：30s 轮询无法精确触发 15s 的升级阈值

17.send-to-agent 消息在 tmux 中被截断：超过 200 字符的修复指令需要 buffer 降级

18.流式工具调用被中断时如何保留已生成的部分内容

19.工具组未激活时如何提示 Agent 正确的激活方法

20.中间件容错逻辑如何与核心容错层协同工作

21.异步协程函数和同步函数的异常处理路径差异

22.LangGraph operator.add reducer 的计数器溢出：长会话中计数器只增不减，跨轮次复用 state 时需要手动重置

23.fallback 节点的 LLM 调用本身也可能失败：降级路径中的 LLM 调用缺少二次降级保护

24.迭代超限后半成品产物的自动收集与兜底提交：Agent未完成任务但沙箱中已有部分产物

25.API错误与评估失败的区分处理：前者值得重试，后者重试无意义

26.经济感知重试：重试消耗token预算，破产后必须停止重试

27.配置热更新时相同配置反复失败需要停止重试，配置变更需要重置计数：用 (count, config_hash) 元组追踪

28.子进程客户端连接耗时不应持有全局锁：锁外连接 + 锁内原子替换避免阻塞查询路径

29.Agent 查询异常的完整现场保存：日志可能被截断，需要将 traceback+request+agent_state 写入临时 JSON 文件

30.参数递减方向选择：context受限时应减少output而非增加，避免加剧溢出

31.结构化输出多维完整性评估：单一长度检查不足以判断YAML/JSON计划的可用性

32.LLM推理服务返回空响应（非异常）需要与真正的API错误区分处理

33.渐进截断的收缩比例选择：过大（0.9）收敛慢浪费重试次数，过小（0.3）丢失过多信息

34.多endpoint随机选择的循环次数与提前退出条件不一致（range(8) vs attempt==4）

35.多 Provider 雪崩：一个 provider 持续失败拖慢整个系统

36.LLM 输出结构验证：JSON 字段类型/枚举值不符合 Agent 预期

37.配置错误前移：YAML 配置缺失或类型错误在运行时才暴露

38.流式响应已开始推送后发生 token 超限：无法返回 HTTP 错误码，必须在 async generator 内部实现 fallback

39.Embedding 批量处理中部分文档维度不一致：混合维度导致 FAISS 索引构建失败，需要按众数过滤

40.多 Provider 异构错误格式：7 种 Provider 的 token 超限错误消息格式不同，需要通用检测策略

41.跨进程沙箱寻址：不同 worker 进程需要定位同一 thread 的沙箱而无共享内存

42.容器端口漂移：容器重启后端口变化导致持久化的 URL 失效

43.信号处理器链冲突：自定义 SIGTERM 处理器可能覆盖框架（FastAPI/Uvicorn）的关闭逻辑

44.空闲资源回收精度：守护线程轮询间隔（60s）与实际空闲超时（600s）的精度权衡

45.悬空工具调用：用户中断或网络异常导致 AIMessage 的 tool_calls 缺少对应 ToolMessage

46.子 Agent 并发过载：LLM 单次响应生成过多并行 task 调用超出线程池容量

47.LLM 返回的实体名与系统内部名不完全匹配（大小写、缩写、多余标点）需要模糊匹配容错

48.多轮迭代中 LLM 的过滤指令可能因路径格式不一致导致所有元素被误过滤

49.API 参数命名在不同模型版本间不兼容（max_tokens vs max_completion_tokens）

50.迭代检索的成本效益递减：后续轮次的置信度增益可能不值得额外的 token 消耗

51.asyncio.CancelledError 在 session.commit() 期间被触发导致写入丢失，需要 rollback+递归重试

52.CancelledError 语义模糊：用户主动取消与系统异常取消需要通过 exc.args 区分处理

53.Alembic 迁移 schema 不一致时需要渐进降级（逐版本回退）而非直接回退到 base

54.SSE 慢消费者阻塞事件广播：需要超时丢弃 + 死亡队列清理防止整体拖慢

55.双层 tenacity 装饰器叠加时外层捕获内层已处理的异常：需要 retry_if_exception 精确分流

56.存储层连接池耗尽：Redis/Neo4j 高并发下连接池满导致操作阻塞

57.Worker 卡死检测：LLM 调用无响应时需要外部 HealthCheck 强制终止

58.重试装饰器叠加冲突：多层装饰器（retry + embedding_wrapper）导致参数注入冲突

59.embedding 批量处理中单批失败需要零向量填充保证维度一致性，避免下游向量索引构建失败

60.LLM 结构化输出的字段名拼写不稳定（如 retrieval 拼成 retrival），需要多候选字段名容错

61.图数据库连接池耗尽与连接失效需要差异化退避策略：池耗尽等更久（等归还），连接失效短退避（快重连）

62.多阶段迭代检索中单阶段 LLM 失败应 continue 而非中断，最终兜底返回初始检索结果

63.LLM 输出大小写不一致导致 schema 字段匹配失败

64.LLM 输出标签对不完整（缺少闭合标签或开始标签）

65.LLM 输出 JSON 含行内注释（# 或 //）导致解析失败

66.LLM 输出 JSON 含非标准引号（单引号、三引号）

67.工具调用命令中的转义字符错误（\f \a 等被 Python 解释为控制字符）

68.双层重试嵌套导致最大重试次数指数膨胀（外层×内层）需要预算控制

69.PDF 单页损坏导致 pypdfium2 import_pages 异常：需要逐页跳过而非整文档失败

70.LLM 推理模型返回 thinking tags 包裹的输出：需要剥离 <think>...</think> 后再解析 JSON

71.多进程 PDF 渲染子进程卡死：SIGTERM 不响应时需要 SIGKILL 强制终止并清理资源

72.json_repair 与 json.loads 的选择：LLM 输出常含非标准 JSON（尾逗号、单引号），json_repair 自动修复

73.Windows 环境不支持 ProcessPoolExecutor 的 fork：需要自动降级为单进程模式

74.流式响应无法中途切换 Provider：streaming 模式下 failover 只能在开始前选择，中途错误无法透明重试

75.Retry-After 格式碎片化：不同 Provider 用 ms/s/min 不同单位和 header/body 不同位置返回重试提示

76.Mutex 中毒恢复：panic 导致 Mutex poisoned 后断路器状态需要 into_inner() 降级恢复

77.断路器参数硬编码：阈值和冷却时间为编译期常量，无法运行时动态调整

78.AuthProfile 冷却窗口内重试导致恢复时间无限延长：需要冷却窗口不可变性保护

79.主模型冷却期间长期停留在降级模型：需要探测恢复机制在冷却接近到期时主动尝试

80.工具调用乒乓循环：两个工具交替调用形成 A→B→A→B 模式，单工具重复检测无法捕获

81.探测请求风暴：多个并发会话同时探测同一 Provider 导致再次触发速率限制

82.渐进截断的两种粒度选择：按消息边界截断（compress_research）vs 按字符截断（final_report），适用场景不同

83.多 Provider 异构异常类型检测：同一语义错误在 OpenAI/Anthropic/Gemini 中的异常类名和消息格式完全不同

84.并行子 Agent 全部失败时的兜底：asyncio.gather 的异常传播需要在外层 try-catch 中统一处理

85.模型 token 限制映射表维护：新模型发布后映射表过期导致无法计算截断阈值

86.锁文件创建与父目录锁检查之间的竞态窗口：需要 double-check 协议防止并发覆盖

87.RM 操作递归子目录锁定的批量并发度控制：过高并发可能耗尽文件系统 IO

88.事务状态机中 RELEASING 阶段的部分释放：锁释放过程中崩溃导致部分锁泄漏

89.LLM 输出含推理模型 thinking tags 导致 JSON 提取失败

90.多模态批量并发中单项失败的隔离与降级

91.外部 CLI 工具多命令名兼容（libreoffice vs soffice）

92.文本文件多编码兼容（utf-8/gbk/latin-1/cp1252）

93.Agent 工具调用无限循环：LLM 反复生成相同 tool_calls 消耗 token 无进展

94.分布式锁持有者崩溃后锁无法释放：需要自动续期+最大生命周期双重保护

95.NestJS 模块初始化时外部依赖未就绪：Redis/BullMQ 连接延迟导致启动失败

96.流式 AsyncGenerator 中断后需要从头重试：普通 retry 无法处理 yield 中间状态

97.DOM 选择器漂移：页面动态渲染导致 LLM 推理出的 XPath 在执行时失效

98.缓存 replay 选择器过期：缓存的操作序列因页面结构变化无法原样回放

99.网络请求未完成时 DOM 不稳定：操作执行前页面仍有 inflight 请求导致元素未就绪

100.自愈与超时预算冲突：selfHeal 的 LLM 重新推理可能耗尽操作的超时预算

101.HTTP 200 伪成功：API 返回 200 状态码但 body 含错误信息，需解析 JSON 检测

102.多供应商数据格式不一致：降级后返回的 CSV/JSON 格式差异影响下游解析

103.批量计算与逐日计算的结果精度差异：stockstats bulk 模式与逐日模式可能因数据窗口不同产生微小数值差异

104.RL 批量轨迹中单条评估失败不应中断整个 batch 的梯度更新

105.Agent 生成的 bbox 坐标可能不合法（非 JSON、负数、维度不足），需要多层验证

106.多轮交互中上下文持续增长超过模型最大长度，需要主动停用而非被动崩溃

107.并行评估中单个评估函数可能陷入死循环，线程池无法 kill 需要进程池隔离

108.LLM 评估输出格式不稳定（大小写、缺标签），解析失败应触发重试而非直接判负

109.Python import lock 与 asyncio 事件循环死锁：多线程导入模块时 import lock 阻塞事件循环

110.跨 Provider 模型名不兼容：同一功能在不同 Provider 使用不同 model_id 需要映射表

111.本地 Agent 冷启动延迟：进程内 Agent 启动需要时间，客户端连接需要差异化重试策略

112.可选组件缺失不应阻塞核心功能：Embedding/VDB 未配置时 Agent 应降级运行而非崩溃

113.数据库连接池陈旧连接：连接池中的连接可能因服务器重启、网络抖动而失效，需要识别 'bad connection'、'gone away' 等错误并重试

114.数据库内部竞态：CREATE DATABASE 后服务器内存目录未及时更新（'Unknown database'）、信息模式查询时根值未初始化（'no root value found'），需要短时间重试等待初始化完成

115.锁文件陈旧：进程崩溃后遗留的锁文件导致后续操作失败，需要检测陈旧锁（如 5 分钟以上）并自动清理

116.连接池耗尽：高并发下连接池满导致操作阻塞，需要配合重试机制和连接池配置（MaxOpenConns、ConnMaxLifetime）缓解

117.服务器冷启动：首次连接时服务器未启动，需要自动启动服务器并重试连接（auto-start 模式）

118.Hook exit code 语义：exit 0 降级 vs exit 2 阻断 vs exit 1 静默，不同 exit code 对宿主程序行为的影响

119.多 Provider 降级时的会话上下文保持：切换 Provider 后 conversationHistory 如何共享

120.stderr 抑制：Hook 场景下 stderr 输出会被宿主程序捕获显示为错误 UI，需要重定向到日志文件

121.异步 API 轮询超时：Provider 返回 taskID 后需要轮询状态，轮询间隔和最大等待时间的平衡

122.压缩反效果检测：图片压缩后文件反而变大（如 PNG 压缩为 JPEG），需要对比原始大小决定是否采用

123.多 Provider 错误格式统一：不同 Provider 的 HTTP 错误响应 JSON 结构不同，需要统一映射到 GenerateError

124.拦截器自身异常导致错误处理失败：on_error 拦截器崩溃时主异常信息丢失

125.自定义过滤器签名不兼容：用户传入的 callable filter 参数数量与预期不匹配需要 TypeError 降级

126.同步/异步拦截器混用：注册表需要同时支持 sync 和 async 拦截器函数

127.多 API Key 中单个 Key 被限流时需要自动轮转到其他 Key 并临时黑名单失败 Key

128.并发请求即使未超过 RPM 限制也可能因突发触发限流，需要时间错开（stagger）而非纯并发控制

129.批量 AI 调用需要同时满足 input token 和 output token 双重约束进行分批

130.异步生成 API 的超时时间不可预知，服务端 estimatedTime 可能动态变化需要自适应延长

131.API 响应格式碎片化：同一接口可能返回标准 JSON、SSE data: 格式、GPT choices 格式或 markdown 图片链接

132.多 rank 并发下载同一文件导致数据损坏：需要跨进程文件锁 + double-check 模式

133.训练恢复时 dataloader 位置偏移导致数据重复或遗漏：需要 advance-by-1 跳过已处理数据

134.旧 checkpoint 缺少新版本模型字段导致 load_state_dict 失败：需要向后兼容补丁函数

135.Python GC 扫描导致 GPU 训练周期性暂停 ~500ms：需要禁用 GC + 手动周期性收集

136.多进程环境中 SIGTERM 重复触发导致 ZMQ socket __del__ 异常

137.父进程崩溃后子 Worker 进程成为孤儿进程无法自动退出

138.进程崩溃前的死亡通知消息可能因输出线程阻塞而发送失败

139.ZMQ LINGER 设置不当导致 shutdown 时 context.term() 无限阻塞

140.多进程 RPC 超时与进程死亡检测的竞态：超时先于 sentinel 触发导致错误信息不准确

141.截断扩容方向选择：应增大 max_tokens 而非缩减 prompt，因为内容已生成到一半

142.主线程与工作线程的超时机制不兼容：signal.SIGALRM 仅限主线程，需要 concurrent.futures 兜底

143.预算熔断的 warn vs abort 模式选择：开发环境宽松告警，生产环境严格中断

144.Cron 任务退避与正常调度间隔的取大值：退避时间不应比正常间隔更短

各项目的解法41 solutions

Signals

横向对比

维度MiroThinkerDeerFlowGPT-ResearcherAI-TraderAIRIAgent-OrchestratorAgentScopeagentic-rag-for-dummiesClawWorkCoPawDeepCodeDeepResearchDeepTutorDeepWikiFastCodeHorizonLangflowLightRAGMemOSMetaGPTMinerUMoltisOpenClawOpenOpenStorylineOpenVikingPageIndexRAG-AnythingReflyStagehandTradingAgentsVRAGValueCellbeadsclaude-memmd2wechat-skillmemUmoyin-creatornanochatvLLMvibe-blog
截断/错误检测finish_reason=="length" 检测截断DanglingToolCallMiddleware 扫描悬挂 tool_callsvisited_urls 跨层去重检测重复DeepSeek 适配器检测 tool_calls.arguments 类型（str vs dict）自动修复滑动窗口检测：5轮内3次错误触发爆发守卫，冷却期5轮LifecycleManager 轮询检测 14 种 SessionStatus 状态转换，inferPriority 按事件类型分级—双计数器检测：iteration_count >= 10 OR tool_call_count > 8，operator.add 自动累加——4维加权评分：section存在性50%+YAML结构20%+末行截断15%+长度15%空响应检测 + OpenAI SDK 三类异常分类 + 内容有效性前缀检查ProviderContextWindowError 检测上下文超限；Pydantic field_validator 检测工具名幻觉流式响应中字符串匹配 3 个 token limit 关键词检查 BadRequestError 消息内容判断参数兼容性；检测 finish_reason 和空响应——InvalidResponseError 检测空响应/无效格式，触发 tenacity 重试—4 种 RepairType 枚举分类：大小写、标签对缺失、特殊字符、JSON 格式LLM 输出用 json_repair 容错解析 + thinking tags 剥离 + 数量一致性验证9 种 CONTEXT_WINDOW_PATTERNS 字符串匹配，优先于其他分类isLikelyContextOverflowError 含中文代理错误检测，Context Overflow 直接 rethrow 不降级is_token_limit_exceeded 按 Provider 分类检测 OpenAI/Anthropic/Gemini 三种错误格式———LLM 输出 JSON 解析失败时触发，无显式截断检测工具调用签名滑动窗口比对检测无限循环，GraphRecursionError 兜底LLM 推理结果通过 Zod schema 验证 + elementId 格式校验 + XPath 映射检查三重检测JSON 响应关键词匹配检测 rate limit，HTTP 200 伪成功识别正则解析 <judge>/<answer>/<search>/<bbox> 标签，解析失败返回 None 触发重试——SDKAgent 检测 prompt is too long 文本 + OpenRouterAgent 滑动窗口截断—LLMCallFilter 多维条件过滤（operation/provider/model/status），三层 try/except 防御TOKEN_BUDGET_EXCEEDED 快速失败不重试 + Error-driven Discovery 从 400 错误自动学习模型限制—ZMQ 帧级 ENGINE_CORE_DEAD 哨兵 + OS 进程 sentinel 双重检测双格式截断检测(OpenAI finish_reason + Anthropic stop_reason) + 尾部50字符重复检测 + 6模式上下文超限匹配
重试/恢复策略max_tokens*1.1 渐进扩容，最多 10 次5 态状态机 FAILED→重新调度搜索源降级链 Tavily→Google→摘要外层重试重建完整会话（含 Agent 和 system_prompt），不累积失败状态—ReactionConfig 声明式配置，send-to-agent 自动重试 + 失败不升级等下轮—无显式重试，orchestrator prompt 指示 LLM 换 query 重搜——参数递减重试：max_tokens逐次减10%/20%，temperature每次-0.15—双层重试：Factory tenacity 指数退避(max=120s) + Provider 1.5^n+random 退避backoff.on_exception 指数退避，max_time=5s参数嗅探式单次重试（非指数退避），失败后立即切换参数名重试——tenacity @retry 装饰器统一范式，10+ Provider 各自配置异常类型和退避参数—双层重试：传输层 tenacity 指数退避 + 语义层渐进式 JSON 修复重试——AuthProfile 冷却状态机 5^n 退避（1min→60min），billing 独立 2^n 退避（5h→24h）四层容错：with_retry 自动重试 + while 渐进截断 + 工具安全包裹 + 优雅终止———无重试，采用 4 级渐进式解析修复替代重试Guard 链式 API 支持指数退避+超时双模式，retryGenerator 支持流式重试selfHeal 自愈：重新捕获页面快照 + LLM 重新推理定位 + 新选择器重试无重试，直接降级到下一个供应商while-loop 最多 20 次无退避重试，异常 catch-continue，耗尽返回 0.0————无内置重试机制，依赖拦截器链的 on_error 钩子由用户实现重试逻辑——无自动重试，进程死亡即全局关闭；请求级错误返回 FinishReason.ERROR截断→max_tokens×1.1扩容重试；429→指数退避(5s×2^n, 上限60s)；上下文超限→快速失败不重试
超时保护@with_timeout(600) 10 分钟execution_future.result(timeout=900s) 15 分钟Semaphore(2) 并发限流LLM 调用 30s 超时 + Tushare API 120s 超时 + MCP 服务 5s 停机超时CancellationToken跨层中断+stop动作清空待执行队列escalateAfter 支持时间字符串（10m/30s/1h），parseDuration 解析后与 firstTriggered 比较无内置超时，依赖工具函数自行实现硬限制替代超时：MAX_ITERATIONS=10 + MAX_TOOL_CALLS=8 双上限双层超时：asyncio.wait_for 120s + ChatOpenAI 内置 max_retries=3asyncio.wait_for 统一超时：MCP 连接 60s，Cron 任务可配置，心跳 120s双重保护：迭代上限800次+时间上限7200秒三重预算：Token 110K上限 + 时间150min + LLM调用100次LLMTimeoutError(408) + embedding request_timeout=30s 配置OpenRouter 60s 超时，Ollama 健康检查 5s 超时自适应行预算控制（按查询复杂度动态调整 6000-12000 行），6 重迭代停止检查—asyncio.wait_for(300s) 工作流级 + 1s SSE 事件发射级双层超时priority_limit_async_func_call 三层超时：Worker(llm×2) → HealthCheck(llm×2+15) → Userconcurrent.futures.wait 30s 超时 + Future.cancel()全局 LLM_API_TIMEOUT=300s，三级优先级：调用参数 > 配置 > 默认ProcessPoolExecutor wait(300s) + SIGTERM→SIGKILL 两阶段终止agent_max_iterations=25 循环上限 + WS 连接池 IDLE_TIMEOUT=55s/MAX_LIFETIME=300sAbortController + setTimeout 双重超时，探测节流 30s 间隔summarize_webpage 使用 asyncio.wait_for 60s 超时，超时返回原始内容—事务层 3600s 超时 + HTTP 层 30s 超时，后台 60s 轮询清理—LibreOffice 转换 60s 超时，MinerU 子进程无显式超时模块初始化 10s 超时，分布式锁 300s 最大生命周期，卡死任务定时巡检createTimeoutGuard 预算制：流程各节点主动检查剩余时间，非 Promise.race 被动超时无显式超时，依赖 requests 默认和 LangGraph recursion_limitPrimeRewardManager 用 asyncio.wait_for(300s) + ProcessPoolExecutor 进程级超时Agent 导入 5s 超时 + HTTP 30s 超时 + 清理 5s 超时，三层超时防护DSN 级超时（连接 5s、读写 10s）+ 重试窗口 30s，双层防护Hook 5min 默认超时 + 队列 3min 空闲超时 + 健康检查 3s 超时 + Windows 平台乘数HTTP Client 30-120s 分层 + ModelScope 异步轮询 120s + 全局可配置 1-300s无显式超时，依赖底层 httpx 客户端的 timeout 配置（transcribe 场景 3x timeout）TaskPoller 动态超时（estimatedTime×2+120s，上限 30min）+ AbortController 60s 请求超时SIGALRM 信号超时 + multiprocessing.Process.kill 双层超时三层超时：握手 5min + 执行 300s + RPC deadline 传播主线程signal.SIGALRM可中断阻塞I/O + 非主线程concurrent.futures线程池超时(默认180s)
优雅降级最后一次仍截断→返回截断结果继续TIMED_OUT 状态 + cancel() 清理breadth 逐层减半 + trim_context 25000 wordsMCP 工具加载失败仅警告不阻断；CSV 兜底；LangChain 版本三层降级导入giveUp暂停Agent等待玩家输入，玩家聊天自动恢复send-to-agent 失败返回 success:false 等下轮重试，不立即升级所有异常转换为 ToolResponse，Agent 可见错误信息fallback_response 汇总压缩上下文+原始检索数据生成最佳答案—MemoryManager 启动失败不阻塞，compact/summary 失败返回空字符串直接函数调用优先，失败fallback到LLM Agent摘要失败时内容×0.7渐进截断至25000字符，Token超限时强制总结已有信息多语言 Prompt fallback 链(zh→cn→en)；safe_parse 返回默认值RAG 失败继续无 RAG 回答，token 超限去上下文重试三级 fallback 链（LLM→embedding+BM25→用户原始选择），每级降低智能提高确定性—组件错误返回 HTTP 200 + error body，允许部分结果；SSE 超时丢弃事件无显式降级方案，重试耗尽后直接抛出异常由上层处理—repair_llm_output 配置开关，OpenAI 关闭修复链，开源模型开启逐页跳过不中断文档 + Worker 优雅关闭 join(timeout) + 批量任务部分完成继续流式模式选最佳非 tripped Provider 直接开始，不做中途重试—compress_research 失败返回错误字符串，supervisor_tools 异常时优雅结束返回已有 notes—json_repair 4 层 JSON 解析降级 + LiteLLM drop_params 参数兼容—批量→逐项降级 + fallback_entity 兜底双层降级递归超限返回部分结果+用户提示，沙箱 CodeInterpreter 失败降级到 runCodewaitForCachedSelector 超时后继续执行；缓存 replay 失败返回 null 回退正常执行三层降级：供应商链降级 + bulk→逐日计算降级 + 异常→错误字符串降级deactivate_batch 按 token 长度主动停用轨迹，active_mask 乘法确保不可逆VDB 惰性初始化返回 None，Agent 自动降级为无知识搜索的 tools-only 模式—Hook 层 exit 0 不阻塞用户 + 版本未知时假设匹配 + 初始化未完成时返回空上下文压缩失败用原图（Warn 级别日志），Provider 创建失败不阻断非图片功能strict=False 模式下拦截器异常静默降级 + 记忆检索 fail-silently 返回空列表processBatched 容错隔离：单批失败不阻塞其他批次，返回 failedBatches 计数 + 部分成功结果—EngineGenerateError 可恢复 vs EngineDeadError 不可恢复两级异常分流DEGRADABLE_NODES白名单7节点 + on_error钩子链 + safe_run装饰器双层降级
重试策略———双层线性退避：内层 API 调用 + 外层交易日会话，delay = base_delay × attempt3次重试，速率限制指数退避min(5s,1s*attempt)+随机200ms，非速率限制150ms固定退避次数限制（retries）+ 时间限制（escalateAfter）双维度，状态转换时清除 tracker无内置重试，通过中间件扩展实现—线性退避 base_delay×attempt，默认 0.5s/1.0s/1.5s，配合 asyncio.wait_for 超时环境变量驱动指数退避（base=0.8, cap=6s），无抖动业务层3次参数递减+API层3次指数退避(2s→4s→8s)三层独立重试：推理层指数退避10次、工具层随机EP轮换5-8次、结果层渐进截断3次tenacity 指数退避，Factory 层 max=5 次，Provider 层 max=3 次Embedding 层通用 Exception 重试，OpenAI 层精确 5 类异常重试——tenacity @retry 配置化：固定等待(2s×10次)用于DB，指数退避(5-60s)用于APItenacity stop_after_attempt(3-5) + wait_exponential，Bedrock 5次其余3次tenacity 装饰器(embedding 4次/DB 3次) + 手动循环(LLM解析 3次) 双模式传输层 3~6 次指数退避，解析层 3 次固定间隔，双层最大 9 次HTTP 层 max_retries=3 + backoff_factor=0.5 指数退避；LLM 层 while 循环 max_retries=3双轨分离：server 固定 2s×1 次 + rate_limit 指数退避 2s-60s×10 次通用 retryAsync 指数退避 + 抖动 + Retry-After 解析，默认 3 次 300ms-30s结构化输出用 with_retry(stop_after_attempt=3)，压缩/报告用 while 循环最多 3 次—纯指数退避 2^attempt 秒，无抖动，max_retries 配置化（默认 2）固定间隔 sleep(1) + max_retries=10，宽泛 except Exception 捕获—guard.retry 支持次数/时间双终止+条件过滤+回调，线性/指数退避可配OpenAI retries=3 递减；Anthropic 最多 5 次；selfHeal 单次重试（非循环）—无退避的立即重试（内网 API 场景），ThreadPoolExecutor(10) 并行独立重试指数退避 0.2s→1.0s 上限，本地 Agent 3 次/远程 1 次差异化重试指数退避（初始 500ms，倍数 1.5，±50% 抖动），永久错误快速失败不重试同一 Provider，直接切换到 Claude SDK 降级固定间隔 1s × 3 次，UploadMaterialWithRetry 集中封装—retryOperation 指数退避（baseDelay×2^attempt），仅 429/quota 错误重试，非速率限制错误直接抛出指数退避 2^attempt 秒，最多 5 次，无随机抖动—指数退避base_wait×2^attempt + max_wait上限 + 环境变量全局可配
降级方案———Tushare API 失败时降级到本地 CSV 文件读取指数成分股数据协作式降级：错误爆发时LLM自主调用giveUp+chat向玩家解释超过阈值后 escalate 到人工通知，按 priority 路由到不同 Notifier 渠道—三路路由：正常完成→collect / 超限→fallback / 继续→toolsWrapUp LangGraph 工作流：扫描沙箱产物→LLM 选择→下载→兜底提交—资源处理：直接调用→LLM Agent→partial状态手动处理渐进截断（0.7倍递减）+ JSON手动提取{} + 强制结束指令熔断器 open 时快速失败；safe_parse 返回 default 值继续执行去掉 RAG 上下文构建 simplified_prompt 重试API 参数降级 + 仓库选择降级 + 过滤清空回退 + JSON 解析降级 + prompt 截断——VDB 操作失败后 raise Exception 中断流程，无 fallback 存储三级降级：零向量填充、零分排序、原始记忆兜底CustomDecoder 宽容解析（单引号/三引号），解析失败返回原始文本页面级跳过损坏页 + 整体回退原始 PDF + LLM 重试耗尽静默保留原始层级ProviderChain 透明代理 + FallbackEmbeddingProvider active 指针切换四层体系：通用重试 → API Key 轮转 → 模型故障转移 → 工具断路器工具失败返回错误字符串让 LLM 自适应，token 超限渐进截断保留最多内容——三级渐进降级：有页码TOC → 无页码TOC → 无TOC全文扫描，accuracy<0.6 触发batch_type_aware → individual + generic processor 兜底CodeInterpreter→runCode，AbortController→数据库直接更新，锁获取失败→继续执行selfHeal 放宽 requireMethodAndArguments=false；twoStep 第二步失败返回第一步结果配置驱动的供应商优先级链，首选失败自动尝试剩余供应商三级降级：API 返回 0.0 分 → Agent 返回错误提示 → 轨迹标记非活跃9-Provider 注册表 + 自动发现降级链 + provider_models 跨 Provider 模型映射—5 层独立降级：Hook exit 0 / Provider 切换 / Chroma→SQLite / 队列自愈 / 优雅关闭——ApiKeyManager 90s 黑名单自动恢复 + 多 Key 轮转，全部 Key 黑名单时兜底返回第一个 Key——中间件白名单(GracefulDegradation) + 装饰器(@safe_run) + 预算熔断(CostTracker warn/abort)
错误分类—SubagentStatus 枚举区分 FAILED（异常）和 TIMED_OUT（超时）两类失败—不区分错误类型，统一 catch Exception；外部 API 层按 Timeout/Connection 分类三级分类：auth不重试直接抛出、rateLimit指数退避、recoverable快速重试isIssueNotFoundError 区分业务错误与基础设施错误，自定义 Error 子类AgentOrientedExceptionBase 基类，区分工具错误、中断、参数错误工具层前缀约定：RETRIEVAL_ERROR / NO_RELEVANT_CHUNKS / NO_PARENT_DOCUMENTAPI_ERROR 可重试 vs 评估失败不重试，经济感知（破产停止）RETRYABLE_HTTP_STATUS 集合（含 409/425），GitHub 403 快速失败区分JSONDecodeError/ValueError/TypeError/通用Exception区分空响应/API异常/通用异常三类，工具层区分Timeout和通用Exception11 个异常类层级 + 规则链映射引擎，区分可重试/不可重试token 超限 vs 其他错误二分法，按字符串匹配区分参数兼容性错误（可降级）vs 其他错误（原样抛出），通过错误消息内容判断—双层 tenacity 装饰器按 429/非429 分流，5 类自定义 Workflow 异常Bedrock 通过 _handle_bedrock_exception 将 AWS 异常映射为可重试/不可重试类型retry_if_exception_type 精确分流：仅 JSONDecodeError 触发重试传输错误(ConnectionError/APIConnectionError) vs 语义错误(RepairType 枚举)区分 HTTP 传输错误、页面损坏、LLM 输出不匹配、进程卡死四类7 类枚举 ProviderErrorKind + 字符串模式匹配 classify_error()50+ 正则模式归类为 7 种 FailoverReason，按优先级链式匹配区分 token 超限（渐进截断）vs 其他错误（直接重试或返回错误）—VLM 层捕获所有 Exception 统一重试，不区分可恢复/不可恢复错误不区分异常类型，统一捕获；语义层通过 accuracy 量化评估质量FileNotFoundError/TimeoutExpired/JSONDecodeError 分类处理retryIf 谓词按错误类型决定是否重试，工具不存在/名称过长提前过滤ActTimeoutError 穿透自愈层；UnderstudyCommandException 触发自愈；schema 验证失败触发 LLM 重试专用 AlphaVantageRateLimitError 区分可恢复与不可恢复错误区分 API 异常（重试）、解析失败（重试）、动作无效（提示修正）、上下文超限（停用）按层分类：Provider 不可用/连接超时/组件缺失/数据源抖动，各层独立处理字符串匹配识别可重试错误（MySQL 驱动、Go net、Dolt 特定错误）Hook 层 isWorkerUnavailableError 区分 transport/5xx/4xx/编程错误，保守默认阻断GenerateError 五字段结构（Provider/Code/Message/Hint/Original），支持 Unwrap 链LLMUsage.status 区分 success/error，LLMCallFilter.statuses 支持按状态过滤拦截器isRateLimitError 双重检测（status code + message 关键词），覆盖 OpenAI/Google/DeepSeek 等多 Provider 格式RequestException/IOError 网络错误、TimeoutException、MemoryError 三类分流—三类分流：ContextLengthExceeded快速失败 / 429指数退避 / 一般错误重试
并发容错—SubagentLimitMiddleware 硬性截断超额 task 调用，限制范围 [2,4]，比 prompt 限制更可靠—fcntl.flock 排他锁保护仓位文件原子读写，按 Agent signature 隔离—pollAll 布尔锁防重入，Promise.allSettled 并发检查所有 Session——exhaust 模式 per-task 失败计数器，最多 10 次 API 重试后 abandon——ThreadPoolExecutor + Future异常捕获，失败任务写入JSONL不阻塞其他任务————SSE 死亡队列批量清理 + asyncio.Lock 保护 listener 集合PriorityQueue + max_size 并发限制 + max_queue_size 防内存溢出ContextThreadPoolExecutor + as_completed 逐个捕获异常不中断批次————asyncio.gather 并行执行 researcher，单个失败触发 supervisor 优雅终止—RM 操作 max_parallel=8 批量并行锁定，失败时逆序回滚已获取的锁asyncio.gather(return_exceptions=True) 隔离单条目修复失败asyncio.gather(return_exceptions=True) 隔离并发失败p-limit 控制工具并行度，Promise.all 工具执行单个失败返回错误 ToolMessage 不中断——ThreadPoolExecutor(10) 并行 rm_score + ProcessPoolExecutor(64) 并行评估，单项失败不影响其他——ProcessRegistry 僵尸进程清理 + waitForSlot 并发限制 + orphan reaper 定期回收——runStaggered 信号量+时间错开双重约束，PromiseSettledResult 收集部分成功结果FileLock 文件锁 + double-check 防止多 rank 并发下载冲突——
配置预验证———JSON 配置驱动重试参数，启动时校验 API key 和 MCP 端口可用性—Zod schema 验证 YAML 配置，项目唯一性和 sessionPrefix 冲突检测———Pydantic model_validator 校验 cron 5 字段 + task_type 字段一致性从YAML配置读取base/retry token限制，运行前确定参数边界—ConfigValidator 启动时校验 YAML 完整性，区分 error/warning 两级———database_connection_retry 开关 + db_driver_connection_settings 配置化——repair_llm_output 布尔开关，按模型类型预设是否启用修复链——————————validate_model() 验证 LLM 模型名，但数据供应商配置无预验证—ConfigManager.validate_provider 在创建前检查 API Key/Endpoint 可用性——NewProvider 工厂函数内 validateXxxConfig 前置检查 API Key 等必要配置—————
监控告警—trace_id 贯穿父子 Agent，所有状态变更含 logger.info/warning/error 记录—print 日志记录每次重试的 attempt 编号和错误详情，无结构化指标—OrchestratorEvent 事件体系，4 级优先级路由到多 Notifier 渠道———每次重试 logger.warning + query_error_dump JSON 现场保存——ErrorRateTracker 60s 滑动窗口，50% 阈值触发 alert_callback————Redis before_sleep_log 重试前日志，每次失败 logger.error/warning 记录———条件编译 metrics feature：COMPLETION_ERRORS_TOTAL 含 provider/model/error_type 标签———TransactionObserver 提供 is_healthy/get_hanging_transactions 接口JsonLogger 记录每步准确率和降级决策，无实时告警—————每次降级/重试均有 logger.warning 记录，含 provider 名和错误详情OTel 指标记录重试次数（bd.db.retry_count）和锁等待时间logger 分级记录 + HealthMonitor lastAiInteraction + OpenRouter 高 token 告警————双守护线程：MultiprocWorkerMonitor + MPClientEngineMonitorCostTracker预算告警 + GlobalRateLimiter指标暴露 + ErrorTrackingMiddleware错误历史收集
无动作循环防护————预算制（默认3/最大8）+签名停滞检测（重复2次即停滞）——retrieval_keys 集合记录已执行查询，prompt 指示不重复调用—————————————————————————————————
事件优先级合并————玩家聊天优先，丢弃低优先级no-action follow-up事件————————————————————————————————————
恢复机制—三层一致性恢复：进程缓存→文件状态→后端发现，逐层降级———Session restore 从 archive 恢复 metadata + workspace.restore 重建工作区——task_completions.jsonl 断点恢复，exhaust 模式跳过已完成任务配置哈希感知重试：相同配置失败 3 次停止，配置变更自动重置计数5级JSON修复：去逗号→闭合结构→截断闭合→工具默认值→放弃—CircuitBreaker 三态机：closed→open→half-open→closed，60s 恢复窗口Memory 对话历史损坏时自动重建 CustomConversation过滤前快照保留，清空时回退到快照 + 智能裁剪（优先级评分排序）—CancelledError 递归重试(max=3) + Alembic 渐进降级(downgrade -1~-5)HealthCheck 每5s巡检卡死任务，Worker 自动恢复，连接池引用计数管理—渐进修复：每次重试前根据上次异常位置定向修复 JSONTianshu 调度器 reset_stale_tasks 自动重置超时任务为 pending断路器 60s 冷却自动恢复 + MCP 服务 running 状态重置计数器———7 态状态机驱动事务回滚，LIFO 逆序释放路径锁定向修复：只重试验证失败的条目（max_attempts=3），不全量重试per-item continue 跳过失败项，不中断管道卡死任务 Cron 巡检+Promise.allSettled 并行恢复，锁自动续期防过期缓存自修复：replay 时检测选择器变化自动 refreshCacheEntry 更新缓存条目无状态恢复，每次调用独立构建降级链———PendingMessageStore claim-confirm + 60s stale 自愈 + 启动时恢复未完成会话———三层 checkpoint（model+optimizer+meta JSON），dataloader advance-by-1 精确恢复无热恢复，崩溃即关闭；依赖外部编排（K8s/Ray）重启—
级联清理—信号处理器链式调用 + atexit 注册 + 幂等 shutdown 三重保障———spawn 4 层 try-catch 级联清理 workspace/runtime/metadata，best-effort 不抛异常———有序关闭：watchers→cron→channels→mcp→runner，每层独立 try-except——————————————————————shutdown → wait_for(5s) → cancel → close client → cancel listener 五步清理链—————.tmp 文件清理 + DDP 进程组销毁 + 临时目录自动删除三阶段终止 wait→SIGTERM→SIGKILL + weakref.finalize + death_pipe—
异步中断处理——————CancelledError 捕获后生成中断响应，保留已生成内容——————————————————————————————————
中间件容错——————洋葱式中间件支持自定义重试、日志、权限检查——————————————————————————————————
流式容错——————_async_generator_wrapper 单独处理流式工具中断——————————————————————————————————
错误响应格式——————统一 ToolResponse(content=[TextBlock(text='Error: ...')]) 格式——————————————————————————————————
工具不存在容错——————返回 FunctionNotFoundError ToolResponse 而非抛异常——————————————————————————————————
工具组激活检查——————未激活工具组返回 FunctionInactiveError 并提示激活方法——————————————————————————————————
可配置重试参数———————config.py 集中定义 4 个阈值常量，修改无需改代码逻辑—4 个环境变量：RETRIES/TIMEOUT/BACKOFF_BASE/BACKOFF_CAP—————————————max_structured_output_retries 通过 Configuration 暴露，支持 UI 调整（1-10）—————————————maxRetries/baseDelay/onRetry 回调均可配置，批处理层 MAX_BATCH_RETRIES=2 + RETRY_BASE_DELAY=3000———
输出验证———————collect_answer 三重验证：isinstance + content 非空 + 无 tool_callsWrapUp 的 LLM 决策节点解析 JSON 数组，解析失败时降级为提交全部产物—YAML计划5个必需section检查+结构完整性+末行完整性—Pydantic BaseModel 验证 LLM 输出结构，ValidationError→LLMParseError→重试Embedding 维度两遍扫描过滤，按众数保留一致维度五级 JSON 解析策略链（直接→清洗→正则→AST→增量），覆盖注释/单引号/截断等问题——OpenAI/Gemini 检测空 content 抛出 InvalidResponseError 触发重试布尔值四格式兼容 + 字段名拼写容错(retrival→retrieval)BasePostProcessPlugin 4 步管道：修复→提取→格式化→解析验证LLM 标题数量匹配验证 + MCP API 轮询状态 done/failed/error 三态检查——with_structured_output + with_retry 自动验证 Pydantic schema 并重试———PDF 大小 >= 100 bytes 验证，content_list 非空检查———bbox 双重验证（JSON 解析 + 坐标非负 + 长度=4），judge 大小写兼容———压缩后文件大小校验，压缩后反而变大则放弃压缩结果—submitImageTask 多格式响应解析（标准 JSON / SSE data: / GPT choices / markdown 图片链接）——is_truncated双格式检测 + is_repeated尾部重复检测(50ch×5次阈值)
资源管理模式—端口分配异常回滚 + 创建失败立即销毁 + 空闲定时回收——————E2B 沙箱健康检查 + 每任务结束后 cleanup，防止沙箱泄漏———————————ModelSingleton 单例复用推理客户端 + clean_memory 清理推理中间结果———————guard.defer RAII + guard.bracket 多资源 LIFO 释放——active_mask 位掩码管理批量轨迹生命周期，每轮检查 + 乘法不可逆停用——————reliability_guard 禁用 20+ 危险系统调用 + RLIMIT 内存限制BackgroundResources dataclass 集中管理 ZMQ socket/进程/任务生命周期—
外部服务容错—Provisioner HTTP 调用分级超时（创建30s/销毁15s/发现10s），销毁失败仅警告———————Skills Hub HTTP 重试 + GitHub 403 rate limit 特殊提示—Jina 3次0.5s延迟 + Serper/Scholar 5次无延迟 + urllib3自动重试500/502/503/504——————Redis限流→内存降级 + Reranker→零分降级 + LLM→原始文本降级—VLM 推理 http_timeout=600s + 健康检查 aiohttp 10s 超时MCP 健康轮询 30s + 指数退避重启 5s×2^n（上限 300s，最多 5 次）———————————————————
续写能力——————————无续写，通过减少output tokens迫使模型用更简洁方式表达———————————————finish_reason + LLM 完整性双条件门控，chat_history 拼接续写最多5轮———————————dataloader state_dict 记录 parquet/row_group/epoch 三维位置——
数据供应商路由———————————SandboxFusion多endpoint随机选择，每次重试换endpoint绕过故障节点——————————————————VENDOR_METHODS 注册表 + 两级配置优先级（工具级 > 类别级）——————————
连接池管理—————————————无连接池，每次请求新建 RAG 实例和 Provider 客户端——async_sessionmaker + 配置化 pool_size/max_overflow/poolclass—putconn(close=True) 回收坏连接 + 池耗尽长退避(0.5s×2^n)—————————————临时 client 失败时主动 close 防泄漏，per-agent asyncio.Lock 防并发竞态MaxOpenConns=10，MaxIdleConns=5，ConnMaxLifetime=5min，定期刷新连接——————GlobalRateLimiter单例5域隔离 + 同步/异步双模式限流 + per-domain独立锁
锁错误处理—fcntl.flock 解锁失败静默忽略（OS 进程退出自动释放）———————————————————————锁文件协议 + 4 步防竞态验证 + 底部向上批量锁定——Lua 原子操作释放/续期，Token 唯一性防误释放，续期失败自动清理定时器————识别 4 种锁错误模式，包装为带操作指引的友好错误————FileLock with 语句自动释放，异常时不会死锁——
陈旧锁清理—确定性 ID + 文件状态 + 后端发现三层验证，自动清除指向已死容器的状态———————————————————————后台 cleanup_loop 按 updated_at 超时检测，自动回滚并释放锁———————检测 5 分钟以上的陈旧锁文件并自动清理，避免死锁———————
模糊匹配容错——————————————仓库名三级模糊匹配（精确→子串→Jaccard 相似度），容忍 LLM 输出的命名偏差——————————————————————————
存储层重试—————————————————VDB 手动循环 0.2s 固定延迟，Redis/Neo4j tenacity 指数退避PolarDB 连接池 SELECT 1 健康检查 + 池耗尽差异化退避——————————————Dolt 数据库连接层，指数退避 30s 上限，10+ 种错误模式识别Chroma 失败回退 SQLite，fellBack 标记供上层感知，无重试直接降级——————
阶段级容错——————————————————deep_search 多阶段 try/except+continue，单阶段失败不中断流程——————————————————————
多模态降级————————————————————Windows 环境自动降级为单进程渲染（跳过 ProcessPoolExecutor）——————4 种专用 Processor + GenericProcessor 终极兜底—————————————
重试提示解析—————————————————————6 种 Retry-After 格式解析（ms/s/min 单位自适应 + clamp 防护）———————————————————
断路器模型—————————————————————per-provider 独立 AtomicUsize 计数 + Mutex<Instant>，3 次触发/60s 冷却工具循环三级断路器：warning(10) → critical(20) → global(30)，SHA-256 哈希签名——————————————————
密钥轮转——————————————————————多源 API Key 收集（环境变量列表/前缀扫描/主 Key）+ 仅 rate_limit 触发轮转——————————————ApiKeyManager 随机起始+轮转+90s 黑名单，handleError 对 429/401/503 自动触发轮转———
冷却探测——————————————————————冷却到期前 2min 主动探测主模型恢复，30s 节流防止探测风暴——————————————————
冷却窗口不可变——————————————————————keepActiveWindowOrRecompute 保持活跃冷却窗口不被重试延长——————————————————
渐进截断收缩比———————————————————————final_report 每次缩减 10%（×0.9），compress_research 按 AIMessage 边界截断—————————————————
事务重试—————————————————————————超时事务自动回滚但不重试，由上层业务决定是否重新发起———————整个事务重试，要求操作幂等性———————
自愈能力—————————————————————————————LLM 驱动的 DOM 自愈：失败后重新感知页面状态，用 AI 重新定位元素而非固定重试———————————
网络稳定性保障—————————————————————————————waitForDomNetworkQuiet 基于 CDP 事件追踪 inflight 请求，500ms 静默窗口 + 2s stalled 强制完成———————————
计算模式降级——————————————————————————————bulk 批量计算失败自动回退到逐日单点计算———————GC disable + 周期性手动 collect 避免训练暂停——
服务器自动启动—————————————————————————————————连接失败时自动启动 Dolt 服务器（auto-start），配合重试机制实现零配置启动———————
拦截器安全隔离————————————————————————————————————_safe_invoke_interceptor 双模式：strict 传播 vs 非 strict 日志吞掉————
不可变快照执行————————————————————————————————————snapshot() 冻结拦截器元组，执行期间注册/移除不影响当前批次————
过滤器容错————————————————————————————————————_should_run_interceptor 三层防御：正常调用→TypeError 降级→兜底 return False————
best-effort 数据提取————————————————————————————————————_extract_usage_from_raw_response 解析失败返回部分数据，不影响主流程————
信号处理链———————————————————————————————————————shutdown_requested 单次触发 + SystemExit 传播 + 防 ZMQ __del__ 异常—
进程死亡检测———————————————————————————————————————death_pipe 父进程退出感知 + sentinel 子进程退出感知—

最佳实践

1.必须有重试：任何 LLM 调用都可能失败，重试是基本要求

2.指数退避 + 抖动：避免重试风暴，加入随机抖动

3.设置最大重试次数：无限重试会耗尽预算

4.日志记录每次失败：便于事后分析失败模式

5.降级方案要预先设计：不要在生产环境临时决定降级策略

6.线性退避适合时间敏感场景（如交易窗口），避免指数退避的过长等待

7.适配器模式在框架层透明修复 Provider 不兼容，业务代码无感知

8.外层重试应重建完整会话状态，不要在失败状态上继续累积

9.错误爆发守卫用滑动窗口而非累计计数，只关注近期趋势

10.协作式降级让LLM自己生成错误解释，比硬编码消息更有用

11.无动作预算可由LLM动态调整，兼顾灵活性和安全性

12.玩家输入自动重置所有容错状态，确保人类干预始终有效

13.每次重试前检查暂停状态，支持外部中断重试循环

14.状态转换时清除对应 reactionTracker，避免旧计数影响新一轮重试

15.send-to-agent 失败时返回 success:false 而非立即升级，给下一轮轮询机会

16.用 Promise.allSettled 并发检查多 Session，单个失败不阻塞其他

17.spawn 过程每层资源分配都配 try-catch 级联清理，防止泄漏

18.项目级 reaction 配置覆盖全局默认，用 spread 合并语义

19.定义面向 Agent 的异常基类，异常消息使用 LLM 可理解的自然语言

20.在工具调用入口统一捕获异常，避免在每个工具函数中重复 try-except

21.流式工具中断时保留 last_chunk，避免丢失已完成的工作

22.使用 <system-info> 标签包裹系统级错误信息，便于 Agent 识别

23.中间件采用洋葱模型，允许用户插入自定义容错逻辑而不修改核心代码

24.用 LangGraph Annotated reducer 做计数器：节点只返回增量，框架自动累加，避免并发读写竞态

25.fallback 应汇总已有数据而非返回空错误：用户体验远优于 'max retries exceeded' 硬错误

26.兜底提交优于完全放弃：半成品仍可能获得部分评分和报酬

27.区分可重试错误和不可重试错误：API失败重试，评估低分不重试

28.断点恢复用JSONL追加写：task_completions.jsonl支持exhaust模式跨进程恢复

29.用环境变量暴露重试参数（retries/backoff_base/backoff_cap/timeout），不同部署环境灵活调整

30.配置感知重试追踪：用 (count, config_hash) 元组，配置变更自动重置计数

31.有序关闭按依赖反序执行，每层独立 try-except 防止级联失败

32.重试时递减temperature：低temperature输出更确定性，减少截断风险

33.确定性操作不走LLM：文件操作等确定性任务先用直接函数调用，失败再fallback到LLM

34.JSON修复分级尝试：从最轻量（去逗号）到最激进（截断闭合），逐级修复

35.空响应也应触发重试：vLLM等推理服务高负载时可能返回空内容而非抛异常

36.Token超限时注入强制总结指令而非直接截断：保留LLM对已有信息的推理能力

37.多endpoint服务将内部重试设为1次，重试权交给上层以实现endpoint轮换

38.熔断器三态保护：连续失败时快速失败，定时探测恢复

39.滑动窗口错误率追踪：比简单计数器更准确反映实时健康状态

40.Pydantic 模型验证 LLM 输出：编译时类型安全 + 运行时结构验证

41.双层重试解耦：业务层和传输层各自独立重试，职责清晰

42.流式 fallback 应保留 system_prompt 和 conversation_history，只去掉最大的上下文块（RAG 结果）

43.Embedding 维度过滤用两遍扫描 + 众数策略，比严格一致性检查更鲁棒

44.backoff 装饰器用 max_time 而非 max_tries 控制重试上限，适合延迟敏感场景

45.确定性 ID 替代 UUID：用哈希函数从业务键生成资源 ID，免去跨进程 ID 传递

46.三层逐级恢复：快路径零 IO，慢路径仍能恢复，避免单点依赖

47.信号处理器必须链式调用原始处理器：保存 getsignal 结果并在自定义逻辑后回调

48.文件状态写失败不致命：状态丢失只影响跨进程恢复，不影响当前进程的沙箱使用

49.创建失败必须立即清理：端口、容器等稀缺资源在异常路径中必须回滚

50.用中间件钩子注入容错逻辑，与业务代码解耦

51.双线程池隔离调度与执行，避免超时监控被执行阻塞

52.轮询兜底超时应比主超时多 1-2 分钟，作为最后安全网

53.合成错误消息应标记 status=error，让 LLM 知道调用未成功

54.参数嗅探优于预配置：先尝试宽兼容参数，通过错误消息判断是否需要降级

55.过滤操作前必须保存快照：LLM 驱动的过滤不可信，需要回退路径

56.fallback 链的每级应降低智能但提高确定性：最终 fallback 必须是确定性的

57.JSON 解析应覆盖 LLM 常见输出问题：注释、单引号、未引用 key、截断

58.配置开关控制重试：开发环境关闭重试快速失败，生产环境开启容错

59.两级错误响应：系统错误返回 HTTP 错误码，业务错误返回 200+error body 保留部分结果

60.CancelledError 语义标记：通过 exc.args 传递取消原因，区分用户操作和系统异常

61.SSE 事件发射设超时上限：防止慢消费者拖垮广播系统，超时后丢弃而非阻塞

62.不同 Provider 使用不同退避参数：OpenAI max=10s 快恢复，Gemini/Bedrock max=60s 慢恢复

63.存储层重试参数通过环境变量可配置：如 REDIS_RETRY_ATTEMPTS 支持运维调整

64.使用 reraise=True 保留原始异常栈：Neo4j 的 READ_RETRY 确保上层能精确处理原始错误

65.三层超时动态计算：基于 llm_timeout 自动推导 Worker 和 HealthCheck 超时值

66.tenacity 的 retry_if_exception_type 精确限定重试条件，避免对不可恢复错误浪费重试次数

67.timed_with_status 装饰器将计时、日志、降级三合一，减少样板代码

68.连接池健康检查用 SELECT 1 而非依赖驱动层自动检测，主动发现坏连接

69.语义修复优先于重新调用：JSON 格式问题本地修复比重新请求 LLM 更经济

70.渐进式修复：每次重试前根据上次异常信息定向修复，而非重复尝试相同输入

71.按模型能力配置修复链：OpenAI 等强模型关闭修复，开源模型开启

72.宽容解析器兜底：CustomDecoder 支持非标准 JSON 格式作为最后防线

73.修复类型枚举化：每种修复独立可测试、可组合、可按需启用

74.LLM 输出验证不仅检查异常，还要检查业务逻辑（如数量一致性）

75.两阶段进程终止：先 SIGTERM 给优雅退出机会，再 SIGKILL 兜底

76.通过环境变量暴露超时配置，适应不同硬件性能差异

77.使用 json_repair 替代 json.loads 解析 LLM 输出，提高容错率

78.单例模式复用推理客户端，避免重试时重复初始化模型

79.错误分类检查顺序很重要：ContextWindow 必须优先于 ServerError，避免 'request too large' 误分类

80.server error 和 rate limit 用独立计数器：避免一种错误消耗另一种的重试预算

81.断路器成功时立即重置：record_success() 清零 consecutive_failures，一次成功即恢复信任

82.Retry-After hint 优先但不替代退避状态：即使使用 Provider 建议的等待时间，仍推进指数退避状态机

83.billing/quota 错误不重试：账户级别问题短期内不会恢复，立即暴露给调用方

84.Context Overflow 不应触发模型降级：切换到更小窗口的模型只会更快失败

85.冷却窗口应不可变：活跃冷却期内的重试不应延长恢复时间

86.API Key 轮转应仅对 rate_limit 触发：billing/auth 错误换 Key 无意义

87.工具循环检测应基于哈希签名而非简单计数：区分不同参数的调用

88.工具失败返回错误字符串而非抛出异常，让 LLM 在下一轮自行决定恢复策略

89.渐进截断优于一次性大幅截断：0.9 收缩比保守但避免信息过度丢失

90.结构化输出重试次数应可配置：不同模型的 schema 遵从度差异大

91.supervisor 层的 catch-all 优雅终止：宁可用不完整结果生成报告也不让流程崩溃

92.锁释放采用 LIFO 逆序：与获取顺序相反，避免中间状态暴露

93.事务超时基于 updated_at 而非 created_at：活跃操作会刷新时间戳，避免长事务被误杀

94.渐进式修复优于一次性解析：从宽松到激进逐级尝试

95.fallback 返回值必须与正常返回值结构一致，保证接口兼容

96.GenericProcessor 作为终极兜底始终注册，处理未知内容类型

97.asyncio.gather 使用 return_exceptions=True 隔离并发任务失败

98.用签名比对而非简单计数检测循环：排序后拼接 name+args 能精确识别重复

99.分布式锁必须有最大生命周期上限：防止续期定时器无限运行导致资源泄漏

100.卡死任务巡检用 Promise.allSettled：单条恢复失败不影响其他任务处理

101.Guard 链式 API 统一错误处理：避免 try-catch 嵌套，orThrow/orElse 语义清晰

102.超时用预算制而非 Promise.race：在流程各节点主动检查剩余时间，避免发起注定被取消的昂贵调用

103.自愈时放宽输出要求：只需定位元素，方法和参数沿用原始值，降低 LLM 推理难度

104.缓存 replay 失败返回 null 而非抛异常：让调用方无感回退到正常执行路径

105.超时错误穿透自愈层：不可恢复的全局约束不应被局部重试消耗

106.仅对可恢复错误触发降级：用专用异常类区分 rate limit 与编程错误，避免掩盖 bug

107.降级链应包含所有可用供应商：配置的首选 + 自动补充剩余，确保最大可用性

108.Agent 工具函数返回错误字符串而非抛异常：兼容 LangGraph ToolNode 的字符串返回值约定

109.RL 训练场景的重试次数可以远高于在线服务（20 次 vs 3 次），因为训练容忍延迟

110.用 active_mask 乘法实现不可逆停用，避免已停用轨迹被意外重新激活

111.评估函数用 ProcessPoolExecutor 而非 ThreadPoolExecutor，确保死循环可被 kill

112.无效 Agent 动作返回错误提示而非终止轨迹，保留 Agent 自我修正的学习机会

113.降级链应可配置：通过环境变量或配置文件动态调整 Provider 优先级

114.区分本地与远程的重试策略：本地服务有冷启动延迟需要更多重试，远程失败通常是持久性的

115.临时资源必须主动清理：创建临时 client 后失败时必须 close，不能依赖 GC

116.可选组件用 Optional 返回值而非异常：让调用方决定降级行为而非强制失败

117.字符串匹配识别错误：数据库驱动的错误消息比错误码更稳定，且能覆盖 Go net 包和数据库特定错误

118.连接池定期刷新：设置 ConnMaxLifetime（如 5 分钟）定期刷新连接，避免陈旧连接累积

119.DSN 级超时 + 重试窗口：DSN 配置短超时（5-10 秒）快速检测故障，重试窗口（30 秒）覆盖服务器重启场景

120.锁错误友好化：识别锁错误并附加操作指引（如 '运行 bd doctor --fix 清理陈旧锁'），加速问题解决

121.重试前清理资源：重试前关闭上次失败的连接/Rows（如 `rows.Close()`），避免连接泄漏

122.保守默认策略：未知错误默认阻断（暴露 bug），而非默认降级（隐藏问题）

123.Provider 降级优于同 Provider 重试：429/5xx 时换 Provider 比指数退避更快恢复

124.存储层回退要标记降级状态：fellBack 标记让上层感知搜索质量下降

125.配置前验证：在创建 Provider 实例前检查必要配置，避免运行时才暴露配置缺失

126.错误携带解决提示：CLI 场景下 Error 消息应包含 Hint 字段，告诉用户如何修复

127.最后一次重试不 sleep：避免用户在最终失败时多等一个无意义的间隔

128.拦截器执行用不可变快照隔离注册期并发修改

129.after 和 on_error 拦截器逆序执行，模拟栈展开语义

130.附属功能（记忆检索、用量统计）采用 fail-silently 模式，返回空值而非抛异常

131.密钥黑名单应有自动过期机制（如 90s），避免永久禁用可恢复的 Key

132.并发控制应结合信号量和时间错开双重约束，纯信号量无法防止突发请求

133.不可重试错误（如 TOKEN_BUDGET_EXCEEDED）应快速失败，避免浪费重试预算

134.从 API 错误消息中自动学习模型限制（Error-driven Discovery），比硬编码限制表更准确

135.原子写入：先写 .tmp 再 rename，防止下载中断留下损坏文件

136.FileLock double-check：锁外快速检查 + 锁内再检查，减少不必要的锁竞争

137.checkpoint 元数据用 JSON 而非 pickle：人类可读、跨版本兼容、便于调试

138.分片保存优化器状态：DDP 下每个 rank 只保存自己的优化器分片，减少 IO

139.用 OS 进程 sentinel 而非轮询检测子进程死亡

140.三阶段终止确保进程一定被清理：等待→SIGTERM→SIGKILL

141.death_pipe 让子进程主动感知父进程退出，避免孤儿进程

142.weakref.finalize 确保 GC 时自动清理子进程资源

143.异常分级区分可恢复和不可恢复，驱动不同上层策略

144.截断检测要兼容多 Provider 格式：OpenAI finish_reason 和 Anthropic stop_reason 同时检查

145.上下文超限错误应快速失败不重试：重试只会重复浪费 token

146.可降级节点用白名单声明式管理：新增降级节点只需加一行配置

147.限流器按 API 域隔离：LLM 和搜索 API 的速率限制差异大，统一限流会互相拖累