performance-profiler

性能分析器

基于分析的性能审查。每项建议都有证据支撑。 包含 6 种模式的流程：Analyze、Profile、Cache、Benchmark、Regression、Leak-Patterns。

**范围：**仅提供性能分析和建议。不用于运行分析器、执行负载测试、监控基础设施或实际检测内存泄漏。此技能提供基于分析的指导，不提供测量结果。

规范术语

在所有模式中统一使用以下术语：

术语	定义
complexity（复杂度）	函数或代码路径的 Big-O 算法分类
hotspot（热点）	资源消耗（时间或内存）不成比例的代码区域
bottleneck（瓶颈）	限制整体吞吐量的系统约束
profiler output（分析器输出）	用户粘贴的 cProfile、py-spy、perf 或类似工具的文本数据
cache strategy（缓存策略）	缓存层的淘汰策略、写入策略和失效方式
benchmark skeleton（基准测试框架）	用于以正确方法测量函数性能的代码模板
regression risk（回归风险）	代码更改导致性能下降的可能性，分为 LOW/MEDIUM/HIGH/CRITICAL
anti-pattern（反模式）	已知会损害性能的代码模式（N+1、无界分配等）
evidence（证据）	具体依据：AST 分析、分析器数据、代码模式匹配或外部参考资料
recommendation（建议）	可执行的优化建议，包含预期影响和权衡
flame graph（火焰图）	调用栈采样数据的层级可视化图
wall time（墙上时间）	实际经过的时间（包括 I/O 等待），与 CPU 时间（仅计算）相对

分发

$ARGUMENTS	模式
analyze <file/function>	算法复杂度分析、Big-O 审查
profile <data>	解读文本分析器输出（cProfile、py-spy、perf）
cache <system>	缓存策略设计（LRU/LFU/TTL/write-through/write-back）
benchmark <code>	基准测试设计与方法审查
regression <diff>	根据代码差异评估性能回归风险
leak-patterns	扫描常见内存泄漏模式（不是实际检测）
留空	显示各模式菜单及示例

模式 1：Analyze

对文件或函数进行算法复杂度分析。

Analyze 第 1 步：扫描

运行复杂度估算脚本：

uv run python skills/performance-profiler/scripts/complexity-estimator.py <path>

解析 JSON 输出。如果脚本运行失败，则手动进行 AST 级分析。

Analyze 第 2 步：分类

对于范围内的每个函数：

1. 确定循环嵌套深度、递归模式和数据结构操作
2. 使用 references/complexity-patterns.md 映射到 Big-O 分类
3. 评估热点风险：嵌套深度 * 调用频率 * 数据规模敏感度
4. 标记热点路径中复杂度为 O(n^2) 或更高的函数

Analyze 第 3 步：报告

以表格形式呈现发现：

函数	估算复杂度	证据	热点风险	建议

对每项建议都提供权衡分析。

模式 2：Profile

解读用户粘贴的文本分析器输出。

Profile 第 1 步：解析

对用户提供的数据运行分析器解析脚本：

uv run python skills/performance-profiler/scripts/profile-parser.py --input <file>

如果数据以内联形式提供，先将其保存到临时文件。解析 JSON 输出。

Profile 第 2 步：识别热点

根据解析后的数据：

1. 按累计时间对函数排序（前 10 个）
2. 找出调用次数多但单次调用耗时低的函数（可能存在开销）
3. 找出调用次数少但单次调用耗时高的函数（优化候选项）
4. 检查 I/O 密集型与 CPU 密集型模式（墙上时间与 CPU 时间的比值）

Profile 第 3 步：提出建议

针对每个热点，提供：

• 结合分析器数据证据提出的根因假设
• 优化方案及预期影响范围
• 优化的权衡与风险
• 指向 references/anti-patterns.md 中相关反模式的参考

模式 3：Cache

为所描述的系统设计缓存策略。

缓存步骤 1：了解访问模式

询问或根据代码推断：

1. 读写比例
2. 数据新鲜度要求（TTL 容忍度）
3. 缓存大小限制
4. 一致性要求（最终一致性还是强一致性）
5. 淘汰压力（工作集与缓存容量的关系）

缓存步骤 2：设计策略

使用 references/caching-strategies.md 决策树：

因素	LRU	LFU	TTL	写穿透	写回
读多、工作集稳定	良好	最佳	尚可	--	--
写多	--	--	--	安全	快速
严格新鲜度要求	--	--	最佳	最佳	有风险
内存受限	最佳	良好	尚可	--	--

缓存步骤 3：具体说明

提供：淘汰策略、写入策略、失效策略、预热方案和监控建议。包含容量规划公式。

模式 4：基准测试

设计基准测试和审查方法。

基准测试步骤 1：生成骨架

运行基准测试设计脚本：

uv run python skills/performance-profiler/scripts/benchmark-designer.py --function <signature> --language <lang>

解析 JSON 输出中的设置代码、基准测试代码、迭代次数和预热设置。

基准测试步骤 2：审查方法

根据基准测试最佳实践进行验证：

1. 预热时间足够长，能使 JIT／缓存趋于稳定
2. 迭代次数足以保证统计显著性
3. 测量不包含设置／清理开销
4. 环境受控（不受其他进程干扰）
5. 结果包含方差／百分位数，而不仅是平均值

基准测试步骤 3：交付

提供完整的基准测试代码、方法说明、预期指标和结果解读指南。

模式 5：回归

评估代码差异带来的性能回归风险。

回归步骤 1：收集差异

如果提供了路径，则读取差异。如果提供了 git 范围，则运行 git diff。找出变更的函数及其调用位置。

回归步骤 2：评估风险

针对每个变更的函数：

风险因素	权重	检查项
复杂度增加	3x	是否增加了循环嵌套、是否更改了算法
热路径变更	3x	函数是否在请求／渲染路径中调用
数据结构变更	2x	集合类型或大小假设是否变更
I/O 模式变更	2x	是否新增网络／磁盘调用、是否移除了批处理
内存分配	1x	循环中是否新增分配、缓冲区是否变大

风险分数 = 权重与严重程度乘积之和。映射为 LOW／MEDIUM／HIGH／CRITICAL。

回归步骤 3：报告

提供回归风险矩阵，包含：

• 每个函数的风险评估及证据
• 此次差异的总体风险分数
• 合并前建议进行基准测试的目标
• 需要验证的具体测量项（分析什么、在哪里分析）

模式 6：泄漏模式

扫描常见的内存泄漏模式。仅进行静态分析——不进行实际泄漏检测。

泄漏步骤 1：扫描

读取目标文件，并根据 references/leak-patterns.md 中的模式进行检查：

• 事件监听器不断累积且未清理
• 闭包捕获的引用阻止垃圾回收
• 集合不断增长且没有上限（无界缓存、只追加的列表）
• 使用引用计数的语言中存在循环引用
• 资源句柄未关闭（文件、连接、游标）
• 全局状态不断累积

泄漏步骤 2：分类

针对发现的每种潜在泄漏模式：

模式	语言	严重程度	误报风险

泄漏步骤 3：报告

提供带代码引用的发现，说明每种模式为何可能导致泄漏，并提出修复建议。说明静态分析的误报率较高，并建议使用实际的性能分析工具进行确认。

扩展策略

范围	策略
单个函数	直接分析，内联报告
单个文件（< 500 LOC）	借助脚本进行分析，提供结构化报告
多个文件／模块	为每个文件并行使用子 Agent，并汇总报告
完整代码库	优先检查入口点和热路径，进行基于采样的分析

参考文件

一次加载一个参考文件。不要将所有参考文件预先加载到上下文中。

文件	内容	读取时机
references/complexity-patterns.md	代码模式到 Big-O 的映射及示例	模式 1（分析）
references/caching-strategies.md	缓存决策树、淘汰策略及权衡	模式 3（缓存）
references/anti-patterns.md	性能反模式目录（N+1、无界分配等）	模式 2（分析性能）、模式 5（回归）、模式 6（泄漏）
references/leak-patterns.md	各语言的内存泄漏模式（Python、JS、Go、Java）	模式 6（泄漏模式）
references/profiler-guide.md	性能分析器输出解读、火焰图阅读	模式 2（分析性能）
references/benchmark-methodology.md	基准测试设计最佳实践、统计方法	模式 4（基准测试）

脚本	运行时机
scripts/complexity-estimator.py	模式 1 — 通过 AST 进行静态复杂度分析
scripts/profile-parser.py	模式 2 — 将 cProfile/pstats 文本输出解析为 JSON
scripts/benchmark-designer.py	模式 4 — 根据函数签名生成基准测试框架

模板	渲染时机
templates/dashboard.html	任何模式完成后 — 将结果 JSON 注入 data 标签

数据文件

文件	内容
data/complexity-patterns.json	代码模式到 Big-O 的映射（机器可读）
data/caching-strategies.json	缓存决策树（机器可读）
data/anti-patterns.json	性能反模式目录（机器可读）

关键规则

1. 绝不声称测量了性能 — 此技能提供的是分析，而非测量
2. 每条建议都必须说明权衡 — 不要只说“直接做 X”
3. 始终承认复杂度估算存在不确定性 — 静态分析有其局限
4. 绝不建议过早优化 — 先确认代码确实处于性能热点路径上
5. 解读性能分析器输出时，必须引用具体数据点，而非泛泛而谈
6. 缓存策略建议必须说明如何处理失效 — “缓存失效很难”不算策略
7. 基准测试设计必须包含预热、统计显著性和方差报告
8. 回归风险评估必须追溯到具体代码变更，而非笼统担忧
9. 泄漏模式扫描仅基于模式匹配 — 始终建议通过实际性能分析进行确认
10. 一次加载一个参考文件 — 不要将所有参考文件预先加载到上下文中
11. 先提供带有证据的发现，再建议修复（审批关卡）
12. 反模式发现必须引用代码 [file:line] — 不要给出泛泛的警告