max-hermes

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

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

🇷🇺 Российская разработка Сделано в Кремёнках · Open source · MIT

🎨 Designed by BR-DESIGN Дизайн, брендинг, визуальный стиль

AI-generated showcase animation

AI-generated showcase animation

📋 Содержание

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

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

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

1. Пользователь пишет боту в MAX (или выбирает команду из меню)
2. MAX API отправляет webhook на мост
3. Мост обрабатывает команды /start, /help, /about напрямую
4. Остальные сообщения — мост показывает индикатор «Печатает...»
5. Мост вызывает Hermes Agent через CLI
6. Ответ Hermes отправляется обратно в MAX через Bot API

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

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

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

🎛️ Bot Commands Menu

При старте мост автоматически регистрирует команды бота через PATCH /me/commands на platform-api2.max.ru.

Зарегистрированные команды:

Команды обрабатываются напрямую в bridge, без вызова Hermes AI.

Пример использования

1. Пользователь открывает диалог с ботом в MAX
2. Нажимает кнопку вызова команд (рядом с полем ввода)
3. Выбирает /help
4. Мост сразу отвечает справкой — без ожидания Hermes

Регистрация при старте

# main.py — добавляется после get_bot_info()
default_commands = [
    {"name": "start", "description": "Начать диалог с ботом"},
    {"name": "help", "description": "Помощь и информация о боте"},
    {"name": "about", "description": "О боте и его возможностях"},
]
await max_client.set_commands(default_commands)

📋 Требования

• 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

⚙️ Настройка

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

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
│   ├── hermes_client.py     # Клиент Hermes (через CLI)
│   ├── converter.py         # Конвертация форматов данных
│   ├── webhook_server.py    # HTTP-сервер для webhook + обработка команд
│   └── 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

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

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

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

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

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

Команды не отображаются в MAX

1. Убедитесь что НЕ используется platform-api2.max.ru — команды регистрируются на нём через set_commands()
2. Проверьте логи: sudo journalctl -u max-bridge -f
3. Если команды не появились — перезапустите мост

Hermes не отвечает

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

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

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

🚀 Релизы и CI/CD

Git flow

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

GitHub Actions

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

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

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

# Собрать изменения в 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

📄 Recent Fixes

📄 Лицензия

MIT License. См. LICENSE.

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

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

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

• Короткий текст для Telegram-каналов
• Подробный текст для Хабра/vc.ru/DTF
• Пост для Reddit/Hacker News