Adapter-Contract коннекторов: каналы и лимиты

Каналы, где ваши клиенты уже есть

AI-workspace полезнее всего там, где разговор уже происходит. Для многих организаций это место - не веб-интерфейс, который вы разворачиваете; это каналы мессенджеров, которые люди открывают не задумываясь - группы WhatsApp, чаты Telegram, серверы Discord, пространства Slack. Simmetric Chat рассматривает эти каналы как поверхности первого класса той же базы знаний: коннектор привязывает канал к workspace и к одному документальному архиву, и каждый вопрос, приходящий по этому каналу, отвечает та же pipeline retrieval, что и у внутреннего чата.

Слово в заголовке - adapter contract - называет проектное правило, делающее это безопасным. Каждая платформа говорит на своём протоколе со своей семантикой учётных данных; каждая работает за выделенным adapter'ом, и всё, что adapter'ы разделяют, - фиксированный словарь полей и лимитов. Результат читается как политика безопасности: один коннектор на канал, один binding на коннектор, один корпус на binding.

Эта статья проходит contract со стороны оператора: что вы настраиваете при создании коннектора, какие поверхности изменились в эру v0.28 (ветка редактирования), как лимиты защищают workspace от внешнего трафика и что происходит, когда в корпусе нет цитируемого ответа.

Только редакция Enterprise: connectors_enabled равен false в лицензии Community, реестр adapter'ов там пуст, и панель админа показывает приглашение к обновлению вместо формы создания. Факт: FACT-CENSUS.md F-CONN-1.

Что вы настраиваете при создании

Форма создания живёт в Settings → Conversations → Connectors и запрашивает два класса полей. Поля binding'а называют интеграцию: name, идентифицирующий экземпляр, platform (одна из telegram, discord, slack, whatsapp), секретный токен канала и workspace, который коннектор обслуживает. Поведенческие поля дают форму разговору: привязку документального архива, определяющую корпус, приветственное сообщение тому, кто открывает разговор, сообщение-фолбэк с его fallbackLocale на случай, когда поиск не даёт цитируемых источников, и два лимита - по запросам и по дневным сессиям, где 0 означает «без ограничения».

Три из этих полей неизменяемы после создания, и эта неизменяемость - не деталь реализации, а модель доверия. Платформа и секретный токен определяют, кто может говорить с корпусом; workspace определяет, что достижимо. Меняется любое из них - меняется идентичность интеграции, и contract отвечает новым коннектором, а не мутацией. Схема серии v0.28 несёт эти правила буквально: приветственные и фолбэк-сообщения ограничены 4000 знаков, платформа и токен только при создании, и PUT их никогда не касается.

Учётные данные по проекту остаются серверными. Приложение вызывает API канала с данными, которые внёс администратор; секретный токен после создания никогда не отображается в интерфейсе, и маршрутизация коннектора живёт в вашей инфраструктуре - канал говорит с вашим сервером, ваш сервер говорит со своей базой знаний.

Слой adapter'ов

Каждая платформа работает за выделенным adapter'ом, и регистрация каждого отражает то, что платформа действительно требует:

• Telegram - токен бота из @BotFather, с поддержкой и polling, и webhook (на карточке - посвящённые режиму кнопки).
• Discord - токен бота из Developer Portal плюс message-intents; adapter читает каналы, для которых бот авторизован.
• Slack - токен бота и signing secret приложения Slack; события сообщений приходят через настроенный webhook.
• WhatsApp - секретный токен Business API провайдера; adapter вызывает API провайдера.

В слое adapter'ов умирают межплатформенные различия. Проверка webhook, объём intents, циклы polling, нормализация формы сообщений - всё живёт за adapter'ом своей платформы, и остальной продукт видит ровно одну форму: запись коннектора. Реестр adapter'ов сам gated: в Community он пуст по построению, так что инстанс Community отказывает закрыто прежде, чем внешний трафик достигнет workspace.

Редактирование: мутабельная поверхность v0.28.1

До v0.28.1 править коннектор означало удалить и создать заново. Изменения серии v0.28 добавляют ветку редактирования: меню карточки несёт пункт Edit, открывающий предзаполненный диалог над в точности мутабельной поверхностью - через PUT /api/connectors/:id:

• Мутабельно - имя, привязка архива, приветственное и фолбэк-сообщения, fallback-язык и оба лимита (пусто = null; 0 = без ограничения).
• Неизменяемо - платформа, токен бота, workspace.

Переключатель isEnabled остаётся на карточке (он приостанавливает маршрутизацию, не стирая конфигурацию), и мутация аудитируется как всякое действие админа: endpoint пишет событие chat_connector.updated, на равных с веткой DELETE и её chat_connector.deleted. Ветка редактирования важна для операторской истории по конкретной причине: перепривязать канал к заново выстроенному архиву или после инцидента ужесточить лимит - больше не за счёт идентичности коннектора.

Путь ответа и фолбэк

Каждый вопрос, приходящий из канала, проходит ту же pipeline, что и внутренний чат: гибридный поиск по связанному архиву, цитирование источников, синтез - затем обоснованный ответ возвращается по исходному каналу. Привязка архива - тихое ядро contract: именно она делает внешнюю беседу обоснованной.

Когда поиск не даёт валидных цитируемых элементов, ответ contract'а - сообщение-фолбэк: настроенный ответ в настроенной fallbackLocale. Внешний канал никогда не получает необоснованную генерацию, пока фолбэк стоит; посетитель читает фолбэк, а не уверенное утверждение без опоры.

Лимиты как шлюз workspace

Лимит запросов и дневных сессий - защита contract'а от внешнего трафика:

• 0 = без ограничения (sentinel-значение роутера).
• N = максимум на коннектор - по запросам и по сессиям в день.

Вместе с isEnabled они позволяют выставить базу знаний на публичный канал, удерживая радиус действия ограниченным: вышедший из-под контроля бот, сканируемый канал или неожиданная аудитория потребит не больше настроенной доли workspace. Отключить, ужесточить или перепривязать - каждое действие теперь одна правка (ветка v0.28.1), без пересоздания.

Читать дальше

Путеводитель несёт полную операторскую процедуру - форму поле за полем, таблицу adapter'ов по платформам, поведение аудита - на /ru/docs/connectors:

• Коннекторы - путеводитель
• Факты этого поста: строки FACT-CENSUS.md F-CONN-1 (барьер редакции), F-CONN-2 (ветка редактирования v0.28.1), F-LIC-1 (активация вставкой ключа - без доступа к серверу)

Provenance: пакеты Simmetric Chat connector.schema.ts (формы полей + лимиты), routes/connectors.ts (роутер + лимитер), CHANGELOG.md v0.28.1, license.ts (connectors_enabled) на зафиксированном census'ом документальном состоянии v0.28.1 (SHA aca5b8ff).