内容
# 网页着色器代理工具包
> 一个为 AI 编程代理（Claude Code、Cursor、Copilot、Windsurf、ChatGPT 等）提供真正擅长 **网页着色器** 的启动套件 —— GLSL、WGSL、WebGL 2、WebGPU、Three.js 和 React Three Fiber。
大多数代理编写的着色器看似合理，但渲染黑色，重新声明 Three.js 注入的统一变量，或忽略颜色空间和长宽比。这个工具包编码了平台矩阵、正确的样板代码和静默失败的陷阱 —— 作为一个可重用的技能、跨工具规则、文档清单、MCP 配置和系统。您可以全部使用，也可以根据需要使用其中的部分。
本工具包与 [Awesome 网页着色器](https://github.com/owenob1/awesome-web-shaders) 列表配套使用。
## 内容
| 文件 | 用途 |
|---|---|
| [`skills/web-shaders/SKILL.md`](skills/web-shaders/SKILL.md) | Claude Code / Codex 代理 **技能** —— 完整的、结构化的专业知识。 |
| [`rules/cursor/web-shaders.mdc`](rules/cursor/web-shaders.mdc) | **Cursor** 项目规则。 |
| [`rules/AGENTS.md`](rules/AGENTS.md) | 通用 `AGENTS.md` / `CLAUDE.md` / Copilot / Windsurf / Cline 规则。 |
| [`llms.txt`](llms.txt) | **文档清单** —— 指向权威着色器文档的代理。 |
| [`mcp/recommended-mcp.json`](mcp/recommended-mcp.json) | 建议的 **MCP 服务器** （Context7 文档、Shadertoy）。 |
| [`prompts/system-prompt.md`](prompts/system-prompt.md) | **系统提示** 用于聊天助手 / 自定义 GPT / 项目。 |
## 安装
**Claude Code** —— 将技能复制到您的项目或用户技能目录：
```bash
mkdir -p .claude/skills
cp -r skills/web-shaders .claude/skills/
```
Claude 在任务与技能描述匹配时自动加载它。
**Cursor** —— 将规则复制到您的项目：
```bash
mkdir -p .cursor/rules
cp rules/cursor/web-shaders.mdc .cursor/rules/
```
**Copilot / Windsurf / Cline / 通用** —— 将 `rules/AGENTS.md` 复制到您的项目根目录（或粘贴到 `CLAUDE.md` / `.github/copilot-instructions.md` / Windsurf 规则）。
**任何代理** —— 将 [`llms.txt`](llms.txt) 交给它，以便它获取真实的 API 文档，并将 [`mcp/recommended-mcp.json`](mcp/recommended-mcp.json) 合并到您的 MCP 客户端配置中，以获取实时文档和 Shadertoy 访问。
**ChatGPT / 自定义 GPT / Claude 项目** —— 将 [`prompts/system-prompt.md`](prompts/system-prompt.md) 粘贴到系统说明中。
## 它教什么
- **目标优先** —— WebGL 2（GLSL ES 3.00）与 WebGPU（WGSL）与 Three.js `ShaderMaterial`/`RawShaderMaterial`/TSL 与 R3F，以及每个的正确样板代码。
- **注入统一变量陷阱** —— Three.js `ShaderMaterial` 已经提供了什么，以便代理停止重新声明 `position`、`uv` 和矩阵。
- **正确性** —— 长宽比、UV 原点、sRGB/线性颜色、色调映射、预乘 alpha。
- **可移植性陷阱** —— 动态数组索引、非常量循环、整数除法、负数的 `pow`/`mod`、精度限定符、WGSL 对齐。
- **调试工作流** —— 可视化中间结果、读取编译错误、验证统一变量、使用 Spector.js / WebGPU Inspector 检查。
## 贡献
欢迎改进 —— 尤其是实际交付浏览器着色器时的陷阱。打开一个问题或拉取请求。
## 许可证
[MIT](LICENSE)。
