python-performance-optimization

python-performance-optimization 技能概览

python-performance-optimization 技能能做什么

python-performance-optimization 技能帮助智能体定位 Python 代码为什么运行慢、为什么占用内存高，并基于 profiling 证据而不是凭感觉给出有针对性的优化建议。它面向真实的性能优化场景：找出瓶颈、区分 CPU / 内存 / I/O 问题，并选择真正符合当前高负载代码路径的改进方案。

谁适合安装它

这个技能最适合开发者、数据工程师、后端团队，以及那些不满足于泛泛“让它更快一点”建议的 agent 工作流。尤其适合这样的场景：你已经有一个功能上可用的脚本、服务、notebook 或 pipeline，但现在需要进一步改善延迟、吞吐量或内存表现。

它实际解决的核心问题

大多数用户并不只是想听一段关于 Big O 的理论说明——他们真正需要的是一套可复用的方法，去回答这些问题：

• 到底哪里慢
• 应该怎样正确测量
• 哪个优化最值得优先做
• 如何避免改动那些并非瓶颈的代码

这正是 python-performance-optimization 技能比普通 prompt 更强的地方。它会把整个流程引导到“先 profiling，再优化”。

这个技能的差异化在哪里

这个仓库不是把性能问题当成单一问题来处理，而是覆盖了多种 profiling 模式和不同层级的优化手段，包括：

• CPU profiling
• memory profiling
• 行级分析
• call graph 思路
• 像 caching 这样的实现模式
• 更进阶的路径，例如 NumPy vectorization、async I/O 和 parallelization

它最实用的差异点，在于覆盖面广，而且始终坚持 profiling-first 的思路。

最适合与不适合的使用场景

适合：

• 变慢的 Python endpoint、job、CLI 工具、ETL 或数据处理流程
• 内存持续增长或 RAM 异常飙升
• 需要在 caching、算法调整、vectorization 或 concurrency 之间做取舍
• 在动生产代码之前先制定优化方案

不适合：

• 真正瓶颈在基础设施、网络拓扑或数据库 schema，而且手头没有任何测量数据的代码库
• 希望开箱即用拿到全自动 benchmarking 脚本的团队
• 只想做代码风格清理，而不是性能诊断的场景

如何使用 python-performance-optimization 技能

python-performance-optimization 的安装方式

从 wshobson/agents 仓库安装这个技能：

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

安装后，当你的 prompt 明确涉及 Python 性能诊断、profiling、内存使用、延迟优化、吞吐提升或瓶颈分析时，就可以调用它。

先读这两个仓库文件

如果你想最快建立正确理解，建议先看：

1. plugins/python-development/skills/python-performance-optimization/SKILL.md
2. plugins/python-development/skills/python-performance-optimization/references/advanced-patterns.md

SKILL.md 提供主流程和工具分类。当前期诊断已经指向 vectorization、caching、内存调优、async I/O 或数据库负载较重的问题时，references/advanced-patterns.md 会是非常有价值的第二份阅读材料。

要让技能发挥效果，你需要提供什么输入

python-performance-optimization usage 的效果，很大程度取决于你提供的证据质量。最好给智能体这些信息：

• 哪个函数、文件、endpoint 或 job 很慢
• 预期工作负载规模
• 实际症状：延迟高、CPU 打满、内存增长、timeout、query 数过高
• profiling 输出（如果已有）
• 约束条件：不能加依赖、必须保持 API 不变、只能给出 production-safe 方案等
• 环境细节：Python 版本、框架、OS、单进程还是多进程

没有这些输入时，这个技能仍然可以建议你怎么做 profiling，但给出的建议会更泛，针对性更弱。

把模糊需求改写成高质量 prompt

弱 prompt：

• “Optimize this Python code.”

更好的 prompt：

• “Use the python-performance-optimization skill to analyze this Django view. P95 latency is 1.8s under ~200 requests/min. CPU is high, memory is stable. Here is the view code and a cProfile summary. Identify the top bottlenecks, explain whether the issue is Python execution, DB access, or serialization, and propose fixes ranked by expected impact and implementation risk.”

之所以这样更有效，是因为它同时给出了负载规模、症状类型、证据，以及你希望输出的格式。

先做诊断，再要求改代码

一个更合理的工作流通常是：

1. 先描述性能症状
2. 提供代码和测量数据
3. 让智能体先判断瓶颈类型
4. 然后再要求给出代码改动建议

这样可以避免过早重写代码。python-performance-optimization skill 在“根据指标推导干预方案”这件事上，比在没有证据时直接改代码更有价值。

哪些 profiling 输入会明显提升输出质量

最有帮助的输入包括：

• 面向 CPU 密集型代码的 cProfile 汇总
• 热点函数的 line-profiler 结果
• 面向 RAM 问题的 memory-profiler 或对象增长证据
• 围绕 I/O、DB、HTTP 和 serialization 边界的耗时拆分
• 具有代表性的样本数据，而不是 toy input

如果你还没有任何测量数据，最好先让智能体设计一套 profiling 方案，而不是盲目开始优化。

python-performance-optimization 支持的典型工作流

一份实用的 python-performance-optimization guide 通常会长这样：

1. 明确性能目标
2. 选择合适的 profiling 类型
3. 对有代表性的工作负载做 profiling
4. 找出最热路径或最大内存分配点
5. 选择风险最低、收益最高的优化项
6. 对比优化前后 benchmark
7. 检查正确性和可读性是否出现回退

这套顺序，就是这个技能最核心的价值所在。

什么情况下该看 advanced reference

当瓶颈大概率落在以下这些方向时，再去打开 references/advanced-patterns.md：

• 可能从 NumPy 中受益的数值循环
• 可能适合用 functools.lru_cache 的重复纯函数计算
• 可能适合 async 模式的高 I/O 负载
• 可能适合 multiprocessing 的高成本可并行工作
• 需要用数据库优化思路来处理的高 query 负载应用

不要一开始就跳过去，除非你已经很清楚问题属于哪个类别。先从已测量到的瓶颈出发。

常见场景下好用的 prompt 模式

对于 CPU-bound 代码：

• “Use the python-performance-optimization skill to review this function and cProfile output. Focus on algorithmic complexity, repeated work, and Python-level loop overhead.”

对于内存问题：

• “Use the python-performance-optimization skill to inspect this batch job. RSS climbs from 400MB to 3GB. Suggest likely retention causes, profiling steps, and memory-safe refactors.”

对于 I/O-heavy 服务：

• “Use the python-performance-optimization skill on this async API client. Requests are slow despite low CPU. Determine whether the bottleneck is blocking I/O, connection handling, serialization, or concurrency limits.”

可以期待它产出什么结果

这个技能最擅长的是：

• 选择合适的 profiling 方法
• 解读常见性能模式
• 按优先级提出可信的优化建议
• 解释 caching、vectorization、parallelization 与代码简化之间的取舍

如果你不给代码、不给工作负载形态、也不给测量数据，那它的结果会明显弱很多。

python-performance-optimization 技能 FAQ

在性能优化场景里，python-performance-optimization 比普通 prompt 更好吗？

通常是的，尤其当你需要的是结构化诊断，而不是临时拼凑的建议。普通 prompt 往往会直接跳到“上 caching”或“用 NumPy”。python-performance-optimization 技能更可能先把 CPU、内存、I/O 和算法层面的问题分开来看。

这个技能对新手友好吗？

友好，只要你能提供代码和症状。你不需要一开始就是 profiling 专家。但对新手来说，如果能提供更具体的证据，并要求智能体先解释“为什么这里是瓶颈”，再给修复建议，效果会好得多。

使用前必须先有 profiling 输出吗？

不需要，但有的话，python-performance-optimization usage 的效果会显著更好。如果你还没有测量数据，可以直接让智能体告诉你：具体该 profile 什么、该用哪类工具。

什么情况下不该用这个技能？

如果问题明显不在 Python 应用逻辑层，就不该把它当主工具，例如：

• 基础设施资源本身不足
• 网络故障
• 数据库服务器配置错误，而且没有任何应用层证据
• 与 Python 后端执行无关的前端延迟

这些情况下，这个技能仍然可以帮助你梳理排查方向，但它不是最合适的一线工具。

它既能看速度问题，也能看内存问题吗？

可以。这个仓库明确覆盖了 memory profiling 和 memory optimization，同时也包括 CPU profiling 与执行时间分析，所以它比那类只谈“提速”的 prompt 更实用。

它能处理数据类工作负载吗？

可以，尤其适合那些优化路径可能涉及 vectorization、batching、caching，或减少 Python 循环开销的场景。对于数值计算和数据处理代码，advanced reference 尤其值得看。

如何改进 python-performance-optimization 技能的使用效果

提供 benchmark 证据，而不只是源代码

想提升 python-performance-optimization 的结果，最有效的一件事就是提供：

• 优化前 / 后耗时
• profiling 汇总
• 样本输入规模
• 吞吐或延迟目标

只有源代码时，智能体只能做推测；有了测量数据，它才能真正排优先级。

明确你怀疑的瓶颈类型

即使你并不完全确定，也可以直接说出你的怀疑：

• CPU-bound
• memory-bound
• database-bound
• network/I/O-bound
• 启动时间问题
• batch 吞吐问题

这样能帮助技能更快选对诊断路径，避免落入泛泛建议。

把真实约束说清楚

优化建议会因为约束不同而发生很大变化。请直接说明：

• 不能改 public API
• 不能引入 NumPy
• 必须保证初级团队成员也能读懂
• 必须运行在 AWS Lambda
• 必须保持确定性顺序
• 多租户场景下的内存上限是固定的

这些信息比单纯要求“最佳性能”更能提升决策质量。

要求按优先级排序给建议

一个高质量 prompt 应该要求智能体按以下维度排序建议：

1. 预期收益
2. 实现成本
3. 正确性风险
4. 依赖成本

这样可以避免一种常见失败模式：第一轮回答就给出很复杂的改造方案，却忽略了像减少重复计算、修正低效查询这类更简单、更划算的优化点。

留意常见失败模式

python-performance-optimization skill 的效果常常会被以下情况削弱：

• 优化了根本不在 hot path 上的代码
• 使用与生产负载不匹配的 microbenchmark
• 过度追求炫技代码，牺牲可维护性
• 在 I/O 或 GIL 特性决定其并不合适时，仍然生搬硬套 multiprocessing
• 推荐 caching，却不讨论失效策略或内存成本

最好要求智能体针对“已测量到的瓶颈”逐条论证每个优化建议的合理性。

根据第一轮结果继续迭代

一个很强的第二轮 prompt 可以是：

• “Here is the updated code and new benchmark. The runtime dropped from 2.4s to 1.5s, but memory increased by 35%. Re-run the python-performance-optimization analysis and suggest the next best change with minimal memory growth.”

这样你用的就不再是一次性改写工具，而是一个持续迭代的优化闭环。

有策略地指定仓库阅读路径

如果第一轮回答还比较泛，可以明确要求智能体把推理锚定到：

• SKILL.md：用于 profiling 分类和整体工作流
• references/advanced-patterns.md：用于查 implementation options，例如 vectorization、caching、memory management、parallelization、async I/O 和 benchmarking

这样通常能明显提升输出的具体程度。

当团队还不知道怎么开始时，先让它给测量计划

如果你的障碍是“我们根本不知道从哪开始”，那就让它先给一份最小可行方案：

• 先测什么
• 哪类 profiler 更合适
• timer 应该放在哪些位置
• 应该复现什么样的工作负载
• 用什么指标来判断成功

对于还处在起步阶段的团队来说，这往往是 python-performance-optimization guide 最有价值的使用方式之一。