AI VFX Editor MVP - Coding Agent 执行说明

🎯 目标

构建一个最小可用的 AI 特效编辑器（Web版），支持：

1. Three.js 实时渲染 Shader
2. 参数面板控制 Shader uniforms
3. 多个特效模板切换
4. 简单 AI 输入生成初始参数
5. 导出 Shader 和 Three.js Material

---

🏗️ 技术栈

• Frontend: React + Vite
• 渲染: Three.js
• Shader: GLSL
• 状态管理: useState（无需复杂方案）
• AI接口: mock（先写死）

---

📁 项目结构

src/ ├── App.tsx ├── components/ │ ├── Preview.tsx // 渲染窗口 │ ├── ControlPanel.tsx // 参数控制 │ ├── ShaderEditor.tsx // shader展示 │ ├── TemplateSelector.tsx // 模板选择 ├── engine/ │ ├── useThree.ts // 初始化Three │ ├── shaderBuilder.ts // shader拼装 │ ├── uniformManager.ts // 参数管理 ├── shaders/ │ ├── base.vert │ ├── modules/ │ │ ├── noise.glsl │ │ ├── uv_scroll.glsl │ │ ├── alpha.glsl │ ├── templates/ │ │ ├── fire.ts │ │ ├── ripple.ts │ │ ├── distortion.ts

---

🎨 功能拆解

1️⃣ Preview（核心）

• 使用 Three.js 创建 full-screen quad

• 使用 ShaderMaterial

• uniforms 包含：

  • u_time
  • u_speed
  • u_scale

• requestAnimationFrame 更新 u_time

---

2️⃣ ControlPanel

• 使用 slider 控制：

  • speed
  • scale
  • intensity

• 实时更新 uniforms

---

3️⃣ ShaderBuilder（关键模块）

实现函数：

buildShader(template, params)

逻辑：

• 根据 template 注入模块：

  • noise
  • uv scroll
  • alpha

• 输出完整 fragment shader

---

4️⃣ 模板系统

每个模板定义：

{ name: "fire", modules: ["noise", "uv_scroll", "alpha"], defaultParams: { speed: 1.0, scale: 3.0 } }

---

5️⃣ AI模块（Mock）

实现函数：

generateEffect(prompt)

返回：

{ template: "fire", params: { speed: 1.5, scale: 4.0 } }

---

6️⃣ 导出功能（必须实现）

按钮：Export

导出内容：

1. fragment.glsl
2. vertex.glsl
3. material.json

---

🧪 测试标准

必须满足：

• 参数修改实时生效（<16ms）
• 模板切换无报错
• Shader 可复制运行
• 导出文件可复用

---

🚀 初始任务顺序

1. 初始化 Vite + React
2. 完成 Three.js 渲染
3. 加入 ShaderMaterial
4. 加入 uniforms 动画
5. 实现 ControlPanel
6. 实现 模板系统
7. 实现 shaderBuilder
8. 实现 Export

---

❗ 注意事项

• 不要引入复杂状态管理
• 不要实现粒子系统
• 不要过度抽象
• 优先保证“可运行”

---

🎯 最终目标

得到一个：

👉 可运行的 Web 特效编辑器 👉 能导出 Shader 👉 能通过参数控制效果

这是后续商业化 POC 的基础

---

🐳 本地 Docker 快速启动（国内镜像）

项目已默认切换到国内镜像源：

• Node 基础镜像：docker.m.daocloud.io
• Debian APT：mirrors.aliyun.com
• NPM：registry.npmmirror.com

1) 启动

chmod +x scripts/docker-up.sh scripts/docker-down.sh
./scripts/docker-up.sh

启动后访问：http://localhost:5173

2) 停止

./scripts/docker-down.sh

3) 查看日志

docker compose logs -f web

🧩 ShaderToy 兼容能力（已接入）

当前项目已支持 ShaderToy 风格 mainImage() 渲染流程，并对齐 test 目录中的输入结构说明：

• 支持 uniforms：iResolution、iTime、iTimeDelta、iFrameRate、iFrame、iChannelTime[4]、iChannelResolution[4]、iMouse、iDate、iSampleRate、iChannel0..3
• 支持把仅包含 mainImage(out vec4, in vec2) 的片段着色器自动包装为可运行的 main()
• 右侧面板支持为 iChannel0..3 上传本地图片纹理并实时参与渲染

快速本地启动

sh start.sh