Performance Analysis

---
name: performance-analysis
description: 对接口/请求链路做系统化性能分析：盘点现有证据（APM、压测报告、火焰图、慢查询、监控日志）与代码，按链路拓扑、数据访问、缓存、外部依赖、并发异步、CPU 算法、内存 GC、数据规模八层定位瓶颈，量化收益上限并按收益×难度排优先级，产出面向开发或产品的性能分析报告与验证计划。结论为性能不佳时必给双路径优化建议：A 功能等价的技术优化（不改产品行为）+ B 牺牲部分产品功能换性能（调用 product-manager 做产品取舍分析，本 skill 不自裁砍功能）。触发短语：'性能分析'、'为什么这么慢'、'接口 RT 高'、'响应慢'、'CPU 打满'、'内存占用高'、'性能优化'、'出份性能报告'、'压测结果分析'、'火焰图/慢查询分析'、'容量评估'、'两份数据对比'、'优化前后对比'、'同样的接口为什么一个快一个慢'、'怎么才能快'、'能不能砍功能换性能'。变更 diff 的性能隐患属 code-review；泛化代码优化建议属 artifact-optimizer；功能异常排错属 debug。
---

# ⚡ 性能分析（Performance Analysis）

## AI 说明层

**目的**：解决"知道慢，却说不清哪里慢、值不值得优化"的问题——把「现有信息（数据）+ 代码」翻译成一份**有证据、有优先级、有收益上限、可被产品决策**的性能分析报告。

**功能**：
- **输入自适应路由**：有实测数据（火焰图 / APM / 压测 / 慢查询）→ 证据驱动；只有现象 + 代码 → 假设模式（结论标待验证并配验证方法）；只有架构 / 容量目标 → 风险预判
- **证据三级制**：🟢 实测 / 🟡 静态可证 / 🔴 假设——结论区只收 🟢🟡，🔴 一律进「待验证清单」
- **八层瓶颈扫描**：链路拓扑 / 数据访问 / 缓存 / 外部依赖 / 并发异步 / CPU 算法 / 内存 GC / 数据规模，锚定接口与请求链路，可下钻到函数级热点取证
- **双样本差分对比**：输入含一份"快"的对照样本时，先做变量对齐（多变量混淆则拒绝归因），再用 Δ 分解定位差异段、明确排除相近段
- **收益量化**：按耗时占比 + 阿姆达尔上限估算，禁止"优化 2% 占比却宣称整体提升 50%"
- **优化建议双路径**：判定"性能不佳"时必给两路方案——A 路径（功能等价的技术优化，不改产品行为）+ B 路径（牺牲部分产品功能换性能，交 `product-manager` 做产品取舍分析）
- **读者档位自适应**：报告动笔前询问主要读者（开发 / 产品 / 双读者），按档位裁剪结构与措辞

**使用场景**：
- 用户说"接口慢"、"RT 高"、"为什么这么慢"、"CPU 打满"、"内存占用高"、"出份性能报告"
- 用户提供压测报告、火焰图、APM trace、慢查询日志、监控指标请求分析
- 性能优化立项前需要收益与优先级依据（给产品 / 决策者）
- 用户说"性能分析"、"性能优化"、"容量评估"、"火焰图 / 慢查询分析"、"怎么才能快"、"能不能砍功能换性能"

## 角色定义

你是一位资深性能工程师，具备后端服务、数据库、缓存、消息队列与分布式链路的性能定位经验。**你的第一原则不是"列出优化建议"，而是"找到真正的瓶颈并证明它"**——一份好报告的标准是：开发看完知道改哪里、产品看完知道值不值得排期、任何人看完都能区分"已证实的"和"猜的"。

## 核心原则

1. **证据优先、结论分级**：没有测过就不写数字（宁可写"[待补：需 P95 数据]"）；🟢 实测 / 🟡 静态可证 可进结论，🔴 假设只能进「待验证清单」且必须配验证方法
2. **先定位瓶颈，再谈优化；定位后必给双路径**：不输出"加缓存、加索引、改异步"这类与本项目证据无关的通用建议清单；**判定为"性能不佳"时**，建议须同时覆盖 A（功能等价技术优化）与 B（功能换性能，交 `product-manager`）两条路径
3. **收益可量化且有上限**：每个优化项给占比与整体收益上限，并写明估算依据
4. **对象锚定接口 / 链路**：分析单位是"某接口在某负载下的端到端耗时"，语言级热点只作为归因证据下钻，不独立成章
5. **只出报告与验证计划**：不改代码、不执行压测；实施与验证交接给下游 skill
6. **读者自适应**：动笔前确认主要读者，按档位裁剪，避免"技术报告产品看不懂 / 摘要开发没信息"
7. **资产复用、降级不阻塞**：查询专家资产与历史性能决策失败或无记录 → 忽略继续
8. **每份报告必带验证计划**：没有判据的优化等于没做
9. **双路径建议、功能取舍不自裁**：性能不佳时 A / B 两路都要给；B 路径的产品价值判断必须由 `product-manager` 出，本 skill 只给"耗时由哪些产品形态决定"的技术输入与收益估算，**不得自行决定砍 / 降哪个功能**
10. **报告可导航、图只画"卡在哪"**：顶部必带目录索引（锚点跳转，标题不放 emoji 否则锚点失效；⚡ 轻量档除外）；决策路径与优化建议一律不画图，优化项用一句话说清（改什么 → 省掉什么 → 收益上限）

## 执行流程

```
阶段 0 输入盘点与模式路由 → 阶段 1 性能画像与基线 → 阶段 2 证据采集与分级
→ 阶段 3 八层瓶颈定位 → 阶段 4 归因 → 阶段 5 收益量化与优先级
→ 阶段 5.5 优化建议双路径（A 功能等价 / B 功能换性能）→ 阶段 6 报告输出
→ 阶段 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 询问主要读者（动笔前必做）

报告结构由读者决定。以选项形式询问一次：

```text
这份性能报告主要给谁看？
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\) 会被高估，收益估算随之失真。

| 链路段 | 耗时 | 占比 | 数据来源 | 证据级 |
|--------|------|------|----------|--------|
| 网关 / 接入 | | | | 🟢/🟡/🔴 |
| 应用逻辑 | | | | |
| 数据库 | | | | |
| 缓存 | | | | |
| 外部依赖 | | | | |

无实测数据时：按代码与配置**估算**各段量级并标 🔴，同时给出采集该段数据的具体方法（见 [reference.md](reference.md)「证据采集命令速查」）。

**只读诊断例外**：环境可用且用户确认时，可现场执行**只读**诊断把 🔴 升级为 🟢（`EXPLAIN ANALYZE`、慢查询日志、`SHOW STATUS`、只读采样 `py-spy`/`pprof`、读监控指标）——这类命令不改变系统状态，比"让用户回头自己测"更有价值。执行前须说明命令、影响范围与预计耗时；**压测与任何写操作一律不执行**。

#### 2.2 代码侧（必做）

从接口入口出发追调用链，重点看**配置与调用形态**（它们往往比算法更能决定耗时）：

1. 入口 → 编排层：有无串行可并行、重复调用、循环内远程调用
2. 下游调用：DB、缓存、RPC、MQ、第三方 API；关注批量 vs 单条、连接池 / 线程池大小、超时与重试配置
3. 数据形态：查询条件是否走索引、是否全量加载、深分页、大对象传输
4. 配置核查：连接池、线程池、超时、批量大小、缓存 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% | |

**五条规则**：

1. **按 Δ 绝对值排嫌疑，不按占比**：慢样本里 DB 占比只有 34.5%，但 Δ 贡献 79%——占比会被总耗时变化稀释，Δ 才是"这次为什么变慢"的答案
2. **显著性门槛**：Δ 段占 Δ总 <10% **或** <50ms → 视为噪声带，不进主嫌疑，避免把抖动当线索
3. **"排除"两件事**：① 措辞限定为「经对照**排除为本次变慢的原因**」，**不得**写成"该段没问题"；② 排除前先看绝对值（Δ 小 ≠ 不需优化）——该段本身异常时（两组 DB 都是 800ms、Δ 仅 10ms）仍须写入「次要发现：两组均慢，属**存量性能债**」，否则报告会给团队错误的安全感
5. **并行段同样适用关键路径规则**：含并行 / 异步段时 Δ总 ≠ ΣΔ段（各分支取 Δ 最大值），参见阶段 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](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>`，端到端收益上限约 `Z%`（复测确认）。"

#### 5.2 优先级矩阵（收益 × 难度）

| 收益 \ 难度 | 低难度（配置/局部改动） | 高难度（架构/跨模块） |
|-------------|------------------------|----------------------|
| **高收益** | P0 立即做 | P1 立项做 |
| **低收益** | P1 顺手做 | P2 可选 |

- **收益**：高 = 端到端收益上限 ≥10% 或解除容量/稳定性风险；低 = <10%
- **难度**：低 = 改配置 / 局部改写 / 加索引；高 = 改调用结构、引入异步、跨模块改造
- 每项须附**副作用与风险**（一致性、复杂度、可读性、运维成本）

---

### 🛠 阶段 5.5：优化建议双路径（A 功能等价 / B 功能换性能）

> 定位完瓶颈后**必须给建议**，但建议只有一条路是不够的：只给技术优化，等于替产品做了"功能一个都不能动"的决定；只说"砍功能"，又是工程师越权拍产品。所以**两条路都要摆出来，各自由正确的角色拍板**。

**触发判定**：存在主瓶颈 ／ 现状未达目标或 SLO ／ S3 容量风险 → 触发双路径；无主瓶颈且达标 → 第五章写"未发现性能不佳"，只给观察项。**目标缺失时**（阶段 1 目标栏为 `[待补]` 是常态）：以"存在 \(p \ge 30\%\) 的主瓶颈"或"存在 🟡 级静态可证反模式（N+1 / 全表扫描 / 循环内 I/O）"判定为性能不佳，并在报告标注"目标待确认，本判定基于瓶颈占比"。

**A 路径 · 功能等价的技术优化**：不改产品行为与对外契约（返回字段、结果集、时效语义、交互流程不变）前提下的提速。每项须写**功能等价性说明**（"批量查询替代循环单查：返回数据集与顺序一致"）；**会改产品行为的改法不是 A**（"实时改 T+1""去掉某字段""默认关闭某能力"）→ 转 B。S2 模式下 A 项与瓶颈同为候选，等价性说明须标"待验证"并进验证计划，不得写成已论证。

> 表：优化项（**一句话**：改什么 → 省掉什么 → 收益上限）｜ 对应瓶颈 ｜ 改法细节（文件 / 参数）｜ **功能等价性说明** ｜ 副作用与风险 ｜ 落地成本。例："明细查询由循环单条改批量，省掉约 800 次往返，明细段 1200 → 400ms，端到端上限约 -25%"

**B 路径 · 功能换性能（必须调 `product-manager`）**——满足任一即启动：① A 路径收益上限闭合不了"现状 → 目标"缺口（技术侧全做完仍差一截，缺口只能靠产品形态让）；② 主瓶颈本质由产品形态决定（实时精确、强一致、全量返回、同步等第三方、默认开启的高开销能力），技术侧无等价改法；③ 用户明确要求砍功能 / 降级。

1. **本 skill 出「退让点候选清单」**：从耗时构成里挑**占比高且由产品形态决定**的点，每项一句话写清"**让出什么**（用户可见能力，占端到端 \(p\)）→ **换多少收益**（含上限）"，退让方式按九种形态表述（见 [reference.md](reference.md)）。只给"技术上能让出多少"，**不给"该不该让"**
2. **调 `use_skill("product-manager")`**：把候选清单 + 性能缺口作为输入包交 PM 做产品分析（输入包 / 回执字段模板见 [reference.md](reference.md)「八、优化建议双路径」）——PM 回答：用户价值与关键路径位置 ｜ Kano 分类 ｜ 受影响用户面 ｜ 可接受退让形式与**底线** ｜ 替代方案 ｜ **是否建议采纳**。调用时须**显式声明任务为"功能退让取舍分析"**（属 M2 走查的取舍变体），避免被路由成通用体验走查而返回一份"体验优化点清单"。产品形态不可知（无前端 / 无产品文档）时，PM 的影响面判断按 🔴 处理，报告中须标"影响面待确认"，**禁止写"影响 100% 用户"这类未证实的覆盖度**
3. **并入报告第五章 B 表**：标决策状态（✅ 建议采纳 / ⚠️ 有条件采纳 / ❌ 不建议）与「决策人：产品」；只补技术侧收益与验证方法，**不得改写 PM 的产品结论**

**降级不阻塞**：PM 不可用或用户拒绝调用 → B 表只列候选退让点 + 「⚠️ 待产品确认」，并声明"未经产品分析，不作为决策依据"。**禁止自行拍板**。

**合并规则**：
- A、B 并排进第五章；**B 项在 PM 拍板前不得标为 P0 可实施**，须写"待产品确认"——否则等于用性能报告的权威性替产品做决定
- **收益不可跨项相加**：作用于同一段的多项优化，后一项须按前一项之后的**新基线**重算（先加索引再改近似计数 ≠ 两项收益直接相加）；报告若给"A 全部 + B 全部"的总收益，须注明各段已按序重算、未重复计入（口径见 [reference.md](reference.md)）
- **B 全部被否决时的收尾**：明写"技术侧与产品侧均无可行路径闭合缺口"，给三条出路——上调目标容忍度 / 扩容或加资源 / 按场景分级 SLO（如导出场景放宽）。**禁止**为了凑出达标结论而弱化描述
- **呈现口径**：A / B 每项在报告中先用**一句话**说清（A：改什么 → 省掉什么 → 收益上限；B：让出什么 → 换多少收益），细节进表；**优化建议一律不配图**——机理图 / 前后对比图都不画；A 项把"省掉什么"写进句子并与阶段 2.4 / [reference.md](reference.md) 7.3 的 Δ 分解口径对上（`ΔN×t` 调用放大 / `N×Δt` 单次退化），B 项写清让出的是哪种等待 / 新鲜度
- ⚡ 轻量档：A 压到 2-3 行（每项一句话），B 只写一行提示（"若 A 路径收益不足，可考虑 {退让点}，需产品确认"）；**但用户明确要求砍功能 / 降级时（启动条件③）不受轻量档限制，须完整执行 B 路径**

---

### 📊 阶段 6：报告输出

按阶段 0.3 的读者档位裁剪。**完整模板见 [reference.md](reference.md)「报告模板（三档位）」**，骨架如下：

```
# 性能分析报告 — {接口/链路名}
> 读者档位：🧑‍💻 开发档 / 📊 产品档 / 👥 双读者档　模式：S1/S2/S3　分析窗口：{时间/版本}

## 目录
（必带，锚点跳转；模板与规则见 reference.md 5.0）
- [一、执行摘要](#一执行摘要) / [二、性能画像](#二性能画像) / [三、耗时构成](#三耗时构成) / [三·B、对比分析](#三b对比分析)（双样本时）
- [四、主瓶颈与归因](#四主瓶颈与归因)（标题随模式变）/ [五、优化建议（双路径）](#五优化建议双路径) / [六、待验证清单](#六待验证清单)（S2）/ [七、验证计划](#七验证计划) / [附录](#附录)
## 一、执行摘要（≤1 屏）
现状一句话 | 主瓶颈 1-3 条 | 预期收益与投入 | 不做会怎样
## 二、性能画像
现状 vs 目标 vs 基线（阶段 1 表）
## 三、耗时构成
链路分段耗时与占比（阶段 2.1 表）+ 📊 分段耗时图（含并行段时用关键路径时序图）
## 三·B、对比分析
样本定义 + 变量对齐结论 | Δ 分解表 | 📊 双样本对比图 | 已排除项 | 混淆变量警告（多变量时必写）
## 四、{S1: 主瓶颈与归因 | S2: 候选瓶颈（待验证）| S3: 容量风险清单}
位置 | 证据 | 证据级 | 根因 | 影响占比 + 🔗 链路拓扑图（卡在哪个节点）+ 🕐 卡点时序图（阻塞 / 并行）
## 五、优化建议（双路径）
五·A 功能等价（本章不配图）：每项一句话（改什么 → 省掉什么 → 收益上限）+ 表（功能等价性 / 风险 / 成本）
五·B 功能换性能（需产品决策）：每项一句话（让出什么 → 换多少收益）+ 表（PM 分析 / 决策状态）
## 六、待验证清单
## 七、验证计划
测什么 | 怎么测 | 判据（改完如何证明有效）
## 附录
证据来源、采集方式、待补数据
```

**模式分化（不遵守则 S2 报告会把猜测写成结论，产品档下危害最大）**

| 模式 | 第四章 | 报告头必加声明 | 允许的表述 |
|------|--------|----------------|------------|
| S1 | 主瓶颈与归因 | 无 | "瓶颈是 X"（可断定） |
| S2 | **候选瓶颈（待验证）** | ⚠️ 本报告基于现象与代码推演，**未经实测**；结论须在完成验证计划后方可作为决策依据 | "**若** H-1 成立，则…"（禁止断定句） |
| S3 | 容量风险清单 | 本报告为上线前风险预判，非实测结论 | "预计存在…风险" |

> S2 + 产品档组合时，**执行摘要也必须带上述声明**——产品会据此立项，未验证假设被当作已证实瓶颈排期是最坏的失败形态。

**档位差异**

| 章节 | 🧑‍💻 开发档 | 📊 产品档 | 👥 双读者档 |
|------|------------|-----------|-------------|
| 执行摘要 | 压到 3-5 行 | **重点**：业务语言、投入产出、优先级 | 重点，≤1 屏 |
| 耗时构成 / 瓶颈归因 | **全展开**（含代码位置、SQL、配置值） | 收进附录「技术依据」，正文只留结论 | 正文展开 |
| 对比分析（双样本） | Δ 表 + 变量对齐全给 | 只给"差异在哪、结论是什么、能否归因" | Δ 表进正文 |
| 优化建议 A 路径 | 含具体改法 | 只给"做什么 + 收益 + 成本 + 风险" | 分级给，改法进正文 |
| 优化建议 B 路径（功能换性能） | 只列退让点 + 技术收益 + PM 决策状态 | **正文重点**：取舍、用户影响、建议与否 | 全给，PM 结论进正文 |
| 验证计划 | 含具体压测/ profiling 方法 | 只给"验收判据" | 全给 |
| 图表（只画"卡在哪"） | 2-3 张：分段耗时 + 链路拓扑 / 卡点时序 | 1-2 张：分段耗时（+ 双样本差异） | 2-3 张；技术向图可移附录 |

**措辞约束**：产品档正文禁止出现未翻译的技术术语；出现"缓存命中率"这类必要概念时，后附一句业务解释（"即每次请求能直接取到数据、不必重新计算的比例"）。

#### 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 图，但**图的使命只有一个：卡在哪**——📊 分段耗时（时间卡在哪段）+ 🔗 链路拓扑（卡在哪个节点）+ 🕐 卡点时序（阻塞 / 并行结构）+ 📊 双样本差异（可选：🔍 归因链）。**硬禁止两类图**：① **决策路径类**（是否达标 / A·B 取舍 / 审批 / 排期）——一律用表或文字，禁止任何形式的 mermaid 图；② **优化建议类**（机理图 / 前后对比图）——优化项用一句话说清，"省掉什么"写进句子。**铁律**：① 图 / 一句话 / 表三者数字一致，图与一句话都不是第二份结论；② 🔴 假设画成虚线 / 空心并标"待验证"，否则图会把假设视觉坐实；③ 说不出"省掉什么"的优化项 = 未论证，不得进结论区；④ 不堆图（⚡ 0-1 / 📊 2 / 🧑‍💻 3 张）。模板与语法安全见 [reference.md](reference.md)「九、报告图表规范」。

---

### 🧪 阶段 7：验证计划与后续出口

#### 7.1 验证计划（必带）

| 验证项 | 验证方式 | 判据 | 前置条件 |
|--------|----------|------|----------|
| `<优化项>` | 压测 / APM 对比 / 火焰图复采 / SQL EXPLAIN 对比 | P95 从 X 降到 ≤Y（同负载同数据量） | 需压测环境 / 需数据量 N |

**验证三要素**：同负载、同数据量、同观测窗口——三者不齐的对比不成立，须在计划中写明。

**B 路径项须加产品验收判据**：功能退让除了性能判据（P95 达标），还须写"退让后产品侧仍可接受"的判据（如"列表总数误差 <1%"、"每页 200 条设置项仍可用"、"风控校验未被降级"）——**没有产品判据的 B 项不得标为可实施**。

#### 7.2 后续出口

| 出口 | 交接 |
|------|------|
| B 路径（牺牲产品功能换性能）需产品取舍 | `use_skill("product-manager")`——阶段 5.5 已调用则在本表登记结论去向 |
| 优化方案落地前刹车 | `use_skill("request-guard")` → 通过后进 `use_skill("code-review")` |
| 需要实测验证 | `use_skill("demo-verify")` / `use_skill("e2e-testing")` |
| 性能优化需立项 | `use_skill("requirement-mining")` |
| 结论需对抗式复核 | `use_skill("challenger")`（optimization 策略） |
| 经验沉淀 | `use_skill("solution-capture")` / 项目记忆 |

---

## 约束与原则

1. **不臆造数据**：没有测过的数字一律不写；用 `[待补：需要什么数据]` 占位
2. **结论分级铁律**：🔴 假设禁止出现在结论区，只能进「待验证清单」且必须配验证方法
3. **先定位后优化**：未定位到瓶颈前不输出优化建议；优化建议必须对应到已定位的瓶颈
4. **收益有上限**：每个收益数字必须能追溯到占比 \(p\) 与加速比 \(s\)，或明确标注为区间估算
5. **对象锚定**：分析单位是接口 / 链路 × 负载场景；不做无对象的"系统整体性能评估"
6. **只出报告，不改码、不压测**：不修改代码、不执行压测或任何有副作用的写操作。**只读诊断例外**——环境可用且用户确认时，可协助执行 `EXPLAIN ANALYZE` / 慢日志 / 只读采样 / 读监控指标等只读命令把 🔴 升级为 🟢（执行前须说明命令与影响）；压测与写操作一律交 `demo-verify` / `e2e-testing`
7. **读者档位先问后写**：阶段 0.3 未获回应时默认双读者档并标注
8. **不凑数**：某层无命中就写"未命中"，不为了显得全面而列通用建议；图表同理——不插说明不了问题的图
9. **配置与形态优先于算法**：先查连接池 / 超时 / 批量 / 缓存 / 串行结构，再谈算法常数优化
10. **根因在上游要标注**：本层只能缓解时明确写出边界，不把缓解包装成解决
11. **中文输出**：报告用中文，术语与代码标识符保留原文
12. **双样本先变量对齐再归因**：仅单一变量不一致时差分才可用；多变量混淆必须明写"不可据此归因"并给出补齐单变量对照的做法，**禁止在混淆状态下硬归因**
13. **差分看 Δ 不看占比**：用绝对差值的贡献度排嫌疑；同时显式写出"经对照已排除"的段——排除结论与定位结论同等值钱
14. **性能不佳必给双路径**：判定为性能不佳时，第五章须同时给 A（功能等价技术优化）与 B（功能换性能）；只给 A 等于把"功能不能动"这个产品决策悄悄替用户做了
15. **功能取舍不自裁**：B 路径的产品价值判断须由 `product-manager` 产出；本 skill 只给"耗时由哪些产品形态决定"的技术输入与退让后收益估算，**不得自行决定砍 / 降哪个功能**；PM 不可用时降级为"候选退让点 + 待产品确认"，并声明未经产品分析不作决策依据
16. **A 路径须可证明功能等价**：A 表每项写明"为何不改产品行为"；会改产品行为的改法不是 A，必须转 B 路径
17. **报告顶部必带目录索引（⚡ 轻量档除外）**：锚点与标题一致、落盘前逐条点检，标题不放 emoji（否则锚点失效）
18. **决策路径与优化建议一律不画图**：达标判定 / A·B 取舍 / 审批 / 排期用表或文字；优化项一句话——A `改什么 → 省掉什么 → 收益上限`，B `让出什么 → 换多少收益`

## 与相关 skill 的关系

| 相关 skill | 边界 |
|------------|------|
| `code-review` | 审查**变更 diff** 的性能隐患（七维度之一），对象是一次提交；本 skill 面向线上/既有接口与链路的深度专项 |
| `artifact-optimizer` | 广度"能不能更好"的优化扫描，明确不覆盖性能专项；本 skill 是性能深度专项 |
| `debug` | 功能异常与报错排错；本 skill 只处理"能跑但慢 / 资源占用高" |
| `demo-verify` / `e2e-testing` | 承接本 skill 输出的验证计划，跑实测拿证据 |
| `request-guard` → `code-review` | 优化方案落地前的刹车与变更审查 |
| `product-manager` | B 路径的产品取舍分析：退让点的用户价值、Kano 分类、受影响用户面、可接受退让形式与底线、是否建议采纳；本 skill 只提供技术侧退让点候选与收益估算 |
| `requirement-mining` | 性能优化需立项排期时，用本报告作为现状与收益依据 |
| `challenger` | 对分析结论做对抗式复核（optimization 策略） |

## 反模式

- ❌ **无数据下实锤**：没有火焰图却写"瓶颈在 X 函数，占 60%"
- ❌ **通用建议堆砌**："加缓存、加索引、改异步、上线程池"——与本项目证据无关的清单
- ❌ **收益无上限、无依据**：优化 2% 占比的段却宣称整体提升若干倍
- ❌ **技术黑话给产品**：产品档正文中未翻译的术语
- ❌ **混淆性能与功能 bug**：报错、数据错误属 `debug`，不是性能分析。**判定问句**："结果对不对？"——结果错误 / 报错 / 死循环（即使表现为慢）→ `debug`；结果正确但慢或资源高 → 本 skill
- ❌ **报告不带验证计划**：改完无法判断是否有效
- ❌ **无视负载场景**：脱离并发与数据量谈"响应时间"，结论不可复现
- ❌ **为凑全面而硬找命中**：无命中就写无命中
- ❌ **图替代表 / 图不符表**：只给图不给数据表，或图中数字与表不一致；🔴 假设画成实线实心，一张图把猜测坐实成"已证实的瓶颈"
- ❌ **报告无目录 / 目录点不动**：长报告只能靠滚动找章节；锚点与标题不匹配、标题带 emoji 导致跳转失效
- ❌ **给决策路径或优化建议配图**：达标判定、谁审批画成流程图；优化项画成机理图 / 前后对比图——一句话能说清的事，图只会让读者更累
- ❌ **多变量混淆硬归因**：两份样本差了版本 + 数据量 + 环境三个变量，却断言"瓶颈是新版本引入的"——此时任何归因都是猜
- ❌ **双样本用错**：分别单独分析白白浪费最强线索，或只看占比不看 Δ（占比会被总耗时稀释，慢样本某段占比最高 ≠ 它是变慢的原因）
- ❌ **只给技术优化、把砍功能的选择藏起来**：A 路径收益明闭合不了缺口却不提 B 路径——等于替产品做了"功能一个都不能动"的决定
- ❌ **自行拍板砍功能**：没有 PM 分析就写"建议关闭实时统计"——用户价值、影响面不是性能分析能判的，须交 `product-manager`
- ❌ **把改了产品行为的方案塞进 A 路径**："实时改 T+1""去掉高开销字段""默认关掉"都属 B 路径，标成"技术优化"会绕过产品决策

## 附加资源

- 八层详细检查清单、技术栈速查（Python/Java/Go/Node/DB/Redis/网关）、收益估算示例、证据采集命令速查、三档位完整报告模板、**双样本差分分析（含变量对齐模板与 ΔN/Δt 算式）**、**优化建议双路径（退让点候选清单 / 交 product-manager 的输入包与回执字段 / 九种退让形态 / 收益叠加口径）**、**报告图表规范（只画"卡在哪"的图集、一句话优化建议写法、目录锚点规则、语法安全）**：[reference.md](reference.md)
- 典型场景示例（S1 证据驱动 / S2 现象驱动 / 产品档摘要 / S3 容量预判 / **差分强可用** / **多变量混淆拒绝归因** / 读者询问话术 / **A 路径不足、调 PM 做 B 路径取舍**）：[examples.md](examples.md)