# 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
```