Yuanbao

Подключите Hermes к Yuanbao, корпоративной платформе обмена сообщениями от Tencent. Адаптер использует WebSocket-шлюз для доставки сообщений в реальном времени и поддерживает как прямые (C2C), так и групповые беседы.

Предварительные требования

• Учётная запись Yuanbao с правами на создание бота

• APP_ID и APP_SECRET Yuanbao (от администратора платформы)

• Пакеты Python: websockets и httpx

• Для поддержки медиа: aiofiles

Установите необходимые зависимости:

pip install websockets httpx aiofiles

Настройка

1. Создание бота в Yuanbao

1. Загрузите приложение Yuanbao с https://yuanbao.tencent.com/

2. В приложении перейдите в PAI → Мой бот и создайте нового бота

3. После создания бота скопируйте APP_ID и APP_SECRET

2. Запуск мастера настройки

Самый простой способ настроить Yuanbao — через интерактивный мастер:

hermes gateway setup

Выберите Yuanbao при запросе. Мастер выполнит:

1. Запросит ваш APP_ID

2. Запросит ваш APP_SECRET

3. Автоматически сохранит конфигурацию

3. Настройка переменных окружения

После начальной настройки проверьте эти переменные в ~/.hermes/.env:

# Обязательно
YUANBAO_APP_ID=your-app-id
YUANBAO_APP_SECRET=your-app-secret
YUANBAO_WS_URL=wss://api.yuanbao.example.com/ws
YUANBAO_API_DOMAIN=https://api.yuanbao.example.com

# Опционально: ID учётной записи бота (обычно получается автоматически из sign-token)
# YUANBAO_BOT_ID=your-bot-id

# Опционально: внутренняя среда маршрутизации (например, test/staging/production)
# YUANBAO_ROUTE_ENV=production

# Опционально: домашний канал для cron/уведомлений (формат: direct:<account> или group:<group_code>)
YUANBAO_HOME_CHANNEL=direct:bot_account_id
YUANBAO_HOME_CHANNEL_NAME="Уведомления бота"

# Опционально: ограничение доступа (устаревшее, см. Access Control ниже для детальных политик)
YUANBAO_ALLOWED_USERS=user_account_1,user_account_2

4. Запуск шлюза

hermes gateway

Адаптер подключится к WebSocket-шлюзу Yuanbao, выполнит аутентификацию с помощью HMAC-подписей и начнёт обработку сообщений.

Возможности

• WebSocket-шлюз — двусторонняя связь в реальном времени

• HMAC-аутентификация — безопасная подпись запросов с APP_ID/APP_SECRET

• C2C-сообщения — прямые беседы пользователя с ботом

• Групповые сообщения — беседы в групповых чатах

• Поддержка медиа — изображения, файлы и голосовые сообщения через COS (Cloud Object Storage)

• Форматирование Markdown — сообщения автоматически разбиваются с учётом ограничений Yuanbao на размер

• Дедупликация сообщений — предотвращает повторную обработку одного и того же сообщения

• Heartbeat/keep-alive — поддержание стабильности WebSocket-соединения

• Индикаторы набора текста — отображает статус «печатает…» во время обработки запроса агентом

• Автоматическое переподключение — обрабатывает разрывы WebSocket с экспоненциальной задержкой

• Запрос информации о группе — получение сведений о группе и списка участников

• Поддержка стикеров/Emoji — отправка стикеров TIMFaceElem и emoji в беседах

• Авто-домашний канал — первый пользователь, написавший боту, автоматически устанавливается владельцем домашнего канала

• Уведомление о медленном ответе — отправляет сообщение об ожидании, когда агент отвечает дольше обычного

Параметры конфигурации

Форматы ID чатов

Yuanbao использует идентификаторы с префиксами в зависимости от типа беседы:

Загрузка медиа

Адаптер Yuanbao автоматически обрабатывает загрузку медиа через COS (Tencent Cloud Object Storage):

• Изображения: поддерживает JPEG, PNG, GIF, WebP

• Файлы: поддерживает все распространённые типы документов

• Голос: поддерживает WAV, MP3, OGG

URL-адреса медиа автоматически проверяются и загружаются перед отправкой для предотвращения SSRF-атак.

Домашний канал

Используйте команду /sethome в любом чате Yuanbao (ЛС или группа), чтобы назначить его домашним каналом. Запланированные задачи (cron) доставляют свои результаты в этот канал.