<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.svg" alt="Atomgit" style="height:20px"/>
  </a>
</p>

<p align="center">
  <a href="./README.md">简体中文</a> | 
  <strong>繁體中文</strong> | 
  <a href="./README.en.md">English</a> | 
  <a href="./README.th.md">ไทย</a> | 
  <a href="./README.vi.md">Tiếng Việt</a> | 
  <a href="./README.ja.md">日本語</a> | 
  <a href="./README.ru.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>
  
  > 🚀 **一站式短劇工程**：從文字到角色，從分鏡到影片，0 門檻全流程 AI 化，創作效率提升 10 倍+！
</div>

---

# 🌐 多語言支援

Toonflow 支援以下語言介面：

| 語言         | Language                  |
|--------------|---------------------------|
| 简体中文     | Chinese (Simplified)      |
| 繁體中文     | Chinese (Traditional)     |
| English      | English                   |
| ไทย          | Thai                      |
| Tiếng Việt   | Vietnamese                |
| 日本語        | Japanese                  |
| Русский      | Russian                   |

> 💡 更多語言正在適配中，歡迎貢獻翻譯！

---

# 🌟 主要功能

Toonflow 是一款 AI 短劇與漫畫創作工具，能夠利用 AI 技術將小說自動轉化為劇本，並結合 AI 生成的圖像與影片，高效完成短劇製作。透過 Toonflow，您可以輕鬆完成從文字到最終影片的全流程，讓短劇創作變得更加智能與便捷。

- ✅ **角色生成**  
  自動分析原始小說文本，智能識別並建立角色設定，包含外貌、性格、身份等詳細資訊，為後續劇本與畫面創作提供堅實基礎。

- ✅ **劇本生成**  
  根據選定的事件與章節，系統自動產生結構清晰的劇本，包含自然對白、場景描述與劇情發展，高效將文學作品轉化為影視劇本。

- ✅ **分鏡製作 (Storyboard)**  
  根據劇本自動生成分鏡提示詞與畫面設計，細化前、中、後景、角色動作、道具與場景佈局，為影片製作提供完整的藍圖。

- ✅ **影片合成**  
  整合 AI 圖像與影片生成技術，可產生高品質影片片段。內建線上剪輯功能，支援個人化調整，讓創作過程更順暢快速。

---

# 📦 應用場景

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

---

# 🔰 使用指南

## 📺 影片教學

[https://www.bilibili.com/video/BV1oXD7BqEqJ](https://www.bilibili.com/video/BV1oXD7BqEqJ)
[![Toonflow 12 分鐘快速上手 AI 影片](./videoCover.jpg)](https://www.bilibili.com/video/BV1oXD7BqEqJ)

**Toonflow 12 分鐘快速上手 AI 影片**
👉 [點擊觀看](https://www.bilibili.com/video/BV1oXD7BqEqJ/?share_source=copy_web&vd_source=5b718c25439a901a34c7bc0c1d35b38e)

📱 使用手機掃描 QR Code 觀看

<img src="./videoQR.png" alt="掃描 QR Code 觀看" width="150"/>

---

# 🚀 安裝

## 前置條件

安裝並使用本軟體前，請先準備以下項目：

- ✅ 大型語言模型 (LLM) 的 API 網址
- ✅ Sora 或豆包影片生成服務的 API 網址
- ✅ Nano Banana Pro 圖像生成模型的 API 網址

## 本機安裝

### 1. 下載與安裝

| 作業系統 | GitHub                                                     | Atomgit                                                       | 夸克網碟下載                                    | 說明           |
| :------: | :----------------------------------------------------------- | :------------------------------------------------------------ | :---------------------------------------------- | :------------- |
| Windows  | [Release](https://github.com/HBAI-Ltd/Toonflow-app/releases) | [Release](https://gitcode.com/HBAI-Ltd/Toonflow-app/releases) | [夸克網碟](https://pan.quark.cn/s/94ef07509df0) | 官方發佈安裝包 |
|  Linux   | [Release](https://github.com/HBAI-Ltd/Toonflow-app/releases) | [Release](https://gitcode.com/HBAI-Ltd/Toonflow-app/releases) | [夸克網碟](https://pan.quark.cn/s/94ef07509df0) | 官方發佈安裝包 |
|  macOS   | [Release](https://github.com/HBAI-Ltd/Toonflow-app/releases) | [Release](https://gitcode.com/HBAI-Ltd/Toonflow-app/releases) | [夸克網碟](https://pan.quark.cn/s/94ef07509df0) | 官方發佈安裝包 |

> [!CAUTION]
> MacOS 系統請至「系統設定」-「隱私權與安全性」設定安全性，否則可能因憑證問題無法正常開啟。
>
> 參考知乎教學：[https://www.zhihu.com/question/433389276](https://www.zhihu.com/question/433389276)

> 因 Gitee OS 環境限制及 Release 檔案上傳大小限制，暫不提供 Gitee Release 下載連結。

### 2. 啟動服務

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

> ⚠️ **首次登入** 
> 帳號：`admin`  
> 密碼：`admin123`

## Docker 部署

### 前置條件

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

### 方式一：線上部署

待完善，暫時使用本機建置。

### 方式二：本機建置

使用本機已有的原始碼直接建置，適合開發者或已 Clone 儲存庫的使用者，這需要您在本機安裝 git：

```shell
# 先 Clone 專案（若已有則跳過）
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 <本機 Port>:10588 -v <本機資料路徑>:/app/data toonflow

# 此時在相應 Port 的 /web/index.html 路徑即可存取頁面
# 例如 http://localhost:10588/web/index.html
```

### 服務 Port 說明

| Port    | 用途     | 部署對應      |
| ------- | -------- | ------------- |
| `10588` | 軟體介面 | `10588:10588` |

**環境變數說明：**

| 變數       | 說明                               |
| ---------- | ---------------------------------- |
| `NODE_ENV` | 執行環境，`prod` 表示正式環境      |
| `PORT`     | 服務監聽 Port（預設 10588）        |
| `OSSURL`   | 檔案儲存存取網址，用於靜態資源存取 |

---

## ☁️ 雲端部署

### 一、伺服器環境要求

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

### 二、伺服器部署

#### 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 Clone：**

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

**從 Gitee Clone（內地網路使用）：**

```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`     | 服務監聽 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 ｜ ✅ 請將 PR 提交到 `develop` 分支
>
> 歡迎開發者們共同參與 Toonflow 的共創。如有興趣加入，請在交流群內聯絡主理人 ACT

## 🛠️ 技術堆疊

| 類別       | 技術                                                                                      |
| ---------- | ----------------------------------------------------------------------------------------- |
| 執行環境   | Node.js 23.11.1+                                                                          |
| 語言       | TypeScript 5.x                                                                            |
| 後端框架   | Express 5                                                                                 |
| 資料庫     | SQLite（better-sqlite3 / knex）                                                           |
| AI 整合    | Vercel AI SDK（OpenAI / Anthropic / Google / DeepSeek / 智譜 / MiniMax / 通義千問 / xAI） |
| 本機推論   | @huggingface/transformers（ONNX）                                                         |
| 即時通訊   | Socket.IO                                                                                 |
| 桌面用戶端 | Electron 40                                                                               |
| 影像處理   | Sharp                                                                                     |
| 容器化     | Docker                                                                                    |

## 開發環境準備

- **Node.js**：版本要求 23.11.1 及以上
- **Yarn**：推薦作為專案套件管理員

## 快速啟動專案

1. **Clone 專案**

   **從 GitHub Clone：**

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

   **從 Gitee Clone（內地網路使用）：**

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

2. **安裝相依套件**

   請先在專案根目錄下執行以下指令以安裝相依套件：

   ```bash
   yarn install
   ```

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

   本專案包含 **後端 API 服務** 和 **前端頁面** 兩部分，請根據需要選擇啟動方式：

   - **方式一：僅啟動後端服務**

     ```bash
     yarn dev
     ```

     > ⚠️ 此指令僅啟動後端 API 服務（Port 10588），**不包含前端頁面**。直接瀏覽 `http://localhost:10588` 只能呼叫 API 介面，無法看到完整的網頁介面。若需同時使用前端頁面，請配合前端專案單獨啟動，或使用下方的 GUI 模式。

   - **方式二：啟動 Electron 桌面用戶端**

     ```bash
     yarn dev:gui
     ```

     > 此指令會同時啟動後端服務和 Electron 桌面視窗，內建前端頁面，開箱即用，無需額外設定。適合想要完整體驗所有功能的開發者。

   - **方式三：正式環境模式啟動**

     ```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 除錯面板（選用）**

   啟動 AI SDK 的視覺化除錯工具，方便對 AI 呼叫進行除錯：

   ```bash
   yarn debug:ai
   ```

## 前端開發

若需修改前端介面，請前往前端儲存庫進行開發：

- **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/               # 前端編譯產物（內建）
📂 docs/                    # 文件資源
📂 env/                     # 環境設定
📂 scripts/                 # 建置與輔助腳本
📂 src/
├─ 📂 agents/               # AI Agent 模組
│  ├─ 📂 productionAgent/   # 製作 Agent
│  └─ 📂 scriptAgent/       # 劇本 Agent
├─ 📂 lib/                  # 公用函式庫（資料庫初始化、回應格式）
├─ 📂 middleware/            # 中介軟體
├─ 📂 routes/               # 路由模組
│  ├─ 📂 agents/            # Agent 記憶管理
│  ├─ 📂 artStyle/          # 畫風管理
│  ├─ 📂 assets/            # 素材管理
│  ├─ 📂 assetsGenerate/    # 素材生成
│  ├─ 📂 cornerScape/       # 分鏡管理
│  ├─ 📂 general/           # 通用 API
│  ├─ 📂 login/             # 登入認證
│  ├─ 📂 migrate/           # 資料轉移
│  ├─ 📂 modelSelect/       # 模型選擇
│  ├─ 📂 novel/             # 小說管理
│  ├─ 📂 other/             # 其他功能
│  ├─ 📂 production/        # 製作管理
│  ├─ 📂 project/           # 專案管理
│  ├─ 📂 script/            # 劇本生成
│  ├─ 📂 scriptAgent/       # 劇本 Agent 介面
│  ├─ 📂 setting/           # 系統設定
│  ├─ 📂 task/              # 任務管理
│  └─ 📂 test/              # 測試介面
├─ 📂 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，直接下載本儲存庫的用戶端即可。前端儲存庫僅供需要二次開發或客製化前端介面的開發者使用。

---

# 👨‍👩‍👧‍👦 Discord 交流群組

點擊下方圖示加入 Discord：

[![Join our Discord](https://cdn.prod.website-files.com/6257adef93867e50d84d30e2/67d00cf7266d2c75571aebde_Example.svg)](https://discord.gg/HEjKmpNpAZ)

或直接點擊連結： [https://discord.gg/HEjKmpNpAZ](https://discord.gg/HEjKmpNpAZ)

---

# 💌 聯絡我們

📧 信箱：[ltlctools@outlook.com](mailto:ltlctools@outlook.com?subject=Toonflow諮詢)

---

# 📜 授權條款

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/docs/transformers.js) - 本機 ML 推論庫

感謝以下組織/單位/個人為 Toonflow 提供支援：

<table>
  <thead>
    <tr>
      <th align="center">Logo</th>
      <th align="center">名稱</th>
      <th align="center">支持方式</th>
      <th>簡介</th>
      <th align="center">官網</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td align="center"><img src="./sponsored/sophnet.png" alt="算能雲 Logo" width="48"></td>
      <td align="center"><b>算能雲</b></td>
      <td align="center">💻 算力贊助</td>
      <td>致力於打造更快、更穩、更省的一站式模型推理 API 服務平台</td>
      <td align="center"><a href="https://www.sophnet.com/">官網</a></td>
    </tr>
    <tr>
      <td align="center"><img src="./sponsored/atlascloud.png" alt="Atlas Cloud Logo" width="48"></td>
      <td align="center"><b>Atlas Cloud</b></td>
      <td align="center">💻 算力贊助</td>
      <td>全球首個全模態推理平台。對話、圖像、視頻、音頻——全部統一 API。300+ 模型，OpenAI 兼容。</td>
      <td align="center"><a href="https://www.atlascloud.ai/">官網</a></td>
    </tr>
    <tr>
      <td align="center"><img src="./sponsored/hunyuan.webp" alt="騰訊混元3D Logo" width="48"></td>
      <td align="center"><b>騰訊混元3D</b></td>
      <td align="center">🌐 世界模型技術支持</td>
      <td>騰訊混元3D AI創作引擎基於騰訊混元3D生成大模型2.5版本，業界首個一站式3D內容AI創作平台。具備文生、圖生3D、3D動畫生成、紋理生成等功能，支援草圖生3D、3D人物生成，具有低多邊形模型生成優勢。</td>
      <td align="center"><a href="https://3d.hunyuan.tencent.com/">官網</a></td>
    </tr>
  </tbody>
</table>

完整的第三方相依性清單請查閱 `NOTICES.txt`

##### copyright © 北京艾阿網絡科技有限公司