追风 (zhuifeng-perf-tuning) · 性能瓶颈诊断与调优
一、定位
追风 是性能诊断与调优专项 skill。它把"性能优化"从"凭感觉改代码"变为可测量、可归因、可验证的工程闭环：
先量化基线，再定位真正瓶颈，定向优化，最后用同一口径复测证明收益。杜绝"优化了个寂寞"。
V1.1 起随包提供三个零依赖脚本（纯 Python 标准库、不联网、不读敏感路径），把方法论落到可执行：
基线能测、慢日志能析、执行前能自检。
二、何时使用（触发方式）
- 性能优化 / 性能调优 / 性能瓶颈 / 慢
- 接口慢 / 页面加载慢 / 慢查询 / 慢 SQL
- 内存泄漏 / CPU 高 / GC 频繁 / 并发瓶颈
- 性能测试 / 压测分析 / 压测报告解读
- Core Web Vitals / LCP / CLS / INP 优化
2.1 触发表达最佳实践
「说"慢"能触发，但说清三件事，结论质量差一个量级。」
| 表达 | 示例 | 效果 |
|---|---|---|
| ✅ 推荐（对象 + 现状 + 目标） | "订单查询接口 P95 是 1.8s，目标降到 200ms 以内，帮我定位瓶颈" | 可直接进入基线测量，无需反复追问 |
| ✅ 推荐（场景 + 现象 + 范围） | "列表页首屏要 4 秒才出来，LCP 一直不达标，主要影响移动端用户" | 能锁定前端 CWV 方向 |
| ⚠️ 可触发但低效 | "接口有点慢" | 缺对象、缺现状、缺目标，需先补全输入（见第四节） |
| ⚠️ 可触发但低效 | "帮我优化一下性能" | 范围过大，必须先收敛到具体接口/页面 |
关键提示：带上量化目标（如"P95 < 200ms"）能让优化方案有的放矢；没有目标时，默认按
"在现有基线基础上量化提升"处理，但仍须先建立基线。
三、能力边界（先说清能帮到什么程度）
> 免责声明（前置）：本 skill 产出的是技术方案与测量数据，不构成任何性能承诺；
> 实际效果以同口径复测数据为准，涉及生产变更须自行灰度验证并保留回滚。
避免期望过高——明确三类清单：
3.1 能做到的
- 建立可复现的性能基线，给出 P50/P95/P99、吞吐、错误率等量化指标。
- 用证据定位 top 瓶颈（慢日志聚合、EXPLAIN 执行计划、火焰图、profiler 数据），不靠猜。
- 给出针对 top 瓶颈的优化方案，每条标注预期收益 + 风险 + 验证方式。
- 用同一口径复测，输出优化前后对比与提升百分比。
- 覆盖前端 CWV / 后端应用 / 数据库 / 网络四层的分层下钻。
3.2 做不到的（重要）
- 不能替代容量评估与全链路压测：本 skill 给出的是单接口/单页面的诊断，不等于系统容量结论。
- 不能保证特定优化幅度：收益取决于瓶颈类型（缺索引 vs 架构问题差异巨大），不承诺具体百分比。
- 不能替代生产灰度与回滚预案：任何生产变更必须自行灰度、保留回滚，本 skill 只给方案不给执行授权。
- 不能直接改线上代码/配置：产出是方案与报告，落地执行由人确认。
- 前端 CWV 需要真实用户数据或 Lighthouse 环境：仅有代码无法凭空算出 LCP。
3.3 预期收益区间（经验参考，非承诺）
| 瓶颈类型 | 典型收益量级 | 说明 |
|---|---|---|
| 缺索引 / 索引失效 | 接口耗时 ↓50%–90% | 收益最高、风险相对可控 |
| N+1 查询 / 循环查库 | ↓40%–80% | 改批量或 join |
| 加缓存（命中率高） | ↓30%–70% | 须先确认瓶颈在读不在写 |
| 前端资源体积 / 加载策略 | LCP ↓20%–50% | 受网络与设备影响大 |
| 锁竞争 / 线程池配置 | ↓20%–50% | 需压测反复调参 |
| 纯 CPU 密集算法 | ↓10%–40% | 收益通常低于预期，先确认是否真瓶颈 |
> 上表为经验区间，实际以复测数据为准。
四、前置信息与输入校验清单
4.1 四项输入与校验规则
开始调优前，按下表逐项校验。任何一项不合法或缺失，必须主动告知用户"缺什么、为什么需要"，
而不是默默用默认值往下跑——这是本 skill 的硬性要求。
| 输入 | 校验规则 | 缺失/不合法时的标准追问话术 |
|---|---|---|
| 优化对象 | 必须是具体的接口 URL / 页面路径 / 服务名 / SQL，不能是"整个系统" | "需要先确定优化对象：是哪一个接口/页面？（例如 /api/orders 或"订单列表页"）范围太大会无法归因。" |
| 性能现状 | 已有的量化指标（P95/LCP/耗时），或可复现的慢场景 | "目前观测到的指标是多少？比如 P95 多少毫秒、LCP 几秒。如果还没有数据，我先用 perf_baseline.py 帮你测一版基线。" |
| 目标 | 可量化指标（如 P95<200ms、LCP<2.5s），或明确"先量化现状" | "期望达到什么指标？（例如 P95 < 200ms）没有明确目标的话，我按"先建基线再谈优化"处理。" |
| 技术栈 | 语言/框架/数据库（影响定位手段与优化手法） | "后端是什么技术栈？数据库用的哪种？（例如 Java + MySQL）这决定了索引与 JVM 调优的具体做法。" |
4.2 追问原则
- 一次问全：把缺失项合并成一轮提问，不要挤牙膏式反复打断。
- 给示例：每个追问都带上具体示例，降低用户回答成本。
- 可降级：用户确实拿不到某项（如没有历史指标）时，明确记录"该项缺失，已改用 X 方式补偿"，而不是假装拥有。
五、工作流（agent 执行）
步骤 0 执行前自检 : python scripts/check_input.py --url <URL> [--log <慢日志>] [--tools wrk,mysql]
提前暴露环境/输入问题（工具未装、目标不可达、日志格式不对）。
有 FAIL 项必须先修复，不带着问题往下跑。
步骤 1 基线测量 : 用同口径测当前性能，记录指标（前端 CWV / 接口 P50/P95/P99 / DB 耗时 / 资源占用）。
HTTP 接口用：python scripts/perf_baseline.py --url <URL> --concurrency N --duration S
--tag baseline --json baseline.json
禁止无基线就谈优化。
步骤 2 瓶颈定位 : 分层下钻——前端（网络/渲染/JS）、网关、应用（CPU/内存/锁/IO）、数据库（慢查询/索引/锁）。
数据库层用：python scripts/slowlog_analyzer.py --log <慢日志> --top 20 --csv top.csv
用 profiling / 慢日志 / 火焰图 / explain 定位 top 瓶颈，不猜。
步骤 3 定向优化 : 针对 top1 瓶颈给优化方案（索引/缓存/异步/池化/减少往返/批处理），
每条标注「预期收益 + 风险 + 验证方式」。一次只动一个变量。
步骤 4 复测验证 : 同口径复测：python scripts/perf_baseline.py ... --tag after-opt --json after.json
再用 baseline_report.py 统一基线并自动出对比（v1.2 新增）：
python scripts/baseline_report.py merge --http baseline.json [--slowlog slow.json] --tag baseline --out base.json
python scripts/baseline_report.py merge --http after.json [--slowlog slow2.json] --tag after --out after_base.json
python scripts/baseline_report.py compare --base base.json --after after_base.json --out compare.md
自动量化前后提升（%），回归项（劣化>5%）与「新增慢SQL」自动标记，不达预期则回滚并记录原因。
步骤 5 输出报告 : 按 templates/perf-report.md 生成性能优化报告（基线 vs 优化后 + 优化项明细 + 遗留风险），
compare.md 的对比表可直接贴入报告「复测验证」一节。
5.1 脚本使用要点
- 四个脚本均为纯 Python 标准库，无需
pip install，Python ≥ 3.8 即可运行。 - 退出码语义统一：0 = 成功，1 = 执行失败，2 = 参数错误。脚本会给出明确的中文错误原因与正确示例。
perf_baseline.py并发 >100 或时长 >120s 时，须显式加--i-know-this-is-prod，防止误压生产。- 拿不准参数时先用
--dry-run预演，确认无误再真跑。 baseline_report.py（v1.2 新增）只做本地 JSON 合并与对比：merge 至少给--http/--slowlog之一；
compare 两边都必须是 merge 产出的zhuifeng-baseline/v1格式。- 慢日志可能含敏感信息，脚本纯本地解析、不联网、不上传。
六、性能分析分层速查
| 层 | 常见瓶颈 | 定位手段 | 典型优化 |
|---|---|---|---|
| 前端 | 大包、慢渲染、长任务 | Lighthouse / Performance / CWV | 懒加载、代码分割、缓存、CDN |
| 应用 | CPU 高、锁竞争、GC 频繁 | 火焰图 / profiler / 线程 dump | 异步化、池化、减少锁粒度 |
| 数据库 | 慢查询、缺索引、锁表 | 慢日志 / explain / 锁监控 | 加索引、SQL 重写、读写分离 |
| 网络 | 往返多、串行请求 | 抓包 / 链路追踪 | 合并请求、HTTP/2、就近接入 |
七、异常情况处置表
遇到下列情况不得静默跳过，必须明确告知用户并按处置动作执行：
| # | 异常情况 | 处置动作 | 告知用户的话术 |
|---|---|---|---|
| 1 | 目标环境不可达 / 连接被拒 | 用 check_input.py 复核；检查服务是否启动、地址与端口、防火墙 |
"目标连不上，先确认服务是否启动、地址端口是否正确——基线测不了，后面的优化没法验证。" |
| 2 | 完全没有历史性能数据 | 先用 perf_baseline.py 建基线，不允许跳过基线直接优化 |
"目前没有历史指标，我先用压测脚本测一版基线，有了基线才能判断优化是否有效。" |
| 3 | 压测可能影响生产 | 降低并发/时长，或改在预发/灰度环境；必须压生产时加 --i-know-this-is-prod 并提前报备 |
"这个压测强度可能影响线上。建议先降到并发 20 或改到预发环境；确需压生产请确认并留好回滚。" |
| 4 | 慢日志格式不匹配 / 解析为 0 条 | 检查是否开启慢日志、是否 MySQL/Percona 格式；降低 --threshold |
"日志没解析出记录。请确认慢日志已开启且为标准 MySQL 格式（含 # Query_time: 行），或把阈值调低。" |
| 5 | 优化后反而变慢 / 不达预期 | 回滚该优化项，记录原因，换下一个瓶颈；严禁为了"有成果"而保留负收益改动 | "这版改动实测是负收益（P95 从 520ms 升到 610ms），建议回滚，我们换下一个瓶颈再试。" |
| 6 | 一次被要求改多个变量 | 拆成逐项验证，每次只动一个 | "同时改三处就无法归因了。我们一次只改一处、测一次，才能知道哪处真正有效。" |
| 7 | 瓶颈数据不足，无法定位 | 补充采集（开启慢日志 / 打火焰图 / 加埋点），不臆断瓶颈 | "现有数据还定位不到瓶颈。需要先开启慢日志 / 抓一次火焰图，避免凭猜测优化。" |
| 8 | 目标环境无 Python 或版本过低 | 改用纯分析方法；或说明需 Python ≥ 3.8 | "当前环境 Python 版本低于 3.8，脚本跑不了。我改用纯分析方法，或请先升级 Python。" |
八、质量门控
- 无基线不优化：任何优化前必须有可复现的基线指标。
- 一次只动一个变量：多优化项须逐项验证，避免归因混淆。
- 量化收益：每个优化项必须有前后对比数据，禁止"感觉变快了"。
- 标注风险：加索引/加缓存等可能有副作用的优化，须标注风险与回滚方式。
- 异常不静默：出现第七节任一情况，必须明确告知，不得跳过或假装成功。
- 零结果视为失败：脚本解析到 0 条记录、压测全部失败，均按失败处理，不产出"看起来正常"的空报告。
九、输出格式
报告按 templates/perf-report.md 模板生成，结构如下：
# 性能优化报告
优化对象 / 目标指标 / 测试环境与口径
## 基线（表格：指标/基线值）
## 瓶颈定位（top 瓶颈 + 证据：火焰图/慢日志/explain）
## 优化项明细（表格：项/预期收益/风险/验证方式）
## 优化后复测（基线 vs 优化后 对比，提升 %）
## 遗留风险与后续建议
十、目录
zhuifeng-perf-tuning/
├── SKILL.md # 本文件
├── README.md # 人类可读简介
├── CHANGELOG.md # 版本记录
├── icon.svg / icon.png
├── scripts/ # 零依赖可执行脚本
│ ├── perf_baseline.py # HTTP 接口基线/复测压测
│ ├── slowlog_analyzer.py # MySQL 慢日志聚合分析
│ ├── baseline_report.py # 统一基线合并 + 基线vs复测对比（v1.2 新增）
│ └── check_input.py # 执行前环境与输入自检
├── templates/
│ └── perf-report.md # 性能优化报告模板
├── examples/
│ ├── case-01-backend-slow-api.md
│ └── case-02-frontend-lcp.md
└── references/
├── frontend-cwv.md # 前端 Core Web Vitals 优化要点
├── backend-tuning.md # 后端/并发/内存调优要点
├── database-tuning.md # 慢查询/索引/锁调优要点
└── faq.md # 常见问题解答
十一、免责声明
优化方案须结合具体环境验证，涉及生产变更须灰度发布并保留回滚，本 skill 不替代压测与容量评估。
随包脚本为辅助测量工具，其输出结果受网络、机器负载与环境差异影响，须结合业务实际判读，
不构成任何性能承诺。
