GitHub - RuslanStrogov/max-hermes: Python bridge between MAX Bot API and Hermes Agent. Webhook, Docker, systemd.

🛠️ Технологии

Мост между MAX Bot API и Hermes Agent

Python-мост через CLI с поддержкой webhook, Docker и systemd

_{🎨 Designed by BR-DESIGN}

📋 Содержание

Архитектура
Возможности
Требования
Установка
Настройка
Запуск
Структура проекта
Переменные окружения
Roadmap
Релизы и CI/CD
Сравнение с Telegram Bot API
Тестирование
Устранение неполадок
Лицензия

🏗️ Архитектура

┌──────────┐   webhook    ┌─────────────┐   CLI/SUB    ┌──────────────┐
│          │ ──────────►  │             │ ──────────►  │              │
│ MAX Bot  │              │ MAX Bridge  │              │ Hermes Agent │
│ API      │ ◄──────────  │ (Python)    │ ◄──────────  │              │
│          │  send_msg    │             │  response    │              │
└──────────┘              └─────────────┘              └──────────────┘

Пользователь пишет боту в MAX
MAX API отправляет webhook на мост
Мост показывает индикатор «Печатает...»
Мост вызывает Hermes Agent через CLI
Ответ Hermes отправляется обратно в MAX через Bot API

Хотите интеграцию уровня Hermes (send_message, cron, sessions)? Используйте MAX Hermes Plugin — нативный платформенный адаптер для Hermes Gateway.

✨ Возможности

Что уже работает

Фича	Статус
Приём сообщений от MAX через webhook	✅
Отправка ответов в MAX	✅
Индикатор «Печатает...» пока агент думает	✅
Inline keyboard (кнопки в сообщении)	✅
Callback от кнопок	✅
Поддержка нескольких пользователей	✅
Белый список пользователей (ALLOWED_USERS)	✅
Markdown-форматирование ответов	✅
systemd-сервис с автозапуском	✅
Docker / Docker Compose	✅
Health check endpoint	✅
Логирование в journald / файл	✅
Обработка всех типов событий MAX API	✅
Скачивание вложений (изображения, видео, аудио, файлы)	✅
Отправка изображений через upload API	✅
Отправка файлов через upload API	✅
Отправка голосовых сообщений (audio attachment)	✅
Редактирование сообщений (PUT /messages/{id})	✅
Удаление сообщений (DELETE /messages/{id})	✅
Long Polling (GET /updates)	✅
Webhook управление (POST/GET/DELETE /subscriptions)	✅
Групповые чаты (group/channel/supergroup)	✅
Маршрутизация ответов: chat_id для групп, user_id для DM	✅
События групп: user_added, user_removed, chat_title_changed	✅
Автодеплой через GitHub Actions	✅
CI (тесты на Python 3.11, 3.12)	✅
Автоматические релизы (GitHub Release)	✅

Roadmap

Фича	Статус	Примечание
Отправка геолокации	🔜	Нужен формат `location` attachment
Стикеры	❓	Нет информации о поддержке в API
Read receipts (галочки)	❌	Не поддерживается MAX Bot API
Menu button (как в Telegram)	❌	Нет аналога `/setMyCommands` в MAX

📋 Требования

Python 3.11+
Hermes Agent (установленный и настроенный)
Сервер с публичным IP (или tunnel) для приёма webhook
SSL-сертификат (Let's Encrypt или самоподписанный)

📦 Установка

1. Клонирование репозитория

git clone https://github.com/RuslanStrogov/max-hermes.git
cd max-hermes

2. Создание виртуального окружения

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

3. Создание бота в MAX

⚠️ Важно: Создание ботов на платформе MAX доступно только юридическим лицам, ИП и самозанятым (резидентам РФ).

Подробная инструкция: MAX для разработчиков — Создание чат-бота

4. Настройка конфигурации

cp .env.example .env
nano .env

5. Запуск

source venv/bin/activate
python -m src.main

⚙️ Настройка

Переменные окружения

Переменная	По умолчанию	Описание
`MAX_BOT_TOKEN`	(обяз.)	Токен бота MAX
`MAX_API_BASE_URL`	`https://platform-api.max.ru`	Базовый URL API
`HERMES_BIN`	`hermes`	Путь к исполняемому файлу hermes
`HERMES_MODEL`	(пусто)	Модель AI (напр. `qwen2:1.5b`)
`HERMES_TIMEOUT`	`120`	Таймаут ожидания ответа (сек)
`BRIDGE_HOST`	`0.0.0.0`	Адрес HTTP-сервера
`BRIDGE_PORT`	`8787`	Порт HTTP-сервера
`LOG_LEVEL`	`INFO`	Уровень логирования
`ALLOWED_USERS`	(пусто)	Список разрешённых ID

Nginx (обратный прокси)

server {
    listen 443 ssl http2;
    server_name your-domain.com;

    ssl_certificate /etc/letsencrypt/live/your-domain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem;

    location /webhook {
        proxy_pass http://127.0.0.1:8787;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    location /health {
        proxy_pass http://127.0.0.1:8787;
    }
}

systemd

sudo cp systemd/max-bridge.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now max-bridge

Docker

docker compose up -d --build

🚀 Запуск

Напрямую

source venv/bin/activate
python -m src.main

Как служба (systemd)

sudo systemctl start max-bridge
sudo systemctl status max-bridge
sudo journalctl -u max-bridge -f

Docker

docker compose up -d --build
docker compose logs -f

📁 Структура проекта

max-hermes/
├── src/
│   ├── main.py              # Точка входа, цикл событий
│   ├── config.py            # Загрузка конфигурации из .env
│   ├── max_client.py        # HTTP-клиент MAX Bot API
│   ├── hermes_client.py     # Клиент Hermes (через CLI)
│   ├── converter.py         # Конвертация форматов данных
│   ├── webhook_server.py    # HTTP-сервер для webhook от MAX
│   └── models.py            # Pydantic модели данных
├── systemd/
│   └── max-bridge.service   # Unit-файл systemd
├── scripts/
│   ├── setup.sh             # Скрипт автоматической установки
│   └── test_max_api.sh      # Тестирование MAX API
├── tests/
│   ├── conftest.py
│   ├── test_config.py
│   ├── test_converter.py
│   ├── test_max_client.py
│   └── test_webhook.py
├── Dockerfile
├── docker-compose.yml
├── requirements.txt
├── .env.example
├── .gitignore
└── README.md

📊 Сравнение с Telegram Bot API

Возможность	Telegram	MAX Bot API
Webhook	✅	✅
Long Polling	✅	✅
Inline keyboard	✅	✅
Reply keyboard	✅	❌ (только inline)
Callback buttons	✅	✅
Send/Edit/Delete messages	✅	✅
Typing indicator	✅	✅
Read receipts	✅	❌
Bot commands menu	✅	❌
Send images/files	✅	✅ (через upload)
Send location	✅	❓
Send stickers	✅	❓
Group chats	✅	✅
Channels	✅	✅

🧪 Тестирование

source venv/bin/activate
pip install pytest pytest-asyncio
python -m pytest tests/ -v

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

Мост не получает сообщения от MAX

Проверьте регистрацию webhook: curl -H "Authorization: TOKEN" https://platform-api.max.ru/subscriptions
Проверьте что порт открыт: curl https://your-domain.com/health
Проверьте логи: sudo journalctl -u max-bridge -f

Hermes не отвечает

Проверьте что Hermes установлен: hermes --version
Проверьте что модель загружена: ollama list

Бот не отвечает в MAX

Проверьте логи моста на наличие ошибок
Убедитесь что MAX_BOT_TOKEN валиден
Проверьте что бот активирован в MAX

🚀 Релизы и CI/CD

Git flow

main — стабильная ветка, релизы
develop — ветка разработки, интеграция изменений
Релизы помечаются тегами v* (например v1.1.0)
При пуше в main или тег v* автоматически деплоится на сервер

GitHub Actions

Workflow	Триггер	Описание
CI	push/PR в `main`, `develop`	Запуск тестов на Python 3.11, 3.12 + линтер
Deploy	push в `main` или тег `v*`	Автодеплой на сервер через SSH
Release	тег `v*`	Автоматическое создание GitHub Release

Настройка автодеплоя

В настройках репозитория GitHub → Settings → Secrets → Actions добавьте:

Secret	Описание
`DEPLOY_HOST`	IP-адрес или домен сервера
`DEPLOY_USER`	Пользователь SSH
`DEPLOY_SSH_KEY`	Приватный SSH-ключ

Создание релиза

# Собрать изменения в develop
git checkout develop
# ... коммиты ...

# Слить в main и создать тег
git checkout main
git merge develop --no-ff
git tag -a v1.2.0 -m "Release v1.2.0: описание"
git push origin main --tags

📄 Лицензия

MIT License. См. LICENSE.

🔗 Связанные проекты

Проект	Описание
MAX Hermes Plugin	Нативный платформенный плагин для Hermes Gateway. Прямая интеграция MAX без моста.

📢 Пресс-релизы

Готовые тексты для публикации в сообществах и СМИ:

_{🎨 Designed by BR-DESIGN}

_{🇷🇺 Опенсорс — Поддержи наш продукт · BR-DESIGN}

Name		Name	Last commit message	Last commit date
Latest commit History 46 Commits
.github/workflows		.github/workflows
assets		assets
scripts		scripts
src		src
systemd		systemd
tests		tests
.env.example		.env.example
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
LICENSE		LICENSE
PRESS_RELEASE.md		PRESS_RELEASE.md
PRESS_RELEASE_DETAIL.md		PRESS_RELEASE_DETAIL.md
PRESS_RELEASE_REDDIT.md		PRESS_RELEASE_REDDIT.md
README.md		README.md
banner.png		banner.png
docker-compose.yml		docker-compose.yml
requirements.txt		requirements.txt

Folders and files

Latest commit

History

Repository files navigation

🛠️ Технологии

Мост между MAX Bot API и Hermes Agent

📋 Содержание

🏗️ Архитектура

✨ Возможности

Что уже работает

Roadmap

📋 Требования

📦 Установка

1. Клонирование репозитория

2. Создание виртуального окружения

3. Создание бота в MAX

4. Настройка конфигурации

5. Запуск

⚙️ Настройка

Переменные окружения

Nginx (обратный прокси)

systemd

Docker

🚀 Запуск

Напрямую

Как служба (systemd)

Docker

📁 Структура проекта

📊 Сравнение с Telegram Bot API

🧪 Тестирование

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

Мост не получает сообщения от MAX

Hermes не отвечает

Бот не отвечает в MAX

🚀 Релизы и CI/CD

Git flow

GitHub Actions

Настройка автодеплоя

Создание релиза

📄 Лицензия

🔗 Связанные проекты

📢 Пресс-релизы

About

Topics

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 2

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages