web3d-runtime 是一个用于构建或修复 Web 实时 3D 场景的技能，主要面向使用 three.js 或 React Three Fiber 的项目，涉及 WebGPURenderer 及其 WebGL2 回退、TSL 节点材质与 compute 计算等。它的核心思路是：three.js 在 WebGPU 上迭代很快，很多问题不会报错，而是“场景照常渲染，只是渲染错了”，因此该技能先列出失败情形，再给出正确模式。
用途 该技能用于在 Web 上搭建或修复实时 3D 场景，尤其是需要同时兼容 WebGPU 与 WebGL2 的项目。它强调先检查再报告：查看 package.json 中 three、@react-three/fiber、@react-three/drei 的版本；确认使用的是 three/webgpu 的 WebGPURenderer 还是经典 WebGLRenderer；检查是否存在自定义 ShaderMaterial、RawShaderMaterial 或 onBeforeCompile（这些在 WebGPU 上无法运行）；确认帧循环由谁掌控（setAnimationLoop、R3F 的 useFrame，还是多个 requestAnimationFrame，后者属于 bug）；以及是否有真实的性能测量证据，而非主观感觉。最终以“区域·现状·问题·修复”的表格形式报告，并只给出一个下一步动作。
主要能力 技能提供一条能力阶梯，按场景自上而下选择，且每一级都必须仍是可工作的页面：WebGPU（new WebGPURenderer() 后 await renderer.init()）；同一渲染器的 WebGL2 后端（WebGPU 不可用时自动启用，也可用 forceWebGL: true 强制，计算密集型功能需要更轻量的路径，可在 init() 后用 renderer.backend.isWebGPUBackend 检测）；以及“平静”降级（完全不用 WebGL、减少动效，或设备丢失无法恢复时，退化为静态图片或 CSS/SVG，仍保持可读）。
技能还汇总了 r186 中若干静默或反直觉的坑，例如：render() 在 await renderer.init() 之前会抛错；positionNode 会替换蒙皮、变形和实例化之后的 position，需用 positionLocal.add(offset) 保留；JS 重新赋值不等于 shader 存储，Fn 内应使用 .toVar() 配合 .assign()/.addAssign()，条件判断应使用 If/select；原子操作需先 storage(buf, 'uint', n).toAtomic()；computeAsync() 不等待 GPU，只有 renderer.getArrayBufferAsync() 能把结果读回 CPU；ShaderMaterial、RawShaderMaterial 和 onBeforeCompile 没有 WebGPU 映射，需移植到 TSL；WebGPURenderer 上 alpha 默认为 true；PostProcessing 现为 RenderPipeline，Clock 已弃用改用 Timer，PCFSoftShadowMap 在 WebGPU 上被移除，renderer.dispose() 是异步的；设备丢失应使用 renderer.onDeviceLost 和 renderer.onError；R3F 9.8.1 的默认值与 three 不同，如 ACES 色调映射默认开启、shadows={true} 会选中已移除的软阴影贴图（应使用 shadows="percentage"）、useFrame 的 delta 未做钳制。
使用方式 技能给出的流程为：渲染器与循环（一个渲染器、await init()、一个 setAnimationLoop、一个 Timer）；材质与着色器使用 TSL，逐粒子或逐实例的内容使用 compute；预热（在首个可见帧前 await renderer.compileAsync(scene, camera)，compute 用 compileComputeAsync），避免首次交互卡顿；在最弱目标设备上用 Inspector 或时间戳查询测量，再分配预算；降级（减少动效、无 WebGPU、设备丢失、标签页隐藏各有明确分支，且每个分支都经过验证）；拆除（释放几何体、材质、纹理和渲染目标，await renderer.dispose()）。
技能还提供三份参考文档：references/renderer-and-loop.md（创建渲染器、回退、循环与时钟、颜色与色调映射、后处理、设备丢失、释放）、references/tsl-and-compute.md（编写 TSL 材质或着色器、compute pass、粒子、原子操作、读回、移植 GLSL）、references/performance-and-r3f.md（测量或修复帧时间、绘制调用与内存；在 WebGPU 上运行 React Three Fiber；drei 在 WebGPU 上的表现）。
适用场景 适用于使用 three.js 或 React Three Fiber 构建实时 3D 场景、需要 WebGPU 与 WebGL2 双后端兼容、需要排查静默渲染错误、需要测量帧时间与绘制调用、需要设计降级策略，以及需要将 GLSL 移植到 TSL 的项目。
限制 该技能的事实以 three.js r186 为基准，其他版本需先查阅版本说明，不能盲目套用 r186 的名称，也不应在未经操作者同意的情况下升级依赖。若宿主环境没有工具，只能写出命令和代码，不能编造结果；没有浏览器或 GPU 时，只能构建、类型检查和审查，视觉与帧时间门槛应标记为 NOT_RUN 并说明需要人工在何种页面和设备上运行。R3F 项目若想使用 WebGPU，需采用异步 gl 工厂模式，并在切换前列出场景中无法在 WebGPU 上运行的 drei 组件。资产文件与预算属于 web3d-assets，让物体动起来属于 web3d-animation。