1实现原理 · 为什么它能做到
SKILL.md 本身只有 93 行 / 3.2KB，是一张路由表：正文用『Skill Contents』把 7 篇 docs、5 个 examples、2 个 templates、1 个 cheatsheet 逐条列名，agent 按当前任务再加载对应文件（渐进披露），而不是把 50KB+ 文档一次性灌进上下文。
skills/webgpu-threejs-tsl/SKILL.md
- `docs/compute-shaders.md` - GPU compute with instanced arrays
注：这里在做什么：SKILL.md 只承担索引职责，把『何时加载什么』交给宿主模型；体量对照——SKILL.md 3.2KB，而 docs/ 7 篇合计 56.6KB、REFERENCE.md 9.1KB。
Cursor 侧把同一套披露策略写成显式话术：.mdc 正文只留三五行摘要，然后用 @file 引用指向 skills/ 下的原始文档（5 个 .mdc 合计仅 5.9KB，却挂了 10 条 @ 引用）。
.cursor/rules/webgpu-threejs-tsl.mdc
The source-of-truth documentation lives under `skills/webgpu-threejs-tsl/`. Reference these files directly when deeper guidance is needed:
注：README 把这些 .mdc 称为 thin shims；@skills/... 的引用行可用 grep 逐条核实（webgpu-threejs-tsl.mdc 4 条、compute-shaders.mdc 3 条、post-processing.mdc 2 条、device-loss-and-limits.mdc 2 条、wgsl-integration.mdc 1 条）。
『能写对代码』的真正支点是文档反复钉死的一条 TSL 语义陷阱：TSL 只能拦截节点属性赋值，拦不住 JS 变量重赋值——所以在 If() 里写 value = value.add(1.0) 会静默失效（返回旧节点、不报错）。
skills/webgpu-threejs-tsl/docs/compute-shaders.md
**TSL can intercept property assignments on nodes, but NOT JavaScript variable reassignment.**
注：为什么这条关键：这是 TSL 里最典型的静默 bug（编译通过、结果错）。skill 在三处重复同一警告——core-concepts.md §『⚠️ CRITICAL: Property Assignment vs Variable Reassignment』、compute-shaders.md 开篇、templates/compute-shader.js 头部注释——并给出 select() / .toVar() / 直接 element.assign() 三种正确写法。
不只给规则，还给失败机理，避免模型换个写法重犯同一个错：文档解释了 JS 变量重赋值会新建节点、而 TSL 看不到这次赋值，且标量没有 .x/.y 属性因此无法绕道属性赋值。
skills/webgpu-threejs-tsl/docs/compute-shaders.md
**Why it fails:** `value = value.add(1.0)` creates a new TSL node and reassigns the JavaScript variable to point to it.
注：同段的补充论证：'Since `value` is a scalar float (no `.x`/`.y` properties), you can't use property assignment.'——把机理讲透后模型才能泛化到文档没列的场景。
版本断层以文档条目形式固化，而非运行时探测：skill 不去读用户项目的 three 版本，而是把 r17x–r18x 的破坏性改动写成对照条目，交由模型自行比对。
skills/webgpu-threejs-tsl/docs/post-processing.md
> **Note:** `PostProcessing` was renamed to `RenderPipeline` in r183. `PostProcessing` still works as a compatibility wrapper but is deprecated.
注：同类条目：REFERENCE.md『Version Notes』的 r178+ 段（PI2→TWO_PI、transformedNormalView/World→normalView/World）、compute-shaders.md『computeAsync() is deprecated since r181』、post-processing.md 的 DOF r181 整体重写与 r177 blur sigma 重标定、r182+ 新增效果清单。SKILL.md 正文本身没有任何『先检查项目版本』的步骤。
模板是可直接落地的整文件骨架而非伪代码：分段骨架（CONFIG/GLOBALS/INITIALIZATION/SCENE/ANIMATION/EVENT）、插入点标记、结尾把内部对象 export 出去供外部调试。
skills/webgpu-threejs-tsl/templates/webgpu-project.js
// Export for external access if needed
注：webgpu-project.js 头部即写死用法：『1. Copy this file to your project 2. Install Three.js: npm install three 3. Replace placeholder content with your scene』；compute-shader.js 同构，另含 init/update/interaction 三 pass 占位与 export。价值在于让模型跳过建工程、装依赖、写渲染循环这些与 shader 无关的路。
WGSL 逃生口：TSL 表达不了或需要移植现成 WGSL 时，用 wgslFn() 把整段 WGSL 函数体嵌进 TSL 节点图；文档同时附 WGSL 类型/语法/内建函数速查，使模型脱离 TSL 也能写对 WGSL。
skills/webgpu-threejs-tsl/docs/wgsl-integration.md
TSL allows embedding raw WGSL (WebGPU Shading Language) code when you need direct GPU control.
注：wgsl-integration.md 内含 simplex noise、FBM 等完整长函数源码，属可直接抄走的语料；文档还给出『复杂数学用 WGSL、简单逻辑用 TSL』的混合范式。
把 WebGPU 特有的运行期故障面（设备丢失、limits/features）也纳入编码指导，使生成的代码不只是能跑，还考虑 GPU 崩溃与缓冲区上限。
skills/webgpu-threejs-tsl/docs/limits-and-features.md
Three.js accepts `requiredLimits` as a renderer constructor option, which gets passed through to `requestDevice()`:
注：配套：limits-and-features.md 列出默认 limits（maxBufferSize 268435456 即 256 MiB 等）与『先查 adapter 再请求』的安全写法；device-loss.md 覆盖 device.lost 检测、页面重载/仅重建 GPU 内容/带状态恢复三种恢复策略、destroy() 与 about:gpucrash 测试法及 Chrome 崩溃限额表。
2核心能力
01WebGPU 渲染器 + TSL 工程初始化与渲染循环骨架（renderer.init() 后再 compute/render）
02TSL 节点材质全谱：12 种 *NodeMaterial 与 colorNode/roughnessNode/metalnessNode/clearcoatNode/transmissionNode/iridescenceNode/sheenNode/anisotropyNode/dispersionNode 等属性映射
03GPU compute shader：instancedArray/attributeArray 存储缓冲、Fn().compute(count, [workgroupSize])、compute builtins、workgroup/storage barrier 与 atomic 操作
04后处理管线：bloom/blur/FXAA/SMAA/DOF/SSR/SSAO/film/outline 等内建效果、多种 MRT 通道、Fn() 自定义效果与效果链
05WGSL 集成：wgslFn() 嵌入自定义 WGSL 函数（含 simplex noise/FBM），并与 TSL 节点混用
06设备丢失（device loss）检测、恢复与测试，含状态保存/恢复与降级提示
07WebGPU limits / 可选 features 的查询与申请（requiredLimits 透传、先查后请、features 由 Three.js 自动申请）
08可运行示例与起步模板：5 个 examples + 2 个 templates（最小工程、自定义材质、10 万粒子 compute、后处理链、程序化地球与大气）
3外部依赖
| 类型 | 依赖 |
|---|---|
| package | three（npm 包，生成项目需自装） |
| package | three/addons 子路径（OrbitControls、BloomNode 等 addons 模块） |
| network | 文档引用链接（仅 markdown 里的参考资料链接，仓库内无任何抓取/请求代码，不被 skill 调用） |
4风险提醒 风险提醒：绿色 · 放心使用
风险提醒：绿色 · 放心使用
- 知识时效风险（版本漂移即失效） — 结论绑定 Three.js r171–r183 世代；若用户项目使用更早/更新的 three，文档中的 API（RenderPipeline、DOF 新签名、blur sigma 标定、compute 同步派发）可能直接不适用，而 skill 不做任何项目版本探测，模型可能照抄。
- 双份维护的实际漂移（已实证两处） — README 宣称 Cursor rules 是自动同步的 thin shims，但 .cursor/rules/post-processing.mdc 仍教 PostProcessing 类、compute-shaders.mdc 仍教 renderer.computeAsync()，与 docs 的 r183/r181 结论相悖；Cursor 用户按 rule 摘要写代码会写出过时/已弃用写法。
- 许可声明缺仓内 LICENSE 文件 — README 与 plugin.json 均声明 MIT，但仓库内没有 LICENSE 文件，GitHub API 检测为 null。多数场景无碍（示例注明源自 three.js MIT），但对需要法务留痕的使用方是程序性缺口。
- 文档自称与自身目录结构不一致（README 漏列 limits-and-features.md） — README 的 Skill Structure 图只列 6 篇 docs，实际 7 篇；对按 README 手动拷贝/裁剪目录的用户会造成漏文件。
- 语言与生态绑定 — 全部面向 JavaScript/TSL 与 three/webgpu 生态；若目标是原生 WebGPU/WGSL 工程或 WebGL/GLSL 项目，文档结构（节点材质、import 模式）帮助有限，仅 wgsl-integration.md 部分可迁移。
绿色档，纯静态知识资产：仓库 git ls-tree 仅 24 个文件，全部为 .md / .mdc / .json / 只读 .js 语料——无 package.json、无 scripts/ 目录、无 .sh/.py，故 scripts_executed 为空；全仓 grep 无 fetch/XMLHttpRequest/curl/wget/importmap 与 CDN 域名（unpkg/jsdelivr 零命中），网络面为空（README/REFERENCE.md 里的 threejs.org、toji.dev、webgpureport.org 只是 markdown 参考链接，无代码请求）；无 process.env/.env/token/cookie/credential 引用，凭证面为空；skill 自身不写文件（localStorage 仅出现在 docs/device-loss.md 教用户应用持久化状态的示例里）。唯一需记的是知识时效风险与双份维护漂移（Cursor 摘要滞后于 docs），属内容质量问题，不构成执行面风险。
5第二遍独立确认
- [ok] pin commit 与工作副本一致 — git rev-parse HEAD 输出 af2319bd01bb7cc881267a9ef42cafdaf5e9029d，与 .git/shallow 首行相同，等于任务 pin commit；结论只对该 commit 有效。
- [ok] skill 目录定位 — skills/webgpu-threejs-tsl/SKILL.md 存在且 frontmatter name: webgpu-threejs-tsl 与 slug 对应；同目录含 REFERENCE.md、docs/×7、examples/×5、templates/×2，路径写入 skill.path。
- [discrepancy] license 声明与仓库实际文件 — README.md 有『## License』段声明 MIT License，.claude-plugin/plugin.json 也写 "license": "MIT"；但 git ls-tree -r 全量清单里没有 LICENSE / LICENSE.md 文件，全仓 grep -il license 只命中 plugin.json、README.md 与 5 个 examples 的注释，与 GitHub API license=null 一致。即：许可为『源码内声明』而非仓内标准许可文件。
- [discrepancy] README 自述的 skill 结构图 vs 实际文件 — README『## Skill Structure』的 docs/ 分支只列 core-concepts / materials / compute-shaders / post-processing / wgsl-integration / device-loss 六篇（以 `└── device-loss.md` 收尾），而 docs/ 实有 7 篇——漏列 limits-and-features.md；SKILL.md 的 Skill Contents 则完整列出七篇。属 README 文档漂移。
- [discrepancy] Cursor 摘要与 docs 的 API 世代是否一致（后处理） — .cursor/rules/post-processing.mdc 仍教 `import { PostProcessing } from 'three/webgpu';` 并说 postProcessing.renderAsync()，而 docs/post-processing.md 开篇即注明 r183 已改名 RenderPipeline、旧名仅为兼容包装，examples/post-processing.js 实际用的是 `new THREE.RenderPipeline(renderer)`。README 自称 shim 会『edits flow through automatically』——该说法对手写摘要句不成立。
- [discrepancy] Cursor 摘要与 docs 的 API 世代是否一致（compute 派发） — .cursor/rules/compute-shaders.mdc 写『dispatched via `renderer.computeAsync()`』与『- `renderer.computeAsync(kernel)` to dispatch』，而 docs/compute-shaders.md『Execution Methods』明确『// Note: computeAsync() is deprecated since r181.』并给出『await renderer.init() at startup, then renderer.compute() synchronously』；templates/compute-shader.js 与 examples/particle-system.js 用的都是 renderer.compute(...)。同一漂移问题的第二例。
- [ok] 外部依赖反查：是否存在 CDN/网络调用 — 全仓 grep -riE 'unpkg|jsdelivr|cdn\.|importmap|import-map' 零命中；templates/examples 的 import 全部是裸包名（three、three/webgpu、three/tsl、three/addons/...），无 URL 形式的模块来源。故 external_deps 只列 npm 包，security.network_calls 为空。
- [ok] 脚本/凭证面反查 — git ls-tree 全清单只有 .md/.mdc/.json/.js；无 package.json（因此无 npm scripts、无依赖安装钩子）、无 scripts/、无 .sh/.py；危险 token 扫描对 child_process/eval/new Function/process.env/.env/token/secret/document.cookie/credentials 均无命中。scripts_executed 与 credential_reads 为空有据。
6结论
适合：适合正在用 Three.js 写 WebGPU/TSL 应用的前端与图形开发者、以及需要让 agent 代写 shader 的团队：项目处于 three r171–r183 世代时价值最大，尤其是自定义节点材质、compute 粒子、后处理链、WGSL 混写这几类任务；也适合作为 Claude Code 插件或 Cursor 规则直接挂载到项目，让 agent 在你写 *.js/*.wgsl 文件时自动带上正确 API 世代与坑位提示。想快速起项目的人可直接拷 templates/webgpu-project.js。
不适合：不适合 three 版本明显偏离 r171–r183 的项目（旧版 r15x 或未来大改版会照抄到失效 API，需人工比对）；不适合把 Cursor rules 当唯一信源——两处摘要已滞后，深水区必须回读 skills/ 下的 docs；不适合原生 WebGPU/WGSL 或 WebGL/GLSL 项目（覆盖仅限 three/webgpu + TSL）；不适合需要即时可运行产物或自动验证的场景（无脚本、无构建、无测试，正确性依赖模型照文档抄写）；也不适合要求仓内标准 LICENSE 文件的合规流程。
安装 agent 直装可复制
① 本站镜像 更新 2026-09-15
方式 A · 人下载镜像包下载 webgpu-three-js.tar.gz
sha256:
方式 B · JSON 格式安装指南，复制给 agentafb594cdc14fec2b…agent 读 JSON 指南后会自动从本站下载安装，无需更多说明。
② 上游 GitHub · 原始来源
来源信息 GitHub 原始
作者 / 仓库dgreenheck / dgreenheck/webgpu-claude-skill
原始 GitHubdgreenheck/webgpu-claude-skill ↗
Stars1192
最近推送2026-04-10
本 skill commit
af2319bd01许可MIT（README.md 的 License 段声明 + .claude-plugin/plugin.json 的 "license": "MIT"；但仓库内不存在 LICENSE/LICENSE.md 文件，GitHub API license 检测为 null）
本站信息
收录日期2026-09-06
分类设计
侦查报告AI 侦查 · 2 遍 · 2026-09-06
本站镜像与 GitHub 原始是不同来源：本站锁定 commit 快照经 /r2 分发；GitHub 为实时上游，内容可能已更新。