umbot

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

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

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

---

Почему umbot?

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

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

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

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

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

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

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

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

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

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

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

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

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

Для кого umbot?

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

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

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

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

---

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

Платформа	Идентификатор	Статус
Яндекс.Алиса	alisa	Полная поддержка
Сбер SmartApp	smart_app	Полная поддержка
Маруся	marusia	Полная поддержка. VK убрала возможность создания новых навыков!
Telegram	telegram	Полная поддержка
VK	vk	Полная поддержка
MAX	max_app	Полная поддержка
Viber	viber	Полная поддержка
Ваша платформа	...	За счет адаптеров

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

---

🧩 Экосистема

Отдельные 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

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' } }));

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

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

---

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

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

npm install umbot

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

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

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

// 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);

// 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}`;
        }
    }
}

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

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

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

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

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

Важно:

• Тесты проводились без сетевых вызовов и операций с базами данных, поэтому цифры показывают потенциал ядра фреймворка.
• В реальном проекте итоговый 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-проект → Ваш сервер

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

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

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

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

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

📝 Лицензия

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

🤝 Поддержка

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

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