Быстрый старт¶

Предварительные требования¶

Python 3.11+
Reticulum Network Stack (pip install rns, version 1.3.8+)
LXMF (pip install lxmf, version 1.0.1+; installed automatically with LXMFy)
CBOR (cbor2, installed automatically, required for RRC)
LXMFy (pip install lxmfy или установка из исходного кода)

Создание вашего первого бота (с помощью CLI)¶

Самый простой способ начать - использовать инструмент командной строки LXMFy.

Откройте терминал в каталоге, где вы хотите создать проект своего бота.
Выполните команду create:
```
lxmfy create my_first_bot
```
Эта команда сгенерирует следующие файлы: * my_first_bot.py: Ваш основной файл бота, настроенный с разумными значениями по умолчанию. * cogs/: Каталог для расширений бота (модулей). * cogs/__init__.py: Делает каталог cogs пакетом Python. * cogs/basic.py: Пример модуля с простыми командами «hello» и «about». * data/: Каталог, в котором бот будет хранить свои данные (по умолчанию используется JSON). * config/: Каталог, в котором бот хранит свою идентификацию и статус объявления.

Просмотрите файл :code:`my_first_bot.py`:

from lxmfy import LXMFBot

bot = LXMFBot(
    name="my_first_bot",  # Bot name used in announces/identity
    announce=600,         # Announce interval in seconds (10 minutes)
    announce_immediately=True, # Announce on first run?
    admins=set(),         # Set of admin LXMF address hashes
    hot_reloading=False,  # Enable/disable hot reloading of cogs
    rate_limit=5,         # Max messages per minute per user
    cooldown=60,          # Cooldown period in seconds for rate limit
    max_warnings=3,       # Warnings before ban for spam
    warning_timeout=300,  # Time (seconds) before warnings reset
    command_prefix="/",   # Prefix for commands (e.g., /hello)
    cogs_dir="cogs",      # Directory to load cogs from
    cogs_enabled=True,    # Enable/disable loading cogs
    permissions_enabled=False, # Enable/disable the role-based permission system
    storage_type="json",  # Storage backend ("json", "sqlite", or "memory")
    storage_path="data",  # Path for storage files/database
    first_message_enabled=True, # Enable special handling for first messages
    event_logging_enabled=True, # Log events to storage?
    max_logged_events=1000,   # Max events to keep in log
    event_middleware_enabled=True, # Enable event middleware?
    announce_enabled=True,   # Enable/disable network announces
    signature_verification_enabled=False, # Enable/disable cryptographic signature verification
    require_message_signatures=False     # Require all messages to be signed
)

# To add an admin, find your LXMF address hash and add it here:
# bot.config.admins.add("your_lxmf_hash_here")
# bot.admins = bot.config.admins # Ensure the running instance knows

# Example of preparing an LXMF icon field (optional)
# from lxmfy import IconAppearance, pack_icon_appearance_field
# try:
#     icon_data = IconAppearance(icon_name="emoji_objects", fg_color=b'\xFF\xA5\x00', bg_color=b'\x8B\x45\x13') # Orange on Brown
#     bot.icon_field = pack_icon_appearance_field(icon_data) # Store for use in send/reply
# except Exception as e:
#     print(f"Could not prepare icon field: {e}")
#     bot.icon_field = None

if __name__ == "__main__":
    print(f"Starting bot: {bot.config.name}")
    print(f"Bot LXMF Address: {bot.local.hash}") # Prints the bot's address
    bot.run()

(Необязательно) Добавьте свой хэш администратора: * Найдите хэш своего адреса LXMF (например, в вашем клиенте Reticulum, таком как Sideband или NomadNet). * Раскомментируйте и отредактируйте строку bot.config.admins.add(...) в файле my_first_bot.py, заменив "your_lxmf_hash_here" на ваш фактический хэш.
Запустите своего бота:
```
python my_first_bot.py
```
Ваш бот запустится, выведет свой адрес LXMF, потенциально отправит объявление по сети Reticulum и начнет прослушивать сообщения.

Взаимодействие с вашим ботом¶

Отправьте сообщение на адрес LXMF бота из вашего клиента.
Попробуйте пример команды: Отправьте /hello боту. Он должен ответить «Hello <your_hash>!». Если вы раскомментировали пример с иконкой выше, этот ответ также может содержать иконку.
Попробуйте команду помощи: Отправьте /help.

Расширенные возможности¶

Когда вы освоитесь с основами, изучите эти расширенные возможности:

Обработчики сообщений:

Используйте @bot.on_first_message() для приветствия новых пользователей
Используйте @bot.on_message() для обработки всех сообщений перед обработкой команд

Надежная доставка:

Configure direct_delivery_retries in LXMFBot(...) for automatic retry before propagation fallback
Configure propagation_node in bot config (or use bot.set_propagation_node(...)) to route through a specific LXMF propagation node
Outgoing queue persistence is on by default (message_persistence_enabled=True) with a bounded queue (message_queue_size)

Reticulum Relay Chat (RRC):

Join RRC hubs as a normal client with rrc_enabled=True or the rrc template
Use the same Reticulum config as MeshChatX or your hub (reticulum_config_dir or LXMFY_RETICULUM_CONFIG_DIR, typically ~/.reticulum)
See the Creating Bots guide for room bots and hub discovery

Безопасность:

Включите signature_verification_enabled=True для принудительной встроенной проверки подписи LXMF
Установите require_message_signatures=True для отклонения неподписанных или недействительных сообщений
On Linux, enable the Landlock LSM filesystem sandbox with landlock_enabled=True (default); override with LXMFY_LANDLOCK=0 or LXMFY_LANDLOCK=1
External script cogs can run in a Landlock, bubblewrap, or firejail sandbox via external_cogs_sandbox_type
Note: LXMF automatically signs all messages; LXMFy enforces verification policy and optional sandboxing

Development:

Run static type checking with make typecheck (pyright lxmfy)
Run the full CI suite with make ci (lint, typecheck, security check, tests, build)

See the Creating Bots guide and API Reference for detailed information on these features.

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

Изучите руководство Создание ботов, чтобы получить более подробную информацию о добавлении команд, использовании модулей и различных типах ботов.
Проверьте Справочник по API для получения подробной информации о компонентах фреймворка.