| 
|
## ✨ 核心价值
- **极致一致性**：全局种子 + 统一风格 + 资产复用，解决 AI 生成最痛的“人物/场景漂移”问题
- **工业化生产流程**：从文学剧本到可拍摄分镜，再到视频片段，一条龙闭环
- **可视化 & 可控**：所见即所得的分镜编辑器 + 精细的镜头语言控制 + 实时预览
- **资产复用体系**：角色/场景/道具/服装/提示词模板全生命周期管理
## 🚀 主要功能一览
| 模块 | 核心功能 | 亮点特性 |
|--------------------|--------------------------------------------------------------------------|-----------------------------------------------|
| 项目管理 | 创建项目、全局风格/种子统一控制、项目仪表盘、章节统计 | 全局种子防漂移、风格强制继承 |
| 章节拍摄工作台 | 剧本输入 → 智能精简 → 智能分镜提取 → 分镜编辑 → 视频生成 → 预览 | 三栏式布局、可收起右侧属性面板、批量操作 |
| 分镜精细控制 | 景别/角度/运镜/情绪/时长/氛围/对白/配乐/音效/隐藏分镜 | 首/尾/关键帧独立提示词、多版本管理 |
| 高级生成控制 | 参考图跨分镜引用、ControlNet骨骼/深度、智能对口型、模型/时长选择 | 动作可控 + 口型同步 |
| 资产管理系统 | 角色/场景/道具/服装集中管理、智能提取 + 手动关联 + 提示词模板 | 项目资产库 vs 全局资产库双层体系 |
| 提示词模板库 | 分镜/角色/场景/视频/配乐/音效/综合提示词模板 | 一键初始化新章节 |
| 视频后期剪辑 | 时间线编辑、多轨视频/音频、素材库拖拽、最终导出 | 从 AI 片段直接剪辑成完整短剧 |
| Agent 工作流 | 剧情提取 / 角色提取 / 分镜建议 等可定制 Agent，支持可视化编排与测试 | 类似 Dify 的节点式工作流编辑器 |
| 模型管理 | 多供应商（OpenAI/Claude/通义/混元等）管理、模型分类（文本/图/视频） | 每类可设默认模型、快速测试连接 |
| 生成素材管理 | 图片/视频统一预览、标签标记、过滤、批量导出 | 支持优质素材快速复用 |
## 🎯 适用场景
- 短剧/微短剧内容创作者
- AI 影视工作室批量生产
- 个人创作者想低成本试水竖屏短剧
- 教育/培训机构制作教学短视频
- 品牌/电商制作带剧情的产品宣传短片
## 🛠 技术栈（示例）
- 前端：React 18 + TypeScript + Vite + Ant Design / Tailwind CSS
- 状态管理：Redux Toolkit / Zustand
- 工作流编辑：React Flow
- 视频播放器：Video.js / Plyr
- 富文本/代码编辑：Monaco Editor / React Quill
- 后端（可选开源部分）：Node.js / NestJS / FastAPI / Spring Boot
- AI 生成层：对接多种大模型 API（OpenAI / Anthropic / Midjourney / Runway / Kling / Luma 等）
## 🔁 前端 OpenAPI 请求/类型生成与更新
前端请求函数与数据结构由后端 OpenAPI 文档生成，生成目录为 `front/src/services/generated/`，OpenAPI 文档缓存为 `front/openapi.json`。
在后端开发服务已启动（默认 `http://127.0.0.1:8000`）时，在前端目录执行：
```bash
cd front
pnpm run openapi:update
```
说明：
- `openapi:update` 会先拉取 `http://127.0.0.1:8000/openapi.json` 到 `front/openapi.json`，再生成代码到 `front/src/services/generated/`
- 如需修改请求基础地址，可配置 `VITE_BACKEND_URL`（构建时）或在部署时通过 `BACKEND_URL` 运行时注入（`front/index.html` 引入 `/env.js`），见 `front/src/services/openapi.ts`
## 🐳 Docker 一键启动（MySQL + RustFS + Backend + Front）
项目已提供开箱即用的 compose 编排，文件位于 `deploy/compose/`。
### 端口
- 前端：`http://localhost:7788`
- 后端：`http://localhost:8000`（`/docs` 为 Swagger）
- MySQL：`localhost:${MYSQL_PORT:-3306}`
- RustFS（S3 API）：`http://localhost:${RUSTFS_PORT:-9000}`（Console：`http://localhost:${RUSTFS_CONSOLE_PORT:-9001}`）
### 启动
```bash
cp deploy/compose/.env.example deploy/compose/.env
docker compose --env-file deploy/compose/.env -f deploy/compose/docker-compose.yml up --build
```
首次启动会自动运行一次 `backend/init_db.py` 创建表结构（`backend-init-db` 服务）。
并在其成功后自动按文件名前缀顺序依次导入 `backend/sql/` 下的 SQL 文件（`mysql-init-sql` 服务），例如：
- `001-init-prompt-template.sql`
- `002-add-shot-extracted-candidates.sql`
## 🧑💻 开发环境启动（前后端分离）
### 端口
- 前端（Vite dev）：`http://localhost:7788`
- 后端（FastAPI）：`http://localhost:8000`（`/docs` 为 Swagger）
### 启动后端
```bash
cd backend
cp .env.example .env
uv sync
uv run uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
```
提交前可在 `backend` 目录执行 `uv sync --group dev` 与 `uv run pylint app` 做静态检查（配置与说明见 [backend/README.md](backend/README.md)）。
### 启动前端
```bash
cd front
pnpm install
pnpm dev
```
### （可选）仅启动依赖服务 MySQL + RustFS
如果你希望开发时使用 MySQL + RustFS（而不是默认 SQLite），可以只启动基础设施服务：
```bash
cp deploy/compose/.env.example deploy/compose/.env
docker compose --env-file deploy/compose/.env -f deploy/compose/docker-compose.yml up -d mysql rustfs
```
### Git 提交说明格式
本地提交时，**首行**须符合：`[类型] 摘要`。`类型` 只能是下列**枚举之一**（**必须小写**），后接**一个空格**再写摘要：
| 类型 | 含义 |
|------|------|
| `feat` | 新功能 |
| `fix` | 缺陷 / Bug 修复 |
| `docs` | 文档 |
| `style` | 格式调整（不改变代码含义） |
| `refactor` | 重构 |
| `perf` | 性能优化 |
| `test` | 测试 |
| `chore` | 杂项 / 工具 / 非 src |
| `ci` | CI 配置 |
| `build` | 构建系统或依赖 |
| `revert` | 回滚 |
示例：`[feat] 新功能`、`[fix] 修复登录`、`[docs] 更新 README`。不可使用未在表中的类型（如 `[wip]`、`[update]`）。
启用校验（在本仓库根目录执行一次即可）：
```bash
git config core.hooksPath .githooks
```
说明：合并提交（`Merge …`）、`Revert …` 及合并流程中的提交会被钩子放行。
**远端强制**：向默认分支发起的 Pull Request 会由 [`.github/workflows/commit-messages.yml`](.github/workflows/commit-messages.yml) 校验 PR 内每个提交的标题行（规则与上相同；`Merge` / `Revert` 开头跳过）。请在分支上把提交信息写成符合规范的格式后再推。
## 🚧 开发状态 / Roadmap
项目处于**活跃开发中**，以下为当前功能完成度与规划进度。欢迎通过 [Issues](https://github.com/Forget-C/Jellyfish/issues) 参与讨论与贡献。
### ✅ 已完成
| 模块 | 说明 |
|------|------|
| 模型管理交互 | 模型列表、筛选、配置等前端交互已就绪 |
| 项目管理交互 | 项目创建、编辑、仪表盘等交互流程已打通 |
| 项目工作台交互 | 项目级工作台布局与基础操作已实现 |
| 章节拍摄工作台交互 | 章节拍摄相关界面与交互已就绪 |
| 模型管理功能 | 多供应商、多类型模型的管理与默认配置 |
| 项目管理功能 | 项目 CRUD、全局风格与种子等配置能力 |
### 🚧 进行中 / 规划中
| 模块 | 说明 |
|------|------|
| 章节拍摄工作台 | 完整分镜编辑、视频生成与预览流程（功能深化中） |
| 高级提示词 | 分镜/角色/场景等高级提示词模板与智能填充（规划中） |
## 开发者
项目仍处于开发阶段，核心流程与数据模型尚未完全稳定；但已提供基于 Docker Compose 的本地启动方式（见上方）。
## 📄 开源协议 / License
本项目采用 [Apache-2.0](LICENSE) 开源协议。
欢迎提交 **Pull Request**、**Issue** 与 **Star**，与社区一起把 AI 短剧生产工具做成可落地的行业方案。
## 💬 交流与反馈 / Community
- **[GitHub Issues](https://github.com/Forget-C/Jellyfish/issues)** — 功能建议、Bug 反馈、使用讨论
- **微信群 / Discord** — 待建设，后续会在本页更新入口