AgentSkillsCN

performance-optimization

针对本仓库（React + R3F + Three.js + Vite）的性能优化手册（测量 → 诊断 → 修复 → 验证）。当用户被要求提升FPS、减少卡顿、降低绘制调用次数、优化加载/打包大小，或排查CPU/GPU/内存瓶颈时，即可使用此服务。

SKILL.md
--- frontmatter
name: performance-optimization
description: Performance optimization playbook (measure → diagnose → fix → verify) for this repo (React + R3F + Three.js + Vite). Use when asked to improve FPS, reduce jank, lower draw calls, optimize loading/bundle size, or investigate CPU/GPU/memory bottlenecks.

Performance Optimization (Opt-in)

Use this skill to make performance work repeatable and evidence-driven.

Workflow (always follow)

  1. •

    Define the symptom + target

    • •Runtime: FPS drops, stutters, GPU/CPU pegged, memory growth.
    • •Load time: slow first paint, large bundle, long shader compile.
    • •Pick a measurable target (e.g., steady 60 FPS, lower draw calls, smaller JS).
  2. •

    Measure before changing code

    • •Reproduce the issue and capture one of:
      • •Browser Performance trace (CPU main thread)
      • •R3F/Three stats (FPS, draw calls, triangles)
      • •Memory timeline (detached nodes, heap growth)
  3. •

    Classify the bottleneck

    • •CPU-bound: heavy JS, too many React renders, expensive per-frame work.
    • •GPU-bound: too many draw calls, heavy shaders/postprocessing, high DPR.
    • •IO/Load-bound: big bundles/assets, blocking work on startup.
    • •Memory-bound: leaks in textures/geometries/materials, retained arrays.
  4. •

    Apply the smallest fix that moves the metric

    • •Prefer fixes that reduce work per frame and draw calls.
    • •Keep changes surgical and verify the metric improved.
  5. •

    Verify and guard against regressions

    • •Run pnpm test, pnpm run lint, pnpm run typecheck.
    • •If you introduced a new helper/heuristic, add a small unit test.

R3F / Three.js tactics (common wins)

  • •Draw calls: prefer instancing/merging; reduce unique materials.
  • •DPR: cap DPR or use dynamic DPR.
    • •If you need dynamic DPR, use the existing dynamic-res-scaler skill.
  • •Per-frame work: keep useFrame callbacks tiny; avoid allocations inside useFrame.
  • •Memoization: cache geometries/materials/textures; reuse vectors/quaternions.
  • •Postprocessing: disable/scale effects on low perf; prefer fewer passes.
  • •Shadows: reduce shadow map size; limit shadow-casting lights.

React tactics (common wins)

  • •Avoid state updates every frame; use refs for frame-local values.
  • •Stabilize props to prevent re-render cascades.
  • •Split heavy components; lazy-load non-critical UI where appropriate.

When to load deeper reference material

  • •For generic perf checklists across frontend/backend/db: read references/performance-optimization.md.
  • •For dynamic DPR in this repo: read the dynamic-res-scaler skill.
  • •For offloading CPU-heavy loops: consider the js-worker-multithreading skill.