用途：诊断并改进浏览器 WebGPU 渲染性能，覆盖帧节奏、绘制与状态提交开销、缓冲区上传、着色器与 JavaScript 成本。核心原则是先定位限制资源，再改渲染器，产出可复现的诊断，把 JavaScript 准备、浏览器/API 提交、数据传输和 GPU 执行分开，只做有测量支撑的改动。
必要上下文：先读仓库 AGENTS.md 与受影响项目的 DEVELOPMENT.md，检查渲染循环、更新路径、缓冲与纹理归属、着色器代码和资源生命周期。改动基准前先看 package.json、本地 Vitest 基准配置、已有 *.test.bench.ts 及其共享配置，不要假设其他项目的测试框架可直接套用。分类瓶颈、选择插桩或提出优化时参考性能诊断手册；新增或审查 *.test.webgpu.ts 套件时参考可复用 WebGPU 测试套件指南。
建立性能问题：测量前先定义工作负载与目标，区分初始化、稳态渲染、交互更新、流式更新、拾取/回读和清理，不要合并成一个指标。记录对象与图元数量、更新频率与大小、绘制/通道数、画布像素尺寸、设备像素比、透明、抗锯齿及相关渲染器设置。选择用户可见指标：帧预算与尾延迟、更新延迟、吞吐、启动时间或内存；仅看 FPS 可能被刷新率上限掩盖丢帧。保持正确性与代表性视觉输出，先看 git status --short 并保留无关改动。
先分类再优化：用独立 CPU 与 GPU 证据加受控扰动，不要仅凭低 FPS 推断 GPU 瓶颈或仅凭繁忙回调推断 CPU 瓶颈。测量帧间隔与 JavaScript 各阶段；在 API 与适配器支持计时查询时异步测量 GPU 通道耗时，不支持应视为测量限制而非零成本。一次只变一个维度：对象或绘制数、变更记录数、上传字节、图元数、画布像素、透明或通道数。用保留大部分管线、只去掉一类工作的诊断开关，比较禁用渲染、冻结更新、绕过上传、降分辨率、降着色器成本等情形。证据归类为 JavaScript/GC、API 提交或状态抖动、传输/同步、顶点/几何、片元/填充、着色器编译、资源分配或混合/未知；仍不明确时提出最小下一步实验，而非大重写。
正确使用仓库 CPU 基准：先发现 test:bench 脚本、基准配置与 .test.bench.ts。共享 Vitest 库基准配置识别 src/**/.test.bench.ts，但运行方式与环境由包本地配置和 DEVELOPMENT.md 决定。普通 Vitest 基准默认是 CPU 微基准，除非环境与回调另有说明；它不测量 GPUQueue.writeBuffer、命令执行、着色器、呈现或帧节奏。遵循包内既有模式，保留基准选项以保持可比性；无先例时显式选择并记录 warmup、duration、iteration。不在计时回调内创建代表性类型化数组，除非分配本身是被测对象。比较稳态复用与替换/增长、部分与全量提交、普通与最坏数据，用记录数、变更百分比、消费者扇出等缩放序列找复杂度和交叉点。基准命名包含工作负载规模与操作。仅在 DEVELOPMENT.md 定义脚本时通过 mise 运行：
mise exec -- pnpm run test:bench mise exec -- pnpm run test:bench -- --outputJson=benchmark.json mise exec -- pnpm run test:bench -- --compare=benchmark.json
保持基线与候选的环境、工作负载、基准选项和工作树状态可比；任何关于 GPU 执行或端到端渲染的结论都要用浏览器插桩。
使用仓库 WebGPU 测试工具：需要在不给被测页面加 Vitest 浏览器客户端的情况下跑生产 WebGPU 渲染器时，用共享的 Node 托管 Vitest 配置与 Playwright 运行器，从 @internals/vite/webgpu 导入配置、运行器、工具与类型，新消费者不要用根包导出或运行器深层导入。区分证据类别：check 模式用无头软件 WebGPU 做确定性的 API 调用、资源、上传、交互与清理不变量，只有它属于普通托管 CI 且不得含时间预算；measure、diagnostic、lifecycle 模式需要原生适配器，属于受控本地或专用 GPU 运行器，解释结果前先拒绝软件回退。test:bench 仍是 CPU/浏览器微基准流程，用于本地基线与候选比较，除非仓库采用受控运行器和明确基线策略，否则不要放进必需 PR CI。消费包负责其工作负载页面、代表性配置、断言、预算、生产边界规则与脚本；共享工具负责浏览器与服务器生命周期、适配器选择、外部 WebGPU 观察、环境捕获、DevTools 轨迹、内存快照、统计辅助与产物写入。
选择有证据支撑的改动：优先减少已确认限制路径上的重复工作。JavaScript 成本看每帧分配、重复转换或校验、矩阵与边界计算、重复扇出、缓存失效和可避免的 DOM/响应式工作；提交成本减少冗余状态变更与 API 穿越，在重复几何足够时批处理兼容绘制或用实例化；上传成本复用容量、合并脏区间、批处理兼容上传、按更新频率分离数据，避免在热循环创建上传视图或类型化数组；GPU 成本按测量到的缩放行为测试剔除、细节层次、过绘与透明、渲染分辨率、附件格式、抗锯齿、纹理采样和着色器工作；初始化成本复用管线与资源、避免重复编译，仅对静态数据考虑创建时映射。高级暂存环、间接绘制、着色器或计算重写、数据布局变更和 WebAssembly 属于增加复杂度的实验，需有证据表明更简单改动无法达标。同时检查绑定组与管线复用、写入频率、缓冲偏移对齐、命令/通道结构、着色器编译、纹理与附件抖动、异步映射或回读行为。
验证与报告：用户只要诊断时报告发现不改代码；要求改进时实现最小有支撑改动并验证：同条件下的目标基线与候选测量；当结论超出 CPU 准备时做真实浏览器渲染器的集成测量；DEVELOPMENT.md 中相关正确性、视觉与项目测试；当改动可能在不同区间取舍时，检查内存、方差和另一工作负载规模。报告工作负载、环境、测量与离散度、瓶颈分类、证据、改动或建议、置信度和剩余不确定性，并明确每个结果是 CPU 微基准、JavaScript 帧测量、GPU 计时结果还是端到端观察。
限制：资料未提供具体价格、平台支持范围或效果承诺；部分能力依赖适配器是否支持计时查询与原生 GPU 运行器。