Files

张鹏 f9f4560459 Initial commit: Pixel AI comic/video creation platform

- FastAPI backend with SQLModel, Alembic migrations, AgentScope agents
- Next.js 15 frontend with React 19, Tailwind, Zustand, React Flow
- Multi-provider AI system (DashScope, Kling, MiniMax, Volcengine, OpenAI, etc.)
- All HTTP clients migrated from sync requests to async httpx
- Admin-managed API keys via environment variables
- SSRF vulnerability fixed in ensure_url()

2026-04-29 01:20:12 +08:00

8.1 KiB

Raw Blame History

Pixel - AI 视频创作平台

English Documentation

Pixel 是一个智能平台，利用 AI 从剧本创作漫画和视频。它简化了从剧本编写到素材管理、分镜生成以及最终视频制作的整个工作流，利用多智能体系统（Multi-Agent Systems）和先进的生成式模型提供强大的创作支持。

✨ 功能特性

智能剧本分析：
- 自动解析剧本，识别角色、场景和道具。
- Agent 工作流：利用基于 AgentScope 的专用智能体进行深度的剧本理解和拆解。
多模型 AI 支持：
- LLM: DashScope (通义千问), Google (Gemini), VolcEngine (豆包)。
- 生图: Flux 1.1 Pro, 通义万相 (Wanx), 可图 (Kolors)。
- 生视频: 可灵 (Kling 1.5), 海螺 (Hailuo/MiniMax), CogVideoX, 通义万相 2.1。
素材管理：集中的“素材中心”，用于管理和编辑创意素材。
AI 分镜：利用 AI 图像生成技术，根据剧本描述生成可视化分镜，并支持风格一致性控制。
视频生成与编辑：
- 将静态分镜转化为动态视频。
- 精细控制：支持首/尾帧控制、运镜控制（推拉摇移）、以及 Motion Bucket 参数调节。
无限画布：基于节点的自由创作工作区（由 React Flow 驱动），支持多选拖拽、丝滑缩放和灵活的节点连接。
项目管理：在结构化的工作区中组织您的创意作品，支持集（Episode）和场（Scene）管理。

🏗 架构

本项目采用 Monorepo 结构，后端采用清晰的三层架构：

frontend/: 基于 Next.js 15 (App Router) 的前端应用，使用 React 19、Tailwind CSS 和 @xyflow/react 构建画布界面。
backend/: 基于 FastAPI 的后端服务，采用三层架构（API层、服务层、仓储层）。使用 AgentScope 进行智能体编排，并通过插件系统支持多种 AI 模型提供商。

📚 文档

完整的技术文档：

ARCHITECTURE.md: 完整的系统架构、设计决策和技术栈
backend/README.md: 后端设置、API文档和开发指南
frontend/README.md: 前端设置、组件结构和开发指南

🚀 快速开始

前置要求

Node.js: v20 或更高版本 (Next.js 15 必需)
Python: v3.12 或更高版本
包管理器: pnpm (前端), uv (后端 - 推荐)
Redis: v7+ (可选但推荐用于缓存)
PostgreSQL: v15+ (生产环境，开发环境使用 SQLite)
API Keys: 根据使用的模型准备阿里云 DashScope, 火山引擎 VolcEngine 或 Google AI Studio 的 Key

安装步骤

1. 克隆仓库

git clone <repository-url>
cd pixel

2. 后端设置

cd backend

# 安装 uv（如果尚未安装）
pip install uv

# 安装依赖
uv sync

# 配置环境变量
cp .env.example .env
# 编辑 .env 文件，填入您的 API Keys

# 运行数据库迁移
alembic upgrade head

# 启动后端服务器
./start.sh
# 或手动运行: uv run uvicorn src.main:app --reload --port 8000

后端将在 http://localhost:8000 运行

3. 前端设置

cd frontend

# 安装依赖
pnpm install

# 启动开发服务器
pnpm dev

前端将在 http://localhost:3000 运行

环境配置

在 backend/ 目录中创建 .env 文件：

# AI 提供商
DASHSCOPE_API_KEY=your_dashscope_key
VOLCENGINE_ACCESS_KEY=your_volcengine_key
VOLCENGINE_SECRET_KEY=your_volcengine_secret
GOOGLE_API_KEY=your_google_key
KLING_API_KEY=your_kling_key

# 存储
OSS_ACCESS_KEY_ID=your_oss_key
OSS_ACCESS_KEY_SECRET=your_oss_secret

# 数据库（可选 - 默认使用 SQLite）
DATABASE_URL=postgresql://user:pass@localhost/pixel

# Redis（可选但推荐）
REDIS_URL=redis://localhost:6379

# 监控
ENABLE_METRICS=true
LOG_LEVEL=INFO

Docker 部署（可选）

# 构建并启动所有服务
docker-compose up -d

# 查看日志
docker-compose logs -f

# 停止服务
docker-compose down

🔌 API 文档

后端提供完整的 RESTful API 文档：

API 文档: 完整的 API 参考和示例
交互式文档: http://localhost:8000/docs (Swagger UI)
ReDoc: http://localhost:8000/redoc
OpenAPI 规范: http://localhost:8000/openapi.json

核心端点

生图: POST /api/v1/generations/image
生视频: POST /api/v1/generations/video
剧本分析: POST /api/v1/script/analyze
任务状态: GET /api/v1/tasks/{task_id}
项目管理: /api/v1/projects/*
画布操作: /api/v1/canvas/*

交互式文档

Swagger UI: http://localhost:8000/docs
ReDoc: http://localhost:8000/redoc
OpenAPI 规范: http://localhost:8000/openapi.json

所有生成接口均支持 extra_params 字段，用于直接向底层 SDK 传递模型特定参数。

🧪 开发

运行测试

后端:

cd backend
pytest                          # 运行所有测试
pytest tests/test_integration.py  # 运行集成测试
pytest --cov=src                # 运行并生成覆盖率报告

前端:

cd frontend
pnpm test                       # 运行所有测试
pnpm test:watch                 # 监听模式运行
pnpm test:coverage              # 运行并生成覆盖率报告

代码质量

后端:

# 格式化代码
black src/
isort src/

# 代码检查
flake8 src/
mypy src/

前端:

# 代码检查
pnpm lint

# 类型检查
pnpm type-check

# 格式化
pnpm format

数据库迁移

cd backend

# 创建新迁移
alembic revision --autogenerate -m "描述"

# 应用迁移
alembic upgrade head

# 回滚一个迁移
alembic downgrade -1

API 类型生成

当后端 API 变更时，重新生成前端类型：

cd frontend
pnpm gen:api

📊 监控

健康检查

curl http://localhost:8000/health

指标（Prometheus）

curl http://localhost:8000/metrics

日志

后端日志采用 JSON 格式，便于解析：

tail -f backend/logs/app.log | jq

🤝 贡献

Fork 本仓库
创建特性分支 (git checkout -b feature/amazing-feature)
提交更改 (git commit -m 'Add amazing feature')
推送到分支 (git push origin feature/amazing-feature)
开启 Pull Request

开发指南

遵循三层架构（API层、服务层、仓储层）
为新功能编写测试
更新文档
遵循代码风格指南
使用约定式提交

🐛 故障排除

后端问题

Redis 连接错误:

# 检查 Redis 是否运行
redis-cli ping
# 应返回: PONG

数据库连接错误:

# 检查数据库连接
psql -h localhost -U user -d pixel

导入错误:

# 重新安装依赖
uv sync --reinstall

前端问题

模块未找到:

# 清除缓存并重新安装
rm -rf node_modules .next
pnpm install

API 类型不匹配:

# 重新生成 API 类型
pnpm gen:api

📦 项目结构

pixel/
├── backend/                 # FastAPI 后端
│   ├── src/
│   │   ├── controllers/    # API 层（HTTP 处理）
│   │   ├── services/       # 服务层（业务逻辑）
│   │   ├── repositories/   # 仓储层（数据访问）
│   │   ├── models/         # 数据模型（实体和模式）
│   │   ├── middlewares/    # API 中间件
│   │   └── utils/          # 工具函数
│   ├── tests/              # 测试套件
│   └── alembic/            # 数据库迁移
├── frontend/               # Next.js 前端
│   ├── src/
│   │   ├── app/           # Next.js 页面（App Router）
│   │   ├── components/    # React 组件
│   │   ├── lib/           # 工具和服务
│   │   └── store/         # 状态管理（Zustand）
│   └── tests/             # 测试套件
├── docs/                   # 文档
├── ARCHITECTURE.md         # 架构文档
└── docker-compose.yml      # Docker 配置

📄 许可证

MIT

8.1 KiB Raw Blame History Unescape Escape