217 lines
3.3 KiB
Markdown
217 lines
3.3 KiB
Markdown
# 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) 启动
|
||
|
||
```bash
|
||
chmod +x scripts/docker-up.sh scripts/docker-down.sh
|
||
./scripts/docker-up.sh
|
||
```
|
||
|
||
启动后访问：`http://localhost:5173`
|
||
|
||
### 2) 停止
|
||
|
||
```bash
|
||
./scripts/docker-down.sh
|
||
```
|
||
|
||
### 3) 查看日志
|
||
|
||
```bash
|
||
docker compose logs -f web
|
||
```
|