RT Desk — инструкция по эксплуатации

RT Desk — это рабочее место поддержки и продаж в одном приложении: канбан-доска задач, недельный календарь, CRM по клиентам и единый почтовый ящик входящих сообщений из мессенджеров (сейчас — Telegram), который умеет отвечать клиентам автоматически с помощью ИИ-агента, при необходимости опираясь на базу знаний компании.

Сервис состоит из трёх независимых программ (контейнеров), которые работают вместе, но не ломают друг друга при сбое:

(связи между ними подробно показаны в разделе 10)

Главное, что нужно понимать: вся информация и вся логика «что говорить клиенту» хранится и настраивается в самом rt-desk, во вкладке Настройки. Агенты-контейнеры ничего не хранят сами — они просто выполняют то, что там написано, и могут быть перезапущены или обновлены в любой момент без потери данных.

Главная страница (/). Обычная канбан-доска: колонки — это «треки» (например, направления работы или проекты), внутри каждого трека — четыре фиксированные дорожки: К выполнению → В работе → На проверке → Выполнено.

• Треки и задачи создаются и удаляются вручную — никакой автоматики на доске нет.
• Карточку можно перетащить между дорожками и между треками (drag&drop).
• У задачи можно открыть карточку и привязать её к клиенту из CRM через поле «Клиент» — тогда на карточке появится цветной бейдж с именем клиента.
• Поле «Ответственный» — ответственный за задачу. Выбирается из пользователей системы (раздел 9); на карточке появляется кружок с инициалами и имя. Ответственного можно сменить или снять (вариант «Не назначен») в любой момент.
• Архив — отдельная колонка справа: туда перетаскиваются завершённые/неактуальные задачи, чтобы не захламлять доску.

Страница /calendar — недельный календарь в стиле доски: вместо треков колонками идут дни недели с понедельника по воскресенье, а записи — это карточки внутри дня. По умолчанию всегда открывается текущая неделя, сегодняшний день выделен рамкой.

Как сделать запись

• Нажмите «+ запись» внизу нужного дня — дата подставится сама. Или кнопку «Новая запись» вверху и выберите дату вручную.
• Обязательно только название. Дополнительно можно указать время, продолжительность (Продолжительность), описание, клиента из CRM и ответственного (Ответственный) из пользователей системы.
• Продолжительность выбирается из списка: от 15 минут до 8 часов. Если указаны и время, и продолжительность, на карточке показывается интервал — например, 10:30–11:30. Если только продолжительность — просто «2 ч»: удобно для дел, которые нужно сделать в этот день, но не к конкретному часу.
• Записи со временем стоят в начале дня по порядку, записи без времени — после них.
• Высота карточки — это продолжительность, в одном масштабе на всю неделю (час ≈ 72 px): двухчасовая встреча вдвое выше часовой. Записи до ~45 минут сворачиваются в одну строку «☐ 10:00 Название». Записи без продолжительности имеют обычную высоту по содержимому.
• Цвет — в окне записи можно выбрать цвет из палитры (9 цветов или без цвета): карточка получит цветную полосу слева и лёгкую заливку. Удобно, например, отличать встречи, звонки и внутренние дела.
• Часы по цветам — под названием дня показывается, сколько времени запланировано каждым цветом: например, ● 3h синим, ● 1h 30m зелёным и итог Σ 4 ч 30 мин. Считаются только записи с продолжительностью; записи без цвета идут отдельной белой плашкой. Подсчёт учитывает включённые фильтры — например, выберите сотрудника, и увидите его загрузку по дням.
• Записи на одно время стоят рядом, в одной строке. Это же касается пересекающихся интервалов: встреча 10:00–11:00 и созвон в 10:30 окажутся рядом, так что накладки видны сразу. В такой узкой карточке время не пишется: более поздняя запись сдвинута вниз на соответствующее число минут, а точное время видно во всплывающей карточке.

Работа с записями

• Посмотреть подробности — карточка компактная: на ней время, название и иконки (кружок клиента, кружок с инициалами ответственного, значок ≡, если есть описание). Имена не пишутся, чтобы карточки помещались рядом. Наведите курсор на карточку — поверх остальных откроется всплывающая карточка с интервалом, полным описанием, клиентом и ответственным.
• Перенести на другой день — перетащите карточку в колонку нужного дня (drag&drop).
• Отметить выполненной — галочка на карточке или чекбокс «Выполнено» в окне редактирования; запись зачёркивается, но остаётся на месте.
• Изменить или удалить — клик по карточке открывает редактирование, там же кнопка «Удалить».
• Другие недели — кнопки ‹ и › листают недели, «Текущая неделя» возвращает к текущей. Выбранная неделя попадает в адрес страницы (/calendar?week=2026-11-09), поэтому ссылку на неё можно переслать коллеге.

Фильтры и поиск

• Над неделей — строка поиска и два фильтра: по сотруднику (все / без ответственного / конкретный человек) и по клиенту (все / без клиента / конкретный клиент).
• Поиск ищет введённый текст простым вхождением в названии и описании, без учёта регистра: «globex» найдёт и «Workshop with Globex», и запись с «Globex» в описании.
• Фильтры и поиск складываются (например, «Мария» + «отчёт»), действуют сразу и сохраняются при перелистывании недель и автообновлении. Включённый фильтр подсвечен рамкой, справа вверху пишется «Показано 3 из 12», а ссылка «Сбросить фильтры» сбрасывает всё разом.

Страница /clients — простая CRM: карточка на каждого клиента со статусом, контактами, заметками и списком привязанных задач с доски.

Страница /dialogs — единый «почтовый ящик» переписки с клиентами из всех подключённых мессенджеров. Один диалог = одна продолжающаяся переписка с одним чатом.

Логика работы диалога

• Создание: первое сообщение из чата автоматически создаёт клиента (если его ещё нет) и открывает диалог.
• Продолжение: все следующие сообщения из того же чата попадают в тот же диалог, пока он не «затих».
• Автозакрытие: если в открытом диалоге час нет новых сообщений — он автоматически закрывается (проверка идёт каждые 5 минут). Это просто статус, переписка не удаляется.
• Переоткрытие: если оператор (или агент) отвечает в закрытый диалог — тот автоматически открывается снова.
• Голосовые сообщения: скачиваются и сохраняются на сервере, в диалоге проигрываются прямо в ленте.

ИИ-агент и человек не отвечают одновременно

У каждого диалога есть переключатель «агент включён / выключен» прямо в карточке переписки. Как только человек вручную отправляет сообщение из этого интерфейса, агент для этого диалога автоматически выключается — чтобы бот и оператор не писали клиенту одновременно. Включить агента обратно можно тем же переключателем.

Раздел Настройки → Мессенджеры → Telegram подключает бота, который принимает и отправляет сообщения для вкладки «Диалоги». Архитектура сделана так, что добавление нового мессенджера (MAX, Instagram, WhatsApp — сейчас в интерфейсе они отмечены как «Скоро») не потребует переделывать «Диалоги» или CRM — это просто отдельный «адаптер».

Шаги подключения бота

1. В Telegram создать бота через @BotFather и получить токен вида 123456:ABC-DEF….
2. Вставить токен в поле Токен бота и нажать Сохранить.
3. Выбрать способ получения сообщений — Опрос или Вебхук (сравнение ниже).

Для Вебхук есть кнопка «Подключить через вебхук» — она в один клик берёт текущий домен страницы (тот, через который вы сейчас открыли /settings) и регистрирует его в Telegram. Ручное поле «Публичный адрес сервера» нужно только для нестандартного адреса.

Статус-индикатор под полем токена показывает реальное состояние: серая точка — выключено, зелёная — подключено и работает, красная — есть ошибка (текст ошибки выводится рядом).

client-agent — отдельная программа (контейнер), которая каждые 10–15 секунд спрашивает у rt-desk: «есть диалоги, на которые никто не ответил?», забирает один диалог, обрабатывает его и отправляет ответ клиенту через тот же канал (Telegram и т.д.). Она намеренно вынесена из основного rt-desk: её логика меняется часто, и её сбой или обновление никогда не может повредить данные — диалог просто подождёт чуть дольше.

Всё, что агент говорит и когда он передаёт диалог человеку, управляется только настройками ниже — в коде контейнера нет захардкоженного поведения.

Пошаговый конвейер обработки одного сообщения

Шаг 5 при отклонении возвращает ответ на шаг 4 с комментарием судьи — так происходит до лимита повторов, заданного в настройках; после лимита диалог автоматически уходит оператору, а не отправляется клиенту без проверки.

Поля настроек и их смысл

Как включить в продакшене

1. Скопировать значение Служебный токен из Настроек.
2. Вставить его в переменную AGENT_SERVICE_TOKEN файла .env рядом с docker-compose.yml.
3. Выполнить docker compose up -d --build — всё остальное (ключ OpenAI, промпты, модели) настраивается только через интерфейс, без переменных окружения.

Страница /knowledgebase — загрузка документов компании (инструкции, тарифы, FAQ и т.п.) плюс тестовый чат, где можно сразу проверить, что на них ответит ИИ.

Документы хранятся внутри самого rt-desk: каждый загруженный текст разбивается на кусочки ~1200 символов, для каждого кусочка строится embedding (через OpenAI) и сохраняется. Поиск по базе — это поиск «похожих по смыслу» кусочков, а не поиск по ключевым словам.

Документы: загрузка .md и ручной ввод

На странице База знаний документ можно добавить двумя способами: кнопкой ⇪ Загрузить .md — загрузить готовый markdown-файл (название берётся из имени файла, текст читается прямо в браузере) — или кнопкой + Добавить — вставить текст вручную. Оба пути ведут в одну и ту же форму перед сохранением, так что текст из файла можно поправить до того, как он уйдёт на эмбеддинг.

Список документов слева разбит на две группы — Загруженные файлы (📄, с именем исходного файла) и Ручные записи (✍️) — чтобы сразу было видно, что пришло из файла, а что ввели руками. Большой документ автоматически режется на несколько кусочков (чанков); все они привязаны к одному документу, и при удалении документа удаляются сразу все его кусочки — «осиротевших» эмбеддингов в базе не остаётся.

Визуализация векторного пространства

Внизу страницы — панель Векторное пространство: 2D-проекция (PCA) эмбеддингов всех кусочков базы. Точки, расположенные рядом на графике, семантически близки по смыслу; цвет точки соответствует документу, которому принадлежит кусочек, а наведение на точку показывает текст кусочка и его номер. Это быстрый способ увидеть, не дублируют ли документы друг друга и насколько плотно/разрозненно покрыта тема базой. Кнопка ↻ Refresh пересчитывает проекцию заново — полезно после добавления или удаления документов.

Конвейер ответа на вопрос

Если судья много раз отклоняет черновик — последний вариант всё равно возвращается, но помечается как «не одобрен судьёй» (проверка не пройдена), а не скрывается.

Настройка (Настройки → Агенты → База знаний)

1. Загрузить документы на странице База знаний.
2. Включить и настроить агента в Настройки → Агенты → База знаний.
3. Проверить ответы в тестовом чате той же страницы.
4. При желании включить доступ к базе для Агент поддержки (раздел 7).

Запуск на проде — тем же способом, что и Агент поддержки: контейнер уже прописан в docker-compose.yml, ему нужен тот же AGENT_SERVICE_TOKEN в .env.

Раздел Настройки → Команда → Пользователи. Два уровня доступа:

При первом запуске, если пользователей ещё нет, автоматически создаётся администратор из переменных ADMIN_USER / ADMIN_PASSWORD (по умолчанию — admin / admin, обязательно сменить перед публикацией сервиса куда-либо, кроме локального теста).

Все созданные здесь пользователи сразу появляются в списке «Ответственный» (ответственный) у задач на доске и записей в календаре — отдельно ничего настраивать не нужно. Если пользователя удалить, его задачи и записи просто станут «без ответственного».

Новый пароль нужно сообщить пользователю напрямую — рассылки на почту сервис не делает.

Полная схема данных и вызовов между тремя контейнерами:

Клиент пишет в Telegram
        │
        ▼
┌───────────────────┐        long polling / webhook
│   Telegram Bot API │◄──────────────────────────────┐
└───────────────────┘                                │
        │ новое сообщение                            │
        ▼                                             │
┌─────────────────────────────────────────────────────────────┐
│                           rt-desk                            │
│  src/channels/telegram  →  dialogs.js  →  clients.js         │
│  (создаёт/обновляет диалог и клиента, кладёт в очередь)      │
│                                                                │
│  Настройки ──────────────────────────────┐                   │
│  (сценарий, модели, токены, правила)      │ читает конфиг     │
└─────────────────────┬──────────────────────┼─────────────────┘
      GET /api/agent/dialogs/pending          │
      POST /api/agent/dialogs/:id/claim       │
      POST /api/agent/dialogs/:id/reply        │
                      │                        │
                      ▼                        │
            ┌───────────────────┐              │
            │   client-agent     │◄─────────────┘
            │  (опрашивает каждые │   POST /api/agent/kb/ask
            │   10–15 секунд)     │──────────────┐
            └───────────────────┘               │
                                                  ▼
                                      ┌─────────────────────┐
      rt-desk  POST /api/knowledgebase/chat ──►│                │
      (тестовый чат на странице KB)   │ knowledgebase-agent  │
                                      │  (поиск + ответ + judge) │
                                      └─────────────────────┘
                                                  ▲
                                   POST /api/agent/kb/search
                                   ищет похожие кусочки в данных rt-desk
      

Ключевые идеи этой схемы:

• Вся правда — в rt-desk. Диалоги, клиенты, документы базы знаний и настройки живут только там, в одном JSON-файле данных (DATA_DIR). Агенты — «безголовые» исполнители, у них нет своей базы данных.
• Агенты общаются только по HTTP, только по токену. Запросы от client-agent и knowledgebase-agent к rt-desk проверяются заголовком X-Service-Token, который сравнивается с токеном из Настроек — обновили токен в интерфейсе, он сразу действует на все новые запросы.
• Один и тот же путь ответа — везде. И тестовый чат страницы База знаний, и инструмент «поиск по базе» у Агент поддержки идут через один и тот же knowledgebase-agent — ответ клиенту в Telegram гарантированно совпадает с тем, что видит админ при проверке.
• Сбой агента не портит данные. Если контейнер агента упал или перезапускается — диалог просто остаётся/возвращается в очередь «pending», ничего не теряется и не дублируется.

Первый запуск на сервере

cp .env.example .env     # задать ADMIN_PASSWORD и остальные переменные
docker compose up -d --build

Поднимаются три сервиса: rt-desk (порт задаётся HOST_PORT, по умолчанию 8090), client-agent и knowledgebase-agent.

Обновление версии

git pull
docker compose up -d --build

Данные (диалоги, клиенты, документы базы знаний, настройки) хранятся в отдельном docker-томе rtdesk-data, подключённом к /app/data — они переживают пересборку и обновление образа.

Переменные окружения (.env)

Бэкап

Всё состояние — это один JSON-файл внутри тома rtdesk-data (плюс папка с голосовыми сообщениями). Достаточно периодически копировать содержимое этого тома:

docker run --rm -v rtdesk-data:/data -v $(pwd):/backup alpine \
  tar czf /backup/rtdesk-backup-$(date +%F).tar.gz -C /data .

Если что-то не отвечает

1. Проверить статус-индикаторы в Настройки (Telegram, Агент поддержки, База знаний) — цвет точки сразу говорит, в каком звене проблема.
2. docker compose logs -f client-agent / knowledgebase-agent — текст ошибки, плюс она же, скорее всего, уже прилетела в Sentry, если он настроен.
3. Диалог, застрявший в «processing» дольше 5 минут, сам вернётся в очередь — вручную трогать не нужно.