umbot

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

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

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

💡 Почему umbot?

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

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

• ✅ Одна кодовая база для любой платформы. Хотите только Алису? Легко. Решите добавить Марусю или Telegram — просто добавьте нужный адаптер, логика остаётся.
• ⚡ В типичных сценариях (до 1 000 команд) полная обработка запроса внутри фреймворка, включая поиск и выполнение команд, занимает менее 30 мс даже в самом сложном случае (fallback). В большинстве случаев это время составляет < 10 мс. Это оставляет разработчику более 2.5 секунд на выполнение собственной бизнес-логики — это критически важно для платформ с жёсткими тайм-аутами (Алиса, Маруся, Сбер и др.).
• При первичной загрузке медиафайлов время ответа может превысить 1 секунду — поэтому umbot предусмотрел это, и рекомендует использовать предзагрузку необходимых ресурсов за счет использования класса Preload.
• 🔒 Безопасная обработка регулярных выражений с защитой от ReDoS из коробки
• 💾 Встроенное состояние, кэширование медиа, кнопки, карточки — «из коробки»
• 🛠 TypeScript, CLI, автодополнение, 80%+ покрытие тестами

umbot — пишешь один раз, запускаешь везде.

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

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

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

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

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

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

Для кого umbot?

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

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

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

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

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

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

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

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

npm install umbot

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

npx umbot create echo
cd echo
npm i
npm run start

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

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

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

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

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

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

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

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

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

• Пропускная способность (реалистичный сценарий) — 41 000 RPS
  (эмуляция полного цикла: входящий запрос → нормализация → логика → ответ)
• Пиковая пропускная способность (burst) — 40 000 RPS
  (одновременная обработка тысяч параллельных вызовов)
• Последовательная пропускная способность (ядро) — 66 000 RPS
  (максимальная скорость одного потока)

Важно:

• Тесты проводились без сетевых вызовов и операций с базами данных, поэтому цифры показывают потенциал ядра фреймворка.
• В реальном проекте итоговый RPS будет определяться внешними факторами (сеть, БД, логика приложения).

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

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

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

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

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

• 📚 Официальная документация
• 📢 Telegram канал
• 💬 Telegram группа
• 📦 npm package
• Создание навыка "Я никогда не"
• Примеры проектов
• Список изменений
• Что ждать в следующем релизе

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

• CLI команды

Рекомендации

re2

Фреймворк поддерживает работу с re2. За счет использования данной библиотеки, можно добиться существенного ускорения обработки регулярных выражений, а также добиться сокращения по потреблению памяти. По памяти потребление уменьшается примерно в 3-7 раз, а время выполнения уменьшается в среднем в 2-15 раз. Установка:

npm install --save re2@latest

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

Хранение данных пользователей

Не рекомендуется использовать в релизной версии приложения файловую базу данных, так как данный подход может привести к падению приложения, при большом количестве записей. Связано это с тем, что в файловой базе, данные хранятся в оперативной памяти. Для корректного сохранения данных в БД укажите:

1. Подключите готовый адаптер (например MongoAdapter), или создайте свой (bot.use(new MyAdapter()))
2. Укажите данные для подключения к базе данных bot.setAppConfig({db:{...}}), либо в конструкторе при подключении адаптера к приложению

📝 Лицензия

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

🤝 Поддержка

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

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