dgreenheck/webgpu-claude-skill · 上手攻略

仓库：dgreenheck/webgpu-claude-skill
链接：https://github.com/dgreenheck/webgpu-claude-skill
分类：Claude Skill · WebGPU · Three.js
作者：Jay
更新：2026-08-13

这是什么

webgpu-claude-skill 是一个 Claude Code Agent Skill，让 Claude 能够帮助开发者编写基于 WebGPU + Three.js 的 3D 图形程序，重点覆盖 TSL（Three.js Shading Language） 着色器编程、GPU 计算着色器和后处理效果。

核心定位：把 Claude 变成一个懂 WebGPU + Three.js TSL 的结对编程搭档——你可以用自然语言描述想要的着色效果，Claude 帮你写出对应的 TSL/WGSL 代码。

⚠️ 版本备注：文档标注"Last updated: April 1, 2026 — aligned with Three.js r183+ API changes"。当前时间为 2026 年 8 月，Three.js 后续版本 API 可能有变化，r183+ 之后的 Breaking Changes（如 normalView/World 重命名、PI2 废弃）请参阅 Three.js TSL Changelog。

解决什么问题

WebGPU 是浏览器的下一代图形 API，Three.js 自 r170+ 开始引入 WebGPU 渲染器并同步推出 TSL（类 JavaScript 风格的着色器语言，替代原来的 GLSL）。但 WebGPU + TSL 的学习曲线很陡：

TSL 语法独特：TSL 节点（float、vec2、color、Fn 等）和 Three.js 原有材质系统完全不同。
WGSL 门槛高：需要编写原生 WGSL 代码时，没有好的中间层抽象。
API 迭代快：Three.js r178+ 有 Breaking Changes（transformedNormalView → normalView），文档过时快。
Claude 不懂 TSL：通用 LLM 不知道 TSL 语法和 Three.js WebGPU API，直接问它会得到 GLSL 风格的错误代码。

这个 Skill 的价值是把 Three.js 官方文档 + 社区最佳实践结构化，让 Claude 在生成 TSL 代码时能引用准确的 API。

快速安装

方式一：Claude Code Skill 安装（推荐）

/skill install webgpu-threejs-tsl@<your-github-username>/webgpu-claude-skill

⚠️ 这里的 <your-github-username> 需要替换为实际的 GitHub 用户名（dgreenheck）或 fork 此仓库后的你自己的用户名。

方式二：手动复制

# 全局安装
cp -r skills/webgpu-threejs-tsl/ ~/.claude/skills/

# 项目级安装
cp -r skills/webgpu-threejs-tsl/ <your-project>/.claude/skills/

方式三：Cursor 项目

# 将两个目录复制到项目根目录
cp -r .cursor/ <your-project>/
cp -r skills/ <your-project>/
# Cursor 会自动识别 .cursor/rules/ 中的 .mdc 文件

核心用法

安装后做什么

Skill 安装完成后，Claude Code 会自动识别以下文件 glob 并加载对应规则：

.mdc 规则文件	触发文件类型
`webgpu-threejs-tsl.mdc`	JS/TS 入口文件
`compute-shaders.mdc`	文件名含 `compute` 或 `particle`
`post-processing.mdc`	文件名含 `post`、`effect`、`bloom`
`wgsl-integration.mdc`	`.wgsl` 文件或文件名含 `wgsl`
`device-loss-and-limits.mdc`	文件名含 `renderer` 或 `webgpu`

基础 WebGPU + TSL 代码示例

以下是一个完整的 Fresnel 材质动画代码（来自 Skill 文档）：

import * as THREE from 'three/webgpu';
import { color, time, oscSine, normalWorld, cameraPosition, positionWorld, Fn, float } from 'three/tsl';

// 初始化 WebGPU 渲染器
const renderer = new THREE.WebGPURenderer();
await renderer.init();

// 创建 TSL 材质
const material = new THREE.MeshStandardNodeMaterial();
material.colorNode = color(0x0066ff);

// Fresnel 发光动画
material.emissiveNode = Fn(() => {
  const viewDir = cameraPosition.sub(positionWorld).normalize();
  const fresnel = float(1).sub(normalWorld.dot(viewDir).saturate()).pow(3);
  return color(0x00ffff).mul(fresnel).mul(oscSine(time));
})();

关键 TSL 节点速查（详见 skills/webgpu-threejs-tsl/docs/core-concepts.md）：

类别	节点
类型构造	`float()`、`vec2()`、`vec3()`、`vec4()`、`color()`、`uniform()`
向量操作	swizzling（`.xyz`）、`.normalize()`、`.sub()`、`.mul()`、`.pow()`
数学函数	`oscSine()`、`oscSquare()`、`mix()`
控制流	`Fn()`、`If`、`Loop`
材质节点	`MeshStandardNodeMaterial`、`MeshPhysicalNodeMaterial`

粒子系统（GPU Compute）

// skills/webgpu-threejs-tsl/examples/particle-system.js
// 使用 GPU compute shader 进行并行粒子模拟
import { /* compute shader nodes from TSL */ } from 'three/tsl';

后期处理

// skills/webgpu-threejs-tsl/examples/post-processing.js
// Bloom / FXAA / DOF 等内置效果链式调用

自定义 WGSL

// 使用 wgslFn() 嵌入原生 WGSL 代码
import { wgslFn } from 'three/tsl';
const myFunc = wgslFn`
  fn myCustomFunc(position: vec3f) -> vec3f {
    return position * 2.0;
  }
`;

核心文档结构

skills/webgpu-threejs-tsl/
├── SKILL.md               # 入口概览
├── REFERENCE.md           # 速查表
├── docs/
│   ├── core-concepts.md   # 类型、运算符、uniform、控制流
│   ├── materials.md       # 节点材质类型与属性
│   ├── compute-shaders.md # GPU 计算文档
│   ├── post-processing.md # 内置/自定义后处理效果
│   ├── wgsl-integration.md# wgslFn() 自定义 WGSL
│   └── device-loss.md     # GPU 设备丢失处理与恢复
├── examples/
│   ├── basic-setup.js     # 最小可运行项目
│   ├── custom-material.js # 自定义着色材质
│   ├── particle-system.js # GPU 计算粒子
│   ├── post-processing.js # 效果管线
│   └── earth-shader.js    # 完整地球 + 大气着色器
└── templates/
    ├── webgpu-project.js  # 项目模板
    └── compute-shader.js   # 计算着色器模板

典型适用场景

场景	为什么用这个 Skill
写 Three.js WebGPU 着色器	Claude 直接输出正确 TSL，而非 GLSL 错误代码
快速原型 3D 可视化	用 examples/ 模板 + 自然语言描述修改
学习 TSL 语法	docs/ 目录系统整理了节点 API
Cursor 项目集成	.mdc 规则自动按文件 glob 加载，不用配置

坑与注意

WebGPU 浏览器支持有限：Chrome 113+ / Edge 113+ 完全支持；Firefox 需手动开启 dom.webgpu.enabled；Safari 处于 Preview 阶段。开发阶段推荐用 Chrome。
Three.js 版本锁定：Skill 文档基于 r183+。Three.js r178 有一次 Breaking Changes（transformedNormalView/World → normalView/World），r183+ 可能还有后续变化。生产项目请在 package.json 锁定确切的 Three.js 版本。
PI2 已废弃：r178+ 中 PI2（2π）已废弃，应使用 TWO_PI，Skill 文档可能未完全同步。
import * from 'three/webgpu' 需要 import map：使用 TSL 需要在 HTML 或构建工具中配置 Three.js 的 import map，正确解析 three/webgpu 路径。
Skill 与 Cursor 规则的同步：Skill 是源码，Cursor 的 .cursor/rules/*.mdc 是引用 skills/webgpu-threejs-tsl/ 的 thin shim。如果修改 skills 目录内容，Cursor 规则会自动同步，但需要保持两个目录都在项目根目录下。
GPU 设备丢失（Device Loss）：WebGPU 不像 WebGL 那样有稳定的上下文恢复机制，Skill 提供了 device-loss.md 专门讲述如何在设备丢失后重建状态，需要显式处理 renderer.forceRestoreDevice() 等。
WSL 2 显存问题（Windows）：在 Windows 上用 WSL 2 运行 Chrome WebGPU 时，显存分配策略与原生 Linux 不同，大型粒子系统可能触发 OOM。

与同类对比

方案	定位	TSL 支持	WGSL 嵌入	浏览器覆盖
webgpu-claude-skill	Claude Agent Skill	✅ 完整	✅ wgslFn()	取决于用户环境
Three.js 官方 Examples	参考代码	✅ 示例代码	✅	需手动适配
Three.js TSL 官方文档	文档	✅ 完整	✅	参考
WebGPU Best Practices (toji.dev)	最佳实践指南	❌	✅	独立文档

这个 Skill 的核心价值是让 Claude 知道 Three.js WebGPU 的正确 API，而不是自己造一个文档。

一句话推荐结论

正在用 Three.js WebGPU 开发，或想用 Claude 辅助写 TSL/WGSL 着色器代码，这个 Skill 是目前最系统的上下文资源；纯学习 Three.js WebGPU 直接看官方文档即可。

原始 commit：https://github.com/dgreenheck/webgpu-claude-skill（具体 SHA 需从仓库确认）