Основные компоненты

LXMFBot

Основной класс бота, который обрабатывает маршрутизацию сообщений, обработку команд и управление жизненным циклом бота.

from lxmfy import LXMFBot

bot = LXMFBot(
    name="MyBot",
    announce=600,
    announce_immediately=True,
    admins=set(),
    hot_reloading=False,
    rate_limit=5,
    cooldown=60,
    max_warnings=3,
    warning_timeout=300,
    command_prefix="/",
    cogs_dir="cogs",
    cogs_enabled=True,
    permissions_enabled=False,
    storage_type="json",
    storage_path="data",
    first_message_enabled=True,
    event_logging_enabled=True,
    max_logged_events=1000,
    event_middleware_enabled=True,
    announce_enabled=True,
    signature_verification_enabled=False,
    require_message_signatures=False
)

Ключевые методы

  • run(delay=10): Запустить основной цикл бота

  • send(destination, message, title="Reply", lxmf_fields=None): Отправить сообщение получателю, опционально с пользовательскими полями LXMF.

  • send_with_attachment(destination, message, attachment, title="Reply"): Отправить сообщение с вложением

  • command(name, description="No description provided", admin_only=False, threaded=False): Декоратор для регистрации команд. Установите threaded=True для запуска обратного вызова команды в отдельном потоке.

  • on_first_message(): Декоратор для обработки первых сообщений от пользователей

  • validate(): Запустить проверочные тесты конфигурации бота

Хранилище

Фреймворк предоставляет два бэкенда для хранения данных:

JSONStorage

from lxmfy import JSONStorage

storage = JSONStorage("data")

SQLiteStorage

from lxmfy import SQLiteStorage

storage = SQLiteStorage("data/bot.db")

Команды

Регистрация и обработка команд:

@bot.command(name="hello", description="Says hello")
def hello(ctx):
    ctx.reply(f"Hello {ctx.sender}!")

Многопоточные команды

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

import time

@bot.command(name="long_task", description="Performs a long-running task in a separate thread", threaded=True)
def long_task_command(ctx):
    ctx.reply("Starting a long task... please wait.")
    time.sleep(10) # This runs in a separate thread
    ctx.reply("Long task completed!")

Важно: Функции, помеченные как threaded=True, не должны напрямую взаимодействовать с сетевым стеком Reticulum (RNS) или любыми компонентами, которые зависят от lxmfy.transport.py, так как они, как правило, не являются потокобезопасными. Используйте ctx.reply() для отправки сообщений пользователю из многопоточной команды.

События

Система событий для обработки различных событий бота:

@bot.events.on("message_received", EventPriority.HIGHEST)
def handle_message(event):
    # Handle message event
    pass

Разрешения

Система разрешений для контроля доступа к функциям бота:

from lxmfy import DefaultPerms

@bot.command(name="admin", description="Admin command", admin_only=True)
def admin_command(ctx):
    if ctx.is_admin:
        ctx.reply("Admin command executed")

Промежуточное ПО

Система промежуточного ПО для обработки сообщений и событий:

@bot.middleware.register(MiddlewareType.PRE_COMMAND)
def pre_command_middleware(ctx):
    # Process before command execution
    pass

Вложения

Поддержка отправки файлов, изображений и аудио:

from lxmfy import Attachment, AttachmentType

attachment = Attachment(
    type=AttachmentType.IMAGE,
    name="image.jpg",
    data=image_data,
    format="jpg"
)
bot.send_with_attachment(destination, "Here's an image", attachment)

Внешний вид иконки (поле LXMF)

Вы можете установить пользовательскую иконку для своего бота, которую смогут отображать совместимые клиенты LXMF. Для этого используется LXMF.FIELD_ICON_APPEARANCE.

from lxmfy import IconAppearance, pack_icon_appearance_field
import LXMF # Required for LXMF.FIELD_ICON_APPEARANCE

# Define the icon appearance
icon_data = IconAppearance(
    icon_name="smart_toy",  # Name from Material Symbols
    fg_color=b'\xFF\xFF\xFF',  # White foreground (3 bytes)
    bg_color=b'\x4A\x90\xE2'   # Blue background (3 bytes)
)

# Pack it into the LXMF field format
icon_lxmf_field = pack_icon_appearance_field(icon_data)

# Send a message with this icon
bot.send(
    destination_hash_str,
    "Hello from your friendly bot!",
    title="Bot Message",
    lxmf_fields=icon_lxmf_field
)

# You can also combine it with other fields, like attachments:
# attachment_field = pack_attachment(some_attachment)
# combined_fields = {**icon_lxmf_field, **attachment_field}
# bot.send(destination, "Message with icon and attachment", lxmf_fields=combined_fields)

Планировщик

Система планирования задач:

@bot.scheduler.schedule(name="daily_task", cron_expr="0 0 * * *")
def daily_task():
    # Run daily at midnight
    pass

Подписи

Криптографическая подпись и проверка сообщений для повышения безопасности:

from lxmfy import SignatureManager

# SignatureManager is automatically available as bot.signature_manager
# when signature_verification_enabled=True

# Manual usage (rarely needed):
sig_manager = SignatureManager(bot, verification_enabled=True, require_signatures=False)

Ключевые методы

  • sign_message(message, identity): Подписать сообщение LXMF, используя предоставленный идентификатор RNS

  • verify_message_signature(message, signature, sender_hash, sender_identity=None): Проверить подпись сообщения по идентификатору отправителя

  • should_verify_message(sender): Определить, следует ли проверять сообщение от данного отправителя

  • handle_unsigned_message(sender, message_hash): Обработать сообщения, у которых отсутствуют действительные подписи

Поля подписи

LXMFy использует пользовательское поле LXMF 0xFA (FIELD_SIGNATURE) для хранения криптографических подписей. Сообщения канонизируются путем сортировки и объединения полей в следующем порядке:

  • хэш источника (с префиксом «source:»)

  • хэш назначения (с префиксом «dest:»)

  • содержимое (с префиксом «content:»)

  • заголовок (с префиксом «title:»)

  • временная метка (с префиксом «timestamp:»)

  • пользовательские поля (исключая поле подписи, с префиксом «field_{id}:»)

Шаблоны

Фреймворк включает в себя несколько готовых к использованию шаблонов ботов:

EchoBot

Простой эхо-бот, который повторяет сообщения:

from lxmfy.templates import EchoBot

bot = EchoBot()
bot.run()

MemeBot

Бот для отправки случайных мемов:

from lxmfy.templates import MemeBot

bot = MemeBot()
bot.run()

NoteBot

Бот для заметок с хранилищем JSON:

from lxmfy.templates import NoteBot

bot = NoteBot()
bot.run()

ReminderBot

Бот для напоминаний с хранилищем SQLite:

from lxmfy.templates import ReminderBot

bot = ReminderBot()
bot.run()

Инструменты командной строки

Фреймворк предоставляет инструменты командной строки для управления ботом:

# Create a new bot
lxmfy create mybot

# Create a bot from template
lxmfy create --template echo mybot

# Run a template bot
lxmfy run echo

# Analyze bot configuration
lxmfy analyze bot.py

# Verify package signature
lxmfy verify package.whl sigstore.json

# Test signature verification with a message
lxmfy signatures test

# Enable signature verification
lxmfy signatures enable

# Disable signature verification
lxmfy signatures disable

Обработка ошибок

Фреймворк предоставляет комплексную обработку ошибок:

try:
    bot.run()
except KeyboardInterrupt:
    bot.cleanup()
except Exception as e:
    logger.error(f"Error running bot: {str(e)}")