Yuanbao

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

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

• Учётная запись Yuanbao с правами на создание бота
• APP_ID и APP_SECRET Yuanbao (от администратора платформы)
• Пакеты Python: websockets и httpx
• Для поддержки медиа: aiofiles

Установите необходимые зависимости: [code] pip install websockets httpx aiofiles

[/code]

Настройка​

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

1. Скачайте приложение Yuanbao с https://yuanbao.tencent.com/
2. В приложении перейдите в PAI → Мой бот и создайте нового бота
3. После создания бота скопируйте APP_ID и APP_SECRET

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

Самый простой способ настроить Yuanbao — через интерактивный мастер: [code] hermes gateway setup

[/code] Выберите Yuanbao при появлении запроса. Мастер выполнит: 1. Запросит ваш APP_ID 2. Запросит ваш APP_SECRET 3. Сохранит конфигурацию автоматически

tip URL WebSocket и домен API имеют разумные значения по умолчанию. Вам нужно указать только APP_ID и APP_SECRET для начала работы.

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

После начальной настройки проверьте эти переменные в ~/.hermes/.env: [code] # Обязательные
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="Уведомления бота"

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

[/code]

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

[code] hermes gateway

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

Возможности​

• WebSocket-шлюз — двусторонняя связь в реальном времени
• HMAC-аутентификация — безопасная подпись запросов с APP_ID/APP_SECRET
• C2C-обмен сообщениями — прямые беседы пользователя с ботом
• Групповой обмен сообщениями — беседы в групповых чатах
• Поддержка медиа — изображения, файлы и голосовые сообщения через COS (Cloud Object Storage)
• Markdown-форматирование — сообщения автоматически разбиваются на части с учётом ограничений Yuanbao по размеру
• Дедупликация сообщений — предотвращает повторную обработку одного и того же сообщения
• Heartbeat/keep-alive — поддержание стабильности WebSocket-соединения
• Индикаторы набора текста — отображает статус «печатает…», пока агент обрабатывает запрос
• Автоматическое переподключение — обработка разрывов WebSocket с экспоненциальной задержкой
• Запрос информации о группе — получение сведений о группе и списка участников
• Поддержка стикеров/эмодзи — отправка стикеров TIMFaceElem и эмодзи в беседах
• Авто-домашний канал — первый пользователь, написавший боту, автоматически становится владельцем домашнего канала
• Уведомление о медленном ответе — отправка сообщения об ожидании, когда агент обрабатывает запрос дольше ожидаемого

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

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

Yuanbao использует идентификаторы с префиксами в зависимости от типа беседы: Тип чата| Формат| Пример
---|---|---
Личное сообщение (C2C)| direct:<account>| direct:user123
Групповое сообщение| group:<group_code>| group:grp456

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

Адаптер Yuanbao автоматически обрабатывает загрузку медиа через COS (Tencent Cloud Object Storage): * Изображения : поддерживаются JPEG, PNG, GIF, WebP * Файлы : поддерживаются все распространённые типы документов * Голос : поддерживаются WAV, MP3, OGG

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

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

Используйте команду /sethome в любом чате Yuanbao (личном или групповом), чтобы назначить его домашним каналом. Запланированные задачи (cron-задания) доставляют свои результаты в этот канал. Авто-домашний канал Если домашний канал не настроен, первый пользователь, написавший боту, автоматически становится владельцем домашнего канала. Если текущий домашний канал — это групповая беседа, первое личное сообщение переключит его на личный канал. Вы также можете настроить его вручную в ~/.hermes/.env: [code] YUANBAO_HOME_CHANNEL=direct:user_account_id
# или для группы:
# YUANBAO_HOME_CHANNEL=group:group_code
YUANBAO_HOME_CHANNEL_NAME="Мои обновления бота"

[/code]

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

1. Начните разговор с ботом в Yuanbao
2. Отправьте команду: /sethome
3. Бот отвечает: «Домашний канал установлен на [имя_чата] с ID [id_чата]. Cron-задания будут доставляться сюда.»
4. Будущие cron-задания и уведомления будут отправляться в этот канал

Пример: Доставка cron-заданий​

Создайте cron-задание: [code] /cron "0 9 * * *" Проверить статус сервера

[/code] Результат выполнения будет доставляться в ваш домашний канал Yuanbao каждый день в 9:00.

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

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

Отправьте любое сообщение боту в Yuanbao: [code] hello

[/code] Бот отвечает в той же ветке разговора.

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

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

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

Чтобы отправить файл боту, просто прикрепите его в чате Yuanbao. Бот автоматически загрузит и обработает вложение. Вы также можете добавить сообщение к вложению: [code] Пожалуйста, проанализируйте этот документ

[/code]

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

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

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

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

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

Ошибка «Connection refused»​

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

Загрузка медиа не удаётся​

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

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

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

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

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

Управление доступом​

Yuanbao поддерживает детальное управление доступом для личных и групповых бесед: [code] # Политика ЛС: open (по умолчанию) | allowlist | disabled
YUANBAO_DM_POLICY=open
# Разделённые запятыми ID пользователей, которым разрешено писать боту в ЛС (используется только при DM_POLICY=allowlist)
YUANBAO_DM_ALLOW_FROM=user_id_1,user_id_2

# Политика групп: open (по умолчанию) | allowlist | disabled  
YUANBAO_GROUP_POLICY=open  
# Разделённые запятыми коды групп, которым разрешено (используется только при GROUP_POLICY=allowlist)  
YUANBAO_GROUP_ALLOW_FROM=group_code_1,group_code_2

[/code] Эти настройки также можно указать в config.yaml: [code] platforms:
yuanbao:
extra:
dm_policy: allowlist
dm_allow_from: "user1,user2"
group_policy: open
group_allow_from: ""

[/code]

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

Разбиение сообщений​

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

Параметры соединения​

Следующие параметры соединения встроены в адаптер с разумными значениями по умолчанию: Параметр| Значение по умолчанию| Описание
---|---|---
Таймаут подключения WebSocket| 15 секунд| Время ожидания WebSocket-рукопожатия
Интервал heartbeat| 30 секунд| Частота ping для поддержания соединения
Макс. попыток переподключения| 100| Максимальное количество попыток переподключения
Задержка переподключения| 1с → 60с (экспоненциально)| Время ожидания между попытками переподключения
Интервал ответного heartbeat| 2 секунды| Частота отправки статуса RUNNING
Таймаут отправки| 30 секунд| Таймаут для исходящих WS-сообщений
note В настоящее время эти значения нельзя настроить через переменные окружения. Они оптимизированы для типичных развёртываний Yuanbao.

Подробное логирование​

Включите отладочное логирование для устранения проблем с подключением: [code] HERMES_LOG_LEVEL=debug hermes gateway

[/code]

Интеграция с другими возможностями​

Cron-задания​

Планируйте задачи, которые выполняются через Yuanbao: [code] /cron "0 /4 * * " Отчёт о состоянии системы

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

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

Запускайте длительные операции без блокировки разговора: [code] /background Проанализировать все файлы в архиве

[/code]

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

Отправка сообщения из CLI в Yuanbao: [code] hermes chat -q "Отправить 'Привет из CLI' в yuanbao:group:group_code"

[/code]

Связанная документация​

• Обзор шлюза сообщений
• Справочник слэш-команд
• Cron-задания

• Фоновые сессии

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

• Настройка
  • 1. Создание бота в Yuanbao
  • 2. Запуск мастера настройки
  • 3. Настройка переменных окружения
  • 4. Запуск шлюза
• Возможности
• Параметры конфигурации
  • Форматы ID чатов
  • Загрузка медиа
• Домашний канал
  • Пример: Установка домашнего канала
  • Пример: Доставка cron-заданий
• Советы по использованию
  • Начало разговора
  • Доступные команды
  • Отправка файлов
  • Получение файлов
• Устранение неполадок
  • Бот онлайн, но не отвечает на сообщения
  • Ошибка «Connection refused»
  • Загрузка медиа не удаётся
  • Сообщения не доставляются в домашний канал
  • Частые разрывы соединения
• Управление доступом
• Расширенная конфигурация
  • Разбиение сообщений
  • Параметры соединения
  • Подробное логирование
• Интеграция с другими возможностями
  • Cron-задания
  • Фоновые задачи
  • Кроссплатформенные сообщения
• Связанная документация