Yuanbao

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

Что понадобится

• Аккаунт Yuanbao с правами на создание ботов
• APP_ID и APP_SECRET от Yuanbao (выдаёт администратор платформы)
• Python-пакеты: websockets и httpx — оба входят в основные зависимости Hermes

Если эти основные зависимости повреждены, почините выбранное окружение:

hermes pm repair

Настройка

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

1. Скачайте приложение Yuanbao с https://yuanbao.tencent.com/
2. В приложении откройте PAI → My Bot и создайте нового бота
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="Bot Notifications"

# Необязательно: ограничить доступ (устаревший вариант; гибкие политики см. в разделе «Контроль доступа» ниже)
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, наращивая паузу по экспоненте
• Запросы информации о группе — получение сведений о группе и списка участников
• Стикеры и эмодзи — отправка стикеров TIMFaceElem и эмодзи в чатах
• Поддержка пересланной истории чата WeChat — когда пользователь пересылает в Yuanbao пакет истории чата WeChat, адаптер декодирует пересланные записи (никнеймы отправителей, текст и мультимедийные вложения, включая вложенные пересылки) и добавляет их в диалог, чтобы агент мог прочитать всю пересланную переписку
• Auto-sethome — первый написавший боту пользователь автоматически становится владельцем домашнего канала
• Уведомление о медленном ответе — если агент думает дольше обычного, бот пришлёт сообщение об ожидании

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

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

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

Загрузка медиафайлов

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

• Изображения: JPEG, PNG, GIF, WebP
• Файлы: все распространённые типы документов
• Голос: WAV, MP3, OGG

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

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

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

Можно задать канал и вручную в ~/.hermes/.env:

YUANBAO_HOME_CHANNEL=direct:user_account_id
# или для группы:
# YUANBAO_HOME_CHANNEL=group:group_code
YUANBAO_HOME_CHANNEL_NAME="My Bot Updates"

Пример: назначение домашнего канала

1. Начните диалог с ботом в Yuanbao
2. Отправьте команду: /sethome
3. Бот ответит: «Home channel set to [chat_name] with ID [chat_id]. Cron jobs will deliver to this location.»
4. Дальше cron-задачи и уведомления будут приходить в этот канал

Пример: доставка результата cron-задачи

Создайте cron-задачу:

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

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

Полезные советы

Как начать диалог

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

hello

Бот ответит в той же ветке диалога.

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

В Yuanbao работают все стандартные команды Hermes:

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

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

Вместе с вложением можно отправить и текст:

Please analyze this document

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

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

Решение проблем

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

Причина: не прошла аутентификация при рукопожатии WebSocket.

Решение:

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

Ошибка «Connection refused»

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

Решение:

1. Проверьте формат адреса WebSocket (должен начинаться с wss://)
2. Проверьте сетевую доступность домена API Yuanbao
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. Увеличьте таймаут heartbeat в настройках соединения
3. Обеспечьте стабильное соединение с API Yuanbao
4. Включите подробное логирование: hermes gateway run -vv

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

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

# Политика для личных сообщений: 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

То же самое можно задать в config.yaml:

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

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

Разбиение сообщений на части

У Yuanbao есть предел на размер сообщения. Hermes сам делит длинные ответы с учётом разметки Markdown — не ломая блоки кода, таблицы и границы абзацев.

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

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

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

Чтобы разобраться с проблемами соединения, включите отладочные логи:

hermes gateway run -vv

Связка с другими возможностями

Cron-задачи

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

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

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

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

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

/bg Analyze all files in the archive

Сообщения между платформами

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

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

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

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