AI短剧漫剧工具 Toonflow 系统架构文档

1. 项目概览

Toonflow 是一款 AI短剧漫剧工具，能够利用 AI 技术将小说自动转化为剧本，并结合 AI 生成的图片和视频，实现高效的短剧创作。借助 Toonflow，可以轻松完成从文字到影像的全流程，让短剧制作变得更加智能与便捷。

1.1 核心功能

角色生成：自动分析原始小说文本，智能识别并生成角色设定
剧本生成：基于选定事件和章节，系统自动生成结构化剧本
分镜制作：根据剧本内容，智能生成分镜提示词与画面设计
视频合成：集成 AI 图像与视频技术，可使用 AI 生成视频片段

1.2 技术栈

后端：Node.js 23.11.1+
前端：基于 Toonflow-web 仓库
依赖管理：Yarn
部署：支持 Windows 本地部署和云端部署（Ubuntu/CentOS）

2. 系统架构设计

2.1 架构 overview

Toonflow 采用前后端分离的架构设计，后端提供 API 服务，前端负责用户界面和交互。系统整体分为以下几个核心层次：

flowchart TD
    subgraph 前端层
        A[Web界面] --> B[用户交互]
        B --> C[前端API调用]
    end
    
    subgraph 后端层
        D[API服务] --> E[业务逻辑]
        E --> F[AI模型调用]
        E --> G[数据处理]
    end
    
    subgraph AI服务层
        H[大语言模型] --> I[剧本生成]
        J[视频生成服务] --> K[视频合成]
        L[图像生成模型] --> M[角色/场景生成]
    end
    
    C --> D
    F --> H
    F --> J
    F --> L

2.2 核心模块

模块	职责	技术实现	关键文件
文本分析	小说文本解析与角色识别	NLP 技术	待确认
剧本生成	基于小说内容生成剧本	大语言模型 API	待确认
分镜设计	根据剧本生成分镜提示词	规则引擎 + AI	待确认
图像生成	生成角色和场景图像	Nano Banana Pro	待确认
视频合成	生成视频片段并合成	Sora/豆包视频 API	待确认
用户管理	账号认证与权限控制	待确认	待确认
项目管理	短剧项目的创建与管理	待确认	待确认

3. 目录结构

基于项目特性和常见 Node.js 项目结构，Toonflow 可能采用以下目录组织：

Toonflow-app/
├── package.json          # 项目配置和依赖
├── yarn.lock             # Yarn 依赖锁定文件
├── tsconfig.json         # TypeScript 配置
├── src/                  # 源代码目录
│   ├── server/           # 后端服务器代码
│   │   ├── api/          # API 路由
│   │   ├── services/     # 业务服务
│   │   ├── models/       # 数据模型
│   │   ├── config/       # 服务器配置
│   │   └── index.ts      # 服务器入口
│   ├── client/           # 前端代码（可能内嵌）
│   ├── common/           # 公共代码
│   └── utils/            # 工具函数
├── public/               # 静态资源
├── build/                # 构建输出目录
├── config/               # 配置文件
└── scripts/              # 脚本文件

3.1 主要目录说明

src/server/：后端服务代码，包含 API 处理、业务逻辑和 AI 模型调用
src/client/：前端代码，负责用户界面和交互
src/common/：前后端共享的代码，如类型定义、工具函数等
src/utils/：通用工具函数
public/：静态资源文件
build/：编译后的代码和可执行文件
config/：配置文件，如 AI 服务接口地址等

4. 核心功能模块解析

4.1 文本分析与角色生成

功能描述：自动分析小说文本，识别角色并生成详细的角色设定。

实现机制：

使用 NLP 技术解析小说文本
识别主要角色、性格特点和关系
生成结构化的角色信息

关键流程：

接收用户上传的小说文本
文本分段和预处理
角色识别和提取
角色信息结构化
生成角色设定文档

4.2 剧本生成

功能描述：基于小说内容自动生成符合影视化要求的剧本。

实现机制：

调用大语言模型 API
提供结构化的提示词
处理模型返回的剧本内容

关键流程：

接收用户选择的小说章节或事件
生成剧本生成提示词
调用大语言模型 API
解析和格式化返回的剧本
提供剧本编辑和调整功能

4.3 分镜设计

功能描述：根据剧本内容生成分镜提示词和画面设计。

实现机制：

分析剧本场景和对话
生成分镜描述和提示词
设计画面布局和镜头角度

关键流程：

解析剧本场景
识别关键镜头和场景转换
生成分镜提示词
设计画面布局和角色动作
生成完整的分镜脚本

4.4 图像生成

功能描述：基于分镜提示词生成角色和场景图像。

实现机制：

调用 Nano Banana Pro 图像生成 API
优化提示词以获得最佳效果
处理和调整生成的图像

关键流程：

接收分镜提示词
优化和扩展提示词
调用图像生成 API
处理生成的图像
提供图像编辑和调整功能

4.5 视频合成

功能描述：生成视频片段并合成完整的短剧。

实现机制：

调用 Sora 或豆包视频生成 API
处理视频片段
合成完整视频

关键流程：

接收分镜和图像信息
生成视频生成提示词
调用视频生成 API
处理生成的视频片段
合成完整的短剧视频

5. 技术实现细节

5.1 AI 服务集成

Toonflow 集成了多种 AI 服务，实现从文本到视频的全流程自动化：

AI 服务	用途	集成方式	关键配置
大语言模型	剧本生成	API 调用	接口地址、API Key
Nano Banana Pro	图像生成	API 调用	接口地址、API Key
Sora/豆包	视频生成	API 调用	接口地址、API Key

5.2 前端实现

前端采用现代化的 Web 技术栈，提供直观的用户界面：

技术栈：待确认（可能是 React、Vue 或其他框架）
主要功能：
- 小说上传和管理
- 剧本编辑和预览
- 分镜设计和调整
- 视频预览和导出
- 用户账号管理

5.3 后端实现

后端基于 Node.js 实现，提供 API 服务和业务逻辑处理：

技术栈：Node.js 23.11.1+, TypeScript
主要功能：
- API 路由处理
- AI 服务调用
- 数据处理和存储
- 用户认证和授权
- 任务调度和管理

5.4 部署方案

Toonflow 支持多种部署方式：

本地部署：

Windows 安装包
内置前端资源
本地配置文件

云端部署：

Ubuntu 20.04+ / CentOS 7+
Node.js 23.11.1+
PM2 进程管理
环境变量配置

6. 核心 API/类/函数

6.1 后端 API

API 端点	方法	功能	请求体	响应
/api/auth/login	POST	用户登录	{username, password}	{token, user}
/api/novel/upload	POST	上传小说	multipart/form-data	{novelId, title}
/api/novel/analyze	POST	分析小说	{novelId}	{characters, events}
/api/script/generate	POST	生成剧本	{novelId, chapterId}	{scriptId, content}
/api/storyboard/generate	POST	生成分镜	{scriptId}	{storyboardId, frames}
/api/image/generate	POST	生成图像	{prompt, type}	{imageId, url}
/api/video/generate	POST	生成视频	{storyboardId}	{videoId, url}
/api/project/create	POST	创建项目	{title, description}	{projectId}
/api/project/list	GET	获取项目列表	N/A	{projects}

6.2 核心类

类名	职责	关键方法	所属文件
NovelAnalyzer	小说文本分析	analyze(), extractCharacters()	待确认
ScriptGenerator	剧本生成	generate(), optimizePrompt()	待确认
StoryboardDesigner	分镜设计	generateFrames(), createPrompt()	待确认
ImageGenerator	图像生成	generate(), optimizePrompt()	待确认
VideoComposer	视频合成	generateClips(), composeVideo()	待确认
ProjectManager	项目管理	create(), update(), delete()	待确认
UserManager	用户管理	authenticate(), authorize()	待确认

6.3 工具函数

函数名	职责	参数	返回值	所属文件
callAIAPI	调用 AI 服务 API	service, endpoint, params	响应数据	待确认
formatScript	格式化剧本内容	scriptText	结构化剧本	待确认
generateImagePrompt	生成图像提示词	scene, characters	提示词文本	待确认
validateUserInput	验证用户输入	input, schema	验证结果	待确认
handleError	错误处理	error, context	错误响应	待确认

7. 数据结构

7.1 核心数据模型

小说 (Novel)

字段	类型	描述
id	String	小说 ID
title	String	小说标题
content	String	小说内容
characters	Array<Character>	识别的角色
chapters	Array<Chapter>	章节信息
createdAt	Date	创建时间
updatedAt	Date	更新时间

角色 (Character)

字段	类型	描述
id	String	角色 ID
name	String	角色名称
description	String	角色描述
traits	Array<String>	性格特点
relationships	Array<Relationship>	与其他角色的关系

剧本 (Script)

字段	类型	描述
id	String	剧本 ID
novelId	String	关联的小说 ID
title	String	剧本标题
content	String	剧本内容
scenes	Array<Scene>	剧本场景
createdAt	Date	创建时间

分镜 (Storyboard)

字段	类型	描述
id	String	分镜 ID
scriptId	String	关联的剧本 ID
frames	Array<Frame>	分镜帧
createdAt	Date	创建时间

分镜帧 (Frame)

字段	类型	描述
id	String	帧 ID
sceneId	String	关联的场景 ID
prompt	String	生成提示词
description	String	帧描述
imageUrl	String	生成的图像 URL
order	Number	帧顺序

视频 (Video)

字段	类型	描述
id	String	视频 ID
storyboardId	String	关联的分镜 ID
url	String	视频 URL
duration	Number	视频时长（秒）
status	String	视频状态
createdAt	Date	创建时间

项目 (Project)

字段	类型	描述
id	String	项目 ID
title	String	项目标题
description	String	项目描述
novelId	String	关联的小说 ID
scriptId	String	关联的剧本 ID
storyboardId	String	关联的分镜 ID
videoId	String	关联的视频 ID
status	String	项目状态
createdAt	Date	创建时间
updatedAt	Date	更新时间

8. 业务流程

8.1 小说到短剧全流程

sequenceDiagram
    participant User as 用户
    participant Frontend as 前端界面
    participant Backend as 后端服务
    participant AI as AI 服务
    
    User->>Frontend: 上传小说
    Frontend->>Backend: 分析小说
    Backend->>AI: 调用文本分析
    AI-->>Backend: 返回角色信息
    Backend-->>Frontend: 显示角色列表
    
    User->>Frontend: 选择章节生成剧本
    Frontend->>Backend: 生成剧本
    Backend->>AI: 调用大语言模型
    AI-->>Backend: 返回剧本内容
    Backend-->>Frontend: 显示剧本
    
    User->>Frontend: 确认剧本生成分镜
    Frontend->>Backend: 生成分镜
    Backend->>AI: 调用图像生成
    AI-->>Backend: 返回图像
    Backend-->>Frontend: 显示分镜
    
    User->>Frontend: 确认分镜生成视频
    Frontend->>Backend: 生成视频
    Backend->>AI: 调用视频生成
    AI-->>Backend: 返回视频
    Backend-->>Frontend: 显示视频预览
    
    User->>Frontend: 导出短剧
    Frontend->>Backend: 处理导出
    Backend-->>Frontend: 返回下载链接
    Frontend-->>User: 提供视频下载

8.2 关键业务流程

1. 小说上传与分析流程

用户上传小说文本文件
系统解析文本内容
调用 AI 服务识别角色和关键事件
生成角色设定和章节摘要
展示分析结果给用户

2. 剧本生成流程

用户选择小说章节或事件
系统生成剧本提示词
调用大语言模型 API 生成剧本
格式化和优化剧本内容
展示剧本给用户编辑

3. 分镜设计流程

用户确认剧本内容
系统分析剧本场景
为每个场景生成分镜提示词
调用图像生成 API 生成场景图像
展示分镜给用户调整

4. 视频生成流程

用户确认分镜内容
系统为每个分镜生成视频提示词
调用视频生成 API 生成视频片段
合成完整的短剧视频
展示视频预览给用户

9. 技术栈与依赖

类别	技术/库	用途	版本要求
运行环境	Node.js	后端运行环境	23.11.1+
包管理	Yarn	依赖管理	最新版
前端框架	待确认	用户界面	待确认
后端框架	待确认	API 服务	待确认
数据库	待确认	数据存储	待确认
AI 服务	大语言模型 API	文本处理和剧本生成	待确认
AI 服务	Nano Banana Pro	图像生成	待确认
AI 服务	Sora/豆包视频 API	视频生成	待确认
工具库	axios	HTTP 请求	待确认
工具库	lodash	工具函数	待确认
部署工具	PM2	进程管理	待确认

10. 配置管理

10.1 配置文件

Toonflow 可能使用以下配置文件：

config/config.js

module.exports = {
  // 服务器配置
  server: {
    port: 60000,
    host: '0.0.0.0'
  },
  
  // AI 服务配置
  ai: {
    llm: {
      apiUrl: 'YOUR_LLM_API_URL',
      apiKey: 'YOUR_LLM_API_KEY'
    },
    image: {
      apiUrl: 'YOUR_IMAGE_API_URL',
      apiKey: 'YOUR_IMAGE_API_KEY'
    },
    video: {
      apiUrl: 'YOUR_VIDEO_API_URL',
      apiKey: 'YOUR_VIDEO_API_KEY'
    }
  },
  
  // 存储配置
  storage: {
    local: {
      path: './storage'
    },
    oss: {
      url: 'http://127.0.0.1:60000/'
    }
  },
  
  // 安全配置
  security: {
    jwt: {
      secret: 'YOUR_JWT_SECRET'
    }
  }
};

10.2 环境变量

环境变量	描述	默认值
NODE_ENV	运行环境	prod
PORT	服务端口	60000
OSSURL	文件存储访问地址	http://127.0.0.1:60000/
LLM_API_URL	大语言模型 API 地址	无
LLM_API_KEY	大语言模型 API Key	无
IMAGE_API_URL	图像生成 API 地址	无
IMAGE_API_KEY	图像生成 API Key	无
VIDEO_API_URL	视频生成 API 地址	无
VIDEO_API_KEY	视频生成 API Key	无

11. 部署与运行

11.1 本地部署（Windows）

下载 Windows 安装包
运行安装程序
启动 Toonflow 应用
首次登录使用默认账号密码：admin / admin123
配置 AI 服务 API 地址
开始使用

11.2 云端部署

服务器环境要求：

Ubuntu 20.04+ / CentOS 7+
Node.js 23.11.1+
内存：1GB+

部署步骤：

安装环境

# 安装 Node.js
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
source ~/.bashrc
nvm install 24
# 安装 Yarn 和 PM2
npm install -g yarn pm2

部署项目

cd /opt
git clone https://gitee.com/HBAI-Ltd/Toonflow-app.git
cd Toonflow-app
yarn install
yarn build

配置 PM2
创建 pm2.json 文件：

{
  "name": "toonflow-app",
  "script": "build/app.js",
  "instances": "max",
  "exec_mode": "cluster",
  "env": {
    "NODE_ENV": "prod",
    "PORT": 60000,
    "OSSURL": "http://127.0.0.1:60000/"
  }
}

启动服务

pm2 start pm2.json
pm2 startup
pm2 save

常用命令

pm2 list              # 查看进程
pm2 logs toonflow-app # 查看日志
pm2 restart all       # 重启服务
pm2 monit             # 监控面板

12. 监控与维护

12.1 日志管理

Toonflow 使用 PM2 进行进程管理，日志存储在 PM2 的日志目录中。可以通过以下命令查看日志：

pm2 logs toonflow-app

12.2 常见问题与解决方案

问题	可能原因	解决方案
AI 服务调用失败	API Key 错误或网络问题	检查 API 配置和网络连接
视频生成超时	视频长度过长或服务繁忙	减少视频长度或重试
图像质量不佳	提示词不够详细	优化提示词或调整参数
服务启动失败	端口被占用	修改配置文件中的端口
内存使用过高	处理大型项目	增加服务器内存或优化项目大小

12.3 性能优化建议

AI 服务调用优化
- 使用批量调用减少 API 请求次数
- 缓存常见请求的结果
- 优化提示词以获得更好的结果
存储优化
- 使用对象存储服务存储生成的图像和视频
- 实现自动清理机制，删除临时文件
- 压缩存储的媒体文件
代码优化
- 使用异步编程提高并发处理能力
- 优化循环和算法复杂度
- 实现请求限流和队列机制

13. 安全考虑

13.1 安全风险

风险	影响	防范措施
API Key 泄露	服务被滥用，产生费用	环境变量存储，限制 API 权限
用户数据泄露	个人信息和项目内容泄露	加密存储，访问控制
服务滥用	资源耗尽，影响其他用户	请求限流，用户配额
注入攻击	系统被恶意代码攻击	输入验证，参数过滤
DDoS 攻击	服务不可用	流量过滤，负载均衡

13.2 安全最佳实践

API 安全
- 使用 HTTPS 加密传输
- 实现 API 密钥管理和轮换
- 限制 API 调用频率和总量
数据安全
- 加密存储敏感信息
- 实现数据备份和恢复机制
- 定期清理不必要的数据
访问控制
- 实现基于角色的权限管理
- 限制敏感操作的访问
- 记录关键操作的审计日志
代码安全
- 定期进行代码审计
- 使用安全的依赖库
- 实现输入验证和参数过滤

14. 未来发展

14.1 功能扩展

多语言支持：扩展支持更多语言的小说和剧本
自定义 AI 模型：允许用户集成自己的 AI 模型
高级编辑工具：提供更强大的剧本和分镜编辑功能
协作功能：支持多人协作创作短剧
模板系统：提供预设的风格和模板

14.2 技术升级

性能优化：进一步优化 AI 调用和视频处理性能
扩展性：改进系统架构，支持水平扩展
容器化：提供 Docker 部署方案
CI/CD：实现持续集成和部署
监控系统：增强系统监控和告警能力

14.3 生态系统

插件系统：支持第三方插件扩展功能
API 开放：提供开放 API，支持与其他系统集成
社区平台：建立用户社区，分享创作和模板
** marketplace**：创建素材和模板市场
教育资源：提供教程和学习资源

15. 总结

Toonflow 是一款创新性的 AI 短剧创作工具，通过整合多种 AI 技术，实现了从小说到短剧的全流程自动化。其核心价值在于大幅降低了短剧创作的门槛和成本，使更多人能够参与到短剧创作中来。

15.1 技术优势

全流程自动化：从文本分析到视频合成的完整 AI 驱动流程
多 AI 服务集成：整合大语言模型、图像生成和视频生成技术
用户友好界面：直观的操作界面，降低使用门槛
灵活的部署选项：支持本地和云端部署
可扩展性：模块化设计，易于功能扩展

15.2 应用价值

内容创作：为短视频平台提供高质量内容
小说改编：为小说提供影视化的可能性
教育娱乐：用于教育内容和娱乐产品的制作
创意表达：为创作者提供新的表达方式
产业升级：推动短剧制作产业的智能化升级

Toonflow 代表了 AI 技术在内容创作领域的重要应用，通过将复杂的短剧制作流程自动化，为行业带来了新的可能性。随着 AI 技术的不断发展，Toonflow 也有望在未来推出更多创新功能，进一步推动短剧创作的智能化和普及化。

附录 A: 项目配置模板

pm2.json 配置模板

{
  "name": "toonflow-app",
  "script": "build/app.js",
  "instances": "max",
  "exec_mode": "cluster",
  "env": {
    "NODE_ENV": "prod",
    "PORT": 60000,
    "OSSURL": "http://127.0.0.1:60000/",
    "LLM_API_URL": "YOUR_LLM_API_URL",
    "LLM_API_KEY": "YOUR_LLM_API_KEY",
    "IMAGE_API_URL": "YOUR_IMAGE_API_URL",
    "IMAGE_API_KEY": "YOUR_IMAGE_API_KEY",
    "VIDEO_API_URL": "YOUR_VIDEO_API_URL",
    "VIDEO_API_KEY": "YOUR_VIDEO_API_KEY"
  }
}

环境变量配置模板

# .env 文件
NODE_ENV=prod
PORT=60000
OSSURL=http://127.0.0.1:60000/
LLM_API_URL=YOUR_LLM_API_URL
LLM_API_KEY=YOUR_LLM_API_KEY
IMAGE_API_URL=YOUR_IMAGE_API_URL
IMAGE_API_KEY=YOUR_IMAGE_API_KEY
VIDEO_API_URL=YOUR_VIDEO_API_URL
VIDEO_API_KEY=YOUR_VIDEO_API_KEY

附录 B: 核心 API 参考

小说相关 API

API	方法	描述	参数
/api/novel/upload	POST	上传小说	file: 文件
/api/novel/analyze	POST	分析小说	novelId: 小说 ID
/api/novel/list	GET	获取小说列表	N/A
/api/novel/detail	GET	获取小说详情	novelId: 小说 ID
/api/novel/delete	DELETE	删除小说	novelId: 小说 ID

剧本相关 API

API	方法	描述	参数
/api/script/generate	POST	生成剧本	novelId: 小说 ID, chapterId: 章节 ID
/api/script/edit	PUT	编辑剧本	scriptId: 剧本 ID, content: 剧本内容
/api/script/list	GET	获取剧本列表	novelId: 小说 ID
/api/script/detail	GET	获取剧本详情	scriptId: 剧本 ID

分镜相关 API

API	方法	描述	参数
/api/storyboard/generate	POST	生成分镜	scriptId: 剧本 ID
/api/storyboard/edit	PUT	编辑分镜	storyboardId: 分镜 ID, frames: 分镜帧
/api/storyboard/detail	GET	获取分镜详情	storyboardId: 分镜 ID

图像相关 API

API	方法	描述	参数
/api/image/generate	POST	生成图像	prompt: 提示词, type: 图像类型
/api/image/edit	PUT	编辑图像	imageId: 图像 ID, params: 编辑参数
/api/image/list	GET	获取图像列表	storyboardId: 分镜 ID

视频相关 API

API	方法	描述	参数
/api/video/generate	POST	生成视频	storyboardId: 分镜 ID
/api/video/edit	PUT	编辑视频	videoId: 视频 ID, params: 编辑参数
/api/video/detail	GET	获取视频详情	videoId: 视频 ID
/api/video/export	GET	导出视频	videoId: 视频 ID

项目相关 API

API	方法	描述	参数
/api/project/create	POST	创建项目	title: 标题, description: 描述
/api/project/update	PUT	更新项目	projectId: 项目 ID, params: 更新参数
/api/project/list	GET	获取项目列表	N/A
/api/project/detail	GET	获取项目详情	projectId: 项目 ID
/api/project/delete	DELETE	删除项目	projectId: 项目 ID

用户相关 API

API	方法	描述	参数
/api/auth/login	POST	用户登录	username: 用户名, password: 密码
/api/auth/logout	POST	用户登出	N/A
/api/auth/register	POST	用户注册	username: 用户名, password: 密码, email: 邮箱
/api/auth/profile	GET	获取用户资料	N/A
/api/auth/profile	PUT	更新用户资料	params: 用户资料

附录 C: 术语表

术语	解释
LLM	大语言模型，如 GPT、Claude 等，用于文本生成和理解
NLP	自然语言处理，处理和分析人类语言的技术
API	应用程序接口，不同软件系统之间的交互接口
分镜	电影或动画制作中的镜头设计，描述每个镜头的内容和构图
提示词	给 AI 模型的指令，指导其生成特定内容
Nano Banana Pro	一种图像生成模型，用于生成角色和场景图像
Sora	OpenAI 开发的视频生成模型
PM2	Node.js 应用的进程管理工具
Node.js	基于 Chrome V8 引擎的 JavaScript 运行时
TypeScript	JavaScript 的超集，添加了类型系统
Yarn	JavaScript 包管理工具

附录 D: 参考资料

Toonflow 官方仓库：https://gitee.com/HBAI-Ltd/Toonflow-app
Node.js 官方文档：https://nodejs.org/en/docs/
PM2 官方文档：https://pm2.keymetrics.io/docs/
AI 模型 API 文档：
- 大语言模型 API 文档
- Nano Banana Pro API 文档
- Sora/豆包视频 API 文档
短剧制作指南：相关影视制作教程和资源

文档版本：2.0
最后更新：2026-02-08
基于：Toonflow-app 项目
作者：架构师AI杜

本文档基于项目公开信息和常见架构模式分析生成，具体实现可能有所不同。实际开发中请参考项目源码和官方文档。