CLI утилита umbot для создания голосовых навыков и чат-ботов

CLI утилита для быстрого создания и настройки проектов на базе мультиплатформенного фреймворка umbot. Позволяет генерировать готовую структуру для голосовых навыков (Алиса, Маруся, Сбер SmartApp) или чат-ботов (Telegram, VK, Viber, MAX) одной командой.

Также позволяет:

• Создавать новые проекты по готовым шаблонам
• Настраивать конфигурацию проекта
• Генерировать базовую структуру приложения

🚀 Быстрый старт

Установите фреймворк и создайте новый проект:

npx umbot create my-bot
cd my-bot
npm install
npm run build
npm start
Copy

После этого приложение будет доступно локально. Для тестирования используйте npm run dev (если настроено).

📋 Команды CLI

Команда	Описание	Параметры
create	Создание нового проекта	<project-name> или <config-file.json>
generateEnv	Сгенерировать файл .env	-

Флаги команды create

Флаг	Описание
--minimal	Создаёт минимальный рабочий проект (один файл, без контроллера и конфигов). Подходит для быстрого прототипа. Работает только с типом default.
--prod	Создаёт production-готовый проект с Dockerfile, .github/workflows/deploy.yml, .env. Удобно для развёртывания на сервере.

💡 Важно: флаг --minimal не применяется к типу quiz, так как викторина требует сложной логики и хранения состояния.

🛠 Примеры использования

Простой проект (базовое приложение)

Для быстрого создания приложения, выполните следующую команду

npx umbot create my-bot-project
Copy

После выполнения команды, приложение успешно создастся, и останется только выполнить команду:

npm i
npm run build
npm start
Copy

Проект с конфигурацией из JSON

Для быстрого создания приложения с дополнительными настройками, выполните следующую команду

Создайте файл config.json

{
    "name": "quiz-bot",
    "type": "quiz",
    "mode": "dev",
    "path": "./bots/quiz",
    "config": {
        "json": "./data",
        "error_log": "./logs",
        "isLocalStorage": true,
        "tokens": {
            "alisa": {
                "token": "..."
            },
            "telegram": {
                "token": "..."
            }
        }
    },
    "isEnv": true
}
Copy

Затем выполните:

npx umbot create config.json
Copy

Утилита создаст проект в папке ./bots/quiz со всеми указанными настройками.

npm i
npm run build
npm start
Copy

⚙️ Конфигурационный файл (подробно)

Структура конфигурационного файла

При создании проекта через JSON можно передать следующие параметры:

interface ProjectConfig {
    // Название проекта (обязательное поле)
    name: string;

    // Тип проекта: "default" или "quiz"
    type?: 'default' | 'quiz';

    // Режим работы: "prod", "dev", "dev-online", "build"
    mode?: 'prod' | 'dev' | 'dev-online' | 'build';

    // Конфигурация приложения (IAppConfig из umbot)
    // В CLI это объект, который будет слит с дефолтным конфигом шаблона.
    config?: Record<string, unknown>;

    // Параметры платформы/интенты (IAppParam из umbot)
    // В CLI это объект, который будет слит с дефолтными params шаблона.
    params?: Record<string, unknown>;

    // Путь для создания проекта
    path?: string;

    // Имя хоста на котором будет запущено приложение. По умолчанию localhost
    hostname?: string;
    // Порт на котором будет запущено приложение. По умолчанию 3000
    port?: number;
    // Определяет нужно создавать .env файл или нет
    isEnv?: boolean;
}
Copy

Пример конфигурационного файла

{
    "name": "my-quiz-bot",
    "type": "quiz",
    "mode": "dev",
    "path": "./bots/quiz",
    "config": {
        "json": "./data",
        "error_log": "./logs",
        "isLocalStorage": true,
        "db": {
            "host": "",
            "user": "",
            "pass": "",
            "database": ""
        },
        "tokens": {
            "alisa": {
                "token": "token"
            }
        }
    },
    "isEnv": true
}
Copy

Типы проектов

Тип	Описание	Особенности
default	Базовый шаблон	Минимальная структура проекта
quiz	Шаблон викторины	Готовая структура для создания викторин

Режимы работы

Режим	Описание
prod	Продакшн режим
dev	Режим разработки
dev-online	Режим разработки с webhook
build	Режим сборки

Лучшие практики

1. Именование проектов:

   • Используйте понятные имена
   • Избегайте пробелов и специальных символов
   • Придерживайтесь kebab-case

2. Конфигурация:

   • Храните конфигурацию в отдельных файлах
   • Не включайте чувствительные данные в репозиторий
   • Используйте разные конфигурации для разных окружений

3. Структура проекта:

   • Следуйте рекомендуемой структуре
   • Размещайте файлы в соответствующих директориях
   • Документируйте нестандартные решения