Cube AI 魔方 AI - 项目总文档

智能视频分析与创作辅助平台

📖 目录

🎯 项目概述

CubeAI (魔方 AI) 是一个专业的视频分析与创作辅助平台，利用多模态AI技术，帮助内容创作者深度分析视频特性、学习拍摄技巧、生成创作脚本，提升视频创作效率和质量。

项目信息

项目	信息
名称	CubeAI-X / 魔方 AI (Rubik AI Engine)
版本	v2.1.0
状态	✅ 生产就绪
开发模式	前后端分离
后端框架	FastAPI (Python 3.9+)
前端框架	React 18 + TypeScript
AI 模型	Qwen2.5-VL, Google Gemini
许可证	MIT

适用场景

🎬 视频创作者 - 学习爆款视频技巧
📹 摄影师 - 分析运镜、打光、调色
📱 实时拍摄 - AR 辅助拍摄，确保素材质量 ⭐
✍️ 编剧/导演 - AI 辅助脚本创作
🎓 教育机构 - 视频制作教学
📊 数据分析师 - 视频内容研究

💡 核心价值

1. 🎯 智能视频分析

AI 驱动的视频内容理解
自动识别爆款因素
多维度评分体系
可视化分析结果

2. 📹 专业镜头拆解

自动镜头切分检测
运镜技巧识别（推拉摇移跟等）
光线布局分析（三点布光、自然光等）
调色风格识别（色调、饱和度等）

3. ✍️ AI 创作辅助

智能脚本生成
跨平台内容适配
分镜可视化编辑
创作策略推荐

4. 📚 知识库管理

影视技巧收藏
创意灵感管理
标签分类系统
快速检索功能

5. 📱 实时拍摄辅导

AR 实时 HUD 界面
环境智能判读
低风险任务推荐
CV 实时分析和反馈

✨ 功能特性

🎬 视频深度拆解

功能描述：全面分析视频的爆款因素和创作特点

核心能力：

✅ 支持 URL 和本地文件上传
✅ 爆款因素智能识别
✅ 节奏曲线可视化
✅ 钩子强度分析
✅ 雷达图多维评分
✅ 实时进度跟踪

技术实现：

多模态 AI 模型分析
异步任务处理
结果数据可视化

📹 镜头拆解分析 ⭐ 新功能

功能描述：专业级镜头语言分析和学习工具

核心能力：

1. 镜头切分

自动识别镜头边界
精确到毫秒级时间戳
支持各类切换方式

2. 运镜识别

推镜 (Push In) - 向主体推进
拉镜 (Pull Out) - 远离主体
摇镜 (Pan) - 水平旋转
移镜 (Track) - 横向/纵向移动
跟镜 (Follow) - 跟随主体
固定机位 (Static) - 无运动
组合运镜 - 复杂运动分析

3. 光线分析

三点布光 - 主光、辅光、轮廓光
自然光 - 窗光、室外光
侧光 - 侧面照明
逆光 - 背光效果
顶光/底光 - 特殊光位
柔光/硬光 - 光质分析

4. 调色识别

暖色调 - 橙黄色系
冷色调 - 蓝绿色系
中性色调 - 平衡色彩
高饱和度 - 鲜艳色彩
低饱和度 - 素雅风格
高对比度 - 明暗分明
低对比度 - 柔和过渡

交互特性：

🎥 内置视频播放器
🌊 实时流式输出 - SSE 推送，片段检测完成后立即显示
🎨 时间轴可视化
📍 播放进度指示器 - 红色竖线实时跟随视频播放
🖱️ 点击跳转播放
📝 详细特征说明
💾 历史记录管理

性能优化：

⚡ CV 算法快速检测（1-2秒完成场景切分）
🔄 流式推送片段数据，无需等待全部完成
🎯 实时进度反馈，用户体验流畅

📱 实时拍摄助手 ⭐ 新功能

功能描述：AR 实时拍摄辅导系统，在拍摄当下帮助用户拍出"成立"的素材

核心能力：

1. 环境智能判读

多模态 VLM 分析拍摄环境
评估场景可拍性（人/物/空间/混乱度）
识别环境主题和可用元素
输出环境分析报告

2. 智能任务推荐

根据环境自动推荐低风险拍摄任务
任务类型包括：
- 静止锁定 - 稳定构图
- 缓慢移动 - 平滑运镜
- 轻柔推进 - 渐进式推镜
- 跟随引导 - 方向性移动
确保素材"锚点成立、关系稳定、信息完成"

3. 实时 HUD 界面

教练胶囊 - 顶部显示 AI 实时指令和目标
方向指示器 - 边缘 chevrons（>>>）指示移动方向
平衡水平仪 - 底部实时显示运动平滑度和稳定性
视觉反馈：绿色（正常）、红色（警告）、闪烁（紧急）

4. 实时 CV 分析

光流分析（Farneback + Lucas-Kanade）
运动平滑度检测
速度方差计算
主体跟踪和占用率分析
自适应降级（低延迟优化）

5. 智能反馈系统

基于 CV 指标的实时纠错建议
优先级分类（critical/warning/info）
平滑滤波和滞后处理（避免抖动）
运动类型抑制规则
触觉反馈支持

6. 任务状态管理

完整任务生命周期：
- 环境扫描 → 任务选择 → 执行中 → 纠错 → 完成/失败
WebSocket 实时通信
多客户端会话管理

技术实现：

前端：React + TypeScript，WebSocket 实时通信
后端：FastAPI + WebSocket，OpenCV 实时分析
AI：Qwen2.5-VL 多模态环境理解
协议：HTTPS/WSS 安全连接

使用场景：

📹 手机拍摄 - 实时 AR 辅导，确保素材质量
🎬 专业拍摄 - 运镜技巧实时指导
🎓 教学培训 - 拍摄技巧现场学习
📱 短视频创作 - 提升拍摄成功率

📊 视频转幻灯片

功能描述：将视频内容自动转换为演示文稿

核心能力：

✅ 智能关键帧提取
✅ 内容自动总结
✅ 多种布局模板
✅ 支持导出 PPT

✍️ 创作中心

功能描述：AI 辅助的视频脚本创作工具

核心能力：

✅ 多种创作策略
- 故事叙述型
- 知识分享型
- 产品展示型
- 情感共鸣型
✅ 跨平台适配
- 抖音 / TikTok
- B站 / YouTube
- 小红书
- 视频号
✅ 分镜可视化
✅ 实时编辑预览
✅ 脚本导出

📚 灵感仓库

功能描述：影视技巧和创意灵感管理系统

核心能力：

✅ 知识点分类
- 钩子技巧
- 叙事结构
- 风格参考
- 配乐方案
- 指纹识别
✅ 标签系统
✅ 搜索过滤
✅ 收藏管理
✅ 笔记编辑

📈 总览面板

功能描述：数据统计和项目管理中心

核心能力：

✅ 统计数据展示
- 已分析视频数
- 生成脚本数
- 知识库条目
- 今日配额
✅ 最近项目列表
✅ 日程热力图
✅ 快速操作入口

技术栈详情

前端技术栈

类别	技术	版本	用途
框架	React	18.x	UI 框架
语言	TypeScript	5.x	类型安全
构建	Vite	6.x	构建工具
样式	Tailwind CSS	3.x	样式方案
图标	Lucide React	0.562	图标库
图表	Recharts	3.6	数据可视化
HTTP	Axios	1.13	API 请求
AI	Google Gemini	1.34	AI 服务

后端技术栈

类别	技术	版本	用途
框架	FastAPI	0.109	Web 框架
服务器	Uvicorn	0.27	ASGI 服务器
语言	Python	3.9+	开发语言
数据验证	Pydantic	2.6	数据校验
数据库	SQLAlchemy	2.0	ORM
HTTP 客户端	httpx	0.26	异步 HTTP
视频处理	FFmpeg	-	视频处理
CV 分析	OpenCV	4.9	计算机视觉
场景检测	PySceneDetect	0.6.3	镜头切分
认证	PyJWT	2.8	JWT Token
AI 模型	Qwen2.5-VL	-	多模态理解

📁 项目结构

Cube AI/
│
├── Backend/                          # 后端服务
│   └── video_ai_demo/
│       ├── app/                      # 应用代码
│       │   ├── api/                  # API 路由
│       │   │   ├── routes_auth.py           认证路由
│       │   │   ├── routes_dashboard.py      仪表板路由
│       │   │   ├── routes_analysis.py       分析路由
│       │   │   ├── routes_jobs.py           任务路由
│       │   │   ├── routes_knowledge.py      知识库路由
│       │   │   ├── routes_terminology.py    术语路由
│       │   │   ├── routes_user.py           用户路由
│       │   │   └── routes_virtual_motion.py 虚拟运镜路由
│       │   │
│       │   ├── core/                 # 核心模块
│       │   │   ├── auth.py                  JWT 认证
│       │   │   ├── config.py                配置管理
│       │   │   ├── errors.py                错误定义
│       │   │   ├── json_schema.py           Schema 校验
│       │   │   ├── logging.py               日志系统
│       │   │   ├── response.py              统一响应
│       │   │   └── shot_terminology.py      镜头术语
│       │   │
│       │   ├── db/                   # 数据库层
│       │   │   ├── models.py                ORM 模型
│       │   │   ├── repo.py                  仓储层
│       │   │   └── session.py               数据库会话
│       │   │
│       │   ├── pipeline/             # 处理流水线
│       │   │   ├── orchestrator.py          任务编排器
│       │   │   └── steps/                   处理步骤
│       │   │       ├── ingest.py               视频摄取
│       │   │       ├── extract_frames.py       抽帧
│       │   │       ├── scene_detect.py         场景检测
│       │   │       ├── mm_llm_decompose.py     LLM 分析
│       │   │       ├── format_analysis.py      格式化
│       │   │       ├── artifacts.py            产物生成
│       │   │       ├── compare_map.py          对比映射
│       │   │       └── improve_steps.py        改进建议
│       │   │
│       │   ├── integrations/         # 外部集成
│       │   │   ├── mm_llm_client.py          多模态 LLM
│       │   │   └── img2video_client.py       图生视频
│       │   │
│       │   ├── main.py               # 主程序入口
│       │   └── plugins/              # 插件系统
│       │
│       ├── data/                     # 数据目录
│       │   ├── demo.db                      SQLite 数据库
│       │   ├── uploads/                     上传文件
│       │   └── jobs/                        任务数据
│       │
│       ├── tests/                    # 测试代码
│       ├── examples/                 # 示例代码
│       ├── requirements.txt          # Python 依赖
│       ├── start.sh                  # 启动脚本
│       ├── .env.example              # 环境变量示例
│       │
│       └── 📚 文档/
│           ├── README.md                    后端说明
│           ├── PROJECT_SUMMARY.md           项目总结
│           ├── QUICKSTART.md                快速入门
│           ├── API_GUIDE.md                 API 指南
│           ├── DEPLOYMENT.md                部署指南
│           └── ...                          更多文档
│
├── frontend/                         # 前端应用
│   ├── components/                   # React 组件
│   │   ├── Dashboard.tsx                 总览面板
│   │   ├── AnalysisPanel.tsx             视频分析
│   │   ├── ShotAnalysis.tsx              镜头拆解 ⭐
│   │   ├── Editor.tsx                    脚本编辑器
│   │   ├── VideoSlideshow.tsx            视频幻灯片
│   │   ├── KnowledgeBase.tsx             知识库
│   │   ├── Discovery.tsx                 发现页
│   │   ├── Login.tsx                     登录
│   │   ├── Settings.tsx                  设置
│   │   ├── Sidebar.tsx                   侧边栏
│   │   └── ProfileModal.tsx              个人资料
│   │
│   ├── services/                     # API 服务层
│   │   ├── api.ts                        Axios 实例
│   │   ├── analysisService.ts            分析 API
│   │   ├── dashboardService.ts           仪表板 API
│   │   ├── videoAnalysisService.ts       镜头拆解 API ⭐
│   │   ├── knowledgeService.ts           知识库 API
│   │   └── geminiService.ts              Gemini AI
│   │
│   ├── types.ts                      # TypeScript 类型
│   ├── App.tsx                       # 主应用组件
│   ├── index.tsx                     # 入口文件
│   ├── index.html                    # HTML 模板
│   ├── index.css                     # 全局样式
│   │
│   ├── package.json                  # Node 依赖
│   ├── tsconfig.json                 # TS 配置
│   ├── vite.config.ts                # Vite 配置
│   ├── .env.example                  # 环境变量示例
│   │
│   └── 📚 文档/
│       ├── README.md                     前端说明
│       ├── PROJECT_OVERVIEW.md           项目总览
│       ├── QUICK_START.md                快速开始
│       ├── API_COMPATIBILITY.md          API 兼容性 ⭐
│       ├── API_DOCUMENTATION.md          API 文档
│       ├── SHOT_ANALYSIS_GUIDE.md        镜头拆解指南
│       ├── ENV_CONFIG.md                 环境配置
│       ├── TROUBLESHOOTING.md            故障排查
│       └── ...                           更多文档
│
└── 📄 PROJECT_README.md              # 项目总文档（本文件）

🚀 快速开始

环境要求

系统要求

操作系统: macOS / Linux / Windows
内存: 最低 4GB，推荐 8GB+
磁盘空间: 最低 10GB（用于视频存储）

软件依赖

后端:

Python 3.9+ (Video AI Demo), Python 3.10+ (Phone AI)
- ✅ 支持 Python 3.13（已更新依赖版本）
- ⚠️ Python 3.13 需要更新版本的依赖（pydantic>=2.9.0, sqlalchemy>=2.0.36）
FFmpeg (包含 ffprobe)
uv (推荐) 或 pip (传统方式)

前端:

Node.js 16+
npm 或 yarn
mkcert (用于生成 HTTPS 证书，可选)

💡 推荐使用 uv: uv 是一个用 Rust 编写的极速 Python 包管理器，可以大幅提升依赖安装速度。项目已完全支持 uv，启动脚本会自动检测并使用。

安装步骤

方式一：一键自动配置（推荐）⭐

# 1. 克隆项目
git clone <repository-url>
cd CubeAI-FlowDecompose

# 2. 运行统一配置脚本
./setup_environment.sh

脚本会自动完成：

✅ 检查系统依赖（Python、Node.js、FFmpeg）
✅ 安装/检测 uv（可选，推荐）
✅ 配置 Phone AI 后端依赖
✅ 配置 Video AI Demo 后端依赖
✅ 配置前端依赖和 HTTPS 证书
✅ 创建必要的配置文件

配置完成后，按照脚本提示：

编辑 Backend/video_ai_demo/.env，填入 MM_LLM_API_KEY
使用 ./start.sh 启动所有服务

💡 提示：

如果使用 Python 3.13，项目已自动配置兼容的依赖版本

所有启动脚本会自动检测并使用 uv（如果已安装）

前端 .env 会自动使用本机 IP 地址（避免手机访问问题）

方式二：手动配置

1️⃣ 安装系统依赖

# 安装 FFmpeg
# macOS
brew install ffmpeg

# Ubuntu/Debian
sudo apt update && sudo apt install ffmpeg

# 安装 uv（推荐，可选）
curl -LsSf https://astral.sh/uv/install.sh | sh

2️⃣ 配置 Phone AI 后端

cd Backend/phone_ai

# 使用 uv（推荐）
uv sync

# 或使用 pip（传统方式）
python3 -m venv venv
source venv/bin/activate
pip install -e ".[dev]"

3️⃣ 配置 Video AI Demo 后端

cd Backend/video_ai_demo

# 使用 uv（推荐）
# 项目已配置 pyproject.toml，支持 Python 3.13
uv sync

# 或使用 pip（传统方式）
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# 配置环境变量
cp .env.example .env  # 如果存在
# 编辑 .env 文件，填入 MM_LLM_API_KEY

⚠️ Python 3.13 用户注意：项目已更新依赖版本以支持 Python 3.13。如果使用 pip 安装遇到构建错误，建议使用 uv 或降级到 Python 3.12。

.env 配置示例:

# 多模态 LLM 配置（必需）
MM_LLM_BASE_URL=https://www.sophnet.com/api/open-apis/v1
MM_LLM_API_KEY=your_api_key_here
MM_LLM_MODEL=Qwen2.5-VL-7B-Instruct

# 数据存储
DATA_DIR=./data
SQLITE_PATH=./data/demo.db

# FFmpeg 路径
FFMPEG_BIN=ffmpeg
FFPROBE_BIN=ffprobe

# API 配置
API_HOST=0.0.0.0
API_PORT=8000

# JWT 密钥（生产环境务必修改）
SECRET_KEY=your-secret-key-change-in-production

4️⃣ 配置前端

cd frontend

# 安装 Node.js 依赖
npm install

# 生成 HTTPS 证书（用于摄像头权限）
mkdir -p certs
LOCAL_IP=$(ifconfig | grep "inet " | grep -v 127.0.0.1 | head -1 | awk '{print $2}')
mkcert -key-file certs/localhost+3-key.pem \
       -cert-file certs/localhost+3.pem \
       localhost 127.0.0.1 ::1 ${LOCAL_IP}

# 创建 .env 文件（使用本机 IP，不要用 localhost）
cat > .env << EOF
VITE_API_BASE_URL=http://${LOCAL_IP}:8000/api/v1
VITE_SHOT_ANALYSIS_BASE_URL=http://${LOCAL_IP}:8000
VITE_PHONE_AI_PORT=8001
VITE_API_TIMEOUT=30000
VITE_ENABLE_MOCK=false
VITE_ENABLE_API_LOG=true
VITE_FREE_DAILY_QUOTA=5
VITE_MAX_FILE_SIZE=100
VITE_POLL_INTERVAL=2000
EOF

⚠️ 重要: 前端 .env 中必须使用本机 IP 地址（如 192.168.1.100），不要使用 localhost，否则手机无法访问。

5️⃣ 启动服务

方式 1：使用统一启动脚本（推荐）

# 在项目根目录
./start.sh
# 选择启动方式（交互模式或后台模式）

方式 2：手动启动（3个终端）

# 终端 1: Video AI Demo
cd Backend/video_ai_demo
./start.sh

# 终端 2: Phone AI
cd Backend/phone_ai
export PORT=8001
./start_backend_https.sh

# 终端 3: 前端
cd frontend
npm run dev

6️⃣ 访问应用

前端应用: https://YOUR_IP:3000 (HTTPS) 或 http://YOUR_IP:3000 (HTTP)
Video AI API 文档: http://YOUR_IP:8000/docs
Phone AI API 文档: https://YOUR_IP:8001/docs
默认账号:
- 邮箱: 任意邮箱
- 密码: demo123

📱 手机访问: 使用 HTTPS 模式启动前端，然后用手机扫描页面上的二维码即可访问。

🎮 使用指南

视频深度拆解

登录系统
进入「总览面板」或「视频分析」
输入视频 URL 或上传本地文件
等待 AI 分析（通常 1-3 分钟）
查看分析结果：
- 爆款因素雷达图
- 节奏曲线
- 钩子强度
- 详细评分

镜头拆解分析 ⭐

点击侧边栏「镜头拆解分析」
上传视频文件
- 支持格式: MP4, MOV, AVI 等
- 最大 100MB
等待 AI 分析（自动场景检测 + 多模态理解）
查看结果：
- 时间轴视图: 可视化镜头序列
- 运镜分析: 每个镜头的运镜类型
- 光线分析: 光线布局和类型
- 调色分析: 色调和风格
交互操作：
- 点击片段 → 跳转到视频对应位置
- 查看详情 → 展开特征详细说明
- 历史记录 → 查看之前的分析

实时拍摄助手 ⭐⭐

启动服务

# 启动后端（Python）
cd phone_ai
uv run uvicorn src.api.app:app --host 0.0.0.0 --port 8000

# 启动前端（HTTPS）
cd story-galaxy-controller
USE_HTTPS=true npm run dev

电脑端操作
- 访问 https://localhost:3000 或 https://YOUR_IP:3000
- 点击「开始体验」生成二维码
手机端操作
- 用手机扫描二维码（首次访问需点击「继续访问」忽略证书警告）
- 允许浏览器访问摄像头权限
- 进入实时拍摄界面
使用实时辅导
- 环境扫描: AI 自动分析拍摄环境
- 任务推荐: 系统推荐低风险拍摄任务
- 开始拍摄: 点击「开始分析」按钮
- 实时反馈:
  - 顶部教练胶囊显示 AI 指令
  - 边缘方向指示器（>>>）提示移动方向
  - 底部平衡水平仪显示运动平滑度
- 纠错提示: 手抖或速度过快时，系统实时提醒
查看结果
- 实时查看 CV 分析数据
- 接收 AI 建议和反馈
- 完成任务后查看总结

脚本创作

完成视频分析后，进入「创作中心」
选择创作策略：
- 故事叙述型
- 知识分享型
- 产品展示型
- 情感共鸣型
选择目标平台（抖音/B站/小红书等）
AI 自动生成分镜脚本
手动调整和优化
导出脚本

知识库管理

进入「灵感仓库」
浏览不同分类：
- 钩子技巧
- 叙事结构
- 风格参考
- 配乐方案
- 指纹识别
搜索关键词
收藏感兴趣的内容
添加笔记和标签

🚢 部署指南

开发环境

已在上面「快速开始」中说明。

生产环境部署

后端部署

方式 1: 使用 Docker

# Dockerfile
FROM python:3.9-slim

# 安装 FFmpeg
RUN apt-get update && apt-get install -y ffmpeg && rm -rf /var/lib/apt/lists/*

WORKDIR /app

# 安装 Python 依赖
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# 复制应用代码
COPY . .

# 暴露端口
EXPOSE 8000

# 启动服务
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]

# 构建镜像
docker build -t Cube AI-backend .

# 运行容器
docker run -d -p 8000:8000 \
  -v $(pwd)/data:/app/data \
  -e MM_LLM_API_KEY=your_key \
  Cube AI-backend

方式 2: 使用 Systemd（Linux）

# /etc/systemd/system/intuition-backend.service
[Unit]
Description=Cube AI Backend Service
After=network.target

[Service]
Type=simple
User=www-data
WorkingDirectory=/var/www/Cube AI/Backend/video_ai_demo
Environment="PATH=/usr/local/bin:/usr/bin:/bin"
ExecStart=/usr/local/bin/uvicorn app.main:app --host 0.0.0.0 --port 8000
Restart=always

[Install]
WantedBy=multi-user.target

sudo systemctl enable intuition-backend
sudo systemctl start intuition-backend
sudo systemctl status intuition-backend

方式 3: 使用 Nginx + Gunicorn

# 安装 Gunicorn
pip install gunicorn

# 启动服务
gunicorn app.main:app \
  --workers 4 \
  --worker-class uvicorn.workers.UvicornWorker \
  --bind 0.0.0.0:8000

前端部署

方式 1: 静态文件部署

# 构建生产版本
npm run build

# 产物在 dist/ 目录
ls dist/

Nginx 配置:

server {
    listen 80;
    server_name your-domain.com;
    
    root /var/www/Cube AI/frontend/dist;
    index index.html;
    
    # SPA 路由支持
    location / {
        try_files $uri $uri/ /index.html;
    }
    
    # API 代理
    location /api {
        proxy_pass http://localhost:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
    
    # 静态资源缓存
    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg)$ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }
}

方式 2: 使用 Docker

# Dockerfile
FROM node:18-alpine AS build

WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
RUN npm run build

FROM nginx:alpine
COPY --from=build /app/dist /usr/share/nginx/html
COPY nginx.conf /etc/nginx/conf.d/default.conf
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]

# 构建和运行
docker build -t Cube AI-frontend .
docker run -d -p 3000:80 Cube AI-frontend

方式 3: 部署到 Vercel

# 安装 Vercel CLI
npm i -g vercel

# 部署
vercel

# 配置环境变量（在 Vercel Dashboard）
VITE_API_BASE_URL=https://api.your-domain.com/v1

Docker Compose 一键部署

# docker-compose.yml
version: '3.8'

services:
  backend:
    build: ./Backend/video_ai_demo
    ports:
      - "8000:8000"
    volumes:
      - ./data:/app/data
    environment:
      - MM_LLM_API_KEY=${MM_LLM_API_KEY}
      - SQLITE_PATH=/app/data/demo.db
    restart: always

  frontend:
    build: ./frontend
    ports:
      - "3000:80"
    depends_on:
      - backend
    environment:
      - VITE_API_BASE_URL=http://localhost:8000/api/v1
    restart: always

volumes:
  data:

# 启动全部服务
docker-compose up -d

# 查看日志
docker-compose logs -f

# 停止服务
docker-compose down

📡 API 文档

API 概览

后端 API 架构:

/api/v1/                        # 新版 API（推荐）
├── /auth/login                     用户登录
├── /auth/register                  用户注册
├── /dashboard/stats                统计数据
├── /dashboard/projects             项目列表
├── /analysis/create                创建分析
├── /analysis/{id}                  获取结果
├── /knowledge/items                知识库列表
└── /user/profile                   用户信息

/v1/video-analysis/             # 原有 API（兼容）
├── /jobs                           任务管理
├── /jobs/{job_id}                  任务状态
└── /history                        历史记录

/v1/terminology/                # 术语查询
└── /search                         搜索术语

统一响应格式

成功响应

{
  "success": true,
  "data": {
    // 实际数据
  },
  "message": "操作成功",
  "timestamp": 1704153600000
}

错误响应

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "错误描述",
    "details": null
  },
  "timestamp": 1704153600000
}

核心 API 示例

1. 用户登录

POST /api/v1/auth/login
Content-Type: application/json

{
  "email": "[email protected]",
  "password": "demo123"
}

响应:

{
  "success": true,
  "data": {
    "user": {
      "id": "user_xxx",
      "email": "[email protected]",
      "name": "用户名"
    },
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expiresIn": 604800
  }
}

2. 创建视频分析任务（镜头拆解）

POST /v1/video-analysis/jobs
Content-Type: application/json

{
  "mode": "learn",
  "target_video": {
    "source": {
      "type": "file",
      "path": "/path/to/video.mp4"
    }
  },
  "options": {
    "frame_extract": {
      "fps": 1.0,
      "max_frames": 20
    },
    "analysis": {
      "enabled_modules": ["camera_motion", "lighting", "color_grading"]
    }
  }
}

响应:

{
  "job_id": "job_abc123",
  "status": "queued",
  "status_url": "/v1/video-analysis/jobs/job_abc123"
}

3. 查询任务状态

GET /v1/video-analysis/jobs/job_abc123

响应:

{
  "job_id": "job_abc123",
  "status": "succeeded",
  "result": {
    "mode": "learn",
    "target": {
      "segments": [
        {
          "segment_id": "seg_001",
          "start_ms": 0,
          "end_ms": 3500,
          "features": [
            {
              "category": "camera_motion",
              "type": "push_in",
              "value": "缓慢推镜",
              "confidence": 0.85
            }
          ]
        }
      ]
    }
  }
}

详细 API 文档

后端 API: Backend/video_ai_demo/API_GUIDE.md
前端集成: frontend/API_DOCUMENTATION.md
兼容性说明: frontend/API_COMPATIBILITY.md

📚 开发文档

文档导航

后端文档

文档	说明	路径
README.md	后端总说明	`Backend/video_ai_demo/README.md`
DOCS_INDEX.md	文档索引	`Backend/video_ai_demo/DOCS_INDEX.md`
PROJECT_SUMMARY.md	项目总结	`Backend/video_ai_demo/PROJECT_SUMMARY.md`
QUICKSTART.md	快速入门	`Backend/video_ai_demo/QUICKSTART.md`
QUICK_REFERENCE.md	快速参考	`Backend/video_ai_demo/QUICK_REFERENCE.md`
API_GUIDE.md	API 使用指南	`Backend/video_ai_demo/API_GUIDE.md`
API_QUICK_REFERENCE.md	API 快速参考	`Backend/video_ai_demo/API_QUICK_REFERENCE.md`
DEPLOYMENT.md	部署指南	`Backend/video_ai_demo/DEPLOYMENT.md`
CV_SCENE_DETECTION.md	场景检测说明	`Backend/video_ai_demo/CV_SCENE_DETECTION.md`
CV_QUICK_REFERENCE.md	CV 快速参考	`Backend/video_ai_demo/CV_QUICK_REFERENCE.md`
SHOT_TERMINOLOGY.md	镜头术语	`Backend/video_ai_demo/SHOT_TERMINOLOGY.md`
UPGRADE_GUIDE.md	升级指南	`Backend/video_ai_demo/UPGRADE_GUIDE.md`

前端文档

文档	说明	路径
README.md	前端总说明	`frontend/README.md`

开发规范

代码规范

后端（Python）:

遵循 PEP 8 规范
使用类型提示（Type Hints）
编写 Docstring
单元测试覆盖

前端（TypeScript）:

使用 TypeScript 严格模式
组件使用 PascalCase 命名
函数使用 camelCase 命名
Props 定义接口类型

Git 工作流

# 主分支
main          生产环境
develop       开发环境

# 功能分支
feature/*     新功能开发
bugfix/*      Bug 修复
hotfix/*      紧急修复

Commit 规范

feat: 新功能
fix: Bug 修复
docs: 文档更新
style: 代码格式
refactor: 重构
perf: 性能优化
test: 测试相关
chore: 构建/工具

❓ 常见问题

安装问题

Q: Python 依赖安装失败？

A: 确保 Python 版本 >= 3.9，可尝试：

# 使用 uv（推荐，更快）
uv sync

# 或使用 pip
pip install --upgrade pip
pip install -r requirements.txt --no-cache-dir

Q: Python 3.13 安装依赖失败？

A: Python 3.13 需要更新版本的依赖，项目已更新：

pydantic>=2.9.0（支持 Python 3.13）
sqlalchemy>=2.0.36（支持 Python 3.13）

如果使用 uv，会自动安装兼容版本。如果使用 pip 且遇到构建错误，建议：

使用 uv（推荐）
或使用 Python 3.12（更稳定）

Q: 如何安装 uv？

A: uv 是一个极速 Python 包管理器，推荐安装：

# 安装 uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# 验证安装
uv --version

# 如果命令未找到，添加到 PATH
export PATH="$HOME/.cargo/bin:$PATH"
# 或添加到 ~/.bashrc / ~/.zshrc
echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.bashrc

Q: uv 和 pip 有什么区别？我应该用哪个？

A:

uv: 推荐使用，速度更快（Rust 实现），自动管理虚拟环境，支持依赖锁定
pip: 传统方式，兼容性更好，但速度较慢

项目已完全支持两种方式，启动脚本会自动检测并使用 uv（如果已安装）。建议新环境使用 uv，现有稳定环境可继续使用 pip。

Q: FFmpeg 未找到？

A: 安装 FFmpeg 并确保在 PATH 中：

# 检查
ffmpeg -version
ffprobe -version

# macOS 安装
brew install ffmpeg

# Ubuntu 安装
sudo apt install ffmpeg

Q: Node.js 依赖安装慢？

A: 使用国内镜像：

npm config set registry https://registry.npmmirror.com
npm install

Q: 一键配置脚本失败？

A: 检查以下几点：

# 1. 确保脚本有执行权限
chmod +x setup_environment.sh

# 2. 检查系统依赖是否已安装
python3 --version  # 需要 3.9+ (Video AI Demo), 3.10+ (Phone AI)
node --version     # 需要 16+
ffmpeg -version    # 需要已安装

# 3. 手动运行脚本查看详细错误
bash -x setup_environment.sh

# 4. Python 3.13 用户：如果遇到依赖构建错误，脚本会自动回退到 pip

Q: 依赖版本冲突？

A: 项目已更新依赖版本以支持 Python 3.13：

pydantic>=2.9.0（原 2.6.0）
sqlalchemy>=2.0.36（原 2.0.25）

如果遇到版本冲突：

# 使用 uv（自动解决冲突）
uv sync

# 或清理后重新安装
rm -rf .venv venv
uv sync  # 或 pip install -r requirements.txt

运行问题

Q: 后端启动失败？

A: 检查：

.env 文件是否配置正确
MM_LLM_API_KEY 是否有效
端口 8000 是否被占用

# 查看端口占用
lsof -i :8000

# 更换端口
uvicorn app.main:app --port 8001

Q: 前端无法连接后端？

A: 检查：

后端是否正常运行（访问 http://YOUR_IP:8000/docs）
.env 中的 VITE_API_BASE_URL 是否正确（必须使用本机 IP，不要用 localhost）
浏览器控制台是否有 CORS 错误或混合内容错误
如果前端使用 HTTPS，后端必须是 HTTP（或都使用 HTTPS）

Q: AI 拍摄助手页面加载不出来？

A: 常见问题：

JavaScript 错误：检查浏览器控制台（F12），查看是否有错误
CORS 错误：确保 Phone AI 后端使用 HTTPS 启动（./start_backend_https.sh）
WebSocket 连接失败：检查后端是否运行，端口 8001 是否可访问
Mixed Content 错误：Video AI Demo 使用 HTTP 是正常的，可以忽略

排查步骤：

# 运行诊断脚本
./check_phone_ai.sh

# 检查服务状态
./status.sh

# 测试 API 端点
curl -k -X POST https://localhost:8001/api/realtime/session

Q: 手机无法访问前端？

A: 常见原因：

使用了 localhost: 前端 .env 中必须使用本机 IP 地址
证书问题: 确保已生成 HTTPS 证书（使用 mkcert）
防火墙: 确保端口 3000、8000、8001 未被防火墙阻止
网络: 确保手机和电脑在同一局域网

解决方法：

# 获取本机 IP
ifconfig | grep "inet " | grep -v 127.0.0.1

# 更新前端 .env 文件
# 将 localhost 替换为本机 IP
sed -i 's/localhost/YOUR_IP/g' frontend/.env

Q: 视频分析失败？

A: 可能原因：

视频格式不支持 → 转换为 MP4
API 密钥额度不足 → 检查账户余额
网络问题 → 检查网络连接
视频太大 → 压缩视频或调整 max_frames

功能问题

Q: 镜头拆解结果不准确？

A: 调整参数：

降低场景检测阈值（更多镜头）
增加抽帧率 fps（更精细分析）
增加 max_frames（更完整分析）

Q: 分析速度太慢？

A: 优化建议：

减少 fps 和 max_frames
使用较短的视频测试
考虑升级服务器配置

Q: Token 过期怎么办？

A: Token 默认 7 天有效期，过期后重新登录获取新 Token。

部署问题

Q: Docker 部署失败？

A: 检查：

Docker 版本 >= 20.10
磁盘空间是否充足
网络是否能访问 Docker Hub

Q: Nginx 配置后前端路由 404？

A: 确保配置了 try_files:

location / {
    try_files $uri $uri/ /index.html;
}

🔄 更新日志

v2.0.0 (2025-01-02) ⭐ 最新版本

重大更新：

✨ 新增镜头拆解分析功能
- 自动场景检测（PySceneDetect + OpenCV）
- 多模态 AI 镜头分析（Qwen2.5-VL）
- 运镜、光线、调色识别
- 时间轴可视化展示
- 实时流式输出

前端改进：

✨ 新增 ShotAnalysis.tsx 组件
✨ 新增 videoAnalysisService.ts 服务
✨ API 格式兼容性增强
🎨 UI/UX 全面优化
🚀 性能提升和优化

后端改进：

✨ 集成 PySceneDetect 场景检测
✨ 新增 scene_detect.py 步骤
✨ 新增镜头术语系统
📚 完善 API 文档
🐛 Bug 修复和稳定性提升

文档更新：

📝 新增项目总文档（本文件）
📝 新增镜头拆解使用指南
📝 更新 API 兼容性文档
📝 更新部署指南

v1.0.0 (2024-12-01)

初始版本：

✅ 视频深度拆解功能
✅ 视频转幻灯片
✅ AI 脚本生成
✅ 知识库管理
✅ 用户认证系统
✅ 总览面板
✅ 完整的前后端分离架构

🤝 贡献指南

欢迎贡献代码、报告问题、提出建议！

如何贡献

Fork 项目

# Fork 到你的账号，然后克隆
git clone <your-fork-url>
cd Cube AI

创建功能分支

git checkout -b feature/your-feature-name

开发和测试

# 后端测试
cd Backend/video_ai_demo
pytest tests/

# 前端测试
cd frontend
npm run lint
npm run type-check

提交代码

git add .
git commit -m "feat: 添加新功能"
git push origin feature/your-feature-name

创建 Pull Request

在 GitHub 上创建 PR，描述你的修改。

开发环境设置

# 安装开发依赖
cd Backend/video_ai_demo
pip install -r requirements.txt
pip install pytest pytest-asyncio  # 测试工具

cd ../../frontend
npm install

代码审查清单

🙏 致谢

开源项目

感谢团队的倾心付出： @Valentina_Yang @Kindin-X @晓叶

感谢以下优秀的开源项目：

后端:

FastAPI - 现代化 Web 框架
SQLAlchemy - 强大的 ORM
Pydantic - 数据验证
PySceneDetect - 场景检测
OpenCV - 计算机视觉

前端:

React - UI 框架
TypeScript - 类型安全
Vite - 构建工具
Tailwind CSS - 样式方案
Lucide Icons - 图标库
Recharts - 图表库
Axios - HTTP 客户端

AI 服务:

Qwen2.5-VL - 多模态视觉理解
Google Gemini - AI 内容生成

📞 联系方式

项目主页: GitHub Repository
问题反馈: GitHub Issues
邮箱: [email protected]
文档: 见 Backend/video_ai_demo/ 和 frontend/ 目录

📄 许可证

本项目采用 MIT License 开源协议。

MIT License

Copyright (c) 2025 Jumping_Cats Team

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

🎉 结语

Cube AI (魔方 AI) 致力于为视频创作者提供专业的 AI 分析和创作辅助工具。

我们相信，通过技术的力量，可以让每个人都能创作出更优质的视频内容。

让视频创作更简单，让灵感触手可及！ ✨

Cube AI - 智能视频分析与创作辅助平台

Made with ❤️ by Jumping_Cats Team

开始使用 • 查看文档 • 反馈问题

⭐ 如果这个项目对你有帮助，请给我们一个 Star！

Name		Name	Last commit message	Last commit date
Latest commit History 22 Commits
Backend		Backend
frontend		frontend
phone_ai/story-galaxy-controller/.vite/deps		phone_ai/story-galaxy-controller/.vite/deps
.DS_Store		.DS_Store
.gitignore		.gitignore
PHONE_AI_TROUBLESHOOTING.md		PHONE_AI_TROUBLESHOOTING.md
QUICK_START_参考卡.md		QUICK_START_参考卡.md
README.md		README.md
check_phone_ai.sh		check_phone_ai.sh
setup_environment.sh		setup_environment.sh
start.sh		start.sh
status.sh		status.sh
stop_all.sh		stop_all.sh
文档中心.md		文档中心.md
项目启动完整攻略.md		项目启动完整攻略.md

tyfuser/CubeAI-FlowDecompose

Folders and files

Latest commit

History

Repository files navigation

Cube AI 魔方 AI - 项目总文档

📖 目录

🎯 项目概述

项目信息

适用场景

💡 核心价值

1. 🎯 智能视频分析

2. 📹 专业镜头拆解

3. ✍️ AI 创作辅助

4. 📚 知识库管理

5. 📱 实时拍摄辅导

✨ 功能特性

🎬 视频深度拆解

📹 镜头拆解分析 ⭐ 新功能

1. 镜头切分

2. 运镜识别

3. 光线分析

4. 调色识别

📱 实时拍摄助手 ⭐ 新功能

1. 环境智能判读

2. 智能任务推荐

3. 实时 HUD 界面

4. 实时 CV 分析

5. 智能反馈系统

6. 任务状态管理

📊 视频转幻灯片

✍️ 创作中心

📚 灵感仓库

📈 总览面板

技术栈详情

前端技术栈

后端技术栈

📁 项目结构

🚀 快速开始

环境要求

系统要求

软件依赖

安装步骤

方式一：一键自动配置（推荐）⭐

方式二：手动配置

1️⃣ 安装系统依赖

2️⃣ 配置 Phone AI 后端

3️⃣ 配置 Video AI Demo 后端

4️⃣ 配置前端

5️⃣ 启动服务

6️⃣ 访问应用

🎮 使用指南

视频深度拆解

镜头拆解分析 ⭐

实时拍摄助手 ⭐⭐

脚本创作

知识库管理

🚢 部署指南

开发环境

生产环境部署

后端部署

前端部署

Docker Compose 一键部署

📡 API 文档

API 概览

统一响应格式

成功响应

错误响应

核心 API 示例

1. 用户登录

2. 创建视频分析任务（镜头拆解）

3. 查询任务状态

详细 API 文档

📚 开发文档

文档导航

后端文档

前端文档

开发规范

代码规范

Git 工作流

Packages