AI VFX Editor MVP - Coding Agent 执行说明
🎯 目标
构建一个最小可用的 AI 特效编辑器（Web版），支持：
- Three.js 实时渲染 Shader
- 参数面板控制 Shader uniforms
- 多个特效模板切换
- 简单 AI 输入生成初始参数
- 导出 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
导出内容：
- fragment.glsl
- vertex.glsl
- material.json
🧪 测试标准
必须满足：
- 参数修改实时生效（<16ms）
- 模板切换无报错
- Shader 可复制运行
- 导出文件可复用
🚀 初始任务顺序
- 初始化 Vite + React
- 完成 Three.js 渲染
- 加入 ShaderMaterial
- 加入 uniforms 动画
- 实现 ControlPanel
- 实现 模板系统
- 实现 shaderBuilder
- 实现 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