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 install создаёт package-lock.json. Сохраните его в репозитории вместе с исходным кодом: он фиксирует проверенные версии зависимостей для CI и Docker-сборки.

После этого приложение будет доступно локально. Для запуска используйте npm run build && npm start — это справедливо и для шаблонов default/quiz, и для проектов, сгенерированных через create from-flow. Для интерактивной отладки в консоли (без HTTP-сервера) создайте проект с режимом dev — тогда index.ts будет использовать BotTest и метод test().

📋 Команды CLI

Команда	Описание	Параметры
create	Создание нового проекта	<project-name> или <config-file.json>
create from-flow	Создание проекта из визуального редактора	<flow.json> [--output ./path] [--usecloud] [--force]
validate	Проверить корректность flow.json	<flow.json>
stats	Агрегировать метрики из лога	--log <path>
generateenv	Сгенерировать файл .env в текущей папке	[--force]
add docker	Добавить Dockerfile и .dockerignore в текущую папку	-
add deploy	Добавить .github/workflows/deploy.yml	-
add env	Сгенерировать .env в текущей папке	[--force]
-v, version	Узнать версию CLI	-

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

Флаг	Описание
--minimal	Создаёт минимальный рабочий проект без класса-контроллера: вся логика описывается прямо в index.ts через addCommand (конфиги проекта генерируются как обычно). Подходит для быстрого прототипа. Работает только с типом default.
--prod	Создаёт production-готовый проект: Dockerfile, .dockerignore и .github/workflows/deploy.yml. Файл .env создаётся отдельно (isEnv в JSON-конфиге или npx umbot add env).
--usecloud	Генерирует Yandex Cloud Functions-приложение: добавляет serverless.yml, отключает локальный HTTP-listener. Применяется только с create from-flow.
--force	Разрешает перезапись непустой целевой директории. Иначе CLI останавливается с ошибкой, чтобы не стереть ваши файлы.

💡 Важно: флаг --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

⚠️ Безопасность: поля вроде tokens.*.token, db.host, db.pass и т.п. в вашем JSON-конфиге — это placeholder-значения. Не храните реальные токены в *.json (он попадёт в git), используйте .env или переменные окружения. Сгенерированный .env автоматически попадает в .gitignore, но если вы делаете его вручную — убедитесь, что .gitignore его покрывает.

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

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;

    // Имя хоста на котором будет запущено приложение. По умолчанию 0.0.0.0
    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

⚠️ В примере выше токены и параметры БД показаны как placeholder-строки. В реальном проекте рекомендуется оставлять их пустыми в конфиге и передавать через .env (с { "isEnv": true } CLI сам сгенерирует .env и добавит его в .gitignore).

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

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

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

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

Создание проекта из визуального редактора (from-flow)

Команда create from-flow позволяет создать проект umbot из JSON-файла, экспортированного из Umbot Flow Editor — визуального редактора для фреймворка umbot.

Цепочка: Визуальный редактор → JSON-конфигурация → npx umbot create from-flow → TypeScript-проект

Подробное описание JSON-формата: src/docs/json-format.md

Использование

npx umbot create from-flow flow.json
npx umbot create from-flow flow.json --output ./my-bot
Copy

Параметры

Параметр	Описание
flow.json	Путь к JSON-файлу, экспортированному из редактора
--output ./path	Путь для выходного проекта (по умолчанию: имя файла flow.json без расширения)

Генерируемая структура

my-bot/
├── src/
│   ├── index.ts              # Точка входа с регистрацией команд
│   └── utils.ts              # Вспомогательные функции setText/setTTS
├── package.json
├── tsconfig.json
└── .gitignore
Copy

Режимы генерации

• Простой (только команды): вся логика генерируется в index.ts
• Сложный (шаги, условия, переменные): команды, шаги и условия также генерируются функциями в index.ts; отдельный файл контроллера не создаётся ни в одном режиме

Пример workflow

1. Откройте визуальный редактор: flow.maxim-m.ru
2. Создайте флоу с командами, шагами и условиями
3. Экспортируйте JSON-конфигурацию → скачайте flow.json
4. Выполните: npx umbot create from-flow flow.json --output ./my-bot
5. Зайдите в проект и запустите:

cd my-bot
npm install
npm run build
npm start
Copy

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

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

   • Используйте понятные имена
   • Избегайте пробелов и специальных символов
   • Учитывайте: CLI заменяет все не-буквенно-цифровые символы имени на _ (npx umbot create my-bot создаст директорию my_bot и такое же имя в package.json), поэтому используйте snake_case или имя одним словом

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

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

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

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