# CreativeForge

**Repository Path**: defiphoenix/creative-forge

## Basic Information

- **Project Name**: CreativeForge
- **Description**: 1234567890
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-10-29
- **Last Updated**: 2026-10-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

---
# 详细文档见https://modelscope.cn/docs/%E5%88%9B%E7%A9%BA%E9%97%B4%E5%8D%A1%E7%89%87
domain: #领域：cv/nlp/audio/multi-modal/AutoML
# - cv
tags: #自定义标签
-
datasets: #关联数据集
  evaluation:
  #- iic/ICDAR13_HCTR_Dataset
  test:
  #- iic/MTWI
  train:
  #- iic/SIBR
models: #关联模型
#- iic/ofa_ocr-recognition_general_base_zh

## 启动文件(若SDK为Gradio/Streamlit，默认为app.py, 若为Static HTML, 默认为index.html)
# deployspec:
#   entry_file: app.py
license: Apache License 2.0
---
# CreativeForge AI

**面向游戏开发的自主规划型 AI 资产生产系统**：一句自然语言目标，经多智能体自主规划与自研技术链（PReCon / FAlign / GImport）处理，产出可直接导入 Unity / Cocos / Godot 的游戏资产。

> CreativeForge 不是一个调用生成模型的工具，而是一个面向游戏开发的自主规划型 AI 资产生产系统，通过 CreativeAsset 统一协议连接自研像素重建、动画切帧对齐和引擎自动导入，实现从创意描述到可运行游戏资源的一体化生成。

## 1. Overview

```text
                自然语言目标（"创建一个像素RPG火焰法师Boss，导入Unity"）
                                  |
                                  v
                    CreativeForge Studio（Web 控制台）
                                  |
                                  v
                     Supervisor Agent 自主规划任务图
                                  |
            +---------------------+---------------------+
            |                     |                     |
        Art Agent          Animation Agent        Engine Agent
       生成 + PReCon            FAlign                GImport
            |                     |                     |
            +---------------------+---------------------+
                                  |
                          QA Agent 质量验证
                                  |
                          游戏引擎就绪资产（Unity / Cocos / Godot）
```

- **产品层** — `studio/`：React 18 + TypeScript + Vite 前端（工作台 / 智能体任务图 / 资产检查器 / 动画工作台 / 基准中心 / 导出中心）+ FastAPI 后端（REST + WebSocket 事件流）
- **智能层** — `agents/` + `agent/`：Supervisor 规划调度专家智能体，带 QA 修复轮、检查点与失败恢复
- **技术层** — `precon/` `falign/` `gimport/`：三项自研引擎
- **标准层** — `schemas/` + `packages/creative-core/`：CreativeAsset v1.0 统一资产协议（冻结契约）
- **验证层** — `benchmark/`：数据集 + 对比指标 + CF Score

## 2. Problem

独立游戏开发者做一个游戏角色需要：美术设计 → 手动像素化 → 手动切帧对齐 → 手动配置动画 → 手动拼 Prefab → 导入引擎，**12 步人工操作、约 45 分钟**，且 AI 生成素材直接使用时有像素错位、动画漂移、脚滑、抖动等硬伤。

## 3. Innovation

### PReCon — 像素重建引擎（`precon/`）

AI 图片 → 网格推断 → 语义化调色板重建 → 轮廓修复 → 风格一致性 → 质量评估。

### FAlign — 动画切帧对齐引擎（`falign/`）

帧抽取 → 锚点检测（root/feet/center/head）→ 运动相位对齐 → 根运动纠偏（区分真实位移与漂移）→ 时序一致性。

### GImport — 引擎一键导入管线（`gimport/`）

CreativeAsset → 资产清单 → 精灵图集 → 动画剪辑 → Prefab → 引擎适配器（Unity/Cocos/Godot）→ 运行时校验 → 一键导出真实 zip 工程包。

## 4. Architecture

见 [docs/architecture.md](docs/architecture.md)：八层架构与 phase 规格 → 合并位置映射。

## 5. Multi-Agent System

```text
Supervisor Agent（规划 + 路由 + QA/修复循环 + 记忆）
  -> Art Agent（Generation + PReCon）
  -> Animation Agent（FAlign）
  -> Engine Agent（GImport：Unity / Cocos / Godot）
  -> QA Agent（验证 -> 修复轮）
  -> Memory Agent（风格 / 版本 / 检查点）
```

入口：`agents.supervisor.supervisor.SupervisorAgent.run(goal)`；Studio 运行时以事件流（`PLAN_CREATED / AGENT_START / AGENT_DONE / QUALITY_REPORT / TASK_COMPLETE`）推送全过程。

## 6. Quick Start

```bash
# 后端 + 前端（推荐）
pip install -r studio/backend/requirements.txt
npm --prefix studio/frontend install && npm --prefix studio/frontend run build
python -m studio.backend.main            # http://127.0.0.1:8600

# 前端开发模式（热更新，代理到 8600）
npm --prefix studio/frontend run dev     # http://127.0.0.1:5173

# Docker 一键起（生产强制鉴权；未设置令牌会拒绝启动）
STUDIO_AUTH_TOKEN=换成一个足够长的随机串 docker compose up -d
# 数据持久化：compose 直接绑定 data/、generated/、model_service/generated/、
# exports/ 宿主目录，重新部署不会丢客户原画/动作/历史/用量台账。
# 创空间/Docker 单容器部署请把同样四个目录挂到持久卷（Dockerfile 已声明 VOLUME）。
```

命令行直跑：

```python
from agents.supervisor.supervisor import SupervisorAgent

result = SupervisorAgent().run("生成一个像素RPG火焰法师Boss，带攻击动画，并导入Unity")
print(result["supervisor"]["status"])        # PASS
print(result["asset"]["engine"]["target"])   # unity
```

## 7. Demo

比赛固定演示（确定性，产物固化在 `examples/competition_demo/`）：

```bash
python examples/competition_demo/run_demo.py
# prompt.txt -> source/(intent+task graph) -> intermediate/(steps+messages+asset)
#            -> output/FireMageGameAsset.zip -> report/(quality+benchmark)
```

## 8. Benchmark

```bash
python -m benchmark.run_benchmark          # 写入 benchmark/results/
```

在 12 个数据集资产上真实渲染源图/动作帧并测 IO（Phase 9 体系）。
以下为 **2026-10-26 本机复跑** 的实测结果（报告由脚本生成，不手写常数）：

| 引擎/系统 | 指标 | Baseline | CreativeForge |
| --------- | ---- | -------- | ------------- |
| PReCon | PSNR / Pixel Score | 14.36 dB / 54.8% | **14.53 dB / 57.0%** |
| PReCon | 实际颜色数 | 16 | **15** |
| FAlign | 根漂移 px/frame（图像检测） | 0.53 | **0.00** |
| FAlign | 脚底滑动稳定性 | 82% | **100%** |
| GImport | 真实 zip 导入成功率 | — | **100%** |
| GImport | 实测导出耗时（中位数 / p95） | — | **2.287 s / 2.839 s** |
| Agent | 任务自主完成率 | — | **100%**（12/12） |
| Agent | 规划准确率 | — | **92%** |

**CF Score = 86.5%**（pixel 0.30 / animation 0.30 / engine 0.25 / agent 0.15 加权）。
数字每次运行都会变化；以 `python -m benchmark.run_benchmark` 生成的
`benchmark/results/benchmark_report.md` 为准。

## 9. Roadmap

- 生成端接入真实图像/视频模型（当前为确定性管线模拟，接口已冻结）
- Benchmark 数据集扩到 1000 资产并引入人工标注
- 引擎侧：Unity Editor 插件实现进程内导入校验
- Studio 协作：多人项目空间与资产版本树

---

### 测试

```bash
python tests/run_tests.py                  # 45 项契约检查（Phase 3-7）
python tests/run_animation_tests.py        # 240 项动画/试玩/自定义动作回归
python tests/release/run_release_tests.py  # 16 项发布验证（五层）
python studio/backend/tests/test_security_api.py  # 路径穿越/生产鉴权
python tests/dump_examples.py              # 用真实运行刷新 examples/*.json
```

### 项目结构

```text
CreativeForge/
├── core/ protocol/ schemas/ packages/    # 契约层（CreativeAsset v1.0）
├── sprite/                               # 八方向精灵表契约 + 两段式提示词库
├── adapters/                             # 外部能力适配层
├── precon/ falign/ gimport/              # 自研引擎层
├── agent/ agents/                        # 智能体层（单 Agent + 多 Agent）
├── studio/frontend studio/backend        # 产品层（Phase 8）
├── benchmark/                            # 验证层（Phase 9）
├── examples/competition_demo/            # 固定演示（Phase 10）
├── tests/ tests/release/                 # 测试体系
└── docs/                                 # 架构与映射文档
    ├── architecture.md                    # 分层架构 + phase→合并位置映射
    ├── mapping/                           # windup / holonic 字段映射
    └── phases/                            # 23 个 Phase 设计/决策记录（1-10 设计演进，11-15 后端框架，16-19 Agent Runtime，20 模型训练，21 MVP 前端，22 高级 Agent 平台，23 研究创新层）
```