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

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

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

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

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

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

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

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]`
`doctor`	Проверить проект, токены и вебхуки	`[--env <path>] [--offline]`
`webhook`	Зарегистрировать вебхук Telegram/MAX с секретом	`<telegram\|max> <https-url>`
`add docker`	Добавить Dockerfile и .dockerignore в текущую папку	-
`add deploy`	Добавить .github/workflows/deploy.yml	-
`add env`	Сгенерировать .env в текущей папке	`[--force]`
`add platform`	Каркас адаптера своей платформы с тестом	`<Name> [--force]`
`add db`	Каркас адаптера базы данных с тестом	`<Name> [--force]`
`add middleware`	Каркас middleware с тестом	`<name> [--force]`
`-v`, `version`	Узнать версию CLI	-

Каркас адаптера и middleware: `add platform`, `add db`, `add middleware`

Команды запускаются в корне проекта (там, где папка src/) и создают модуль вместе с тестом:

Команда	Файлы
`npx umbot add platform <Name>`	`src/platforms/<Name>Adapter.ts`, `<Name>Adapter.test.ts`
`npx umbot add db <Name>`	`src/db/<Name>DbAdapter.ts`, `<Name>DbAdapter.test.ts`
`npx umbot add middleware <n>`	`src/middleware/<name>.ts`, `<name>.test.ts` (функция-фабрика)

Имя пишется латиницей: discord, my-chat, Postgres. Суффикс Adapter можно не писать. У адаптера платформы platformName получается из имени (my-chat → my_chat).

Каркас сразу компилируется и проходит свои тесты. Места, которые нужно заполнить под свою платформу или базу, отмечены комментарием TODO:

платформа — чат-платформа с вебхуком: распознаёт запрос, передаёт текст в команды и отправляет ответ через Request (запрос ограничен по времени). Неизвестные события получают ответ без вызова команд: на ошибку платформа повторила бы доставку. Заполнить нужно формат запроса, адрес API, авторизацию и формат кнопок;
база данных — рабочий адаптер, который хранит данные в памяти процесса. Методы заменяются на вызовы драйвера своей базы. Тесты проверяют ответы, которых ждёт фреймворк, в том числе раздельные записи одного userId на разных платформах (uniqueKeys);
middleware — фабрика с настройками на примере блокировки пользователей.

Тесты написаны на встроенном node:test и не требуют дополнительных зависимостей. Запуск — командой, которую CLI печатает после генерации:

npx umbot add platform discord
npm run build && node --test dist/platforms/DiscordAdapter.test.js

CLI не меняет src/index.ts: строки подключения (bot.use(...)) он печатает в консоль. Существующие файлы без --force не перезаписываются. Как устроен каждый метод, описано в руководствах по адаптеру платформы, адаптеру БД и middleware.

Команда `webhook`

npx umbot webhook <telegram|max> <https-url> включает проверку подписи вебхука одной командой. Запускайте её в папке проекта: токен берётся из .env (TELEGRAM_TOKEN / MAX_TOKEN) или окружения. Команда генерирует секрет, регистрирует вебхук сразу с ним (setWebhook у Telegram, POST /subscriptions у MAX) и сохраняет секрет в .env как TELEGRAM_WEBHOOK_SECRET / MAX_WEBHOOK_SECRET. Фреймворк читает эти переменные сам и начинает отклонять запросы без верного секрета. Секрет пишется в .env только после успешной регистрации, а если он там уже есть — используется существующий. Для VK секретный ключ задаётся в настройках Callback API сообщества (VK_SECRET_KEY в .env).

npx umbot webhook telegram https://bot.example.com/webhook

Команда `doctor`

npx umbot doctor в папке проекта проверяет, готов ли бот к запуску, и печатает отчёт:

версия Node.js подходит umbot, пакет umbot установлен;
.env есть и указан в .gitignore (иначе токены попадут в git — это ошибка);
токены платформ из .env и окружения рабочие: запрос к API (Telegram getMe, MAX GET /me, VK groups.getById, Viber get_account_info, Алиса — квота загрузки файлов). Для SmartApp и Маруси проверяется только наличие токена;
вебхуки: адрес, число недоставленных обновлений и последняя ошибка доставки Telegram, подписки MAX, вебхук Viber; предупреждение, если вебхук зарегистрирован без секрета. Без вебхука — подсказка про bot.startPolling().

Токены в отчёт не попадают. --offline отключает запросы к API, --env <path> задаёт другой файл .env. При ошибках команда завершается с кодом 1 — её можно запускать в CI перед деплоем.

npx umbot doctor

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

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

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

Файл .env. Проект, созданный create, всегда читает .env (env: './.env' в src/config/*Config.ts), и CLI создаёт его с пустыми переменными токенов, секретов вебхука и MongoDB — заполните те, что нужны. Пустые значения фреймворк пропускает. Существующий .env не перезаписывается. Если файла нет (Docker, serverless), переменные берутся из окружения процесса. Команды generateenv и add env пишут тот же шаблон в текущую папку.

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

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

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

npx umbot create my-bot-project

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

npm i
npm run build
npm start

Проект с конфигурацией из 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
}

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

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

npx umbot create config.json

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

npm i
npm run build
npm start

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

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

При создании проекта через 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;
    // Перенести токены и параметры БД из этого JSON в .env проекта (без флага они удаляются из конфигурации)
    isEnv?: boolean;
}

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

{
    "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
}

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

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

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

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

Режим	Что генерируется в `src/index.ts`
`prod`	`Bot` в режиме `strict_prod` и `bot.start()` — сервер для вебхуков (по умолчанию, если `mode` нет)
`dev`	`BotTest` и `bot.test()` — диалог в консоли, без сервера
`dev-online`	`Bot` в режиме `dev` и `bot.start()` — сервер с подробными логами
`build`	Запуск через `run(config, mode)` из `umbot/build`; режим переключается одной строкой в файле

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

Команда create from-flow позволяет создать проект umbot из JSON-файла, экспортированного из Umbot Flow — визуального редактора для фреймворка 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

Параметры

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

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

my-bot/
├── src/
│   ├── index.ts              # Точка входа с регистрацией команд
│   └── utils.ts              # Вспомогательные функции setText/setTTS
├── package.json
├── tsconfig.json
├── README.md                 # Как установить, вписать токены, запустить и подключить платформы
├── .env                      # Переменные токенов выбранных платформ (не коммитится)
└── .gitignore

Файл .env создаётся всегда: переменные токенов выбранных платформ пустые, если токенов нет во flow.json. При повторной генерации (--force) заполненные значения сохраняются, недостающие переменные дописываются, а пустые заполняются токенами из flow.json. Сгенерированный бот читает .env из папки запуска.

Слоты команд

Строковые слоты генерируются в нижнем регистре: реплика пользователя приходит в бот уже в нижнем, и слот «Погода» из редактора иначе не сработал бы. Слоты-регулярки (isPattern) остаются как есть — пишите их под текст в нижнем регистре. Подробнее — в описании JSON-формата.

Старт диалога

Приветствие (нода welcome или текст и кнопки welcome из настроек, если ноды нет) срабатывает:

на /start (Telegram, в том числе с deep-link параметром) и на слоты «привет»/«здравст» (или собственные слоты ноды);
в начале диалога без команды — новая сессия Алисы/Маруси, «Начать» в MAX/Viber (messageId === 0): fallback-команда в этом случае вызывает приветствие.

Шаг, ожидавший ответ в прошлой сессии, начало диалога пропускает (return false). Без приветствия старт уходит в fallback. Режим бота (mode во flow.json) генерируется вызовом bot.setAppMode(...) сразу после создания Bot — до регистрации команд. Без поля mode (или с неизвестным значением) генерируется strict_prod.

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

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

Пример workflow

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

cd my-bot
npm install
npm run build
npm start

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

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

Ключевые классы API

Bot — точка входа: регистрация платформ, команд, lifecycle
BotController — базовый класс контроллера с бизнес-логикой
IAppConfig — интерфейс конфигурации приложения
IPlatformAdapter — контракт платформенного адаптера
Preload — предзагрузка медиафайлов платформ
Card — карточки и галереи для всех платформ
Buttons — кнопки: простые, inline, с payload

Полный справочник — API v-3.1 · все версии.

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

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

📋 Команды CLI

Каркас адаптера и middleware: `add platform`, `add db`, `add middleware`

Команда `webhook`

Команда `doctor`

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

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

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

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

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

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

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

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

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

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

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

Параметры

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

Слоты команд

Старт диалога

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

Пример workflow

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

Ключевые классы API

Settings

On This Page

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

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

📋 Команды CLI

Каркас адаптера и middleware: add platform, add db, add middleware

Команда webhook

Команда doctor

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

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

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

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

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

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

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

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

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

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

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

Параметры

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

Слоты команд

Старт диалога

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

Пример workflow

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

Ключевые классы API

Settings

On This Page

Каркас адаптера и middleware: `add platform`, `add db`, `add middleware`

Команда `webhook`

Команда `doctor`

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