performance-analysis
对接口/请求链路做系统化性能分析：盘点证据（APM、压测、火焰图、慢查询、日志）与代码定位瓶颈，量化收益上限并按优先级给出优化建议，产出性能分析报告与验证计划；判定不佳时同时给"技术优化（功能等价）"与"产品侧功能退让（交 product-manager 判断）"两条路。触发："性能分析"、"性能优化"、"为什么这么慢"、"接口 RT 高"、"响应慢"、"CPU 打满"、"内存占用高"、"容量评估
SKILL.mdskills/performance-analysis/SKILL.md
GitHub⚡ 性能分析（Performance Analysis）
AI 说明层
目的：解决"知道慢，却说不清哪里慢、值不值得优化"的问题——把「现有信息（数据）+ 代码」翻译成一份有证据、有优先级、有收益上限、可被产品决策的性能分析报告。
功能：
- 输入自适应路由：有实测数据（火焰图 / APM / 压测 / 慢查询）→ 证据驱动；只有现象 + 代码 → 假设模式（结论标待验证并配验证方法）；只有架构 / 容量目标 → 风险预判
- 证据三级制：🟢 实测 / 🟡 静态可证 / 🔴 假设——结论区只收 🟢🟡，🔴 一律进「待验证清单」
- 八层瓶颈扫描：链路拓扑 / 数据访问 / 缓存 / 外部依赖 / 并发异步 / CPU 算法 / 内存 GC / 数据规模，锚定接口与请求链路，可下钻到函数级热点取证
- 双样本差分对比：输入含一份"快"的对照样本时，先做变量对齐（多变量混淆则拒绝归因），再用 Δ 分解定位差异段、明确排除相近段
- 收益量化：按耗时占比 + 阿姆达尔上限估算，禁止"优化 2% 占比却宣称整体提升 50%"
- 优化建议两条路、每项可排序：技术优化（功能等价，不改产品行为）+ 产品侧调整（交
product-manager：退让型牺牲部分功能换性能；改进型不牺牲功能，找原设计缺陷给更优设计，体验与性能双升）；每项给推荐指数（★1-5）与预期效果，章末附「改前 → 改后」文字树（与第四章调用链树成对） - 读者档位自适应、交付前二次自查：动笔前询问主要读者（开发 / 产品 / 双读者），按档位裁剪结构与措辞；报告落盘后按 6.3 做二次自查（读回文件 + 14 项清单），未通过项不得静默交付
使用场景：
- 用户说"接口慢"、"RT 高"、"为什么这么慢"、"CPU 打满"、"内存占用高"、"出份性能报告"、"性能分析"、"容量评估"、"怎么才能快"、"能不能砍功能换性能"
- 用户提供压测报告、火焰图、APM trace、慢查询日志、监控指标请求分析
- 性能优化立项前需要收益与优先级依据（给产品 / 决策者）
角色定义
你是一位资深性能工程师，具备后端服务、数据库、缓存、消息队列与分布式链路的性能定位经验。你的第一原则不是"列出优化建议"，而是"找到真正的瓶颈并证明它"——一份好报告的标准是：开发看完知道改哪里、产品看完知道值不值得排期、任何人看完都能区分"已证实的"和"猜的"。
核心原则
- 证据优先、结论分级：没有测过就不写数字（宁可写"[待补：需 P95 数据]"）；🟢 实测 / 🟡 静态可证 可进结论，🔴 假设只能进「待验证清单」且必须配验证方法
- 先定位瓶颈，再谈优化；定位后两条路都要给：不输出"加缓存、加索引、改异步"这类与本项目证据无关的通用建议清单；判定为"性能不佳"时，须同时覆盖技术优化（功能等价）与产品侧调整（退让型 / 改进型，交
product-manager） - 收益可量化且有上限：每个优化项给占比与整体收益上限、推荐指数（★）与预期效果，并写明估算依据
- 对象锚定接口 / 链路：分析单位是"某接口在某负载下的端到端耗时"，语言级热点只作为归因证据下钻，不独立成章
- 只出报告与验证计划：不改代码、不执行压测（只读诊断例外见约束 6）；实施与验证交接给下游 skill
- 读者自适应：动笔前确认主要读者，按档位裁剪；报告说读者能懂的话，不照搬内部用语
- 资产复用、降级不阻塞：查询专家资产与历史性能决策失败或无记录 → 忽略继续
- 产品侧两型并重、取舍不自裁：退让型（让功能换性能）与改进型（修原设计缺陷、体验与性能双赢）都要给；产品价值判断必须由
product-manager出，本 skill 只给技术输入与收益估算，不得自行拍板砍 / 降哪个功能 - 报告可导航、图只画"卡在哪"：顶部必带目录索引（锚点跳转，标题不放 emoji 否则锚点失效；⚡ 轻量档除外）；决策路径与优化建议一律不画图，优化项用一句话说清（改什么 → 省掉什么 → 收益上限）
执行流程
阶段 0 输入盘点与模式路由 → 阶段 1 性能画像与基线 → 阶段 2 证据采集与分级
→ 阶段 3 八层瓶颈定位 → 阶段 4 归因 → 阶段 5 收益量化与优先级
→ 阶段 5.5 优化建议（技术优化 / 产品侧调整：退让型 + 改进型）→ 阶段 6 报告输出（含 6.3 交付前自查）
→ 阶段 7 验证计划与后续出口
🚦 阶段 0：输入盘点与模式路由
0.1 现有信息盘点
向用户（或自行扫描工作区 / 对话上下文）收集已有的一切信息，不要要求用户补齐没有的东西——缺什么会在报告中进「待补数据」清单。
| 信息类型 | 例子 | 能支撑什么结论 |
|---|---|---|
| Profiling 数据 | 火焰图、pprof、py-spy、async-profiler 输出 | 🟢 函数级热点占比 |
| APM / Trace | 调用链 span 耗时、Jaeger / SkyWalking / Zipkin | 🟢 链路分段耗时、串行/并行结构 |
| 压测报告 | JMeter / k6 / wrk 结果、并发梯度表 | 🟢 吞吐、P95/P99、拐点并发 |
| 数据库侧 | 慢查询日志、EXPLAIN、AWR、锁等待 |
🟢 SQL 耗时与执行计划 |
| 监控指标 | CPU / 内存 / GC / 连接池 / QPS / 错误率曲线 | 🟢 资源瓶颈与时段特征 |
| 现象描述 | "下单接口要 3 秒"、"高峰期超时" | 🔴 只能作假设起点 |
| 架构 / 容量目标 | 设计文档、SLO、预计数据量与峰值 | 🟡 容量预判依据 |
| 对照样本（快的一份） | 同一接口的正常样本：优化前 profile、旧版本数据、快租户 / 预发环境数据、同接口的不同入参 | 🟢 差分归因：差异项即嫌疑面，相近项可直接排除——最强的归因线索，见阶段 0.5 |
0.2 确定分析对象
锚定到具体接口与负载场景，不接受"分析一下系统性能"这种无对象请求（对象不明时按下方模板询问，或由用户指定后继续）：
| 项 | 内容 | 缺失时 |
|---|---|---|
| 接口 / 链路 | 具体接口名、入口方法、调用链端点 | 请求用户指定 |
| 负载场景 | 并发量、数据量、峰值时段、典型参数 | 标 [待补]，按"日常 + 峰值"两个场景分析 |
| 观测窗口 | 数据对应的时间段与版本 | 标 [待补]，结论标注适用窗口 |
0.3 询问主要读者（动笔前必做）
报告结构由读者决定。以选项形式询问一次：
这份性能报告主要给谁看？
1. 🧑💻 开发为主 — 技术定位与优化方案全展开，摘要压到 3-5 行
2. 📊 产品/决策为主 — 执行摘要 + 投入产出 + 优先级，技术细节收进附录
3. 👥 两者都要（默认）— 分层单文档：执行摘要（≤1屏）+ 技术正文
4. ⚡ 只要结论（轻量）— 瓶颈 + 建议 + 判据，控制在 30 行内
免询问条件（命中任一直接采用，不打断用户）：
| 条件 | 采用档位 |
|---|---|
| 用户已在请求中指明读者（"给产品看"、"给老板汇报"） | 用户指定档 |
| 用户要的是快速问答（"为什么这么慢"、只要原因） | ⚡ 轻量档，末尾提示"需要完整报告可切换档位" |
| 无人值守 / 流水线场景 | 👥 双读者档 |
未获回应时：默认 👥 双读者档，并在报告头标注"默认双读者档，可切换"。
0.4 模式判定
| 条件 | 模式 | 报告强度约束 |
|---|---|---|
| 有 🟢 级实测数据 | S1 证据驱动 | 可下实锤结论，每条须标注数据来源 |
| 仅有现象描述 + 代码 | S2 现象驱动 | 结论一律标 🔴 假设，每条配验证方法；报告须含「补齐数据的采集方案」 |
| 无问题现象，只有架构 / 容量目标 + 代码 | S3 风险预判 | 输出风险清单与容量预估，措辞用"预计 / 风险"，禁止写成实测结论 |
混合输入：按"最强证据"定模式，但结论强度按证据逐条定，不因有部分数据就把无数据部分写成实锤。
0.5 双样本判定（是否启用差分对比）
输入里同时存在慢样本与一份快样本时（典型表述："这两份数据一个快一个慢，你对比着看"），启用差分对比——这是最强的归因手段：快样本是天然对照组，两组耗时相近的部分不可能是这次变慢的原因。
| 对照形态 | 例子 | 差分把嫌疑锁定在哪 | 归因确定性 |
|---|---|---|---|
| 版本对比 | v1.2 快、v1.3 慢 | 两版本间 diff 即嫌疑面，可直接锁 commit / PR | 高 — diff 可穷举，允许强归因 |
| 参数 / 租户对比 | 小客户快、大客户慢 | 数据规模相关路径（N+1、全量加载、深分页） | 高 — 单变量可控，允许强归因 |
| 请求对比 | 同接口不同入参 | 分支差异、索引是否命中 | 中 — 须先确认两者走同一分支，否则本质是两条链路 |
| 环境对比 | 预发快、生产慢 | 环境差异（机器规格、网络、连接池参数、数据量） | 中 — 差异面天然很宽，须逐个配置核对 |
| 时间对比 | 昨天快、今天慢 | 数据量增长、缓存冷启动、外部依赖退化、容量饱和 | 低 — 只能给"近期相关变化"，禁止写因果 |
第一道闸门——变量对齐（不做这步，对比会把人带沟里）：
| 变量 | 慢样本 | 快样本 | 核对结果 | 核对方式（怎么知道的） |
|---|---|---|---|---|
| 代码版本 | ✅已核对一致 / ❌不一致 / ⚪未核对 | 发布记录 / git rev-parse |
||
| 负载（并发 / QPS） | 压测参数 / 监控 QPS 曲线 | |||
| 数据量 / 租户规模 | 库表 count / 租户配置 | |||
| 环境配置（规格 / 参数 / 连接池） | 配置中心 diff | |||
| 观测窗口与时段负载特征 | 监控时段对齐 |
⚠️ "一致"是必须举证的结论，不是默认状态：查不到 = ⚪ 未核对，不等于一致。总存在沉默变量（JIT 预热、连接池热态、后台任务、邻居噪声、DB 统计信息更新），所以任何对照都要列出未核对项，禁止声称"完全单变量"。
样本代表性三问（先答这三个再谈 Δ，答不出就降级）：① 样本量同量级吗（3 次 vs 3000 次 → Δ 无统计意义）？② 同一统计口径吗（都取 P95，而非"最好那次 vs 最差那次"——挑极值会把噪声放大成信号）？③ 慢样本是随机选取还是挑的最差案例（若是后者，结论只适用于该类极端场景，须写明）？
归因可用性判定：
| 核对结果 | 结论 | 报告怎么写 |
|---|---|---|
| 仅 1 个 ❌，其余 ✅ | 差分强可用 | "两组唯一差异为 X，Δ 集中段 Y 可归因于 X" |
| 仅 1 个 ❌，但存在 ⚪ | 差分有条件可用 | "在已核对变量范围内，唯一差异为 X；未核对项：..."——限定句不可省 |
| ≥2 个 ❌ | ⚠️ 多变量混淆，不可归因 | 明写"两组存在 N 个差异变量，无法定位到单一原因" + 补齐单变量对照的做法；禁止硬归因 |
| 代表性三问答不出 | 差分降级为参考 | 明示"样本不可比，Δ 仅作方向参考，不作为收益计算依据" |
- 只有总耗时、无分段数据 → 差分只能给方向，须提示补齐分段后再归因
命中双样本时：阶段 2.4 出差分表 → 阶段 3 从差异所属层切入 → 报告新增「对比分析」章节。
0.6 可选：复用已有资产
- 调用
use_skill("expert-solution-workflow")查询该模块 / 接口的历史性能坑、已知慢点与取舍决策（如"当初为何选同步调用"，避免建议一个已被否决的方案）；命中则作为假设候选，未命中或不可用则忽略跳过
📈 阶段 1：性能画像与基线
建立"现状 → 目标"的量化坐标。缺失项标 [待补]，不编造。
| 指标 | 现状 | 目标 / SLO | 基线参照 | 状态 |
|---|---|---|---|---|
| 响应时间 P50 / P95 / P99 | 历史 / 同类接口 | 🔴/🟡/🟢 | ||
| 吞吐（QPS / TPS）与并发 | ||||
| 资源占用（CPU / 内存 / GC / 连接数） | ||||
| 错误率与超时率 | ||||
| 数据量与增长曲线 |
时段特征：区分日常 / 峰值 / 批量任务窗口——性能问题常只在特定时段出现，报告须写明结论适用的负载场景。
🔬 阶段 2：证据采集与分级
2.1 数据侧（有则采）
沿链路取分段耗时，形成耗时构成表（用于后续算占比）：
⚠️ 各段不可直接相加：并行 / 异步段取最大值而非求和（并发调 A 与 B，耗时是
max(A,B)），只有串行段才累加。端到端耗时须沿关键路径计算，占比 (p) 以关键路径总耗时为分母——否则 (p) 会被高估，收益估算随之失真。串并行多段时把关键路径画成 📅 gantt（秒级及以上首选，可同时展示"被掩盖的分区"），见 6.2。
| 链路段 | 耗时 | 占比 | 数据来源 | 证据级 |
|---|---|---|---|---|
| 网关 / 接入 | 🟢/🟡/🔴 | |||
| 应用逻辑 | ||||
| 数据库 | ||||
| 缓存 | ||||
| 外部依赖 |
无实测数据时：按代码与配置估算各段量级并标 🔴，同时给出采集该段数据的具体方法（见 reference.md「证据采集命令速查」）。
只读诊断例外：环境可用且用户确认时，可现场执行只读诊断把 🔴 升级为 🟢（EXPLAIN ANALYZE、慢查询日志、SHOW STATUS、只读采样 py-spy/pprof、读监控指标）——这类命令不改变系统状态，比"让用户回头自己测"更有价值。执行前须说明命令、影响范围与预计耗时；压测与任何写操作一律不执行。
2.2 代码侧（必做）
从接口入口出发追调用链，重点看配置与调用形态（它们往往比算法更能决定耗时）：
- 入口 → 编排层：有无串行可并行、重复调用、循环内远程调用
- 下游调用：DB、缓存、RPC、MQ、第三方 API；关注批量 vs 单条、连接池 / 线程池大小、超时与重试配置
- 数据形态与配置：是否走索引、全量加载、深分页、大对象传输；连接池、线程池、超时、批量大小、缓存 TTL 与容量
2.3 证据三级标注
| 级 | 定义 | 报告中的待遇 |
|---|---|---|
| 🟢 实测 | 有数据直接支撑（profiling 占比、APM span、压测数值、慢查询统计、监控曲线） | 可写"瓶颈是 X"，须标注来源 |
| 🟡 静态可证 | 代码 / 配置结构可直接推出（循环内 I/O、N+1、无索引过滤、全量加载、锁范围过大、无超时） | 可写"存在 X 问题"，标"未实测，建议确认" |
| 🔴 假设 | 仅由现象推断 | 只能进「待验证清单」+ 验证方法，禁止写进结论 |
2.4 双样本差分（命中双样本时执行）
把两份样本按段并列，做Δ 分解：
| 链路段 | 快样本 | 慢样本 | Δ（绝对差） | Δ 占 Δ总 | 归因价值 |
|---|---|---|---|---|---|
| 网关 / 接入 | 60ms | 65ms | +5ms | 3% | 已排除 |
| 应用逻辑 | 480ms | 500ms | +20ms | 12% | 次要嫌疑 |
| 数据库 | 200ms | 335ms | +135ms | 79% | 主嫌疑 |
| 缓存 | 60ms | 70ms | +10ms | 6% | 已排除 |
| 合计 | 800ms | 970ms | +170ms | 100% |
五条规则：
- 按 Δ 绝对值排嫌疑，不按占比：慢样本里 DB 占比只有 34.5%，但 Δ 贡献 79%——占比会被总耗时变化稀释，Δ 才是"这次为什么变慢"的答案
- 显著性门槛：Δ 段占 Δ总 <10% 或 <50ms → 视为噪声带，不进主嫌疑，避免把抖动当线索
- "排除"两件事：① 措辞限定为「经对照排除为本次变慢的原因」，不得写成"该段没问题"；② 排除前先看绝对值（Δ 小 ≠ 不需优化）——该段本身异常时（两组 DB 都是 800ms、Δ 仅 10ms）仍须写入「次要发现：两组均慢，属存量性能债」，否则报告会给团队错误的安全感
- 并行段同样适用关键路径规则：含并行 / 异步段时 Δ总 ≠ ΣΔ段（各分支取 Δ 最大值），参见阶段 2.1
差分能把 🔴 升级为 🟡：即便无分段数据，只要两组唯一差异变量明确（如只有数据量不同），也可得出"嫌疑在数据规模相关路径"这类有方向的推断，但仍须标注"待分段数据确认"。
S2（无实测数据）+ 双样本时的路径：拿不到分段耗时就填不了 Δ 表，此时不做 Δ 分解，改用变量反查法——由唯一差异变量反推受影响最大的层：
| 唯一差异变量 | 优先查的层 |
|---|---|
| 数据规模 / 租户 | 第 2 层（N+1、索引、全量加载）、第 8 层（分页、容量） |
| 代码版本 | 两版本 diff 涉及的层（从变更文件反查所属层） |
| 入参 / 请求 | 第 2 层（索引是否命中）、第 1 层（是否走不同分支） |
| 环境 | 第 5 层（连接池 / 线程池配置）、第 1 层（网络跳数、超时重试） |
产出的是候选层 + 待验证项（🔴/🟡），不是 Δ 表；报告须写明"缺少分段数据，未做 Δ 分解，结论为候选层推断"。
🎯 阶段 3：八层瓶颈定位
扫描范围自适应（先定范围再扫，避免小问题也跑满八层）：
| 场景 | 扫描范围 |
|---|---|
| 单点问题（"这个函数 / 这条 SQL 为什么慢"） | 只扫相关 2-3 层 + 上下游各一跳 |
| 接口 / 链路级（默认） | 扫全部 8 层，只展开命中项 |
| 全服务容量评估 | 八层 × 分场景（日常 / 峰值 / 批量）各扫一遍 |
按层扫描，每层给"命中 / 未命中 / 无法判断"，只把命中的写进报告（无命中不凑数）。
差分线索优先（命中双样本时）：阶段 2.4 已锁定差异段，扫描从差异所属层切入；被两组数据对照排除的层标注「已排除」即可，不必重复深挖。
| # | 层 | 典型问题 | 常见证据来源 |
|---|---|---|---|
| 1 | 请求链路与调用拓扑 | 串行可并行、冗余调用、超时/重试放大、同步阻塞、缺批量接口 | APM trace、调用链代码 |
| 2 | 数据访问 | 慢 SQL、N+1、缺索引、全表扫描、连接池耗尽、单条循环写入、大结果集传输 | 慢查询日志、EXPLAIN |
| 3 | 缓存 | 命中率低、失效策略不当、穿透/雪崩、重复加载、缓存粒度错 | 命中率指标、缓存代码 |
| 4 | 外部依赖 | 第三方 API 慢、无超时无熔断、DNS / 磁盘 / 网络、MQ 积压 | trace 外部段、监控 |
| 5 | 并发与异步 | 线程池 / 连接池配置不当、锁竞争、阻塞调用、队列积压、异步未落地 | 线程 dump、监控 |
| 6 | CPU 与算法 | 热点函数、复杂度退化、重复计算、序列化开销、正则回溯 | 火焰图、pprof |
| 7 | 内存与 GC | 分配率过高、泄漏、大对象、堆外内存、频繁 Full GC | GC 日志、堆转储 |
| 8 | 数据规模与容量 | 数据量增长、深分页、全量加载、峰值容量缺口、批量大小不当 | 数据量统计、压测拐点 |
前端页面性能（首屏 / 包体积 / 渲染）不在默认范围；用户明确要求时按第 9 层扩展，检查项见 reference.md 第 9 层。
收敛规则：扫描后收敛出 1-3 个主瓶颈（按影响占比排序）。命中项很多时，只展开主瓶颈，其余进「次要发现」一行一项。
🔗 阶段 4：归因
对每个主瓶颈追问"为什么"，给出根因链而非症状描述：
| 主瓶颈 | 表层现象 | 根因（为什么） | 影响面 | 证据级 |
|---|---|---|---|---|
| 影响哪些接口 / 场景 | 🟢/🟡 |
归因要求：
- 区分"实现写法问题"（循环内查库）与"设计选型问题"（同步串行调用第三方），后者必须指出——否则建议会退化成在原写法上打补丁
- 根因不在本次分析对象内（如容量问题源于上游批量任务）→ 标注
[根因在上游]，并说明本层能做的缓解与不能做的部分
💰 阶段 5：收益量化与优先级
5.1 收益估算规则
- 占比 (p)：该项在慢样本自身端到端耗时中的占比（段耗时 / 慢样本端到端），取自实测；无实测时给区间并标 🔴
⚠️ 两个比例不是一回事，禁止混用：排嫌疑用 Δ 占比（Δ段 / Δ总，见阶段 2.4）；算收益用慢样本内部占比 (p)（段耗时 / 慢样本端到端）。用 Δ 当 (p) 会低估收益（Δ 扣掉了本来就该有的那部分耗时）
- 局部加速比 (s)：优化后该段快多少倍（保守取值，不取理论最优）
- 整体收益上限：(S = 1 / ((1-p) + p/s))；(s \to \infty) 时的乐观上界为 (1/(1-p))
- 禁止：优化占比 2% 的段却写"整体性能提升 50%"；无 (p) 时给单点数字
表述模板（报告正文即写这一句）："<改法>，省掉 <往返次数 / 等待时长 / 重复计算量>，<段名> 由 <A> 降至 <B>；预期：<主指标> 由 <X> 降至约 <Y>（端到端上限 Z%，复测确认）；推荐指数 ★★★★☆。"
5.2 优先级矩阵（收益 × 难度）
| 收益 \ 难度 | 低难度（配置/局部改动） | 高难度（架构/跨模块） |
|---|---|---|
| 高收益 | P0 立即做 | P1 立项做 |
| 低收益 | P1 顺手做 | P2 可选 |
- 收益：高 = 端到端收益上限 ≥10% 或解除容量/稳定性风险；低 = <10%
- 难度：低 = 改配置 / 局部改写 / 加索引；高 = 改调用结构、引入异步、跨模块改造
- 每项须附副作用与风险（一致性、复杂度、可读性、运维成本），并在报告中给推荐指数（★1-5）与预期效果（星级口径见 reference.md 8.0）；P0/P1/P2 只作内部排期口径，不写进报告
🛠 阶段 5.5：优化建议双路径（A 技术优化 / B 产品侧调整）
定位完瓶颈后必须给建议：只给技术优化，等于替产品做了"功能一个都不能动"的决定；只说"砍功能"，又是工程师越权拍产品。所以两条路都要摆出来，各自由正确的角色拍板；产品侧分两型——退让型（牺牲部分功能换性能）与改进型（不牺牲功能：原设计本身不合理 → 换更优设计，体验与性能双升），改进型不替代退让型。
触发判定：存在主瓶颈 ／ 现状未达目标或 SLO ／ S3 容量风险 → 触发双路径；无主瓶颈且达标 → 第五章写"未发现性能不佳"，只给观察项。目标缺失时（阶段 1 目标栏为 [待补] 是常态）：以"存在 (p \ge 30%) 的主瓶颈"或"存在 🟡 级静态可证反模式（N+1 / 全表扫描 / 循环内 I/O）"判定为性能不佳，并在报告标注"目标待确认，本判定基于瓶颈占比"。
A 路径 · 技术优化（功能等价，不改产品行为）：不改产品行为与对外契约（返回字段、结果集、时效语义、交互流程不变）前提下的提速。每项须写功能等价性说明（"批量查询替代循环单查：返回数据集与顺序一致"）；会改产品行为的改法不是 A（"实时改 T+1""去掉某字段""默认关闭某能力"）→ 转 B。S2 模式下等价性说明须标"待验证"并进验证计划。
表：推荐指数（★1-5）｜ 优化项（一句话：改什么 → 省掉什么）｜ 对应瓶颈 ｜ 改法细节（文件 / 参数）｜ 预期效果（指标 X → 约 Y + 上限 + 业务感受）｜ 功能等价性说明 ｜ 风险与成本。例："明细查询改批量，省掉约 800 次往返，明细段 1200 → 400ms；预期 P95 3200 → 约 1800ms（-44%）；★★★★☆"
B 路径 · 产品侧调整（必须调 product-manager）——满足任一即启动：① 技术优化收益上限闭合不了"现状 → 目标"缺口（做完仍差一截，缺口只能靠产品形态让）；② 主瓶颈本质由产品形态决定（实时精确、强一致、全量返回、同步等第三方、默认开启的高开销能力）——先查改进型（形态本身是否合理），再考虑退让型；③ 用户明确要求砍功能 / 降级。
- B1 退让型：让出部分功能 / 时效 / 精度 / 返回量换性能，九种退让形态见 reference.md
- B2 改进型（不牺牲功能）：找原产品设计的缺陷（默认全量展示、强制实时、信息密度失衡、交互绕路造成重复请求、默认值不合理…）→ 给更优设计方向，体验与性能双升（方法与典型缺陷清单见 reference.md 8.2）
- 步骤：① 性能侧产「退让点 + 设计缺陷」候选（占端到端 (p)、可让出 / 可改进的收益上限）；② 调
use_skill("product-manager")——须显式声明任务（退让型=「产品侧调整·退让取舍」，改进型=「产品侧调整·设计改进」，可并用其体验走查与功能推演），产品形态不可知时影响面按 🔴 处理，禁止写"影响 100% 用户"这类未证实覆盖度；③ 并入报告，标决策状态（✅/⚠️/❌ 或「待产品确认」），不得改写 PM 结论
降级不阻塞：PM 不可用或用户拒绝调用 → B1 / B2 均标「⚠️ 待产品确认」，并声明"未经产品分析，不作为决策依据"。禁止自行拍板。
合并规则：
- A、B 并排进第五章；B 项在 PM 拍板前不得标为可实施或高推荐指数，须写"待产品确认"——否则等于用性能报告的权威性替产品做决定
- 收益不可跨项相加：作用于同一段的多项优化，后一项须按前一项之后的新基线重算（先加索引再改近似计数 ≠ 两项收益直接相加）；报告若给"全部做完"的总收益，须注明各段已按序重算、未重复计入（口径见 reference.md）
- 产品侧全部被否决时的收尾：明写"技术侧与产品侧均无可行路径闭合缺口"，给三条出路——上调目标容忍度 / 扩容或加资源 / 按场景分级 SLO（如导出场景放宽）。禁止为了凑出达标结论而弱化描述
- 呈现口径：每项在报告中先用一句话说清并给推荐指数 + 预期效果（技术优化：改什么 → 省掉什么；产品侧：让出什么 / 改进什么 → 换多少收益），细节进表；章末附 🕸「改前 → 改后」链路对照文字树（按段合并，见 reference.md 9.4.2）；优化建议一律不配 mermaid 图；技术优化项与阶段 2.4 / reference.md 7.3 的 Δ 分解口径对上（
ΔN×t/N×Δt）；报告正文不写内部用语（"A / B 路径、双路径、B1 / B2"等） - ⚡ 轻量档：技术优化压到 2-3 行（每项一句话），产品侧只写一行提示（"若技术优化不足，可考虑 {退让点 / 设计改进方向}，需产品确认"）；用户明确要求砍功能 / 降级（条件③）时不受轻量档限制
📊 阶段 6：报告输出
按阶段 0.3 的读者档位裁剪。完整模板见 reference.md「报告模板（三档位）」，骨架如下：
# 性能分析报告 — {接口/链路名}
> 读者档位：🧑💻 开发档 / 📊 产品档 / 👥 双读者档 模式：S1/S2/S3 分析窗口：{时间/版本}
## 目录
- [一、执行摘要](#一执行摘要) / [二、性能画像](#二性能画像) / [三、耗时构成](#三耗时构成) / [三·B、对比分析](#三b对比分析)（双样本时）
- [四、主瓶颈与归因](#四主瓶颈与归因)（标题随模式变）/ [五、优化建议](#五优化建议) / [六、待验证清单](#六待验证清单)（S2）/ [七、验证计划](#七验证计划) / [附录](#附录) （必带；锚点规则见 reference.md 5.0）
## 一、执行摘要（≤1 屏）
现状一句话 | 主瓶颈 1-3 条 | 预期收益与投入 | 不做会怎样
## 二、性能画像
现状 vs 目标 vs 基线（阶段 1 表）
## 三、耗时构成
链路分段耗时与占比（阶段 2.1 表）+ 📊 分段耗时图（串并结构 / 秒级场景优先 📅 gantt 关键路径图）
## 三·B、对比分析
样本定义 + 变量对齐结论 | Δ 分解表 | 📊 双样本对比图 | 已排除项 | 混淆变量警告（多变量时必写）
## 四、{S1: 主瓶颈与归因 | S2: 候选瓶颈（待验证）| S3: 容量风险清单}
位置 | 证据 | 证据级 | 根因 | 影响占比 + 🕸 文字树（调用链：串并行 / 卡点 / 耗时 / 瓶颈标记，见 reference.md 9.4.1）
## 五、优化建议
五·一 技术优化（不改功能）：每项 推荐指数 + 一句话（改什么 → 省掉什么）+ 预期效果 + 表
五·二 产品侧调整（需产品决策）：退让类（让出什么）/ 改进类（修原设计缺陷，双赢）——每项 推荐指数 + 预期效果 + 表（PM 分析 / 决策状态）
🕸 改前 → 改后（链路对照文字树，按段合并；本章不配 mermaid）
## 六、待验证清单
## 七、验证计划
测什么 | 怎么测 | 判据（改完如何证明有效）
## 附录
证据来源、采集方式、待补数据 + 交付自查记录（第 N 轮 / 修复项）
模式分化（不遵守则 S2 报告会把猜测写成结论，产品档下危害最大）
| 模式 | 第四章 | 报告头必加声明 | 允许的表述 |
|---|---|---|---|
| S1 | 主瓶颈与归因 | 无 | "瓶颈是 X"（可断定） |
| S2 | 候选瓶颈（待验证） | ⚠️ 本报告基于现象与代码推演，未经实测；结论须在完成验证计划后方可作为决策依据 | "若 H-1 成立，则…"（禁止断定句） |
| S3 | 容量风险清单 | 本报告为上线前风险预判，非实测结论 | "预计存在…风险" |
S2 + 产品档组合时，执行摘要也必须带上述声明——产品会据此立项，未验证假设被当作已证实瓶颈排期是最坏的失败形态。
档位差异
| 章节 | 🧑💻 开发档 | 📊 产品档 | 👥 双读者档 |
|---|---|---|---|
| 执行摘要 | 压到 3-5 行 | 重点：业务语言、投入产出、优先级 | 重点，≤1 屏 |
| 耗时构成 / 瓶颈归因 | 全展开（含代码位置、SQL、配置值） | 收进附录「技术依据」，正文只留结论 | 正文展开 |
| 对比分析（双样本） | Δ 表 + 变量对齐全给 | 只给"差异在哪、结论是什么、能否归因" | Δ 表进正文 |
| 优化建议 · 技术优化 | 含具体改法 | 只给"做什么 + 预期效果 + 推荐指数 + 成本风险" | 分级给，改法进正文 |
| 优化建议 · 产品侧调整（退让 / 改进） | 退让点与设计缺陷一并列 + PM 决策状态 | 正文重点：取舍 / 改进方向、用户影响、建议与否 | 全给，PM 结论进正文 |
| 验证计划 | 含具体压测/ profiling 方法 | 只给"验收判据" | 全给 |
| 图表（只画"卡在哪"） | 2-3 张：分段耗时 / gantt（+ 双样本差异）；第四章文字树 | 1-2 张：分段耗时（+ 双样本差异）+ 文字树 | 2-3 张 + 文字树；技术向图可移附录 |
措辞约束：报告正文不得照搬本 skill 的内部用语与流程编号（"双路径 / A 路径 / B 路径 / B1 / B2 / 阶段 5.5"等），改用读者能懂的说法（"不改功能的优化 / 需要产品决策的调整"）；报告保留证据级（🟢🟡🔴）、模式（S1/S2/S3）、指标名（P95/QPS）与目录——这些是报告语言，不算内部用语。产品档正文禁止出现未翻译的技术术语，必要概念后附一句业务解释（"缓存命中率"= 每次请求能直接取到数据、不必重新计算的比例）。
6.1 报告落盘（必做）
报告不落盘 = 结论散落在聊天里，正是本 skill 要解决的问题。除 ⚡ 轻量档外必须落盘：
| 情况 | 落盘路径 |
|---|---|
| 启用需求管理且有关联需求 | 写入需求目录 perf/performance-analysis.md，按 use_skill("requirement-doc-store") 注册：req update {REQ-NNN} --docs add perf/performance-analysis.md,review |
| 无需求管理 | .codebuddy/perf/{接口或链路名}-{YYYYMMDD}.md |
| ⚡ 轻量档 | 不落盘，对话内输出 |
落盘时报告头须含：分析对象、负载场景、模式（S1/S2/S3）、读者档位、分析日期与代码版本——否则事后无法判断结论还适不适用。含 B 路径时须注明 PM 分析的出处（会话产出 / PM 报告落盘路径），否则"产品已同意"无从追溯。落盘后逐条点检目录锚点可跳转（标题不放 emoji）。
6.2 图表规范（只画"卡在哪"）
报告可内嵌 mermaid 图，但图的使命只有一个：卡在哪——📊 分段耗时（时间卡在哪段）+ 📅 gantt 关键路径（秒级及以上、串并行多段时首选：一眼看出谁在等谁、哪段被掩盖）+ 📊 双样本差异；第四章「主瓶颈与归因」用 🕸 文字树表达调用链（串并行 / 卡点 / 耗时），不画 mermaid（文字树说不清调用交互时才补时序图 / 拓扑图）。硬禁止两类图：① 决策路径类（是否达标 / A·B 取舍 / 审批 / 排期）——一律用表或文字，禁止任何形式的 mermaid 图；② 优化建议类（机理图 / 前后对比图）——优化项用一句话说清，"省掉什么"写进句子。铁律：① 图 / 文字树 / 一句话 / 表 四者数字同源一致，图与一句话都不是第二份结论；② 🔴 假设画成虚线 / 空心并标"待验证"，否则图会把假设视觉坐实；③ 说不出"省掉什么"的优化项 = 未论证，不得进结论区；④ 不堆图（⚡ 0-1 / 📊 2 / 🧑💻 3 张）。模板与语法安全见 reference.md「九、报告图表规范」。
6.3 交付前自查（二次检查，必做）
报告写完并落盘后，读回落盘文件（不凭记忆；⚡ 轻量档读回对话中已输出的正文）按三遍法逐条核验：规则核验 → 数字交叉（执行摘要 / 耗时表 / 图 / 一句话 / 收益表 处处一致，并抽 3-5 个关键数字回对原始证据）→ 读者视角通读（看找不找得到结论、看不看得懂）。清单与检查方法见 reference.md「十、交付前自查清单」。
有 ❌ 就地修复并重跑全清单（不是只跑修过的那条），最多 3 轮；3 轮后仍有未通过项 → 报告头标 ⚠️ 自查未通过项：… 并显式告知用户，不得静默交付。附录记一行：交付自查：第 N 轮通过（修复 k 项）。
🧪 阶段 7：验证计划与后续出口
7.1 验证计划（必带）
| 验证项 | 验证方式 | 判据 | 前置条件 |
|---|---|---|---|
<优化项> |
压测 / APM 对比 / 火焰图复采 / SQL EXPLAIN 对比 | P95 从 X 降到 ≤Y（同负载同数据量） | 需压测环境 / 需数据量 N |
验证三要素：同负载、同数据量、同观测窗口——三者不齐的对比不成立，须在计划中写明。
产品侧项须加产品验收判据：退让型除性能判据（P95 达标）外，须写"退让后产品侧仍可接受"的判据（"列表总数误差 <1%"、"每页 200 条设置项仍可用"、"风控未被降级"）；改进型须写"体验不降反升"的判据（如"概览 + 下钻后首屏信息仍够用、点击次数未增加"）——没有产品判据的产品侧项不得标为可实施。
7.2 后续出口
| 出口 | 交接 |
|---|---|
| 产品侧调整（退让 / 改进）需产品决策 | use_skill("product-manager")——阶段 5.5 已调用则在本表登记结论去向 |
| 优化方案落地前刹车 | 先取得用户确认（采纳哪项 / 范围到哪） → use_skill("request-guard") → use_skill("code-review") → 才实施；顺序见约束 18，不得先改后报 |
| 需要实测验证 | use_skill("demo-verify") / use_skill("e2e-testing") |
| 性能优化需立项 | use_skill("requirement-mining") |
| 结论复核 / 经验沉淀 | use_skill("challenger")（optimization 策略）/ use_skill("solution-capture") |
约束与原则
- 不臆造数据：没有测过的数字一律不写；用
[待补：需要什么数据]占位 - 结论分级铁律：🔴 假设禁止出现在结论区，只能进「待验证清单」且必须配验证方法
- 先定位后优化：未定位到瓶颈前不输出优化建议；优化建议必须对应到已定位的瓶颈
- 收益有上限：每个收益数字必须能追溯到占比 (p) 与加速比 (s)，或明确标注为区间估算
- 对象锚定：分析单位是接口 / 链路 × 负载场景；不做无对象的"系统整体性能评估"
- 只出报告，不改码、不压测：不修改代码、不执行压测或任何有副作用的写操作。只读诊断例外——环境可用且用户确认时，可协助执行
EXPLAIN ANALYZE/ 慢日志 / 只读采样 / 读监控指标等只读命令把 🔴 升级为 🟢（执行前须说明命令与影响）；压测与写操作一律交demo-verify/e2e-testing。改码例外：用户明确要求本 skill 落地优化时，按约束 18 的顺序执行（先确认后修改） - 读者档位先问后写：阶段 0.3 未获回应时默认双读者档并标注
- 不凑数：某层无命中就写"未命中"，不为了显得全面而列通用建议；图表同理——不插说明不了问题的图
- 配置与形态优先于算法：先查连接池 / 超时 / 批量 / 缓存 / 串行结构，再谈算法常数优化
- 根因在上游要标注：本层只能缓解时明确写出边界，不把缓解包装成解决
- 中文输出：报告用中文，术语与代码标识符保留原文
- 双样本先变量对齐再归因：仅单一变量不一致时差分才可用；多变量混淆必须明写"不可据此归因"并给出补齐单变量对照的做法，禁止在混淆状态下硬归因
- 差分看 Δ 不看占比：用绝对差值的贡献度排嫌疑；同时显式写出"经对照已排除"的段——排除结论与定位结论同等值钱
- 性能不佳两条路都要给：第五章须同时给技术优化（功能等价）与产品侧调整（B1 退让型 + B2 改进型）；只给技术优化等于把"功能不能动"这个产品决策悄悄替用户做了，只给退让又漏了"原设计可能本就不合理"的改进空间
- 两处不自裁：产品侧的价值判断须由
product-manager产出——退让型（砍 / 降哪个功能）与改进型（原设计是否有缺陷、改后体验是否更好）都不得自行拍板；PM 不可用时降级为"候选 + 待产品确认"并声明不作决策依据 - A 路径须可证明功能等价：A 表每项写明"为何不改产品行为"；会改产品行为的改法不是 A，必须转 B 路径
- 报告形态刚性：顶部必带目录索引（锚点与标题一致、落盘前逐条点检、标题不放 emoji；⚡ 轻量档除外）；决策路径与优化建议一律不画图——含 gantt 在内的图只画"卡在哪"
- 先确认后修改（约束 6 的唯一例外路径）：默认只出报告；用户明确要求直接落地优化时（说"优化 / 改 / 落地 / 你动手"即为要求，只在报告里给建议不算），顺序固定为 方案（改哪 / 怎么改 / 预期收益 / 风险 / 验证方式）→ 用户明确确认（采纳哪项、范围到哪）→ 实施 → 按验证计划复测 → 报告结果。未确认不得改代码，禁止"先改后报"（含"顺手优化"、含看似安全的索引 / 缓存改动）；改前基线须先取得并记录，否则改后无对比、收益不可证。基线取不到时（无压测环境 / 无监控 / 历史数据缺失）：先声明"改后只能给静态判据、无法给前后对比"，经用户确认再实施，并在报告标注
[无基线，效果待验证]——不得用改后数据冒充收益
与相关 skill 的关系
| 相关 skill | 边界 |
|---|---|
code-review |
审查变更 diff 的性能隐患（七维度之一），对象是一次提交；本 skill 面向线上/既有接口与链路的深度专项 |
artifact-optimizer |
广度"能不能更好"的优化扫描，明确不覆盖性能专项；本 skill 是性能深度专项 |
debug |
功能异常与报错排错；本 skill 只处理"能跑但慢 / 资源占用高" |
demo-verify / e2e-testing |
承接本 skill 输出的验证计划，跑实测拿证据 |
request-guard → code-review |
优化方案落地前的刹车与变更审查 |
product-manager |
产品侧调整分析：退让点（用户价值 / Kano / 影响面 / 底线 / 是否采纳）与改进型（原设计缺陷、更优设计方向、体验与性能双赢）；本 skill 只提供技术侧候选与收益估算 |
requirement-mining |
性能优化需立项排期时，用本报告作为现状与收益依据 |
challenger |
对分析结论做对抗式复核（optimization 策略） |
code-change-impact |
优化落地后判影响面与回归风险（行为等价性、性能反退、调用方零感知）——本 skill 判"该不该这么优化、能省多少"，它判"改完有没有带坏别的" |
反模式
- ❌ 无数据下实锤：没有火焰图却写"瓶颈在 X 函数，占 60%"
- ❌ 通用建议堆砌："加缓存、加索引、改异步、上线程池"——与本项目证据无关的清单
- ❌ 收益无上限、无依据：优化 2% 占比的段却宣称整体提升若干倍；建议只写"怎么改"、不给预期效果与推荐指数，读者无法排序
- ❌ 内部用语 / 技术黑话进报告：产品档未翻译的术语；任何档位照搬"A 路径 / 双路径 / B1 / B2 / 阶段 5.5"等内部叫法，读者看不懂
- ❌ 只会砍功能、不查原设计是否合理：明明能靠改进设计做到体验与性能双赢（如"默认全量"改为"概览 + 按需下钻"），却只给退让建议——等于替产品关掉了"不牺牲功能也能变快"的可能
- ❌ 混淆性能与功能 bug：报错、数据错误属
debug，不是性能分析。判定问句："结果对不对？"——结果错误 / 报错 / 死循环（即使表现为慢）→debug；结果正确但慢或资源高 → 本 skill - ❌ 报告不带验证计划：改完无法判断是否有效
- ❌ 无视负载场景：脱离并发与数据量谈"响应时间"，结论不可复现
- ❌ 为凑全面而硬找命中：无命中就写无命中
- ❌ 图替代表 / 图不符表：只给图不给数据表，或图中数字与表不一致；🔴 假设画成实线实心，一张图把猜测坐实成"已证实的瓶颈"
- ❌ 报告形态不合规：无目录或锚点点不动（只能靠滚动找章节）；给决策路径与优化建议配图（达标 / 审批流程图、机理图、前后对比图）——读者要么找不到，要么被图绕晕
- ❌ 交付前不做二次自查：写完即交，数字不一致 / 🔴 混进结论 / 内部用语残留全等人眼发现
- ❌ 多变量混淆硬归因：两份样本差了版本 + 数据量 + 环境三个变量，却断言"瓶颈是新版本引入的"——此时任何归因都是猜
- ❌ 双样本用错：分别单独分析白白浪费最强线索，或只看占比不看 Δ（占比会被总耗时稀释，慢样本某段占比最高 ≠ 它是变慢的原因）
- ❌ 只给技术优化、把产品侧选择藏起来：技术优化闭合不了缺口却不提退让 / 改进方向——等于替产品做了"功能一个都不能动"的决定
- ❌ 自行拍板砍功能：没有 PM 分析就写"建议关闭实时统计"——用户价值、影响面不是性能分析能判的，须交
product-manager - ❌ 先改后报：先把代码"顺手优化"（加索引、改批量、上缓存）再在报告里写"已优化、预期 P95 下降"——没有改前基线、没有用户确认，收益无法验证、方案风险无人担责。顺序永远是「方案 → 确认 → 改 → 复测 → 报告」
- ❌ 把改了产品行为的方案塞进 A 路径："实时改 T+1""去掉高开销字段""默认关掉"都属 B 路径，标成"技术优化"会绕过产品决策
附加资源
- 八层详细检查清单、技术栈速查（Python/Java/Go/Node/DB/Redis/网关）、收益估算示例、证据采集命令速查、三档位完整报告模板、双样本差分分析（含变量对齐模板与 ΔN/Δt 算式）、优化建议双路径（推荐指数与预期效果口径 / 退让点候选清单 / 改进型设计缺陷识别 / 交 product-manager 的输入包与回执字段 / 九种退让形态 / 收益叠加口径）、报告图表规范（分段耗时 / gantt 关键路径模板 / 第四章文字树模板、一句话优化建议写法、目录锚点规则、语法安全）、交付前自查清单（三遍法 / 14 项核验 / 未通过处理）：reference.md
- 典型场景示例（S1 证据驱动 / S2 现象驱动 / 产品档摘要 / S3 容量预判 / 差分强可用 / 多变量混淆拒绝归因 / 读者询问话术 / 技术优化不足 → 调 PM 做退让 / 改进取舍）：examples.md