performance-optimization

性能优化

当核心问题是**“我们应该相信哪个产物、实际瓶颈在哪里，以及首先值得尝试的最小调优措施是什么？”**时，使用此技能。

这项工作的目的不是罗列泛泛的 React、SQL、缓存或游戏性能建议。 而是对问题进行分类，将当前产物整理成一份调优简报，选定一种主要模式，指出一个瓶颈，推荐一到两项高杠杆改动，然后验证改动前后的影响，并妥善转交剩余工作。

处理不熟悉的产物资料包前，请先阅读 references/intake-packets-and-escalations.md。 处理不熟悉的性能问题前，请先阅读 references/tuning-modes.md。 判断下一步应由 performance-optimization、monitoring-observability、debugging、testing-strategies、code-refactoring 还是 game-performance-profiler 负责时，请阅读 references/handoff-boundaries.md。 编写基准测试或性能分析计划前，请先阅读 references/measurement-checklist.md。

何时使用此技能

• 交互、页面加载、路由切换、API 热路径、查询计划、内存增长、包体积回退或帧预算相关问题，且瓶颈尚未定位
• 以跟踪记录、Lighthouse/CWV 报告、火焰图、查询计划、负载测试差异、性能分析器截图、基准测试记录或利益相关方仪表板形式提交的性能资料包
• 跨领域性能需求，涉及 CLI/开发工作流、Web/全栈、产品/运维、营销/内容性能或游戏相关路由，且尚不清楚下一步由谁负责
• 需要一份范围明确的调优简报，而非泛泛的性能建议清单

何时不使用此技能

• 主要任务是部署仪表板、告警、指标、跟踪记录或日志管道 → 使用 monitoring-observability
• 主要任务是复现正确性错误、定位回退或弄清行为异常的原因 → 使用 debugging
• 主要任务是在没有性能证据的情况下安全地进行结构清理、拆分或制定代码转换计划 → 使用 code-refactoring
• 主要任务是选择组织级测试层、合并/发布门禁或基准测试政策 → 使用 testing-strategies
• 瓶颈明确位于 Unity/Unreal/Godot 捕获数据中，且主要工作是针对特定引擎进行解读 → 使用 game-performance-profiler
• 瓶颈已定位，下一步是针对特定技术栈的实现细节；先整理调优简报，再转交给实现类技能

指南

步骤 1：梳理问题

在提出修复方案前，先用尽可能简短且有用的表述说明问题。

记录：

• 范围：CLI/开发 | 前端/页面加载 | API/服务 | 数据库 | 异步/容量 | 报告/仪表板 | 运行时/游戏 | 未知
• 症状：高延迟 | 低吞吐量 | 内存增长 | CPU 饱和 | 查询缓慢 | 包体积过大 | CWV 表现不佳 | 帧时间突增 | 未知
• 决策目标：p50/p95/p99 延迟、吞吐量、包体积、内存上限、帧预算、CWV 指标或基准测试时长
• 环境：本地 | CI 基准测试 | 预发布 | 生产环境 | 目标设备/硬件 | 混合/未知
• 问题是回退、长期存在的热点，还是描述模糊的问题

快速梳理：

Surface: API + database
Symptom: p95 latency jumped from 180ms to 850ms on order search
Decision target: restore p95 < 250ms
Environment: production-like staging
Regression: yes, after filter expansion

步骤 2：从接收材料包开始

使用 references/intake-packets-and-escalations.md。

选择用户目前实际拥有的材料包：

• 浏览器跟踪记录 / DevTools 录制
• Lighthouse、WebPageTest 或 CWV 报告
• APM 跟踪记录、火焰图、分析器输出或基准测试差异
• EXPLAIN / 查询计划 / 慢查询材料
• 分析器截图 / 统计信息叠加层 / 引擎捕获数据
• 电子表格、仪表板、报告摘要，或目前还没有可用材料

将此步骤的输出写为：

## Intake Packet
- Current artifact:
- Why it is enough (or not enough):
- Missing context to collect next:

规则：如果现有材料已经能缩小下一步决策的范围，就不要强迫用户采用理想的测量流程。

步骤 3：选择一种主要调优模式

从 references/tuning-modes.md 中选择一种主要模式。

主要模式：

• interaction-and-rendering
• page-load-and-bundle
• api-latency-and-hot-paths
• database-plan-and-data-access
• throughput-and-capacity
• memory-and-allocation
• runtime-frame-budget
• unknown-needs-better-measurement

规则：一种主要模式，可选一种次要模式。 不要在一个回答中混合所有可能的优化方向。

步骤 4：提出修复建议前，先指出瓶颈

将证据归纳为一条瓶颈陈述。

好的瓶颈陈述示例：

• “数据库工作已经完成，但端点受限于 JSON 序列化的 CPU 开销。”
• “搜索查询计划执行了范围很广的排序和筛选，因为复合索引与查询条件不匹配。”
• “交互延迟主要由一个长任务以及结果面板中的布局抖动造成。”
• “在目标硬件上，帧率峰值与资源流式加载突增同时出现。”
• “CWV 报告显示，LCP 主要受图像负载和阻塞渲染的脚本开销影响，而非服务器延迟。”

避免“整体性能不好”之类的模糊说法。

步骤 5：推荐一到两项高影响改动

优先选择能直接解决所述瓶颈、且最小而可靠的改动。

按模式划分的候选改动：

• interaction-and-rendering：缩小重新渲染范围，延迟非关键工作，避免布局抖动，对大型列表进行虚拟化，减少主线程上的同步工作
• page-load-and-bundle：拆分路由 / 模块，减少 JS，优化资源交付，压缩 / 调整图像尺寸，削减第三方开销，积极使用缓存
• api-latency-and-hot-paths：移除阻塞工作，缓存开销大的响应，降低序列化开销，并行执行安全的下游调用，预先计算开销大的转换
• database-plan-and-data-access：调整查询结构，添加 / 调整索引，移除 N+1 访问，更早应用筛选，改变分页策略，缩减行宽
• throughput-and-capacity：调整并发限制、队列结构、工作线程池大小、连接池大小、批次大小或缓存命中路径
• memory-and-allocation：减少内存分配与回收，限制缓存，在适当情况下复用缓冲区 / 对象，采用流式处理而非缓冲，缩小负载
• runtime-frame-budget：减少每帧工作量，分散开销大的任务，降低绘制 / 过度绘制压力，延迟流式加载突发任务，简化开销大的效果
• unknown-needs-better-measurement：不要猜测；询问用户能以最低成本区分可能原因的材料

经验法则：除非下一步是收集更多证据，否则最多推荐两项候选改动。

步骤 6：说明权衡并转交其他任务

每条调优建议都应说明可能带来的负面影响。

示例：

• 缓存可能降低延迟，但会增加数据陈旧或内存压力
• 批处理可能提高吞吐量，但会加剧尾延迟
• 分页或索引变更可能加快某个查询，但会让写入更复杂
• 延迟加载或拆分可能加快初始加载，但会增加后续交互延迟
• 图像压缩或简化资源可能降低质量，或需要内容／设计团队批准

需要时转交实现工作：

• 组件／状态架构清理 → react-best-practices、state-management 或 design-system
• 架构／索引／数据模型重设计 → database-schema-design
• 遥测部署或持续告警 → monitoring-observability
• 基准测试门禁策略 → testing-strategies
• 特定引擎的分析器结果解读 → game-performance-profiler
• 优先保证正确性的复现或环境漂移 → debugging

步骤 7：验证优化前后的影响

请使用 references/measurement-checklist.md。

验证材料应包括：

• 基线指标和环境
• 已变更的变量
• 在可比条件下测得的优化后指标
• 主要瓶颈是否转移或消失
• 残余风险／后续测量

良好的验证简报：

Baseline: p95 search latency 850ms on staging replay dataset
Change: added `(team_id, status, created_at)` index and removed N+1 author lookup
After: p95 230ms, DB time down 68%, CPU flat
Residual risk: cache-miss path still spikes at 400ms for very wide date ranges
Next if needed: cap date window or async export path

输出格式

## Performance Brief
- Surface:
- Symptom:
- Decision target:
- Primary mode:
- Current artifact:

## Bottleneck Hypothesis
- Primary bottleneck:
- Confidence:
- Why:

## Highest-Leverage Changes
1. ...
2. ...

## Tradeoffs / Risks
- ...

## Verification Plan
- Baseline:
- After:
- Guardrail:

## Route-outs
- ...

示例

示例 1：API + 数据库延迟回归

输入：“添加更多筛选条件后，我们的订单搜索端点突然变慢了。我们有 EXPLAIN ANALYZE 输出和慢查询日志。”

**预期形式：**归类为 database-plan-and-data-access，并将 API 作为次要模式；使用现有材料，而不是先索要通用遥测数据；找出最耗时的查询或序列化层；提出一两项有针对性的改动，然后定义优化前后的验证方法。

示例 2：营销／内容性能报告

输入：“我们的落地页 CWV 报告显示 LCP 和 INP 表现不佳。我们有 Lighthouse 和现场数据，但还没有分析器跟踪记录。”

**预期形式：**归类为 page-load-and-bundle，将报告视为完整的初始材料；区分可能的资源／渲染阻塞原因与遥测数据缺口；建议一两项范围明确的后续行动，并说明何时值得收集更多跟踪记录。

示例 3：转交至可观测性配置

输入：“我们需要仪表板、跟踪记录和告警，以便在用户投诉之前发现响应缓慢的端点。”

**预期形式：**转交至 monitoring-observability，而不是假装主要任务已经是性能优化。

示例 4：转交至游戏引擎分析器技能

输入：“Unreal 在 Steam Deck 上出现卡顿，我有一份 Insights 捕获记录。你能帮我解读吗？”

**预期形式：**承认更广泛的性能背景，但将特定引擎的捕获记录解读工作转交至 game-performance-profiler。

最佳实践

1. 从用户已有的材料入手；将其整理为调优简报，而不是丢弃。
2. 先测量，再调优。
3. 提出改动前，先指出一个主要瓶颈。
4. 控制建议范围：一两项高收益改动胜过一长串清单。
5. 验证影响时，确保环境可比。
6. 明确说明权衡，尤其是缓存、一致性、内存和内容质量方面的成本。
7. 将遥测配置、调试、重构和特定引擎分析器解读转交给相关技能，而不是包揽一切。

References

• Chrome DevTools Performance
• Lighthouse overview
• Core Web Vitals
• PostgreSQL EXPLAIN
• pg_stat_statements
• Flame Graphs
• Unity Profiler
• Unreal Insights
• Godot Profiler