WeCom (Корпоративный WeChat)

Подключите Hermes к WeCom (企业微信), корпоративной мессенджер-платформе от Tencent. Адаптер использует WebSocket-шлюз AI Bot от WeCom для двусторонней связи в реальном времени — не требует публичного эндпоинта или webhook.

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

• Учётная запись организации WeCom

• AI Bot, созданный в консоли администратора WeCom

• Bot ID и Secret со страницы учётных данных бота

• Python-пакеты: aiohttp и httpx

Настройка

Шаг 1: Создание AI Bot

Рекомендуется: Сканирование для создания (одна команда)

hermes gateway setup

Выберите WeCom и отсканируйте QR-код с помощью мобильного приложения WeCom. Hermes автоматически создаст приложение-бота с правильными разрешениями и сохранит учётные данные.

Мастер настройки выполнит:

1. Отображение QR-кода в вашем терминале

2. Ожидание сканирования с помощью мобильного приложения WeCom

3. Автоматическое получение Bot ID и Secret

4. Проведение по настройке контроля доступа

Альтернатива: Ручная настройка

Если сканирование недоступно, мастер переключается на ручной ввод:

1. Войдите в Консоль администратора WeCom

2. Перейдите в Приложения → Создать приложение → AI Bot

3. Настройте имя и описание бота

4. Скопируйте Bot ID и Secret со страницы учётных данных

5. Запустите hermes gateway setup, выберите WeCom и введите учётные данные по запросу

Шаг 2: Настройка Hermes

Вариант A: Интерактивная настройка (рекомендуется)

hermes gateway setup

Выберите WeCom и следуйте подсказкам. Мастер проведёт вас через:

• Учётные данные бота (через сканирование QR или ручной ввод)

• Настройки контроля доступа (белый список, режим сопряжения или открытый доступ)

• Домашний канал для уведомлений

Вариант B: Ручная настройка

Добавьте следующее в ~/.hermes/.env:

WECOM_BOT_ID=your-bot-id
WECOM_SECRET=your-secret

# Optional: restrict access
WECOM_ALLOWED_USERS=user_id_1,user_id_2

# Optional: home channel for cron/notifications
WECOM_HOME_CHANNEL=chat_id

Шаг 3: Запуск gateway

hermes gateway

Возможности

• WebSocket-транспорт — постоянное соединение, не требует публичного эндпоинта

• Личные и групповые сообщения — настраиваемые политики доступа

• Белые списки отправителей по группам — точный контроль того, кто может взаимодействовать в каждой группе

• Поддержка медиа — загрузка и скачивание изображений, файлов, голоса, видео

• AES-зашифрованные медиа — автоматическая расшифровка входящих вложений

• Контекст цитирования — сохраняет структуру переписки при ответах

• Рендеринг Markdown — форматированные текстовые ответы

• Потоковая передача в режиме ответа — связывает ответы с контекстом входящего сообщения

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

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

Установите их в config.yaml в разделе platforms.wecom.extra:

Политики доступа

Политика ЛС

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

WECOM_DM_POLICY=allowlist

Политика групп

Определяет, в каких группах бот отвечает:

WECOM_GROUP_POLICY=allowlist

Белые списки отправителей по группам

Для точного контроля можно ограничить, какие пользователи могут взаимодействовать с ботом в определённых группах. Это настраивается в config.yaml:

platforms:
  wecom:
    enabled: true
    extra:
      bot_id: "your-bot-id"
      secret: "your-secret"
      group_policy: "allowlist"
      group_allow_from:
        - "group_id_1"
        - "group_id_2"
      groups:
        group_id_1:
          allow_from:
            - "user_alice"
            - "user_bob"
        group_id_2:
          allow_from:
            - "user_charlie"
        "*":
          allow_from:
            - "user_admin"

Как это работает:

1. Параметры group_policy и group_allow_from определяют, разрешена ли группа в принципе.

2. Если группа проходит верхнеуровневую проверку, список groups.<group_id>.allow_from (если указан) дополнительно ограничивает, какие отправители внутри этой группы могут взаимодействовать с ботом.

3. Запись группы "*" служит значением по умолчанию для групп, не указанных явно.

4. Записи в белом списке поддерживают символ * для разрешения всех пользователей, и записи не чувствительны к регистру.

5. Записи могут опционально использовать префиксы wecom:user: или wecom:group: — префикс автоматически удаляется.

Если для группы не настроен allow_from, все пользователи в этой группе разрешены (при условии, что сама группа проходит верхнеуровневую проверку политики).

Поддержка медиа

Входящие (получение)

Адаптер получает медиа-вложения от пользователей и кэширует их локально для обработки агентом:

Цитируемые сообщения: Медиа из цитируемых (на которые дан ответ) сообщений также извлекается, чтобы агент имел контекст того, на что отвечает пользователь.

Расшифровка AES-зашифрованных медиа

WeCom шифрует некоторые входящие медиа-вложения с помощью AES-256-CBC. Адаптер обрабатывает это автоматически:

• Когда входящий медиа-элемент содержит поле aeskey, адаптер скачивает зашифрованные байты и расшифровывает их с использованием AES-256-CBC с PKCS#7-выравниванием.

• AES-ключ — это декодированное из base64 значение поля aeskey (должно быть ровно 32 байта).

• IV (вектор инициализации) формируется из первых 16 байт ключа.

• Для этого требуется Python-пакет cryptography (pip install cryptography).

Никакой дополнительной настройки не требуется — расшифровка происходит прозрачно при получении зашифрованного медиа.

Исходящие (отправка)

Фрагментированная загрузка: Файлы загружаются фрагментами по 512 КБ через трёхэтапный протокол (init → chunks → finish). Адаптер обрабатывает это автоматически.

Автоматическое понижение: Когда медиа превышает лимит размера для нативного типа, но не превышает абсолютный лимит в 20 МБ, оно автоматически отправляется как обычное файловое вложение:

• Изображения > 10 МБ → отправляются как файл

• Видео > 10 МБ → отправляются как файл

• Голос > 2 МБ → отправляется как файл

• Аудио не в формате AMR → отправляется как файл (WeCom поддерживает только AMR для нативного голоса)

Файлы, превышающие абсолютный лимит в 20 МБ, отклоняются с отправкой информационного сообщения в чат.

Потоковые ответы в режиме ответа

Когда бот получает сообщение через callback WeCom, адаптер запоминает ID входящего запроса. Если ответ отправляется, пока контекст запроса ещё активен, адаптер использует режим ответа WeCom (aibot_respond_msg) с потоковой передачей, чтобы связать ответ непосредственно с входящим сообщением. Это обеспечивает более естественный опыт общения в клиенте WeCom.

Если контекст входящего запроса истёк или недоступен, адаптер переключается на упреждающую отправку сообщения через aibot_send_msg.

Режим ответа также работает для медиа: загруженные медиафайлы могут быть отправлены как ответ на исходное сообщение.

Подключение и переподключение

Адаптер поддерживает постоянное WebSocket-соединение со шлюзом WeCom по адресу wss://openws.work.weixin.qq.com.

Жизненный цикл соединения

1. Подключение: Открывает WebSocket-соединение и отправляет аутентификационный фрейм aibot_subscribe с bot_id и secret.

2. Heartbeat: Отправляет ping-фреймы прикладного уровня каждые 30 секунд для поддержания соединения.

3. Прослушивание: Непрерывно читает входящие фреймы и диспетчеризует callback'и сообщений.

Поведение при переподключении

При потере соединения адаптер использует экспоненциальную задержку для переподключения:

После каждого успешного переподключения счётчик задержки сбрасывается. Все ожидающие фьючерсы запросов завершаются ошибкой при отключении, чтобы вызывающие стороны не зависали бесконечно.

Дедупликация

Входящие сообщения дедуплицируются с использованием ID сообщений в окне 5 минут с максимальным кэшем на 1000 записей. Это предотвращает двойную обработку сообщений во время переподключения или сетевых сбоев.

Все переменные окружения

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