Weixin (WeChat)

Команды установки Python-зависимостей на этой странице рассчитаны на чекаут исходников, подготовленный через PM. После изменения зависимостей заново активируйте чекаут и перезапустите Hermes.

Подключите Hermes к WeChat (微信) — личному мессенджеру от Tencent. Адаптер работает через iLink Bot API Tencent для персональных аккаунтов WeChat; это не то же самое, что WeCom (корпоративный WeChat). Сообщения приходят по long-polling, поэтому публичный эндпоинт или вебхук не нужны.

Требования

• Личный аккаунт WeChat
• Python-пакеты: aiohttp и cryptography
• Отрисовка QR в терминале идёт в комплекте, если Hermes установлен с extra-пакетом messaging

Установите нужные зависимости:

# Включает aiohttp и поддержку QR-кода в терминале
python -c "import pm; pm.sync_venv(['messaging'], explicit=True)"

Установка

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

Проще всего подключить аккаунт WeChat через интерактивную настройку:

hermes gateway setup

Когда появится выбор, укажите Weixin. Мастер сделает следующее:

1. Запросит QR-код у iLink Bot API
2. Покажет QR-код в терминале (или даст URL)
3. Подождёт, пока вы отсканируете код мобильным приложением WeChat
4. Попросит подтвердить вход на телефоне
5. Автоматически сохранит учётные данные аккаунта в ~/.hermes/weixin/accounts/

После подтверждения вы увидите сообщение вроде такого:

微信连接成功，account_id=your-account-id

Мастер сохранит account_id, token и base_url, так что прописывать их вручную не придётся.

2. Задайте переменные окружения

После первого входа по QR пропишите как минимум ID аккаунта в ~/.hermes/.env:

WEIXIN_ACCOUNT_ID=your-account-id

# Опционально: переопределить токен (обычно сохраняется сам после входа по QR)
# WEIXIN_TOKEN=your-bot-token

# Опционально: ограничить доступ
WEIXIN_DM_POLICY=open
WEIXIN_ALLOWED_USERS=user_id_1,user_id_2

# Опционально: вернуть прежнее поведение с разбиением многострочных сообщений
# WEIXIN_SPLIT_MULTILINE_MESSAGES=true

# Опционально: домашний канал для cron и уведомлений
WEIXIN_HOME_CHANNEL=chat_id
WEIXIN_HOME_CHANNEL_NAME=Home

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

hermes gateway

Адаптер восстановит сохранённые учётные данные, подключится к iLink API и начнёт long-polling за сообщениями.

Возможности

• Транспорт на long-poll — публичный эндпоинт, вебхук или WebSocket не требуются
• Вход по QR-коду — подключение сканированием через hermes gateway setup
• Личные сообщения — настраиваемые политики доступа; групповая переписка зависит от того, доставляет ли iLink групповые события для подключённой идентичности (для аккаунтов iLink-бота это часто не так — см. предупреждение выше)
• Поддержка медиа — картинки, видео, файлы и голосовые сообщения
• Шифрованный CDN на AES-128-ECB — автоматическое шифрование и расшифровка при любой передаче медиа
• Хранение контекстных токенов — преемственность ответов сохраняется на диске и переживает перезапуски
• Форматирование Markdown — Markdown сохраняется (заголовки, таблицы, блоки кода), поэтому клиенты WeChat с поддержкой Markdown отрисовывают его как родной
• Умная нарезка сообщений — пока текст укладывается в лимит, он остаётся одним пузырём; разбиваются по логическим границам только слишком длинные сообщения
• Индикаторы набора текста — пока агент обрабатывает запрос, в клиенте WeChat виден статус «печатает…»
• Защита от SSRF — исходящие URL медиа проверяются перед скачиванием
• Дедупликация сообщений — скользящее окно в 5 минут не даёт обработать сообщение дважды
• Автоповтор с задержкой — восстанавливается после временных ошибок API

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

Задаются в config.yaml в секции platforms.weixin.extra:

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

Политика личных сообщений

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

WEIXIN_DM_POLICY=allowlist
WEIXIN_ALLOWED_USERS=user_id_1,user_id_2

WEIXIN_ALLOWED_USERS — это входящий фильтр, а не система приглашений. Вход по QR связывает с Hermes одну идентичность iLink-бота. Другие люди не сканируют QR-код Hermes собственными аккаунтами — им нужно написать подключённому iLink-боту или контакту через WeChat, и Hermes обработает личное сообщение только тогда, когда Weixin-ID отправителя есть в WEIXIN_ALLOWED_USERS.

Рабочий порядок настройки такой:

1. Один раз свяжите Hermes командой hermes gateway setup и запишите подключённый аккаунт iLink-бота.
2. Попросите каждого разрешённого пользователя отправить личное сообщение этому боту/контакту.
3. Возьмите ID отправителя из логов шлюза или из полезной нагрузки входящего события.
4. Добавьте эти ID в WEIXIN_ALLOWED_USERS и перезапустите шлюз.

Если с Hermes общается только тот аккаунт, что сканировал QR-код, проверьте, что остальные пишут именно идентичности iLink-бота, а не личному аккаунту WeChat, которым выполнялся вход по QR. iLink-бот — отдельная идентичность, а маршрутизация обычных контактов и групп WeChat может быть ограничена поведением iLink со стороны Tencent.

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

Определяет, в каких группах бот отвечает, когда iLink доставляет групповые события для подключённой идентичности. Для идентичностей iLink-бота, полученных входом по QR (например, ...@im.bot), групповые события обычно не доставляются вовсе, поэтому эта политика может ни на что не влиять — см. предупреждение об ограничении iLink-бота в начале страницы.

WEIXIN_GROUP_POLICY=allowlist
# ВНИМАНИЕ: это список ID групповых чатов через запятую, а НЕ ID участников,
# хотя в имени переменной и есть слово "USERS". Учитывайте это при настройке.
WEIXIN_GROUP_ALLOWED_USERS=group_id_1,group_id_2

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

Входящие (приём)

Адаптер принимает медиавложения от пользователей, скачивает их с CDN WeChat, расшифровывает и кэширует локально для обработки агентом:

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

Шифрованный CDN на AES-128-ECB

Медиафайлы WeChat передаются через шифрованный CDN. Адаптер берёт это на себя незаметно для пользователя:

• Входящие: шифрованное медиа скачивается с CDN по URL с encrypted_query_param, а затем расшифровывается алгоритмом AES-128-ECB по ключу для конкретного файла, который приходит в полезной нагрузке сообщения.
• Исходящие: файлы шифруются локально случайным ключом AES-128-ECB, выгружаются на CDN, а в исходящее сообщение подставляется шифрованная ссылка.
• Ключ AES — это 16 байт (128 бит). Ключи могут приходить как сырой base64 или в hex-кодировке; адаптер понимает оба формата.
• Для этого нужен Python-пакет cryptography.

Настраивать ничего не надо — шифрование и расшифровка идут автоматически.

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

Любое исходящее медиа проходит через шифрованную выгрузку на CDN:

1. Сгенерировать случайный ключ AES-128
2. Зашифровать файл алгоритмом AES-128-ECB с дополнением PKCS#7
3. Запросить URL для выгрузки у iLink API (getuploadurl)
4. Выгрузить шифротекст на CDN
5. Отправить сообщение с шифрованной ссылкой на медиа

Хранение контекстных токенов

iLink Bot API требует, чтобы вместе с каждым исходящим сообщением для конкретного собеседника возвращался context_token. Адаптер держит дисковое хранилище контекстных токенов:

• Токены сохраняются по паре аккаунт+собеседник в ~/.hermes/weixin/accounts/<account_id>.context-tokens.json
• При запуске ранее сохранённые токены восстанавливаются
• Каждое входящее сообщение обновляет сохранённый токен для этого отправителя
• В исходящие сообщения автоматически подставляется свежий контекстный токен

Благодаря этому ответы сохраняют преемственность даже после перезапусков шлюза.

Форматирование Markdown

Клиенты WeChat, подключённые через iLink Bot API, отрисовывают Markdown напрямую, поэтому адаптер сохраняет разметку, а не переписывает её:

• Заголовки остаются заголовками Markdown (#, ##, …)
• Таблицы остаются таблицами Markdown
• Блоки кода остаются ограждёнными блоками кода
• Лишние пустые строки вне блоков кода схлопываются до двойного перевода строки

Нарезка сообщений

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

• Максимальная длина сообщения — 4000 символов
• Сообщения в пределах лимита остаются целыми, даже если в них несколько абзацев или переносов строк
• Слишком длинные сообщения разбиваются по логическим границам (абзацы, пустые строки, блоки кода)
• Блоки кода по возможности сохраняются целиком (не режутся посередине, пока сам блок не превысит лимит)
• Отдельные блоки сверх лимита уходят на логику усечения базового адаптера
• Задержка в 0,3 с между фрагментами не даёт WeChat сбрасывать сообщения по rate-limit, когда отправляется сразу несколько частей

Индикаторы набора текста

Адаптер показывает в клиенте WeChat статус набора:

1. Когда приходит сообщение, адаптер получает typing_ticket через API getconfig
2. Тикеты набора кэшируются на 10 минут для каждого пользователя
3. send_typing шлёт сигнал начала набора; stop_typing — сигнал остановки
4. Пока агент обрабатывает сообщение, шлюз сам включает индикаторы набора

Соединение по long-poll

Для приёма сообщений адаптер использует HTTP long-polling (а не WebSocket):

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

1. Подключение: проверка учётных данных и старт цикла опроса
2. Опрос: вызов getupdates с таймаутом 35 секунд; сервер удерживает запрос, пока не придут сообщения или не истечёт таймаут
3. Диспетчеризация: входящие сообщения раздаются параллельно через asyncio.create_task
4. Буфер синхронизации: постоянный курсор синхронизации (get_updates_buf) сохраняется на диск, чтобы после перезапуска адаптер продолжил с нужной позиции

Поведение при повторах

При ошибках API адаптер действует по простой схеме повторов:

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

Входящие сообщения дедуплицируются по ID сообщений с окном в 5 минут. Так двойная обработка не происходит при сетевых сбоях или перекрывающихся ответах опроса.

Блокировка токена

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

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

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