umbot

umbot — это TypeScript-фреймворк для разработки голосовых навыков и чат-ботов. Он даёт единую бизнес-логику для всех платформ — но одинаково эффективен, даже если вы работаете только с одной. Поддерживаются: Яндекс.Алиса, Сбер Салют (SmartApp), а также Telegram, VK, MAX и Viber из коробки. Для существующих навыков Маруси есть отдельный адаптер.

В отличие от большинства решений, требующих отдельной реализации под каждую платформу, umbot абстрагирует различия в форматах запросов и ответов, предоставляя разработчику единый, предсказуемый интерфейс. Это позволяет писать логику один раз — и запускать её везде.

Фреймворк следует SemVer. Breaking changes возможны только в MAJOR-версиях.

---

Почему umbot?

Больше не нужно писать несколько версий одного приложения.
Больше не нужно разбираться в JSON-форматах Алисы, Сбера, Маруси, Telegram, MAX и т. д.
Бизнес-логика — одна. Платформа — любая.

Ключевые преимущества:

• Одна кодовая база для любой платформы. Хотите только Алису? Легко. Решите добавить Сбер Салют или Telegram — просто добавьте нужный адаптер, логика остаётся.
• В типичных сценариях (до 1 000 команд) полная обработка запроса внутри фреймворка, включая поиск и выполнение команд, занимает менее 30 мс даже в самом сложном случае (fallback); в большинстве случаев — единицы–десятки миллисекунд. На бизнес-логику остаётся практически весь бюджет голосовых платформ: фреймворк пишет предупреждение при обработке дольше 2000 мс и ошибку — дольше 2900 мс, практический ориентир — ~3 секунды (подробнее — в «Производительность и гарантии»).
• При первичной загрузке медиафайлов время ответа может вырасти на 200–1000 мс на файл — поэтому umbot рекомендует заранее загружать необходимые ресурсы через класс Preload.
• Безопасная обработка регулярных выражений с защитой от ReDoS из коробки
• Встроенное состояние, кэширование медиа, кнопки, карточки — «из коробки»
• TypeScript, CLI, автодополнение, развитое тестовое покрытие
• Дополнительные утилиты для навигации и поиска текста, ускоряющие разработку.

Ключевая мысль: umbot — это не «надстройка для мультиплатформенности», а базовый слой, который делает разработку под любую платформу (даже одну) быстрее, чище и готовой к масштабированию.

umbot предоставляет унифицированный интерфейс для работы с ответами, но при этом учитывает специфику каждой платформы:

• Голосовые платформы (Алиса, Сбер Салют, Маруся) — всё, что нужно типичному навыку: текст и TTS, кнопки, карточки, звуки, состояние сессии и пользователя, авторизация. Отдельные директивы Алисы (запрос геолокации, аудиоплеер, события аналитики) фреймворк пока не абстрагирует — их можно добавить в своём наследнике AlisaAdapter.
• Чат-боты (Telegram, VK, Viber, MAX и др.) — поддерживается только необходимый и востребованный набор функций ( карточки, кнопки, аудиосообщения). Специфические элементы вроде опросов или кастомных интерфейсов мессенджеров исключены, так как они не имеют аналогов в голосовых платформах и редко нужны в кроссплатформенной логике.

Этот подход гарантирует, что ваш навык/бот будет вести себя предсказуемо и не потребует специальных обходных путей при переходе между платформами.

Чем umbot отличается от других решений?

Большинство фреймворков (например, telegraf, alice-sdk и т.д.) ориентированы только на одну платформу. Чтобы запустить приложение и в Алисе, и в Telegram, приходится:

• писать две (или больше) версии логики,
• поддерживать разные форматы ответов,
• дублировать обработку состояний, кнопок, медиа
• знать API каждой платформы.

umbot решает эту проблему:
одна бизнес-логика для всех платформ,
единый API для кнопок, карточек, голоса и текста,
автоматическая адаптация под формат каждой платформы "под капотом".

Это особенно ценно, если вы уже поддерживаете навык на Алисе и хотите быстро выйти в Сбер Салют, Telegram, MAX или VK — без переписывания или существенных доработок кода.

Даже если вы пока разрабатываете только под одну платформу, umbot избавляет от boilerplate, даёт единый API для работы с состоянием, кнопками и медиа, а главное — не мешает, когда придёт время добавлять новые каналы.

Для кого umbot?

umbot — это не просто обёртка под несколько платформ. Это архитектурное решение для проектов, где диалог инициирует пользователь. Оно одинаково ценно как для одной платформы, так и для десятка.

Вы будете использовать umbot, если:

• Вы разрабатываете под одну платформу (Алиса, Сбер Салют, Telegram, VK и др.). Вы получите чистое разделение логики и транспорта, избавитесь от дублирования кода внутри проекта и заложите архитектуру, которая безболезненно масштабируется, когда потребуется вторая платформа. Инструмент не усложнит — он упорядочит.
• Вы поддерживаете несколько платформ одновременно. Вы перестанете синхронизировать изменения вручную. Новая функциональность появляется сразу везде, а поддержка разных API сводится к единому интерфейсу.
• Вы проектируете систему с прицелом на будущее. Вы не хотите переписывать ядро, когда бизнес попросит добавить Telegram, корпоративный портал или голосового ассистента. umbot делает расширение предсказуемым.
• Вы работаете в корпоративной среде с внутренними мессенджерами. Вы унифицируете разработку чат-ботов, упрощаете онбординг и переиспользование компонентов между командами.
• Вы цените чистоту кода и не терпите копипасту. Вы устали переносить обработчики из проекта в проект или мучительно адаптировать бизнес-логику под каждый новый API. umbot позволяет писать ядро один раз и забыть о boilerplate.

Ключевая мысль: umbot — это не «надстройка для мультиплатформенности», а базовый слой, который делает разработку под любую платформу (даже одну) быстрее, чище и готовой к масштабированию.

---

Поддерживаемые платформы

Платформа	Идентификатор	Что поддерживается
Яндекс.Алиса	alisa	Протокол навыков: текст, TTS, кнопки, карточки, звуки, состояние, авторизация
Сбер Салют	smart_app	Протокол SmartApp API: текст, озвучка, кнопки, карточки, состояние
Telegram	telegram	Базовый набор: текст, кнопки (inline и reply), фото и медиагруппы, голос, callback, inline-запросы, события сообщений
VK	vk	Базовый набор: текст, клавиатура, карусель, голос, callback-кнопки
MAX	max_app	Базовый набор: текст, inline-клавиатура, изображения, аудио, callback, deep-link bot_started
Viber	viber	Базовый набор: текст, клавиатура, rich media. Боты Viber с 2024 года создаются только на коммерческих условиях
Маруся	marusia	Протокол навыков. VK закрыла создание новых навыков (20.12.2024) — только для существующих
Ваша платформа	...	За счет адаптеров

Для мессенджеров «базовый набор» — это то, что имеет смысл в общей логике для всех платформ. Специфичные возможности (опросы, платежи, редактирование сообщений и т. п.) фреймворк не абстрагирует, но они доступны напрямую: через controller.api и API-клиенты платформ (TelegramRequest, VkRequest, MaxRequest, ViberRequest из umbot/plugins, у каждого есть универсальный метод call(method)).

Все платформы подключаются через вебхук: long polling не поддерживается, поэтому для проверки с реальным мессенджером на локальной машине нужен туннель (ngrok и аналоги). Без сети логику можно проверить в консоли через BotTest. Проверку подписи вебхука Telegram и MAX включает одна команда: npx umbot webhook <telegram|max> <https-url>.

Нужна своя платформа?
Просто создайте свой адаптер согласно документации для нужной платформы и подключите его к приложению.
Это позволяет интегрировать umbot в любую внутреннюю систему, корпоративный мессенджер или поддержать любую другую платформу, например WhatsApp или WeChat.

---

🧩 Экосистема

Отдельные npm-пакеты, которые подключаются одной строкой через bot.use(). Ядро остаётся лёгким: драйверы СУБД и API сторонних платформ ставятся только тем, кому они нужны.

Пакет	Назначение
umbot-knex-adapter	Реляционные БД через Knex.js: PostgreSQL, MySQL/MariaDB, SQLite, MSSQL
umbot-wechat-adapter	WeChat Official Account (Weixin)

npm install umbot umbot-knex-adapter knex pg
Copy

import { Bot } from 'umbot';
import { TelegramAdapter } from 'umbot/plugins';
import { KnexAdapter } from 'umbot-knex-adapter';

const bot = new Bot()
    .use(new TelegramAdapter(process.env.TELEGRAM_TOKEN))
    .use(new KnexAdapter({ host: 'localhost', database: 'bot_db', options: { client: 'pg' } }));
Copy

Хотите написать свой адаптер? Технические задания с контрактами и чек-листами готовности:

• Адаптер платформы
• Адаптер базы данных

---

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

Установите фреймворк:

npm install umbot
Copy

Создайте и запустите проект за пять команд:

npx umbot create echo
cd echo
npm i
npm run build
npm start
Copy

Поправьте файлы нужным вам образом. Например:

// index.ts
import { Bot } from 'umbot';
import { fullPlatforms } from 'umbot/plugins';
import { EchoController } from './controller/EchoController';

const bot = new Bot()
    .use(fullPlatforms)
    .setAppConfig({ json: './data', isLocalStorage: true })
    .initBotController(EchoController)
    .start('localhost', 3000);
Copy

// EchoController.ts
import { BotController, WELCOME_INTENT_NAME } from 'umbot';

export class EchoController extends BotController {
    public action(intentName: string | null): void {
        if (intentName === WELCOME_INTENT_NAME) {
            this.text = 'Привет! Я повторяю за вами.';
        } else {
            this.text = `Вы сказали: ${this.userCommand}`;
        }
    }
}
Copy

Протестируйте приложение, и в случае необходимости опубликуйте его.

👉 Подробное руководство по запуску

Производительность

В стресс-тестах на стандартном оборудовании (AMD Ryzen 5 5600G, Windows 10) фреймворк при 1003 командах показывает:

• Пропускная способность (реалистичный сценарий) — 68 000 RPS
  (эмуляция полного цикла: входящий запрос → нормализация → логика → ответ)
• Последовательная пропускная способность (ядро) — ~80 000 RPS
  (максимальная скорость одного потока)
• Под непрерывным потоком (1000 команд, 200 запросов in-flight) — 580 000–760 000 RPS, в 28–3 000 раз больше, чем у grammy, telegraf, vk-io, viber-bot, max-bot-api и yandex-dialogs-sdk в том же стенде (BENCHMARKS)

Важно:

• Тесты проводились без сетевых вызовов и операций с базами данных, поэтому цифры показывают потенциал ядра фреймворка.
• В реальном проекте итоговый RPS будет определяться внешними факторами (сеть, БД, логика приложения).
• На реальном сервере (2 ядра / 4 ГБ RAM) с фоновой нагрузкой фреймворк показывает 16 000+ RPS — подробнее в Производительность и гарантии.

Длительное тестирование (48 часов) не выявило утечек памяти или снижения производительности: средняя пропускная способность в последовательном сценарии осталась на уровне ~67 000 RPS, а потребление памяти стабильно.

📚 Документация

Подробная документация доступна в следующих разделах:

• Быстрый старт - Подробное описание, для быстрого старта проекта
• Подробная инструкция по созданию приложений
• API Reference - Подробное описание всех классов, методов и интерфейсов
• Поддерживаемые платформы - Руководство по интеграции с различными платформами
• Конфигурация и безопасность
• Кастомизация HTTP-клиента
• Производительность и гарантии
• Тестирование
• Развертывание
• Middleware
• FAQ

Полезные ссылки

• 📚 Официальная документация
• 📢 Telegram канал
• 💬 Telegram группа
• 📦 npm package
• Создание навыка "Я никогда не"
• Примеры проектов
• Список изменений
• Миграция с umbot 2.x на 3.0

🛠 Инструменты разработчика

• CLI команды

Визуальный редактор (Umbot Flow)

Umbot Flow — визуальный редактор для создания ботов на фреймворке umbot. Собирайте логику на холсте, экспортируйте JSON-конфигурацию и генерируйте TypeScript-проект через CLI.

Цепочка:

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

Быстрый старт с редактором:

1. Откройте редактор в браузере
2. Соберите логику бота на холсте
3. Экспортируйте JSON-конфигурацию → скачайте flow.json
4. Выполните:

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

5. Готовый проект в папке my-bot

Описание JSON-формата — полная спецификация всех типов узлов, связей и правил генерации кода.

📝 Лицензия

MIT License. См. LICENSE для деталей.

🤝 Поддержка

Если у вас есть вопросы или предложения:

• 📧 Email: maximco36895@yandex.ru
• 🐛 Issues на GitHub