api-resilience

当用户说『调外部API老超时』『被限流了』『接口抖一动就挂』『怎么给agent加重试退避』，或 agent 依赖的第三方服务(模型/搜索/数据库)不稳定、需要限流/退避/熔断/降级时使用。把外部调用当『会失败的对象』：指数退避+抖动重试、限流计数、熔断降级，失败可恢复不雪崩。理论根基：LGD 三律（有籍·有证·有门禁）。触发词：API重试、限流、退避、熔断、降级、接口抖动、resilience、超时、调用不稳定。

凡自治之物 · LGD 治理学 · 创造术家族 ｜ 评测协议：skill-quality-gate（外部公开评测门禁文档）

English

When to use

• Frequent timeouts, 429 TooManyRequests or jittery responses from external deps (model/search/DB).
• Build a "failure-prone object" model for unreliable external services to prevent cascading collapse.
• The user asks "external API keeps timing out" / "how to add retry backoff".
• Complex calls needing exponential backoff, rate limiting, circuit breakers or degradation.

Usage

• Call the core function in resilience_demo.py with policy='exponential', jitter=True.
• Configure limiter and max retries: max_retries=5, initial_retry_delay=1000ms.
• Enable circuit breaker: enable_circuit_breaker=true, failure_rate_threshold=0.8.
• Load resilience_demo.py classes for current backoff algorithm config.

Flow

1. Init: bind request context to the external object (LGD registered).
2. Verify: first request; record status code and latency (LGD evidenced).
3. Judge: compute backoff from rate-limit/timeout evidence; decide whether to retry.
4. Retry: apply exponential backoff + jitter.
5. Circuit-break: on consecutive failures, open the breaker; stop further calls.
6. Recover: after a cooldown / error reduction, re-validate and auto-close the breaker.

Evidence & safety

• Evidence: TBD. Version: 1.0.1. Security: no independent scan (TBD).

中文

何时用

• 当外部依赖（模型/搜索/数据库）出现频繁超时、返回 RateLimit-TooManyRequests 或响应异常抖动时。
• 当 Agent 需要在不可靠的外部服务上建立"会失败的对象"模型，防止系统雪崩效应时。
• 当用户明确提出『调外部 API 老超时』『怎么给 agent 加重试退避』等请求时。
• 在需要实施指数退避、限流计数或熔断降级策略的复杂调用场景下。

用法

• 调用脚本 resilience_demo.py 中的核心函数，设置参数 policy='exponential', jitter=True。
• 配置限流计数器与最大重试次数，例如 max_retries=5, initial_retry_delay=1000ms。
• 启用熔断机制开关 enable_circuit_breaker=true，并设定失败阈值 failure_rate_threshold=0.8。
• 若技能需读取逻辑，直接加载 resilience_demo.py 类定义以获取当前退避算法配置。

流程

1. 初始化：识别外部对象属性并绑定请求上下文（LGD 有籍）。
2. 验证：执行首次请求并记录状态码与耗时，积累失败证据（LGD 有证）。
3. 判断：基于限流或超时证据计算退避时间，判断是否触发重试。
4. 重试：应用指数退避 + 抖动公式重新发送请求（LGD 有籍·有证·有门禁）。
5. 熔断：连续失败达标则激活熔断状态，停止进一步调用以保护主系统。
6. 恢复：等待熔断半冷却期过或错误减少，验证后可自动解除限制并恢复连接。

证据与安全声明

• 证据：TBD（暂无评测/徽章链接；产生后在此更新实际链接）
• 版本：1.0.1
• 安全：未做独立安全扫描（TBD），结论待补；补全前不作推荐背书。