# 使用手册

## 界面

```
┌──────────────────────────────────────────────────────────────────┐
│ Shader 工作台   demo/plasma  [存图][快照][导出 GLSL][插入示例]      │
├──────────┬────────────────────────────────────┬──────────────────┤
│ 资源树    │  Pass 标签: image BufferA +Buffer   │  诊断日志         │
│  ├ 项目   │ ┌──────────────┬─────────────────┐ │                  │
│  │ ├ 材质 │ │ 节点库（搜索）│   节点画布       │ │  生成的 GLSL      │
│  └ 快照   │ │  输入/数学/… │  拖拽 / 连线     │ │                  │
├──────────┤ │              │                 │ │                  │
│ 参数面板  │ └──────────────┴─────────────────┘ │                  │
│  uniform │  预览：全屏 Shader ⇄ 材质网格       │                  │
│  节点参数 │  [暂停][截图] 速度 ──●── 质量 1×    │                  │
└──────────┴────────────────────────────────────┴──────────────────┘
```

### 节点画布操作

| 操作 | 快捷键 |
|---|---|
| 加节点 | 从左侧节点库点一下，或直接拖进画布 |
| 连线 | 从输出端口拖到输入端口 |
| 拆线 | 从输入端口往外拖 |
| 移动 | 拖节点体 |
| 多选 | Shift/Ctrl + 点，或空白处框选 |
| 平移 | 中键拖，或空格 + 左键拖 |
| 缩放 | 滚轮（以光标为锚点） |
| 适应视图 | 双击空白，或顶栏按钮 |
| 复制 | Ctrl+D |
| 删除 | Delete |
| 全选 | Ctrl+A |
| 右键菜单 | 节点上出「复制/断开/删除」，空白处出「插入示例/视图/清空 Pass」 |
| 重复接同一输入端口 | 后接的替换先接的（一个输入端口只保留一条来线） |

连线的颜色代表数据类型：灰=float、绿=vec2、黄=vec3、粉=vec4。
**任意两种类型都能连**：生成器会自动补转换（广播 / 补位 / 截断）。
有损转换（比如 vec4 → vec2 丢分量）会在状态栏提示，但不阻止。只有成环会被拒绝。

---

---

## 节点库（55 个，只放通用件）

| 分类 | 节点 |
|---|---|
| 输入 | uv、aspect、time、resolution、mouse、mouseUV、const、uniform |
| 数学 | add、sub、mul、div、pow、sqrt、abs、floor、fract、mod、clamp、saturate、smoothstep、stepNode、mixNode、oneMinus、minNode、maxNode |
| 向量 | vec2Node、vec3Node、vec4Node、split、dot、normalize、length、distance、rotate、scaleP |
| 颜色 | rgb、mixColor、palette、hsv、gamma、luminance |
| 程序化 | noise、fbm、hash、circle、gradient |
| 纹理 | texture（iChannel0-3）、bufferSample（BufferA-D） |
| 自定义 | custom（直接写 GLSL 表达式） |
| 分组 | group（元节点，**带「重复次数」= 循环**）、groupInput、groupOutput、loopIndex |
| 输出 | output |

> **循环用「重复次数」，别把重复写成复制。** 组的 `repeat > 1` 就是循环：
> 循环体只写一遍，外面套 `for`；跨迭代传递的量用 `params.graph.carries` 指定，
> 循环体里放一个 `loopIndex` 节点就能拿到当前轮次。
>
> 这条是踩出来的：IFS 隧道的 99 步一度展开成 99 份复制 —— 801 个节点、
> **676 KB 着色器**、2 MB 图、codegen 352 ms，面板一打开就卡；贝塞尔的 24 段复制
> 也要 51 KB 着色器。改成重复组之后是 10 个节点 / 9 KB / 34 KB 图，**输出逐像素一致**。
> 测试里有护栏（`examples.test.js`：节点数 / 图大小 / 着色器大小都封顶）。
>
> **列表也支持多级**：节点分类写 `"例程/傅里叶"`，面板上就是可折叠的两级；
> 项目名可以带斜杠（`傅里叶/series`），磁盘上就是多层目录，资源树按 `/` 分层渲染。

> **效果专用节点不在这里，也不在任何地方。** `ifsTunnel`（IFS 隧道）、
> `fourierSeries`（傅里叶级数）、`epicycles`（DFT 本轮）先后做过内置节点和
> 示例自带的用户节点，**两次都是黑盒**：循环藏在 `glslPrelude` 里，
> 画布上展不开、参数改不了。
>
> 现在它们被**展开成普通节点铺在图上**：每个谐波一个 `custom` 节点、
> 每个旋转向量一个节点、每次 IFS 折叠一个节点。代价是 `terms` 滑块没了 ——
> 项数变成图上节点的个数，想加就复制一个节点。这就是"可编辑"的样子，
> 详见 [`examples/README.md`](../examples/README.md)。
>
> `glslPrelude` 这条机制本身还在（用户节点靠它，写法见
> [`docs/架构说明.md` 7.1](架构说明.md)），但它是**最后手段**：
> 能展开成节点的就别藏进 prelude。

`float` 与 `vecN` 之间、以及不同维度的 `vecN` 之间都可以直连，
生成器自动补转换：

| 方向 | 生成的代码 |
|---|---|
| float → vecN | `vecN(x)` 广播 |
| vecN → vecM（M>N） | `vec4(x.x, x.y, 0.0, 1.0)` 补位 |
| vecM → vecN（N<M） | `vec2(x.x, x.y)` 截断 |
| vecN → float | `(x).x` 取第一分量 |

**第 4 位（alpha）补 1.0，不是 0.0。** 这条踩过坑：补 0 会让画面全透明，
而且编译器不报错。

---

---

## 给 agent 的 9 个工具

| 工具 | 作用 |
|---|---|
| `shader_node_library` | 拿完整节点手册（写图之前先看这个） |
| `shader_workspace` | 工作区概览 |
| `shader_project` | 项目 list / create / read |
| `shader_material` | 材质 list / create / read / save / archive |
| `shader_graph_build` | 用「节点别名 + `别名.端口`」建图并落盘 |
| `shader_compile` | 只做代码生成，不开工作台也能验证 |
| `shader_export` | 写 shader.frag + bundle.json |
| `shader_snapshot` | 快照 create / list / restore |
| `shader_texture_import` | 把磁盘上的图拷进材质并绑通道 |

`shader_graph_build` 的写法（最省事的一种）：

```json
{
  "project": "demo",
  "material": "plasma",
  "nodes": [
    { "id": "uv0", "type": "uv", "x": 0, "y": 0 },
    { "id": "t0", "type": "time", "x": 0, "y": 160 },
    { "id": "pal", "type": "palette", "x": 220, "y": 80 },
    { "id": "out0", "type": "output", "x": 460, "y": 80 }
  ],
  "edges": [
    { "from": "uv0.out", "to": "pal.t" },
    { "from": "t0.out", "to": "pal.t" },
    { "from": "pal.out", "to": "out0.color" }
  ]
}
```

---

---

## 工作区结构

```
shader-workbench/
├── projects/<项目>/materials/<材质>/
│   ├── graph.json          节点图
│   ├── material.json       材质清单
│   ├── <材质>.frag         导出的 GLSL
│   ├── textures/           纹理
│   └── .snapshots/         版本快照
├── library/{nodes,snippets,presets,comfy-workflows}/
└── cache/{compiled,previews}/
```

**归档材质是移动到 `.trash/`，不是删除。**
**回滚快照前会自动再打一份 `before-rollback` 快照**，所以回滚本身也可回滚。

---