🏠 Главная › User Guide › yuanbao

sidebar_position: 16 title: "Yuanbao" description: "Connect Hermes Agent to the Yuanbao enterprise messaging platform via WebSocket gateway" lang: ru

Юаньбао

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

:::информация Yuanbao — это корпоративная платформа обмена сообщениями, которая в основном используется в Tencent и корпоративных средах. Он использует WebSocket для связи в реальном времени, аутентификацию на основе HMAC и поддерживает мультимедийные файлы, включая изображения, файлы и голосовые сообщения.

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

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

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

При появлении запроса выберите Юаньбао. Мастер:

  1. Запросите свой APP_ID
  2. Попросите свой APP_SECRET.
  3. Автоматическое сохранение конфигурации.

:::совет URL-адрес WebSocket и домен API имеют разумные встроенные значения по умолчанию. Для начала вам нужно только указать APP_ID и APP_SECRET.

3. Настройка переменных среды

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

# Required
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

# Optional: bot account ID (normally obtained automatically from sign-token)
# YUANBAO_BOT_ID=your-bot-id

# Optional: internal routing environment (e.g. test/staging/production)
# YUANBAO_ROUTE_ENV=production

# Optional: home channel for cron/notifications (format: direct:<account> or group:<group_code>)
YUANBAO_HOME_CHANNEL=direct:bot_account_id
YUANBAO_HOME_CHANNEL_NAME="Bot Notifications"

# Optional: restrict access (legacy, see Access Control below for fine-grained policies)
YUANBAO_ALLOWED_USERS=user_account_1,user_account_2

4. Запустите шлюз

hermes gateway

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

Особенности

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

Форматы идентификаторов чата

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

Тип чата Формат Пример
Прямое сообщение (C2C) direct:<account> direct:user123
Групповое сообщение group:<group_code> group:grp456

Медиа-загрузки

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

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

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

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

:::совет Если домашний канал не настроен, первый пользователь, отправивший сообщение боту, будет автоматически назначен владельцем домашнего канала. Если текущий домашний канал является групповым чатом, первый DM обновит его до прямого канала. Вы также можете установить его вручную в ~/.hermes/.env:

YUANBAO_HOME_CHANNEL=direct:user_account_id
# or for a group:
# YUANBAO_HOME_CHANNEL=group:group_code
YUANBAO_HOME_CHANNEL_NAME="My Bot Updates"

Пример: установка домашнего канала

  1. Начать разговор с ботом в Юаньбао
  2. Отправьте команду: /sethome
  3. Бот отвечает: «Домашний канал установлен на [chat_name] с идентификатором [chat_id]. Задания Cron будут доставляться в это место».
  4. Будущие задания cron и уведомления будут отправляться на этот канал.

Пример: доставка заданий Cron

Создайте задание cron:

/cron "0 9 * * *" Check server status

Запланированный выпуск будет транслироваться на ваш домашний канал Yuanbao каждый день в 9 утра.

Советы по использованию

Начало разговора

Отправьте любое сообщение боту в Юаньбао:

hello

Бот отвечает в той же ветке разговора.

Доступные команды

На Юаньбао работают все стандартные команды Гермеса:

Команда Описание
/new Начать новый разговор
/model [provider:model] Показать или изменить модель
/sethome Установить этот чат как домашний канал
/status Показать информацию о сеансе
/help Показать доступные команды

Отправка файлов

Чтобы отправить файл боту, просто прикрепите его прямо в чате Yuanbao. Бот автоматически загрузит и обработает вложенный файл.

Вы также можете добавить сообщение с вложением:

Please analyze this document

Получение файлов

Когда вы просите бота создать или экспортировать файл, он отправляет его прямо в ваш чат Yuanbao.

Устранение неполадок

Бот онлайн, но не отвечает на сообщения

Причина: не удалось выполнить аутентификацию во время установления связи через WebSocket.

Исправление: 1. Убедитесь, что APP_ID и APP_SECRET верны. 2. Убедитесь, что URL-адрес WebSocket доступен. 3. Убедитесь, что у учетной записи бота есть соответствующие разрешения. 4. Просмотрите журналы шлюза: tail -f ~/.hermes/logs/gateway.log.

Ошибка «Соединение отклонено»

Причина: URL-адрес WebSocket недоступен или неверен.

Исправление: 1. Проверьте формат URL-адреса WebSocket (должен начинаться с wss://). 2. Проверьте сетевое подключение к домену Yuanbao API. 3. Убедитесь, что брандмауэр разрешает соединения WebSocket. 4. Проверьте URL-адрес с помощью: curl -I https://[YUANBAO_API_DOMAIN].

Не удалось загрузить медиафайлы

Причина: учетные данные COS недействительны или медиасервер недоступен.

Исправление: 1. Убедитесь, что API_DOMAIN верен. 2. Убедитесь, что для вашего бота включены разрешения на загрузку мультимедиа. 3. Убедитесь, что медиа-файл доступен и не поврежден. 4. Проверьте конфигурацию сегмента COS у администратора платформы.

Сообщения не доставлены на домашний канал

Причина: неверный формат идентификатора домашнего канала или не запущено задание cron.

Исправление: 1. Убедитесь, что YUANBAO_HOME_CHANNEL имеет правильный формат. 2. Проверьте с помощью команды /sethome, чтобы автоматически определить правильный формат. 3. Проверьте расписание заданий cron с помощью /status. 4. Убедитесь, что у бота есть разрешения на отправку в целевой чат.

Частые отключения

Причина: соединение WebSocket нестабильно или сеть ненадежна.

Исправление: 1. Проверьте журналы шлюза на наличие шаблонов ошибок. 2. Увеличьте время ожидания пульса в настройках соединения. 3. Обеспечьте стабильное сетевое соединение с API Yuanbao. 4. Рассмотрите возможность включения подробного журналирования: HERMES_LOG_LEVEL=debug

Контроль доступа

Yuanbao поддерживает детальный контроль доступа как для личных сообщений, так и для групповых разговоров:

# DM policy: open (default) | allowlist | disabled
YUANBAO_DM_POLICY=open
# Comma-separated user IDs allowed to DM the bot (only used when DM_POLICY=allowlist)
YUANBAO_DM_ALLOW_FROM=user_id_1,user_id_2

# Group policy: open (default) | allowlist | disabled
YUANBAO_GROUP_POLICY=open
# Comma-separated group codes allowed (only used when GROUP_POLICY=allowlist)
YUANBAO_GROUP_ALLOW_FROM=group_code_1,group_code_2

Их также можно установить в config.yaml:

platforms:
  yuanbao:
    extra:
      dm_policy: allowlist
      dm_allow_from: "user1,user2"
      group_policy: open
      group_allow_from: ""

Расширенная конфигурация

Разделение сообщений

Yuanbao имеет максимальный размер сообщения. Hermes автоматически разбивает большие ответы на части с помощью разделения с учетом Markdown (учитывает границы кода, таблицы и границы абзацев).

Параметры подключения

Следующие параметры подключения встроены в адаптер с разумными значениями по умолчанию:

Параметр Значение по умолчанию Описание
Тайм-аут подключения WebSocket 15 секунд Время ждать рукопожатия WS
Интервал сердцебиения 30 секунд Частота Ping для поддержания соединения
Максимальное количество попыток переподключения 100 Максимальное количество попыток переподключения
Повторное подключение отсрочки 1 с → 60 с (экспоненциальная) Время ожидания между попытками переподключения
Ответить интервал сердцебиения 2 секунды Частота отправки статуса РАБОТАЕТ
Отправить тайм-аут 30 секунд Тайм-аут исходящих WS-сообщений

:::примечание Эти значения в настоящее время невозможно настроить с помощью переменных среды. Они оптимизированы для типичных развертываний Yuanbao.

Подробное ведение журнала

Включите ведение журнала отладки, чтобы устранить проблемы с подключением:

HERMES_LOG_LEVEL=debug hermes gateway

Интеграция с другими функциями

Задания Крон

Запланируйте задачи, которые выполняются на Yuanbao:

/cron "0 */4 * * *" Report system health

Результаты доставляются на ваш домашний канал.

Фоновые задачи

Выполняйте длинные операции, не блокируя разговор:

/background Analyze all files in the archive

Межплатформенные сообщения

Отправьте сообщение из CLI в Yuanbao:

hermes chat -q "Send 'Hello from CLI' to yuanbao:group:group_code"

Сопутствующая документация