Performance Analysis

---
name: performance-analysis
description: 对接口/请求链路做系统化性能分析：盘点证据（APM、压测、火焰图、慢查询、日志）与代码定位瓶颈，量化收益上限并按优先级给出优化建议，产出性能分析报告与验证计划；判定不佳时同时给"技术优化（功能等价）"与"产品侧功能退让（交 product-manager 判断）"两条路。触发："性能分析"、"性能优化"、"为什么这么慢"、"接口 RT 高"、"响应慢"、"CPU 打满"、"内存占用高"、"容量评估"、"出份性能报告"、"两份数据对比"、"优化前后对比"、"怎么才能快"；其他问题走 code-review / artifact-optimizer / debug；优化落地后的影响面与回归风险走 code-change-impact。
---

# ⚡ 性能分析（Performance Analysis）

## AI 说明层

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

**功能**：
- **输入自适应路由**：有实测数据（火焰图 / APM / 压测 / 慢查询）→ 证据驱动；只有现象 + 代码 → 假设模式（结论标待验证并配验证方法）；只有架构 / 容量目标 → 风险预判
- **证据三级制**：🟢 实测 / 🟡 静态可证 / 🔴 假设——结论区只收 🟢🟡，🔴 一律进「待验证清单」
- **八层瓶颈扫描**：链路拓扑 / 数据访问 / 缓存 / 外部依赖 / 并发异步 / CPU 算法 / 内存 GC / 数据规模，锚定接口与请求链路，可下钻到函数级热点取证
- **双样本差分对比**：输入含一份"快"的对照样本时，先做变量对齐（多变量混淆则拒绝归因），再用 Δ 分解定位差异段、明确排除相近段
- **收益量化**：按耗时占比 + 阿姆达尔上限估算，禁止"优化 2% 占比却宣称整体提升 50%"
- **优化建议两条路、每项可排序**：技术优化（功能等价，不改产品行为）+ 产品侧调整（交 `product-manager`：**退让型**牺牲部分功能换性能；**改进型**不牺牲功能，找原设计缺陷给更优设计，体验与性能双升）；每项给**推荐指数（★1-5）**与**预期效果**，章末附「改前 → 改后」文字树（与第四章调用链树成对）
- **读者档位自适应、交付前二次自查**：动笔前询问主要读者（开发 / 产品 / 双读者），按档位裁剪结构与措辞；报告落盘后按 6.3 做二次自查（读回文件 + 14 项清单），未通过项不得静默交付

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

## 角色定义

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

## 核心原则

1. **证据优先、结论分级**：没有测过就不写数字（宁可写"[待补：需 P95 数据]"）；🟢 实测 / 🟡 静态可证 可进结论，🔴 假设只能进「待验证清单」且必须配验证方法
2. **先定位瓶颈，再谈优化；定位后两条路都要给**：不输出"加缓存、加索引、改异步"这类与本项目证据无关的通用建议清单；**判定为"性能不佳"时**，须同时覆盖技术优化（功能等价）与产品侧调整（退让型 / 改进型，交 `product-manager`）
3. **收益可量化且有上限**：每个优化项给占比与整体收益上限、**推荐指数（★）**与**预期效果**，并写明估算依据
4. **对象锚定接口 / 链路**：分析单位是"某接口在某负载下的端到端耗时"，语言级热点只作为归因证据下钻，不独立成章
5. **只出报告与验证计划**：不改代码、不执行压测（只读诊断例外见约束 6）；实施与验证交接给下游 skill
6. **读者自适应**：动笔前确认主要读者，按档位裁剪；报告说读者能懂的话，**不照搬内部用语**
7. **资产复用、降级不阻塞**：查询专家资产与历史性能决策失败或无记录 → 忽略继续
8. **产品侧两型并重、取舍不自裁**：退让型（让功能换性能）与改进型（修原设计缺陷、体验与性能双赢）都要给；产品价值判断必须由 `product-manager` 出，本 skill 只给技术输入与收益估算，**不得自行拍板砍 / 降哪个功能**
10. **报告可导航、图只画"卡在哪"**：顶部必带目录索引（锚点跳转，标题不放 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 询问主要读者（动笔前必做）

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

```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\) 会被高估，收益估算随之失真。串并行多段时把关键路径画成 📅 gantt（秒级及以上首选，可同时展示"被掩盖的分区"），见 6.2。

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

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

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

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

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

1. 入口 → 编排层：有无串行可并行、重复调用、循环内远程调用
2. 下游调用：DB、缓存、RPC、MQ、第三方 API；关注批量 vs 单条、连接池 / 线程池大小、超时与重试配置
3. 数据形态与配置：是否走索引、全量加载、深分页、大对象传输；连接池、线程池、超时、批量大小、缓存 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）仍须写入「次要发现：两组均慢，属**存量性能债**」，否则报告会给团队错误的安全感
4. **并行段同样适用关键路径规则**：含并行 / 异步段时 Δ总 ≠ ΣΔ段（各分支取 Δ 最大值），参见阶段 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>`；**预期**：`<主指标>` 由 `<X>` 降至约 `<Y>`（端到端上限 `Z%`，复测确认）；推荐指数 `★★★★☆`。"

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

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

- **收益**：高 = 端到端收益上限 ≥10% 或解除容量/稳定性风险；低 = <10%
- **难度**：低 = 改配置 / 局部改写 / 加索引；高 = 改调用结构、引入异步、跨模块改造
- 每项须附**副作用与风险**（一致性、复杂度、可读性、运维成本），并在报告中给**推荐指数（★1-5）**与**预期效果**（星级口径见 [reference.md](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](reference.md)
- **B2 改进型（不牺牲功能）**：找**原产品设计的缺陷**（默认全量展示、强制实时、信息密度失衡、交互绕路造成重复请求、默认值不合理…）→ 给更优设计方向，**体验与性能双升**（方法与典型缺陷清单见 [reference.md](reference.md) 8.2）
- **步骤**：① 性能侧产「退让点 + 设计缺陷」候选（占端到端 \(p\)、可让出 / 可改进的收益上限）；② 调 `use_skill("product-manager")`——须显式声明任务（退让型=「产品侧调整·退让取舍」，改进型=「产品侧调整·设计改进」，可并用其体验走查与功能推演），产品形态不可知时影响面按 🔴 处理，**禁止写"影响 100% 用户"这类未证实覆盖度**；③ 并入报告，标决策状态（✅/⚠️/❌ 或「待产品确认」），**不得改写 PM 结论**

**降级不阻塞**：PM 不可用或用户拒绝调用 → B1 / B2 均标「⚠️ 待产品确认」，并声明"未经产品分析，不作为决策依据"。**禁止自行拍板**。

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

---

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

按阶段 0.3 的读者档位裁剪。**完整模板见 [reference.md](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](reference.md)「九、报告图表规范」。

#### 6.3 交付前自查（二次检查，必做）

报告写完并落盘后，**读回落盘文件**（不凭记忆；⚡ 轻量档读回对话中已输出的正文）按三遍法逐条核验：规则核验 → 数字交叉（执行摘要 / 耗时表 / 图 / 一句话 / 收益表 处处一致，并抽 3-5 个关键数字回对原始证据）→ 读者视角通读（看找不找得到结论、看不看得懂）。清单与检查方法见 [reference.md](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")` |

---

## 约束与原则

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