Yuanbao

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

к сведению

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

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

• Учётная запись 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 — через интерактивный мастер:

vibeos gateway setup

При появлении запроса выберите Yuanbao. Мастер выполнит следующие действия:

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

подсказка

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

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

После начальной настройки проверьте эти переменные в ~/.vibeos/.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="Уведомления бота"

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

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

vibeos gateway

Адаптер подключится к 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-задания) доставляют свои результаты в этот канал.

Автоустановка дома

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

Вы также можете установить его вручную в ~/.vibeos/.env:

YUANBAO_HOME_CHANNEL=direct:user_account_id
# или для группы:
# YUANBAO_HOME_CHANNEL=group:group_code
YUANBAO_HOME_CHANNEL_NAME="Обновления моего бота"

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

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

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

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

/cron "0 9 * * *" Проверить статус сервера

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

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

Начало беседы

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

привет

Бот ответит в той же ветке беседы.

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

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

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

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

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

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

Пожалуйста, проанализируйте этот документ

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

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

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

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

Причина: Сбой аутентификации при рукопожатии WebSocket.

Решение:

1. Проверьте правильность APP_ID и APP_SECRET
2. Убедитесь, что URL WebSocket доступен
3. Убедитесь, что учётная запись бота имеет соответствующие разрешения
4. Просмотрите журналы шлюза: tail -f ~/.vibeos/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. Рассмотрите возможность включения подробного логирования: VIBEOS_LOG_LEVEL=debug

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

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 имеет максимальный размер сообщения. VibeOS автоматически разбивает большие ответы на части с учётом Markdown (соблюдая границы блоков кода, таблиц и абзацев).

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

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

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

примечание

В настоящее время эти значения не настраиваются через переменные окружения. Они оптимизированы для типичных развёртываний Yuanbao.

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

Включите отладочное логирование для устранения неполадок соединения:

VIBEOS_LOG_LEVEL=debug vibeos gateway

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

Cron-задания

Планируйте задачи, выполняемые в Yuanbao:

/cron "0 */4 * * *" Отчёт о состоянии системы

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

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

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

/background Проанализировать все файлы в архиве

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

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

vibeos chat -q "Отправить 'Привет из CLI' в yuanbao:group:group_code"

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

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