<p>
  <a href="https://github.com/HBAI-Ltd/Toonflow-app">
    <img src="https://img.shields.io/badge/GitHub-181717?style=flat-square&logo=github&logoColor=white" alt="GitHub" />
  </a>
  &nbsp;|&nbsp;
  <a href="https://gitee.com/HBAI-Ltd/Toonflow-app">
    <img src="https://img.shields.io/badge/Gitee-C71D23?style=flat-square&logo=gitee&logoColor=white" alt="Gitee" />
  </a>
  &nbsp;|&nbsp;
  <a href="https://gitcode.com/HBAI-Ltd/Toonflow-app">
    <img src="./atomgitLogo.png" alt="Atomgit" style="height:16px"/>
    Atomgit
  </a>
</p>

<p align="center">
  <a href="../README.md">简体中文</a> | 
  <strong>繁體中文</strong> | 
  <a href="./README.en.md">English</a> | 
  <a href="./README.en.md">ไทย</a> | 
  <a href="./README.en.md">Tiếng Việt</a> | 
  <a href="./README.en.md">日本語</a> | 
  <a href="./README.en.md">Русский</a>
</p>

<div align="center">

<img src="./logo.png" alt="Toonflow Logo" height="120"/>

# Toonflow

  <p align="center">
    <b>
      AI短劇工廠
      <br />
      一鍵點擊，小說秒變短劇！
      <br />
      AI劇本 × AI視覺 × 渦輪生成 🔥
    </b>
  </p>
  <p align="center">
    <a href="https://github.com/HBAI-Ltd/Toonflow-app/stargazers">
      <img src="https://img.shields.io/github/stars/HBAI-Ltd/Toonflow-app?style=for-the-badge&logo=github" alt="Stars Badge" />
    </a>
    <a href="https://www.apache.org/licenses/LICENSE-2.0" target="_blank">
      <img src="https://img.shields.io/badge/License-Apache%202.0-blue.svg?style=for-the-badge" alt="Apache-2.0 License Badge" />
    </a>
    <a href="https://github.com/HBAI-Ltd/Toonflow-app/releases">
      <img alt="release" src="https://img.shields.io/github/v/release/HBAI-Ltd/Toonflow-app?style=for-the-badge" />
    </a>
  </p>
  
  > 🚀 **一站式短劇生產**：從文本到人物、從分鏡到影片，零門檻全流程AI，10倍以上創作效率！
</div>

---

# 🌟 主要功能

Toonflow 是一款AI短劇漫畫工具，利用AI自動將小說轉換為劇本，並用AI生成圖片、視頻，助力高效短劇製作。有了Toonflow，您可輕鬆完成從文本到圖片的全流程操作，讓短劇製作更智能、更便捷。

- ✅ **人物生成**  
  自動解析原小說文本，智能識別並生成人物設定，包括外貌、性格、身份等，為後續劇本和視覺創作提供穩固基礎。
- ✅ **劇本生成**  
  根據所選事件和章節，系統自動生成結構化劇本，涵蓋對話、場景描述、劇情走向，實現文學文本向影視劇本高效轉化。
- ✅ **分鏡製作**  
  根據劇本內容，智能生成分鏡提示與視覺設計，細化前景/中景/背景、人物動態、道具設定與場景佈局，自動將劇本轉換為分鏡，為影片製作提供完整藍圖。
- ✅ **影片合成**  
  集成AI圖像與視頻技術，通過AI生成視頻片段，支持線上編輯與個性化輸出調整，讓影視製作協同高效。

---

# 📦 應用場景

- 短視頻內容創作
- 小說改編影視實驗
- AI文學改編工具
- 劇本開發與快速原型
- 影片素材生成

---

# 🔰 用戶指南

## 📺 視頻教程

https://www.bilibili.com/video/BV1na6wB6Ea2
[![Toonflow 8分鐘快速上手AI視頻](./videoCover.png)](https://www.bilibili.com/video/BV1na6wB6Ea2)

**Toonflow 8分鐘快速上手AI視頻**
👉 [點此觀看](https://www.bilibili.com/video/BV1na6wB6Ea2/?share_source=copy_web&vd_source=5b718c25439a901a34c7bc0c1d35b38e)

📱 用手機微信掃碼觀看

<img src="./videoQR.png" alt="Scan WeChat to Watch" width="150"/>

---

# 🚀 安裝方法

## 前置準備

安裝與使用前請準備以下內容：

- ✅ 大語言模型AI服務API地址
- ✅ Sora或豆包視頻服務API地址
- ✅ Nano Banana Pro圖像生成模型API

## 本地安裝

### 1. 下載安裝

| 作業系統      | GitHub下載                                               | Quark雲下載                                    | 備註           |
| :------------: | :------------------------------------------------------ | :---------------------------------------------- | :------------- |
| Windows         | [釋出版](https://github.com/HBAI-Ltd/Toonflow-app/releases) | [Quark雲](https://pan.quark.cn/s/94ef07509df0)  | 官方安裝包      |
|  Linux          | [釋出版](https://github.com/HBAI-Ltd/Toonflow-app/releases) | [Quark雲](https://pan.quark.cn/s/94ef07509df0)  | 官方安裝包      |
|  macOS          | [釋出版](https://github.com/HBAI-Ltd/Toonflow-app/releases) | [Quark雲](https://pan.quark.cn/s/94ef07509df0)  | 官方安裝包      |

> [!CAUTION]
> MacOS上需進入設定–隱私安全配置安全設定，否則可能因憑證問題無法打開應用。
>
> 參考知乎文檔：[https://www.zhihu.com/question/433389276](https://www.zhihu.com/question/433389276)

> 受Gitee作業系統環境與釋出檔案大小限制，目前Gitee釋出下載暫不開放。

### 2. 啟動服務

安裝完成後，啟動程式即可開始使用本服務。

> ⚠️ **首次登入**  
> 用戶名：`admin`  
> 密碼：`admin123`

## Docker部署

### 前置準備

- 已安裝 [Docker](https://docs.docker.com/get-docker/)（20.10+）

### 方法一：線上部署

待開發，現請使用本地構建。

### 方法二：本地構建

適用於開發者或已克隆源碼的用戶，需本地安裝Git：

```shell
# 克隆專案（已克隆則略過）
git clone https://github.com/HBAI-Ltd/Toonflow-app.git
cd Toonflow-app

# 用docker-compose本地構建啟動
yarn docker:local

# 或手動構建
docker build -t toonflow .
docker run -d -p <local_port>:10588 -v <local_data_path>:/app/data toonflow

# 完成後可通過映射端口/web/index.html訪問
# 如 http://localhost:10588/web/index.html
```

### 服務端口說明

| 端口     | 用途         | 部署映射             |
| -------- |------------| -------------------- |
| `10588`  | 應用介面    | `10588:10588`        |

**環境變數說明：**

| 變數           | 說明                                       |
| -------------- | ------------------------------------------ |
| `NODE_ENV`     | 環境，生產用`prod`                          |
| `PORT`         | 服務監聽端口（預設10588）                   |
| `OSSURL`       | 靜態檔案存取地址                            |

---

## 雲端部署

### 1. 伺服器需求

- **作業系統：** Ubuntu 20.04+ / CentOS 7+
- **Node.js：** 24.x（推薦，最低23.11.1+）
- **記憶體：** 2GB+

### 2. 伺服器部署

#### 1. 安裝環境

```bash
# 安裝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
```

#### 2. 專案部署

**GitHub克隆：**

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

**Gitee克隆（中國大陸推薦）：**

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

#### 3. 配置PM2

新建`pm2.json`：

```json
{
  "name": "toonflow-app",
  "script": "data/serve/app.js",
  "instances": "max",
  "exec_mode": "cluster",
  "env": {
    "NODE_ENV": "prod",
    "PORT": 10588,
    "OSSURL": "http://127.0.0.1:10588/"
  }
}
```

**環境變數說明：**

| 變數           | 說明                                       |
| -------------- | ------------------------------------------ |
| `NODE_ENV`     | 環境，生產用`prod`                          |
| `PORT`         | 服務監聽端口                               |
| `OSSURL`       | 靜態檔案存取地址                            |

---

#### 4. 啟動服務

```bash
pm2 start pm2.json
pm2 startup
pm2 save
```

#### 5. 常用命令

```bash
pm2 list              # 查看進程列表
pm2 logs toonflow-app # 查看日誌
pm2 restart all       # 重啟服務
pm2 monit             # 監控面板
```

> ⚠️ **首次登入**  
> 用戶名：`admin`  
> 密碼：`admin123`

#### 6. 前端網站部署

若需單獨部署前端或自定義，參見前端專案：

- **GitHub**: [Toonflow-web](https://github.com/HBAI-Ltd/Toonflow-web)
- **Gitee**: [Toonflow-web](https://gitee.com/HBAI-Ltd/Toonflow-web)

> 💡 **注意：** 本專案已預設內建前端，普通用戶無需單獨部署。前端源碼主要供開發者二次開發使用。

---

# 🔧 開發指南

> [!CAUTION]
> 🚧 **PR提交規範** 🚧
>
> ⛔ `master`分支不接受PR | ✅ 請提交至`develop`分支
>
> 歡迎開發者協同合作，共同開發Toonflow。欲加入請聯繫owner ACT入群。

## 🛠️ 技術棧

| 分類        | 技術                                                                                    |
| ----------- | -------------------------------------------------------------------------------------- |
| 運行環境    | Node.js 23.11.1+                                                                       |
| 語言        | TypeScript 5.x                                                                         |
| 後端        | Express 5                                                                              |
| 資料庫      | SQLite（better-sqlite3 / knex）                                                        |
| AI接入      | Vercel AI SDK（OpenAI / Anthropic / Google / DeepSeek / 智譜 / MiniMax / Qwen / xAI）|
| 本地推理    | @huggingface/transformers（ONNX）                                                      |
| 實時通信    | Socket.IO                                                                              |
| 桌面端      | Electron 40                                                                            |
| 影像處理    | Sharp                                                                                  |
| 容器化      | Docker                                                                                 |

## 開發環境準備

- **Node.js**：需23.11.1以上版本
- **Yarn**：推薦作為包管理器

## 快速上手

1. **克隆專案**

   **GitHub克隆：**

   ```bash
   git clone https://github.com/HBAI-Ltd/Toonflow-app.git
   cd Toonflow-app
   ```

   **Gitee克隆（大陸推薦）：**

   ```bash
   git clone https://gitee.com/HBAI-Ltd/Toonflow-app.git
   cd Toonflow-app
   ```

2. **安裝依賴**

   在專案根目錄執行：

   ```bash
   yarn install
   ```

3. **啟動開發環境**

   本專案包含 **後端API服務** 和 **前端介面**，按需啟動：

   - **方案1：僅啟動後端服務**

     ```bash
     yarn dev
     ```

     > ⚠️ 此命令僅啟動後端API（10588端口），沒有Web介面。僅可存取API，完整UI需啟動前端專案或用下述GUI模式。

   - **方案2：啟動Electron桌面客戶端**

     ```bash
     yarn dev:gui
     ```

     > 此命令即啟動後端又開Electron視窗，內建Web UI。開箱即用，體驗完整。

   - **方案3：生產模式啟動**

     ```bash
     yarn start
     ```

     > 編譯後以生產模式運行（需先執行`yarn build`）。

4. **構建專案**

   - 編譯TypeScript：

     ```bash
     yarn build
     ```

   - Windows可執行檔打包：

     ```bash
     yarn dist:win
     ```

   - Mac打包：

     ```bash
     yarn dist:mac
     ```

   - Linux打包：

     ```bash
     yarn dist:linux
     ```

5. **代碼質量檢查**

   - 執行Lint：

     ```bash
     yarn lint
     ```

6. **AI調試面板（可選）**

   啟動Vercel AI SDK可視化調試工具，便於AI對接調測：

   ```bash
   yarn debug:ai
   ```

## 前端開發

需修改前端UI，請於專用前端專案開發：

- **GitHub**: [Toonflow-web](https://github.com/HBAI-Ltd/Toonflow-web)
- **Gitee**: [Toonflow-web](https://gitee.com/HBAI-Ltd/Toonflow-web)

前端打包後將`dist`內容複製至本專案`data/web`即可集成。

## 專案結構

```
📂 build/                    # 編譯產物
📂 data/                     # 運行時資料
│  ├─ 📂 models/            # 本地推理模型（ONNX）
│  ├─ 📂 oss/               # 物件儲存（素材/角色/場景）
│  ├─ 📂 serve/             # 生產模式入口
│  ├─ 📂 skills/            # Agent技能提示
│  └─ 📂 web/               # 前端資產
📂 ./                     # 文檔資產
📂 env/                      # 環境配置
📂 scripts/                  # 構建與輔助腳本
📂 src/
├─ 📂 agents/               # AI Agent模組
│  ├─ 📂 productionAgent/   # 製作Agent
│  └─ 📂 scriptAgent/       # 劇本Agent
├─ 📂 lib/                  # 通用庫（資料庫、響應）
├─ 📂 middleware/           # 中間件
├─ 📂 routes/               # API路由
│  ├─ 📂 agents/            # Agent記憶管理
│  ├─ 📂 artStyle/          # 美術風格管理
│  ├─ 📂 assets/            # 素材管理
│  ├─ 📂 assetsGenerate/    # 素材生成
│  ├─ 📂 cornerScape/       # 分鏡管理
│  ├─ 📂 general/           # 通用API
│  ├─ 📂 login/             # 認證
│  ├─ 📂 migrate/           # 資料遷移
│  ├─ 📂 modelSelect/       # 模型選擇
│  ├─ 📂 novel/             # 小說管理
│  ├─ 📂 other/             # 其他功能
│  ├─ 📂 production/        # 製作管理
│  ├─ 📂 project/           # 專案管理
│  ├─ 📂 script/            # 劇本生成
│  ├─ 📂 scriptAgent/       # 劇本Agent API
│  ├─ 📂 setting/           # 系統設定
│  ├─ 📂 task/              # 任務管理
│  └─ 📂 test/              # 測試API
├─ 📂 socket/               # WebSocket通訊
├─ 📂 types/                # TypeScript型別
├─ 📂 utils/                # 工具函式
├─ 📄 app.ts                # 應用入口
├─ 📄 core.ts               # 核心初始化
├─ 📄 env.ts                # 環境變數
├─ 📄 err.ts                # 錯誤處理
├─ 📄 logger.ts             # 日誌模組
├─ 📄 router.ts             # 路由註冊
└─ 📄 utils.ts              # 通用工具
📄 Dockerfile                # Docker構建
📄 electron-builder.yml      # Electron打包配置
📄 skillList.json            # 技能列表
📄 LICENSE                   # (Apache-2.0) 授權
📄 NOTICES.txt               # 第三方依賴
📄 package.json              # 專案配置
📄 tsconfig.json             # TypeScript配置
```

---

# 🔗 相關倉庫

| 倉庫           | 說明                        | GitHub                                            | Gitee                                              |
| -------------- | -------------------------- | ------------------------------------------------- | -------------------------------------------------- |
| **Toonflow-app** | 完整客戶端（本倉庫，供用戶） | [GitHub](https://github.com/HBAI-Ltd/Toonflow-app)| [Gitee](https://gitee.com/HBAI-Ltd/Toonflow-app)   |
| **Toonflow-web** | 前端源碼（前端開發者用）     | [GitHub](https://github.com/HBAI-Ltd/Toonflow-web)| [Gitee](https://gitee.com/HBAI-Ltd/Toonflow-web)   |

> 💡 **提醒：** 若僅需使用Toonflow，直接下載本倉庫客戶端即可。前端源碼僅供需二次開發或UI自訂者使用。

---

# 👨‍👩‍👧‍👦 微信交流群

~~群1~~

~~群2~~

...

~~群10~~

~~群11~~

~~群12~~

~~群13~~

...

~~群24~~

群助手：

<img src="./QR.png" alt="Toonflow QR" height="400"/>

---

# 💌 聯繫我們

📧 郵箱：[ltlctools@outlook.com](mailto:ltlctools@outlook.com?subject=Toonflow inquiry)

---

# 📜 開源協議

Toonflow 基於 Apache-2.0 協議開源發布，並附有補充商業協議。

授權詳情：https://www.apache.org/licenses/LICENSE-2.0

## 補充協議

- 若將本軟體以產品形式分發給 **2 個及以上獨立第三方**使用，須取得 HBAI-Ltd **書面商業授權**。
- **≤ 5 個法人**聯合運營內部使用，不對外提供服務的，視為內部使用，**無需授權**。
- 不得刪除或修改 Toonflow 中的標識或版權資訊。

## 永久免費場景

- ✅ 用 Toonflow 製作內容並獲得平台分帳
- ✅ 二次開發供自己團隊內部使用
- ✅ ≤ 5 個法人聯合運營內部使用
- ✅ 個人學習、研究、非商業用途

## 商業授權定價

| 階段 | 年銷售額 | 年費 |
|------|---------|------|
| 🌱 扶持期 | < ¥10 萬 | **免費** |
| 🚀 初創期 | ¥10–50 萬 | ¥5,000/年 |
| 📈 成長期 | ¥50–150 萬 | ¥20,000/年 |
| 🏢 規模期 | ¥150–500 萬 | ¥80,000/年 |
| 🌐 企業級 | > ¥500 萬 | 面議 |

> **不追溯條款**：v1.0.8 發布前基於 AGPL-3.0 使用的用戶，繼續按 AGPL-3.0 執行，不受本協議變更約束。

完整協議詳見 [LICENSE](../LICENSE) 檔案。

---

# ⭐️ Star 歷史

[![Star History Chart](https://api.star-history.com/svg?repos=HBAI-Ltd/Toonflow-app&type=timeline&legend=top-left)](https://www.star-history.com/#HBAI-Ltd/Toonflow-app&type=timeline&legend=top-left)

---

# 🙏 感謝

感謝以下開源專案對Toonflow的支持：

- [Express](https://expressjs.com/) - 快速、開放、極簡的Node.js Web框架
- [AI SDK](https://ai-sdk.dev/) - TypeScript優先的AI工具包
- [Better-SQLite3](https://github.com/WiseLibs/better-sqlite3) - 高效能SQLite3綁定
- [Sharp](https://sharp.pixelplumbing.com/) - Node.js高性能影像工具
- [Axios](https://axios-http.com/) - Promise的HTTP用戶端
- [Zod](https://zod.dev/) - TypeScript優先的型別驗證庫
- [Socket.IO](https://socket.io/) - 實時雙向事件框架
- [Electron](https://www.electronjs.org/) - 跨平台桌面應用框架
- [Hugging Face Transformers](https://huggingface.co./transformers.js) - 本地ML推理庫

感謝以下組織/個人的支持：

<table>
  <tr>
    <td>
      <img src="./sponsored/sophnet.png" alt="SophNet Logo" width="48">
    </td>
    <td>
      <b>SophNet Cloud</b> 提供算力贊助
      <a href="https://www.sophnet.com/">[官方網站]</a>
    </td>
  </tr>
</table>

完整第三方依賴列表請見 `NOTICES.txt`