<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> | 
  <a href="./README.zhtw.md">繁體中文</a> | 
  <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> | 
  <strong>Русский</strong>
</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 — инструмент для создания коротких сериалов и комиксов с помощью AI, позволяющий автоматически превращать романы в сценарии и генерировать изображения и видео с помощью нейросетей. Используя Toonflow, вы легко пройдёте путь от текста к видео: создание коротких фильмов становится умнее и удобнее.

- ✅ **Генерация персонажей**  
   Автоматически анализирует исходный текст романа, интеллектуально идентифицирует и генерирует параметры персонажей, включая внешний вид, характер, социальный статус и др., формируя прочную основу для дальнейшей разработки сценария и визуала.
- ✅ **Генерация сценария**  
   На основе выбранных событий и глав система автоматически создает структурированный сценарий, включая диалоги, описание сцен и развитие сюжета, обеспечивая эффективную трансформацию из литературного текста в кинематографический сценарий.
- ✅ **Раскадровка**  
   На основе сценария AI генерирует креативные промпты и дизайн кадров, прорабатывает передний-средний-задний план, динамику персонажей, реквизит и компоновку сцен, автоматически создаёт раскадровку для дальнейшей видеосборки.
- ✅ **Видеосборка**  
   Интегрирует AI-технологии генерации изображений и видео. Позволяет создавать фрагменты видео с помощью ИИ. Системы онлайн-редактирования поддерживают индивидуальные настройки и быстрый вывод конечного результата.

---

# 📦 Области применения

- Создание коротких видео-контента
- Эксперименты по экранизации романов
- Инструмент AI для литературных адаптаций
- Разработка сценариев и быстрые прототипы
- Генерация видеоматериалов

---

# 🔰 Руководство пользователя

## 📺 Видеоруководство

https://www.bilibili.com/video/BV1na6wB6Ea2
[![Toonflow — Быстрый старт с AI-видео за 8 минут](./videoCover.png)](https://www.bilibili.com/video/BV1na6wB6Ea2)

**Toonflow: 8 минут до полного освоения AI-видео**
👉 [Смотреть видео](https://www.bilibili.com/video/BV1na6wB6Ea2/?share_source=copy_web&vd_source=5b718c25439a901a34c7bc0c1d35b38e)

📱 Сканируйте WeChat QR-код для просмотра на телефоне

<img src="./videoQR.png" alt="微信扫码观看" width="150"/>

---

# 🚀 Установка

## Предварительные требования

Перед установкой и использованием программы подготовьте следующее:

- ✅ Адрес API сервиса языковой AI-модели
- ✅ Адрес API Sora или Doubao для видео
- ✅ Адрес API сервиса модели Nano Banana Pro для генерации изображений

## Установка локально

### 1. Скачивание и установка

| Операционная система | Скачать с GitHub                                          | Скачать с Quark Disk                               | Примечание               |
| :------------------: | :------------------------------------------------------- | :------------------------------------------------- | :----------------------- |
| Windows              | [Release](https://github.com/HBAI-Ltd/Toonflow-app/releases) | [Quark Disk](https://pan.quark.cn/s/94ef07509df0) | Официальный установщик   |
| Linux                | [Release](https://github.com/HBAI-Ltd/Toonflow-app/releases) | [Quark Disk](https://pan.quark.cn/s/94ef07509df0) | Официальный установщик   |
| macOS                | [Release](https://github.com/HBAI-Ltd/Toonflow-app/releases) | [Quark Disk](https://pan.quark.cn/s/94ef07509df0) | Официальный установщик   |

> [!CAUTION]
> Для macOS: откройте "Настройки → Конфиденциальность и безопасность" и настройте параметры безопасности, иначе может не открыться из-за проблемы с сертификатом.
>
> См. на Zhihu: [https://www.zhihu.com/question/433389276](https://www.zhihu.com/question/433389276)

> Из-за ограничений Gitee OS и лимита по размеру файлов Release — отдельная ссылка для загрузки с Gitee временно недоступна.

### 2. Запуск сервиса

После установки запустите приложение для начала работы.

> ⚠️ **Первый вход**  
> Логин: `admin`  
> Пароль: `admin123`

## Развертывание через Docker

### Предварительные требования

- Установлен [Docker](https://docs.docker.com/get-docker/) (версия 20.10+)

### Способ 1: Онлайн-развертывание

В разработке — пока используйте локальную сборку.

### Способ 2: Локальная сборка

Собирается локально из скачанного репозитория, подходит для разработчиков либо скачавших код через 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 <локальный_порт>:10588 -v <путь_к_данным>:/app/data toonflow

# Доступ по адресу: http://localhost:10588/web/index.html
```

### Описание портов

| Порт     | Назначение    | Мэппинг в контейнере          |
| -------- | ------------- | ---------------------------- |
| `10588`  | Web-интерфейс | `10588:10588`                |

**Переменные окружения:**

| Переменная   | Описание                                |
| ------------ | --------------------------------------- |
| `NODE_ENV`   | Среда запуска, `prod` — продуктивная    |
| `PORT`       | Порт службы (по умолчанию 10588)        |
| `OSSURL`     | Доступ к хранилищу файлов, для статики  |

---

## Развёртывание в облаке

### 1. Требования к серверу

- **ОС**: Ubuntu 20.04+ / CentOS 7+
- **Node.js**: 24.x (рекомендуется; минимум 23.11.1+)
- **ОЗУ**: от 2 ГБ

### 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)

> 💡 **Примечание:** В этот репозиторий уже встроен скомпилированный фронт. Обычным пользователям отдельная установка канала не требуется. Фронт-репозиторий — только для тех, кто хочет разрабатывать/модифицировать UI.

---

# 🔧 Руководство по процессу разработки

> [!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 / Zhihu / MiniMax / Tongyi Qianwen / xAI)                    |
| Локальный AI | @huggingface/transformers (ONNX)                                                                                   |
| RTC          | 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. **Запуск среды разработки**

   Проект состоит из backend API и frontend. Возможные варианты запуска:

   - **1: Только backend**

     ```bash
     yarn dev
     ```

     > ⚠️ Запускает только backend API (порт 10588); без интерфейса. Для доступа к UI — используйте отдельный frontend проект или запускайте через GUI-модули ниже.

   - **2: Electron-desktop-клиент**

     ```bash
     yarn dev:gui
     ```

     > Открывает backend и Electron GUI-окно — всё встроено, без доп. настроек. Рекомендуется для полноценного использования.

   - **3: Режим продакшн**

     ```bash
     yarn start
     ```

     > Запуск производственной сборки (предварительно `yarn build` обязателен).

4. **Сборка проекта**

   - Компиляция .ts файлов:

     ```bash
     yarn build
     ```

   - Сборка exe для Windows:

     ```bash
     yarn dist:win
     ```

   - Сборка для Mac:

     ```bash
     yarn dist:mac
     ```

   - Сборка для Linux:

     ```bash
     yarn dist:linux
     ```

5. **Lint и проверка кода**

   - Проверка кода на ошибки и стиль:

     ```bash
     yarn lint
     ```

6. **AI Debug-панель (по желанию)**

   Запуск GUI для отладки AI SDK:

   ```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/            # Локальные AI-модели (ONNX)
│  ├─ 📂 oss/               # Объектное хранилище (ассеты/персонажи/сцены)
│  ├─ 📂 serve/             # Вход в проде
│  ├─ 📂 skills/            # Prompt-словари умений Agent
│  └─ 📂 web/               # Скомпилированный фронтенд (встроен)
📂 docs/                     # Документация
📂 env/                      # Переменные окружения
📂 scripts/                  # Скрипты и утилиты
📂 src/
├─ 📂 agents/               # AI agent-модули
│  ├─ 📂 productionAgent/   # Агент генерации
│  └─ 📂 scriptAgent/       # Агент сценария
├─ 📂 lib/                  # Общие библиотеки
├─ 📂 middleware/            # Мидлвари
├─ 📂 routes/               # Роутинг модули
│  ├─ 📂 agents/            # Память агента
│  ├─ 📂 artStyle/          # Управление стилями
│  ├─ 📂 assets/            # Ассеты
│  ├─ 📂 assetsGenerate/    # Генерация ассетов
│  ├─ 📂 cornerScape/       # Раскадровка
│  ├─ 📂 general/           # Общие эндпоинты
│  ├─ 📂 login/             # Авторизация
│  ├─ 📂 migrate/           # Миграции
│  ├─ 📂 modelSelect/       # Выбор модели
│  ├─ 📂 novel/             # Управление романами
│  ├─ 📂 other/             # Другое
│  ├─ 📂 production/        # Управление производством
│  ├─ 📂 project/           # Управление проектом
│  ├─ 📂 script/            # Генерация сценария
│  ├─ 📂 scriptAgent/       # Эндпоинты агента сценария
│  ├─ 📂 setting/           # Настройки системы
│  ├─ 📂 task/              # Задачи
│  └─ 📂 test/              # Тестовые эндпоинты
├─ 📂 socket/               # RealTime WebSocket
├─ 📂 types/                # TypeScript типы
├─ 📂 utils/                # Утилиты
├─ 📄 app.ts                # Точка входа
├─ 📄 core.ts               # Инициализация ядра
├─ 📄 env.ts                # Работа с окружением
├─ 📄 err.ts                # Обработка ошибок
├─ 📄 logger.ts             # Модуль логгирования
├─ 📄 router.ts             # Регистрация роутов
└─ 📄 utils.ts              # Вспомогательные функции
📄 Dockerfile                # Dockerfile
📄 electron-builder.yml      # Конфиг Electron Builder
📄 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 — скачайте этот клиент. Отдельный frontend нужен только разработчикам UI.

---

# 👨‍👩‍👧‍👦 WeChat-группы

~~Группа 1~~

~~Группа 2~~

...

~~Группа 10~~

~~Группа 11~~

~~Группа 12~~

~~Группа 13~~

...

~~Группа 24~~

Ассистент по добавлению в группу:

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

---

# 💌 Обратная связь

📧 Email: [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 юрлиц — совместная внутренняя эксплуатация
- ✅ Личное обучение, исследования, некоммерческое использование

## Цены на коммерческую лицензию

| Этап | Годовой оборот | Годовая плата |
|------|---------|------|
| 🌱 Старт | < ¥100 тыс. | **Бесплатно** |
| 🚀 Стартап | ¥100–500 тыс. | ¥5 000/год |
| 📈 Рост | ¥500 тыс.–1,5 млн | ¥20 000/год |
| 🏢 Масштаб | ¥1,5–5 млн | ¥80 000/год |
| 🌐 Корпоративный | > ¥5 млн | По договорённости |

> **Условие отсутствия обратной силы**: Пользователи, использовавшие Toonflow по AGPL-3.0 до релиза v1.0.8, продолжают работу по AGPL-3.0 и не затрагиваются данным изменением.

Полный текст соглашения см. в файле [LICENSE](../LICENSE).

---

# ⭐️ История звёзд

[![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)

---

# 🙏 Благодарности

Спасибо нижеперечисленным open-source проектам за мощную поддержку Toonflow:

- [Express](https://expressjs.com/) — быстрый, открытый и лёгкий фреймворк для Node.js
- [AI SDK](https://ai-sdk.dev/) — инструменты AI для TypeScript
- [Better-SQLite3](https://github.com/WiseLibs/better-sqlite3) — высокопроизводительная обвязка SQLite3
- [Sharp](https://sharp.pixelplumbing.com/) — быстрая библиотека для работы с изображениями на Node.js
- [Axios](https://axios-http.com/) — HTTP-клиент на промисах
- [Zod](https://zod.dev/) — TS-first валидация схем
- [Socket.IO](https://socket.io/) — обмен событиями в реальном времени
- [Electron](https://www.electronjs.org/) — кроссплатформенный desktop-фреймворк
- [Hugging Face Transformers](https://huggingface.co/docs/transformers.js) — фреймворк для локального ML

Спасибо за поддержку проекту Toonflow от следующих организаций:

<table>
  <tr>
    <td>
      <img src="./sponsored/sophnet.png" alt="算能云 Logo" width="48">
    </td>
    <td>
      <b>Sophnet Cloud</b> — спонсор вычислительных ресурсов
      <a href="https://www.sophnet.com/">[сайт]</a>
    </td>
  </tr>
</table>

Полный список сторонних зависимостей — в файле `NOTICES.txt`

