ErisPulse ErisPulse
Открыть интерактивную версию →
Разделы страницы
Статическое зеркало — интерактивная версия является основной Открыть интерактивную версию →

Создание первого бота

Tip

Когда стоит читать эту статью: бот уже запускается, и вы хотите написать первый обработчик команды /hello, а также разобраться, что именно делают sdk.run и декораторы команд. Если вы ещё не установили ErisPulse и не инициализировали проект, сначала выполните три шага из быстрого старта за 5 минут: «Установка», «Инициализация проекта» и «Запуск проекта»; если всё готово — пропустите.

Успешно пройденный быстрый старт — это лишь первый шаг. Эта статья поможет вам написать первый обработчик команды и объяснит, что происходит с каждой строкой кода внутри фреймворка.

Шаг первый: написание первой команды

Откройте main.py и напишите простой обработчик команды:

from ErisPulse import sdk
from ErisPulse.Core.Event import command

@command("hello", help="Отправить приветственное сообщение")
async def hello_handler(event):
    """Обработка команды hello"""
    user_name = event.get_user_nickname() or "друг"
    await event.reply(f"Привет, {user_name}! Я бот ErisPulse.")

@command("ping", help="Проверить, работает ли бот")
async def ping_handler(event):
    """Обработка команды ping"""
    await event.reply("Pong! Бот работает нормально.")

async def main():
    """Основная точка входа"""
    print("Запуск ErisPulse...")
    
    # keep_running=True (по умолчанию): фреймворк блокируется и продолжает работу, пока не получит сигнал о завершении (например, Ctrl+C)
    await sdk.run(keep_running=True)

if __name__ == "__main__":
    import asyncio
    asyncio.run(main())

Параметр keep_running

Параметр sdk.run(keep_running) управляет тем, блокируется ли фреймворк для поддержания работы:

  • keep_running=True (по умолчанию): run() будет блокироваться до тех пор, пока не получит сигнал о завершении (например, Ctrl+C), подходит для чистых ботов.
  • keep_running=False: run() завершит инициализацию и немедленно вернёт управление. Фреймворк не будет остановлен — запущенные адаптеры/модули продолжат обрабатывать события сообщений в фоновом режиме, вы можете продолжить выполнять собственную логику, пока цикл событий не завершится и фреймворк не закроется. Например:
async def main():
    await sdk.run(keep_running=False)   # Инициализация завершена, немедленно возвращаем управление
    # Фреймворк уже работает в фоне, здесь можно делать что-то ещё
    while True:
        await asyncio.sleep(3600)
        print("Проверка каждый час")

Помимо двух режимов run(), существуют более тонкие способы управления жизненным циклом, такие как init()/uninit() для ручного управления, а также отдельный запуск и остановка адаптеров/маршрутизации. Подробнее см. Жизненный цикл и ручное управление.

Шаг второй: Запуск робота

# Обычный запуск
epsdk run main.py

# Режим разработки (поддержка горячей перезагрузки)
epsdk run main.py --reload

Шаг 3: Тестирование бота

Отправьте команду в вашей системе общения:

/hello

Вы должны получить ответ от бота.

Описание кода

Декоратор команды

@command("hello", help="Отправить приветственное сообщение")
  • hello: имя команды, вызывается пользователем с помощью /hello
  • help: описание команды, отображается в команде /help

Параметры события

async def hello_handler(event):

Параметр event представляет собой объект Event, содержащий:

  • Текст сообщения: event.get_text()
  • Информация о отправителе: event.get_user_id(), event.get_user_nickname()
  • Информация о платформе: event.get_platform()
  • Информация о группе: event.get_group_id()
  • Исходные данные: event.get_raw()

Полный список методов объекта Event см. в разделе Подробное описание Event-объекта.

Отправка ответа

await event.reply("Содержимое ответа")

Метод event.reply() — это удобный способ отправки сообщения отправителю.

Расширение: добавление дополнительных функций

ErisPulse предоставляет богатые возможности для обработки событий и данных:

Часто задаваемые вопросы

Команда не отвечает?

  1. Проверьте, правильно ли настроен адаптер, убедитесь, что status адаптера в файле config/config.toml установлен в true
  2. Проверьте вывод логов в терминале, убедитесь, что нет ошибок (особенно сообщений уровня ERROR)
  3. Убедитесь, что префикс команды верный (по умолчанию это /), можно проверить в разделе [ErisPulse.event.command] файла конфигурации
  4. Убедитесь, что имя команды написано правильно, обратите внимание на настройки чувствительности к регистру

Как изменить префикс команды?

Добавьте в config.toml следующее:

[ErisPulse.event.command]
prefix = "!"
case_sensitive = false

Как поддерживать несколько платформ?

ErisPulse использует стандарт OneBot12 для унификации формата событий на разных платформах. Обработчики, зарегистрированные с помощью @command и @message, автоматически получают события со всех платформ. С помощью event.get_platform() можно определить источник платформы:

@command("hello")
async def hello_handler(event):
    platform = event.get_platform()
    
    if platform == "yunhu":
        await event.reply("Привет! От Юньху")
    elif platform == "telegram":
        await event.reply("Hello! От Telegram")
    else:
        await event.reply("Привет!")

Дополнительные советы по адаптации под несколько платформ можно найти в разделе Примеры типичных задач.

Следующие шаги

  • Продолжайте по учебному пути: прочитайте Основные концепции, чтобы понять, что фреймворк делает «под капотом» обработчиков команд
  • Хотите реагировать на больше типов сообщений: Введение в обработку событий — как писать обработчики для сообщений / уведомлений / запросов / мета-событий
  • Хотите добавить практичные функции: Примеры распространённых задач — готовый код для персистентности, задач по расписанию и контроля прав доступа