Перейти к содержанию

Ассистент в Telegram

Telegram — вторая поверхность той же беседы с ассистентом, что и окно рабочего места: написанное боту приходит в беседу, ответ возвращается в чат, а подтверждения действий можно дать кнопкой. Статья для человека, который пользуется ассистентом, и для администратора, который это включает. Обоснование — TAI-ADR-0051 (п.7) и TAI-ADR-0050.

Что видит человек

  • Написать ассистенту. Любой текст (не команда) в личном чате с ботом становится репликой в вашей единственной беседе. Ответ ассистента придёт в этот же чат и будет виден в окне — беседа одна.
  • Длинный ответ в Telegram обрезается со ссылкой «Открыть окно».
  • Подтверждение действия. Если ассистенту в этом ходе нужно ваше подтверждение (создать задачу, принять результат, вызвать скилл), бот пришлёт сообщение с кнопками «Разрешить» и «Отклонить». Тот же запрос виден в окне: засчитывается первый ответ.
  • Уведомления платформы (решения, результаты на проверке) приходят как раньше — см. Telegram.

Без привязки — никуда

Текст из аккаунта Telegram, не привязанного к учётной записи, дальше сервиса уведомлений не уходит: бот подскажет, как привязать аккаунт. Сообщения в группах беседой не считаются.

Как это устроено

sequenceDiagram
    participant P as Человек (Telegram)
    participant N as notification-service
    participant L as harness-launcher
    participant H as Рабочее место
    P->>N: текст в личном чате
    N->>L: POST /_launcher/internal/principals/{id}/inbound (service-токен, harness:inbound)
    L->>H: /internal/harness/inbound (секрет контейнера)
    H->>H: ход ассистента (источник channel)
    H->>N: POST /api/v1/notifications (токен человека, notifications:send)
    N->>P: ответ в чат
  • Вход. notification-service находит человека по привязанному аккаунту и передаёт текст launcher'у своим service account (audience human-harness, scope harness:inbound). Launcher будит контейнер, если он спал, и дописывает реплику в беседу.
  • Ответ. Рабочее место отправляет последний ответ хода уведомлением самому человеку его собственным токеном (audience notification-service, scope notifications:send). Канал выбирается по предпочтениям человека.
  • Подтверждение. Кнопки несут data.kind = "harness_approval" и случайный requestId. Нажатие принимается только в личном чате адресата, записывается один раз на callback и возвращается тем же inbound как {approval: {id, decision}}. Рабочее место знает только свои requestId: чужое или запоздалое нажатие ничего не меняет. Если канал недоступен, запрос остаётся за окном.

Включение

Нужны профили notify и harness (см. Рабочее место человека) и настроенный бот (Telegram).

Что Где
Адрес launcher'а для сервиса уведомлений NS_HARNESS_LAUNCHER_URL (в compose — http://harness-launcher:8080/harness)
Право service account сервиса уведомлений audience human-harness, scope harness:inbound — заводит bootstrap; при росте потолка он перевыпускает service account
Право человека отправлять себе уведомления PAT человека на audiences control-plane и notification-service (notifications:send) — bootstrap, шаг --harness-people; старый PAT перевыпускается при смене потолка
Адрес сервиса уведомлений для рабочего места HARNESS_NOTIFY_URL в LAUNCHER_HARNESS_ENV

После перевыпуска PAT контейнер человека нужно пересоздать (docker rm -f harness-<principal-id>, volume с беседой остаётся) — launcher создаст его заново с новым окружением при следующем запросе.

Типичные проблемы

Симптом Причина
Бот отвечает «не привязан» Аккаунт не привязан или отвязан (/unlink) — привязать кодом из веб-интерфейса
«Ассистент сейчас недоступен» launcher не ответил или сервис уведомлений не получил service-токен (нет audience human-harness)
«Нет рабочего места с ассистентом» Человека нет в реестре людей launcher'а
Текст дошёл, ответа в чате нет PAT человека без audience notification-service — перевыпустить (bootstrap) и пересоздать контейнер

См. также