hermes-vk-community 1.0.5

VK Community Long Poll platform plugin for Hermes Agent

Hermes VK Community

Плагин платформы Hermes Agent, который подключает личного агента к сообщениям бота сообщества VK через Community Long Poll API.

Проверяемый диапазон Hermes: >=0.18.2,<0.19.

Hermes 0.18.2 сам фиксирует cryptography==46.0.7 и Pillow==12.2.0, для которых опубликованы advisory с исправлениями в 48.0.1 и 12.3.0. До совместимого upstream-релиза supply-chain gate содержит только точечные исключения конкретных advisory ID; расширять версии на стороне плагина нельзя, поскольку это сделает dependency graph с Hermes 0.18.2 неразрешимым.

Быстрая настройка

Установить плагин можно из PyPI:

pip install hermes-vk-community
hermes plugins enable vk-community

Либо напрямую из подкаталога GitHub-репозитория:

hermes plugins install shkarupa-alex/hermes-plugins/packages/hermes-vk-community --enable

Во втором варианте Hermes клонирует только каталог плагина. При первой фактической загрузке плагин проверяет зависимости из pyproject.toml и при необходимости устанавливает их через uv в то же виртуальное окружение, где работает Hermes. Повторная загрузка ничего не переустанавливает. Автоустановку можно запретить штатной настройкой Hermes security.allow_lazy_installs: false или переменной HERMES_DISABLE_LAZY_INSTALLS=1; тогда сообщение об ошибке покажет точную команду для ручной установки зависимостей.

После установки запустите мастер:

hermes gateway setup

В списке платформ выберите VK Community. Тот же мастер можно запустить напрямую:

hermes vk setup

Мастер:

1. расскажет, какие настройки включить в сообществе и какие права выдать ключу;
2. примет ключ без отображения введённых символов;
3. примет обычные ссылки на сообщество и профили пользователей;
4. сам получит числовые VK ID;
5. с подтверждением сделает сообщество приватным и включит сообщения;
6. включит Community Long Poll 5.199 и событие входящего сообщения;
7. проверит ключ, доступ к сообществу, пользователей и итоговые настройки;
8. сохранит секрет и конфигурацию в активный профиль Hermes.

Если проверка не пройдёт, мастер не сохраняет локальную конфигурацию. Уже подтверждённые изменения сообщества могут быть применены VK до последующей ошибки проверки; повторный запуск безопасен, потому что настройки идемпотентны.

Создание сообщества и ключа

Подойдёт в том числе закрытое сообщество, в котором состоите только вы.

1. Создайте сообщество VK или откройте его управление.
2. Включите Сообщения сообщества.
3. Настройки Long Poll можно оставить мастеру. При ручной настройке откройте Управление → Настройки → Работа с API → Long Poll API, включите Long Poll, выберите API 5.199 и отметьте только событие входящего сообщения (message_new). Другие типы событий текущему адаптеру не нужны.
4. Там же откройте Ключи доступа и создайте ключ сообщества.
5. Выберите права:
   • управление сообществом;
   • сообщения сообщества;
   • фотографии сообщества;
   • документы сообщества.

Права на истории, стену, товары и заказы плагину не нужны. Права на фотографии и документы используются реальными upload-flow: фото, обычные документы и голосовые сообщения/TTS отправляются как нативные вложения VK. Для голоса плагин преобразует исходное аудио в OGG/Opus через ffmpeg; если VK отклонит voice-flow, безопасный fallback отправляет ZIP-документ без потери исходных байт.

Официальная отправная точка: боты VK — начало работы.

Где взять ID

Вручную извлекать числовые ID не обязательно: мастер принимает ссылки.

• https://vk.com/club240186772 → ID сообщества 240186772;
• https://vk.com/id7750207 → ID пользователя 7750207;
• https://vk.com/shkarupa.alex → мастер запросит числовой ID через VK API;
• короткая ссылка сообщества с собственным именем тоже разрешается через API.

Можно указать несколько разрешённых профилей через запятую. Пустой список запрещён: доступ к личному агенту закрыт по умолчанию.

Где хранится ключ

Как и Telegram-токен в Hermes, ключ VK хранится под именем VK_COMMUNITY_TOKEN в .env активного профиля Hermes, а не в YAML:

• профиль по умолчанию: обычно ~/.hermes/.env;
• именованный профиль: его собственный каталог профиля и собственный .env.

Hermes устанавливает секретный scope конкретного профиля перед запуском адаптера. Плагин читает ключ только через этот scope, поэтому при нескольких профилях ключ одного профиля не подменит ключ другого.

Несекретные значения мастер записывает в config.yaml активного профиля:

platforms:
  vk:
    enabled: true
    group_id: 240186772
    allowed_user_ids:
      - 7750207
    typing_indicator: true

Ключ, помещённый в .env этого репозитория, предназначен только для локальных тестов разработчика. Он не переносится в профиль Hermes автоматически. При обычной установке вводите ключ в мастере — тот использует штатную атомарную запись секретов Hermes.

Разработка без установленного пользователем Hermes

Глобально или в пользовательскую установку Hermes ничего ставить не требуется. uv создаёт изолированное окружение проекта и устанавливает совместимую версию Hermes как зависимость плагина:

uv sync --all-packages
uv run pytest packages/hermes-vk-community/tests
uv run ruff check packages/hermes-vk-community
uv run pyright packages/hermes-vk-community

То есть тесты можно запускать до установки Hermes пользователем. Полностью без кода Hermes проверить платформенный плагин нельзя: его контракт содержит классы адаптеров, реестр платформ и профильное хранилище секретов. Изолированная .venv решает это без изменения рабочей установки пользователя.

Для реальной end-to-end проверки всё равно нужны сеть, сообщество и тестовое сообщение. Мастер уже выполняет безопасную часть live-проверки: API, права, разрешение ID и получение Long Poll server.

Ручная настройка

Если мастер использовать нельзя, добавьте VK_COMMUNITY_TOKEN в .env активного профиля и внесите показанный выше блок platforms.vk в его config.yaml. Не помещайте токен в YAML: валидатор плагина намеренно отклоняет такую конфигурацию.

После изменения перезапустите gateway и напишите со своего разрешённого профиля в сообщения сообщества:

hermes gateway restart

Hermes передаёт адаптеру Markdown. Live-проверенный профиль API 5.199 использует Unicode codepoint offsets и компилирует bold/italic/underline/url в format_data; заголовки становятся жирными. Цитаты передаются как ▎ плюс курсив, списки — как Unicode-маркеры с отступами. Markdown-таблицы всегда рендерятся в JPEG и отправляются фотографиями. Поэтому смешанный ответ может стать упорядоченной серией сообщений: текст, таблица, следующий текст. Отдельная Markdown-картинка аналогично становится фото между текстовыми сообщениями. HTML и исходный Markdown в VK отправлять нельзя — клиент показывает их буквально.

hermes vk probe-formatting --peer-id <PRIVATE_TEST_PEER_ID> \
  --output vk-formatting-format-data-probe.json

auto использует проверенный rich-профиль; явный rich доступен для API 5.199, а plain оставлен как детерминированный fallback. Unknown profile/API по-прежнему переключает auto в plain и отклоняет явный rich. Probe проверяет send/edit, Unicode offsets и readback, после чего best-effort удаляет тестовые сообщения. Подробности и текущий проверенный профиль записаны в docs/vk-rich-text-compatibility.md.

Статус «печатает» отправляется через messages.setActivity, если typing_indicator: true; live-тест подтвердил и ответ API, и отображение в клиенте VK.

Release live-матрица дополнительно проверяет DM reply на реальное входящее сообщение, pinned media download, format_data, inline keyboard, photo upload и восстановление подготовленного outbox после закрытия/повторного открытия SQLite. Для запуска нужны только VK_COMMUNITY_TOKEN, VK_GROUP_ID и VK_TEST_PEER_ID; тестовый пользователь должен предварительно прислать фото.

Интерактивность, длинные ответы и pairing

Clarify-вопросы, подтверждения опасных команд и slash-confirm показываются как одноразовые VK-клавиатуры. Payload — случайный opaque nonce, связанный в памяти с разрешённым user ID, peer ID, сессией, допустимым действием и сроком жизни. Повторный, просроченный или скопированный payload отклоняется до Hermes.

Длинные ответы и финализация streaming-preview поддерживают продолжения. Доставленные части не отправляются повторно после timeout/частичной ошибки; outbox сохраняет random_id и wire payload. После рестарта безопасные prepared-строки досылаются, а неоднозначные sending переводятся в delivery_unknown и доступны через hermes vk doctor --delivery-unknown. Ошибка VK 914 уменьшает рабочий лимит вплоть до 256 символов и кеширует его.

Опциональный pairing включается в YAML:

platforms:
  vk:
    pairing:
      enabled: true
      code_ttl_seconds: 600

Создайте одноразовый код командой hermes vk pair и отправьте его боту только текстом. В SQLite хранится SHA-256, а не сам код; вложения, forwards и payload от непривязанного пользователя не загружаются.

Диагностика

hermes vk doctor проверяет discovery/enabled, secret scope, конфликты политики, identity сообщества, Community Long Poll, SQLite migration/schema, platform lock, formatting profile и media flow. Флаги --inflight и --delivery-unknown выводят только bounded идентификаторы и ошибки без текста сообщений и секретов.