python-resilience

python-resilience 技能概览

python-resilience 能做什么

python-resilience skill 用于帮助你设计在依赖不稳定时也能更安全失败的 Python 代码。它聚焦的是实用型韧性模式：重试、指数退避、jitter、超时、受限重试窗口，以及围绕外部调用构建的容错包装层。

谁适合安装这个技能

这个 python-resilience skill 特别适合开发者、平台团队，以及在服务中需要对接 API、数据库、队列或其他网络系统的 agent 用户。尤其当你需要的不只是“加个重试”，而是希望代码生成能够合理划定失败处理边界时，这个技能会更有价值。

它真正解决的是什么问题

大多数用户并不需要一整页可靠性理论，他们需要的是能直接落地的 Python 模式，来回答这类问题：

• “这个错误应该重试，还是直接失败？”
• “在有负载压力时，什么样的 backoff 策略更安全？”
• “timeout 应该放在哪一层？”
• “怎样避免无限重试和 thundering herd？”
• “这个外部调用该用什么 decorator 或 helper 来包裹？”

python-resilience 的价值在于，它会把这些决策明确展开，而不是把重试逻辑当成一句补丁式修改。

它和通用 prompt 的区别是什么

通用的编码 prompt 往往会给所有地方都加上重试，或者忽略瞬时失败与永久失败之间的差别。python-resilience for Reliability 的判断更明确：只重试可重试的失败，加入 jitter，限制尝试次数和总耗时，并把外部边界视为最应该放置韧性逻辑的位置。

源技能实际覆盖了什么

上游技能只有一个 SKILL.md 文件，但内容并不空泛，核心包括：

• transient vs permanent failures
• exponential backoff
• jitter
• bounded retries
• practical Python examples using tenacity

这意味着它很轻量，便于快速检查、快速采用；但也意味着你拿到的是指导思路，而不是现成打包好的库或测试框架。

什么情况下这个技能很匹配

在下面这些场景中，使用 python-resilience 会比较合适：

• 调用第三方 API
• 包装不稳定的网络或服务交互
• 构建微服务或 worker
• 给共享 client 工具增加可靠性控制
• 处理 rate limiting、临时故障或间歇性 timeout

如果你的代码主要是纯进程内逻辑，这个技能大概率不是收益最高的安装项。

如何使用 python-resilience skill

安装 python-resilience 的上下文

从 wshobson/agents 仓库安装该技能：

npx skills add https://github.com/wshobson/agents --skill python-resilience

安装后，先打开这个技能文件：

• plugins/python-development/skills/python-resilience/SKILL.md

从仓库结构看，这个区域似乎只包含技能文档本身，因此上手路径很直接：先读技能内容，再把其中的模式应用到你自己的代码库里。

先读这个文件

建议先从头到尾读一遍 SKILL.md。优先看的高价值部分是：

1. When to Use This Skill
2. Core Concepts
3. Quick Start

按这个顺序阅读，你会先建立适配判断、设计规则和实现轮廓，再去让模型修改你的代码，效果通常更好。

这个技能需要你提供哪些输入

python-resilience usage 的效果很大程度取决于你提供的上下文是否充分。在调用技能之前，最好先准备好：

• 需要保护的函数或服务边界
• 依赖类型：HTTP API、DB、queue、cache、filesystem
• 观察到的具体异常或失败症状
• 这些失败是 transient 还是 permanent
• timeout 预期
• 幂等性约束
• 可接受的最大延迟
• retry budget：尝试次数或总持续时间
• 是否会有很多客户端同时重试

如果缺少这些输入，模型通常会生成范围过宽、过于笼统的重试逻辑。

把模糊目标改写成高质量 prompt

较弱的 prompt：

Add resilience to this Python API client.

更好的 prompt：

Use the python-resilience skill to refactor this Python client method.

Context:
- Dependency: third-party HTTP API
- Library: httpx
- Traffic: moderate, bursty
- Common failures: read timeout, connect timeout, occasional 429 and 503
- Permanent failures: 400, 401, 403 should not be retried
- Idempotency: safe to retry GET requests only
- SLO: fail within 8 seconds total
- Requirement: use bounded retries, exponential backoff with jitter, and clear logging

Task:
- Propose a retry policy
- Implement the wrapper/decorator
- Explain which exceptions and status codes are retryable
- Show where timeout configuration should live

这样更有效，因为它把这个技能最擅长推理的决策边界都明确给出来了。

先要策略，再要代码

一个更稳妥的 python-resilience guide 使用流程是：

1. 先让模型做失败分类
2. 再让模型提出 retry/timeout 策略
3. 评估其中的 tradeoff
4. 然后再生成实现代码

这样可以避免一上来就直接套 decorator，却还没想清楚哪些情况该重试、哪些不该重试。

把技能用在外部边界上

这个技能在处理跨进程或跨网络边界的代码时最有效，例如：

• httpx 或 requests 调用
• 消息发布或消费
• 已知存在瞬时失败模式的数据库查询
• cloud SDK 调用
• service client methods

不要一开始就把大块业务流程从头到尾整体包起来。更好的做法，是先把韧性控制放在那个不稳定依赖的外围。

好的 python-resilience 输出应该包含什么

当技能发挥正常时，输出通常应该包括：

• 明确的 transient vs permanent failure 规则
• 有上限的重试限制
• exponential backoff
• jitter
• timeout 放置位置
• 使用 tenacity 等 Python 工具的示例
• 关于幂等性和副作用的说明

如果结果只是写着“重试 3 次”，那就应该继续追问，让它给出更明确的重试策略。

实际落地时值得要求的实现模式

源技能里包含一个基于 tenacity 的 quick start。实际使用时，你可以要求模型给出这类模式：

• 围绕 service client method 的 decorator
• 统一包装所有出站 HTTP 调用的 helper
• 区分 read 与 write 的重试策略
• 按异常类型或状态码过滤的重试规则

对于有状态修改的操作，要让模型解释为什么这样重试是安全的。忽视幂等性的可靠性模式，很容易造成重复副作用。

使用 python-resilience 时的常见错误

在生成代码时，重点留意这些问题：

• 重试认证失败或校验失败
• 只有重试，没有 timeout
• 重试循环没有总预算
• backoff 没有 jitter
• 包装范围过大，掩盖根因
• 默认重试非幂等写操作

这些才是实际落地时比代码风格更关键的阻碍点。

在你的仓库里，一个实用的工作流

为了获得更好的结果，建议给技能提供：

• 当前的 client function
• 日志里出现过的异常类
• 样例状态码
• 延迟预算或重试预算
• 一到两个有代表性的失败 trace

然后要求它输出：

1. policy summary
2. code changes
3. 你应该补充的 tests
4. 需要记录的 monitoring fields

相比只让模型直接写代码，这个顺序通常更容易得到可直接采用的结果。

python-resilience skill 常见问题

python-resilience 只适用于 web API 吗？

不是。python-resilience skill 面向的是“不可靠依赖”这一类问题。HTTP 调用只是最容易举例的场景，但同样的推理方式也适用于队列、数据库、缓存和 cloud services 等经常出现瞬时失败的系统。

它是一个库，还是一个指导型 skill？

它是一个指导型 skill，不是独立的 Python package。它会讲清楚模式、展示实现风格，也包含基于 tenacity 的示例，但你仍然需要把这些模式落实到自己的代码库中。

什么情况下不该使用 python-resilience？

不要把 python-resilience 当作所有函数的默认包裹层。它不适合这些情况：

• 纯 CPU-bound 的本地逻辑
• 明显属于永久失败的错误
• 重试会导致不安全重复副作用的流程
• 延迟预算紧到容不下重试窗口的系统

遇到这类场景，更合适的做法通常是快速失败，或者重新设计集成方式。

python-resilience 适合初学者吗？

适合，前提是你已经掌握基础的 Python 和异常处理。这个技能的核心概念并不难，但使用者仍然需要提供业务上下文，比如重试是否安全、timeout budget 有多少、哪些失败可以接受重试。

相比直接让 LLM 写重试，它好在哪里？

python-resilience for Reliability 的优势不只是生成代码，更在于帮助模型判断失败类别、受限重试和 backoff 行为。通用 prompt 往往忽略这些边界，最后生成出在生产环境里不安全、或者在负载下噪声很大的重试逻辑。

python-resilience 会自动帮我选定精确的重试策略吗？

不会自动替你定死。它提供的是一套很强的模式语言，但最佳策略仍取决于你的依赖行为、延迟要求和幂等性规则。你应该预期还需要根据实际环境调整尝试次数、等待区间和重试过滤条件。

如何改进 python-resilience skill 的使用效果

先把失败分类说清楚

想提升 python-resilience 的结果质量，最快的方法就是明确哪些失败是 transient，哪些是 permanent。例如：

• transient: ConnectTimeout, ReadTimeout, 503, some 429
• permanent: 400, 401, 403, schema errors, bad credentials

这一个区分，往往就决定了生成出来的策略是否安全。

提供延迟预算和重试预算

如果你不提供 budget，模型就可能随意选择重试次数。最好明确给出这类限制：

• max 3 attempts
• total retry window under 8 seconds
• single request timeout 2 seconds
• background job can tolerate 30 seconds total

这些约束能让生成出来的代码更贴近真实环境。

明确告诉它操作是否幂等

很多韧性设计错误，根源都是缺少副作用上下文。想改善 python-resilience usage，可以直接标记操作属于哪一类：

• safe to retry
• safe only with idempotency key
• unsafe to retry automatically

这会同时影响 decorator 设计和异常过滤规则。

主动要求明确的“不可重试”规则

不要只问“哪些应该重试？”，也要一起问：

• 哪些应该 fail fast？
• 哪些应该立刻暴露给调用方？
• 哪些应该记录日志但不重试？

这样产出的内容会更接近可直接用于生产的方案。

要求实现中包含可观测性

一个好的 python-resilience guide 不该只停留在 decorator。你可以要求模型额外加上：

• 日志中的 attempt count
• exception type
• elapsed time
• final failure reason
• retry exhaustion message

缺少这些信息时，你的韧性层很可能会把“为什么调用失败”这件事隐藏掉。

在第一版结果基础上继续迭代

拿到第一版输出后，用更具体的反馈继续收敛，例如：

• “Do not retry POST requests.”
• “Cap total time, not just attempts.”
• “Handle 429 differently from 500.”
• “Use jitter to avoid synchronized retries.”
• “Separate timeout config from retry config.”

这类迭代会实质性提升最终实现质量。

把技能建议的失败路径测试出来

可以要求模型为这些情况生成测试：

• transient exception retries
• permanent exception fast-fail behavior
• retry exhaustion
• timeout enforcement
• backoff policy boundaries

没有经过测试的 resilience 代码，很容易配置错误，也很难让人真正放心使用。

用真实 trace 提升 python-resilience 输出质量

如果你手头有日志或样例 stack trace，尽量一并提供。真实的失败证据，往往能帮助 python-resilience 给出更窄的异常过滤规则，以及更可信的 timeout/backoff 设置，而不是停留在抽象层面。

把抽象层级控制在适中范围

一个常见失败模式是：你其实只需要一个可靠的 client wrapper，却让技能去设计整套 resilience framework。更好的做法是从小处开始：

• one function
• one dependency
• one retry policy

等这个模式被验证有用后，再逐步扩展。

把 python-resilience 当作审查视角来用

即使代码已经写好了，python-resilience 仍然很适合作为 reviewer prompt。你可以让它检查现有重试逻辑里是否存在：

• unbounded retries
• missing jitter
• bad timeout placement
• retrying permanent failures
• hidden side-effect risks

在成熟代码库里，这种以审查为导向的用法，往往反而是这个技能最有价值的使用方式。