VFX-Agent

Imported from yangfei1223/VFX-Agent (AGENTS.md). Install upstream with npx skills add yangfei1223/VFX-Agent. Copyright stays with the author.

VFX-Agent v2.0 项目信息

本文档记录 v2.0 codex OD 架构、工作流、测试结果与决策记录，用于后续开发对齐。

项目概述

目标：构建一个 AI Agent 驱动的系统，从 UX 视频/图片输入自动生成 Shadertoy 格式 GLSL 着色器代码，经隔离子 Agent 评分反馈迭代直至收敛。

范围：专注于 2D/2.5D 平面动效（涟漪、光晕、磨砂、流光等 UI 视效），支持移动端和 Web 平台。排除 3D raymarching/场景渲染/体渲染。

技术栈：

• Backend: Python 3.11+, FastAPI, codex CLI 0.144.1+
• Frontend: React 18, Vite, Three.js（复用 v1.0）
• 浏览器自动化: Playwright
• 视频处理: FFmpeg
• 状态持久化: JSON 文件

v2.0 架构详解

codex OD 动态编排

v2.0 用 codex OD（Orchestrated Dispatch）模式替代 v1.0 LangGraph 静态编排。核心思路：

Python Orchestrator (~270 行)
  ├── FFmpeg 提取关键帧
  ├── 创建 workdir + symlink skills/
  ├── spawn codex exec（主 agent）
  ├── 解析 JSONL 流 → 推前端
  ├── 提取 final_shader / evaluation
  └── 更新 PipelineState 持久化

codex exec（主 agent，按 SKILL.md 自主编排）
  ├── Phase 1: 分析关键帧 → visual_description.json
  ├── Phase 2: 生成 shader → shader.glsl
  ├── Phase 3: 验证编译 → validate_shader.py
  ├── Phase 4: 渲染截图 → render_shader.py + Playwright
  ├── Phase 5: 子 agent 评分 → spawn_agent (fork_turns="none")
  └── Phase 6: 迭代或收尾

Orchestrator 职责边界

6-Phase 工作流

Phase 5 Subagent 协议

Protocol:
  spawn: spawn_agent with fork_turns: "none"
  input:
    - Reference keyframe path (via message)
    - Render screenshot path (via message)
    - visual_description.json (shared filesystem)
  output: evaluation.json (shared filesystem)
  
evaluation.json schema:
  {
    "overall_score": 0.0-1.0,
    "dimension_scores": {
      "color_accuracy": 0.0-1.0,
      "shape_fidelity": 0.0-1.0,
      "animation_match": 0.0-1.0,
      "overall_impression": 0.0-1.0
    },
    "visual_issues": [
      {"severity": "high|medium|low", "description": "...", "suggestion": "..."}
    ]
  }

为什么用 subagent：主 agent 自评有正偏差，隔离 agent 更客观。v1.0 经验证明自评评分偏高 10-15%。

Skill 体系

backend/app/skills/
├── AGENTS.md                   # codex 主指令（~470 行）
└── vfx-shader/
    ├── SKILL.md (~415 行)      # 6-phase 工作流
    └── reference/
        ├── shader_templates.md (~1230 行)  # 9 个模板 + SDF/噪声/光效
        ├── few_shot_examples.md (~540 行)  # 9 个端到端示例
        └── scripts/
            ├── validate_shader.py          # GLSL 编译检查
            ├── render_shader.py            # Playwright 渲染
            └── analyze_pixels.py           # 像素级分析

v2.0 将 v1.0 的 7 个 prompt 文件（4521 行）浓缩到 3 个 skill 文件 + 3 个脚本。

已实现功能

v2.0 核心

复用 v1.0

关键决策记录

测试规范

基线标准：backend/test_results/2026-07-13_v2-codex-od-19samples/

测试脚本

测试参数

评分标准：

• ≥0.85: ✅ PASS
• 0.80-0.85: ⚠️ ACCEPTABLE
• <0.80: ❌ FAIL

测试结果目录结构

backend/test_results/<YYYY-MM-DD_描述>/
├── index.html                 # 主报告（v1.0 vs v2.0 对比）
├── test_results.json          # 汇总
└── <sample_name>/
    ├── pipeline_state.json    # 状态快照
    ├── reference_frame.png    # 参考帧
    ├── render_0.png ~ render_N.png  # 各迭代渲染
    ├── shader.glsl            # 最终 shader
    └── visual_description.json

test_results.json 结构

{
  "<sample_name>": {
    "sample_name": "4-col-grad",
    "pipeline_id": "v2-4-col-grad-xxx",
    "status": "passed|failed|timeout",
    "elapsed_seconds": 133.0,
    "score": 0.997,
    "iteration": 1,
    "effect_type": "{effect.gradient}",
    "shader_lines": 14,
    "issues": [...],
    "timestamp": "2026-07-13T20:40:00"
  }
}

Issue Severity：

• P0: 关键问题（pipeline 失败、超时、无 shader）
• P1: 重要问题（编译错误、渲染失败）
• P2: 次要问题（字段缺失、格式问题）

测试样本列表

19 个基线样本（存放于 test-samples/）：

v2.0 测试结果（2026-07-13，19 样本）

完整结果

统计

显著变化

Subagent Cross-validation

Subagent A/B cross-validation delta: 0.111（borderline bias 嫌疑，需进一步分析）。

已知问题与改进方向

问题

1. 编译失败：部分样本 codex 生成的 shader 语法错误或语义错误，渲染全黑（score ≈ 0）。原因是 GLSL 模板匹配不足。
2. 600s 超时：复杂样本（hypnotic-ripples、moon-distance-2d）在 Phase 2/5 耗时过长，触发 orchestrator 硬超时。
3. 迭代质量差：即使 3 次迭代用满，部分样本仍然不收敛。codex 的语义反馈利用率不足。
4. Subagent 评分偏差：cross-validation delta 0.111，评分一致性待验证。
5. 平均分落后 v1.0：v2.0 avg 0.642 vs v1.0 0.715。v1.0 的 LangGraph 路由 + 专业 prompt 仍有优势。

改进方向

• Few-shot 增强：增加编译失败样本的 few-shot 示例
• 时间预算管理：SKILL.md 增加 phase 级时间约束
• 评分配准：优化 Phase 5 subagent prompt，降低评分方差
• Prompt 资产移植：v1.0 中已验证有效的 prompt 内容逐步移植到 v2.0 skill 体系

文件结构

VFX-Agent/
├── backend/
│   ├── app/
│   │   ├── __init__.py
│   │   ├── main.py                       # FastAPI 入口
│   │   ├── config.py                     # v2.0 配置
│   │   ├── orchestrator.py (~304 行)     # v2.0 核心编排器
│   │   ├── state_store.py (~65 行)       # JSON 持久化
│   │   ├── pipeline_states/              # 运行时状态文件
│   │   ├── routers/
│   │   │   ├── __init__.py
│   │   │   ├── pipeline.py (~95 行)      # POST /run + GET /status
│   │   │   └── config.py
│   │   ├── services/
│   │   │   ├── browser_render.py         # Playwright 渲染复用
│   │   │   ├── shader_render_page.html   # v2.0 standalone HTML (128 行)
│   │   │   ├── shader_validator.py       # GLSL 编译检查
│   │   │   ├── video_extractor.py        # FFmpeg 关键帧
│   │   │   ├── session_logger.py         # Agent 会话日志
│   │   │   └── validators.py             # API 校验
│   │   └── skills/                       # v2.0 codex skill 资产
│   │       ├── AGENTS.md (~471 行)       # codex 主指令
│   │       └── vfx-shader/
│   │           ├── SKILL.md (~414 行)    # 6-phase 工作流
│   │           └── reference/
│   │               ├── shader_templates.md (~1230 行)  # shader 模板
│   │               ├── few_shot_examples.md (~540 行)  # 9 个 few-shot
│   │               └── scripts/
│   │                   ├── validate_shader.py
│   │                   ├── render_shader.py
│   │                   └── analyze_pixels.py
│   ├── tests/
│   │   ├── unit/                         # 5 文件，18 tests pass
│   │   └── e2e/
│   │       ├── run_v2_samples.py         # 批量运行器
│   │       ├── collect_v2_results.py     # 结果收集
│   │       └── generate_v2_report.py     # HTML 报告生成
│   ├── test_results/                     # 测试归档 (.gitignore)
│   ├── requirements.txt
│   └── .env.example
├── frontend/                             # 复用 v1.0
│   ├── src/
│   │   ├── App.tsx
│   │   ├── components/
│   │   │   ├── InputPanel.tsx
│   │   │   ├── UploadPanel.tsx
│   │   │   ├── VFXDiscoveryForm.tsx
│   │   │   ├── ShaderEditor.tsx
│   │   │   ├── ShaderPreview.tsx
│   │   │   ├── ParameterPanel.tsx
│   │   │   ├── AgentLog.tsx
│   │   │   ├── SettingsPanel.tsx
│   │   │   └── PipelineStatus.tsx
│   │   ├── hooks/
│   │   │   └── usePipeline.ts
│   │   └── lib/
│   │       ├── shader-renderer.ts
│   │       └── glsl-parser.ts
│   └── package.json
├── test-samples/                         # 19 基线样本 (.gitignored)
├── docs/
├── start.sh
├── AGENTS.md
├── README.md
└── .gitignore

配置说明

模型配置通过 backend/.env 指定：

# codex 模型配置
CODEX_MODEL=gemini-2.5-flash
CODEX_BASE_URL=https://generativelanguage.googleapis.com/v1beta/openai
CODEX_API_KEY=your_api_key

# 代理（海外 API）
PROXY=http://127.0.0.1:7890
codex_proxy=http://127.0.0.1:7890

# Pipeline 参数
codex_timeout=600          # codex 调用超时（秒）
max_iterations=5           # SKILL.md 中配置的迭代上限（硬 cap）
passing_score=0.85         # 通过阈值
render_timeout_ms=2000     # 渲染超时
screenshot_width=1280
screenshot_height=720
workdir_root=/tmp/vfx_workdirs  # 运行 workdir 根目录

代码统计

参考文档

• 设计文档：docs/superpowers/specs/2026-07-13-vfx-agent-v2-codex-od-design.md
• codex Agent 主指令：backend/app/skills/AGENTS.md
• 6-phase 工作流：backend/app/skills/vfx-shader/SKILL.md
• Shader 模板库：backend/app/skills/vfx-shader/reference/shader_templates.md
• Few-shot 示例：backend/app/skills/vfx-shader/reference/few_shot_examples.md
• Orchestrator 源码：backend/app/orchestrator.py
• 设计文档（原始）：基于 AI Agent 的操作系统级自定义视效生成管线设计方案.md
• iq SDF 算子：https://iquilezles.org/articles/distfunctions2d/
• Shadertoy 案例：https://www.shadertoy.com/

最后更新: 2026-07-14