# Pixel - AI 视频创作平台

[English Documentation](README.md)

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](ARCHITECTURE.md)**: 完整的系统架构、设计决策和技术栈
- **[backend/README.md](backend/README.md)**: 后端设置、API文档和开发指南
- **[frontend/README.md](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. 克隆仓库

```bash
git clone <repository-url>
cd pixel
```

#### 2. 后端设置

```bash
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. 前端设置

```bash
cd frontend

# 安装依赖
pnpm install

# 启动开发服务器
pnpm dev
```

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

### 环境配置

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

```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 部署（可选）

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

# 查看日志
docker-compose logs -f

# 停止服务
docker-compose down
```

## 🔌 API 文档

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

- **[API 文档](docs/API.md)**: 完整的 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 传递模型特定参数。

## 🧪 开发

### 运行测试

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

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

### 代码质量

**后端:**
```bash
# 格式化代码
black src/
isort src/

# 代码检查
flake8 src/
mypy src/
```

**前端:**
```bash
# 代码检查
pnpm lint

# 类型检查
pnpm type-check

# 格式化
pnpm format
```

### 数据库迁移

```bash
cd backend

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

# 应用迁移
alembic upgrade head

# 回滚一个迁移
alembic downgrade -1
```

### API 类型生成

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

```bash
cd frontend
pnpm gen:api
```

## 📊 监控

### 健康检查

```bash
curl http://localhost:8000/health
```

### 指标（Prometheus）

```bash
curl http://localhost:8000/metrics
```

### 日志

后端日志采用 JSON 格式，便于解析：
```bash
tail -f backend/logs/app.log | jq
```

## 🤝 贡献

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

### 开发指南

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

## 🐛 故障排除

### 后端问题

**Redis 连接错误:**
```bash
# 检查 Redis 是否运行
redis-cli ping
# 应返回: PONG
```

**数据库连接错误:**
```bash
# 检查数据库连接
psql -h localhost -U user -d pixel
```

**导入错误:**
```bash
# 重新安装依赖
uv sync --reinstall
```

### 前端问题

**模块未找到:**
```bash
# 清除缓存并重新安装
rm -rf node_modules .next
pnpm install
```

**API 类型不匹配:**
```bash
# 重新生成 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