Uroboros

Модульный юзербот для Telegram на Python и Telethon.
Модули одной командой, кнопки и формы, защита аккаунта от вредного кода.

📚 Документация · 🚀 Установка · ⌨️ Команды · 🧩 Писать модули · 📦 Модули

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

🚀 Установка

Linux, VPS, Termux и macOS:

curl -fsSL https://raw.githubusercontent.com/asykixd/uroboros/master/install.sh | sh

Или через pip: pip install uroboros-userbot. Docker, служба systemd, автозапуск в Termux и Windows — в документации по установке.

При первом запуске Uroboros пишет в консоль ссылку на веб-панель входа: откройте её в браузере, введите api_id и api_hash с my.telegram.org/apps, номер, код и пароль 2FA — или отсканируйте QR-код. После входа панель выключается, а Uroboros сам создаёт inline-бота для кнопок через @BotFather. Вход в консоли — --cli.

⌨️ Главные команды

Все команды с уровнями доступа — в справочнике.

🧩 Пишем модуль

# meta developer: @you
# meta permissions: none
# requires_uroboros: 1.0
from uroboros import Module, command, utils


class Notes(Module):
    """Заметки"""

    @command("save", emoji="💾")
    async def save(self, message):
        """<имя> <текст> — сохранить заметку"""
        name, _, text = utils.get_args_raw(message).partition(" ")
        self.set(name, text)
        await utils.answer(
            message,
            utils.card(
                "✅ <b>Заметка сохранена</b>",
                [f"🏷 Имя: <code>{utils.escape_html(name)}</code>", f"📏 Длина: <code>{len(text)}</code>"],
                hint=f"показать: <code>.note {utils.escape_html(name)}</code>",
            ),
        )

В модуле есть self.client (Telethon), своё хранилище self.get/self.set, настройки self.config, фильтры команд, вотчеры, фоновые задачи @loop, библиотеки, формы с кнопками self.inline.form(...) и хелперы в utils. Подробно — в руководстве для авторов, готовые модули — в uroboros-modules (это и шаблон для своего репозитория).

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

Сторонние модули выполняются в одном процессе с ботом. Uroboros проверяет их код при установке, показывает права и изменения, закрепляет модули с GitHub на коммите и не даёт им трогать сессию и угонять аккаунт. Но это не песочница — ставьте модули, которым доверяете. Подробнее — в docs/security.md.

🛠 Разработка

Ветка dev — разработка (версии X.Y.Z-dev), master — стабильные версии.

python3 -m venv .venv && .venv/bin/pip install -e '.[dev,docs]'
.venv/bin/python -m pytest
.venv/bin/mkdocs serve

🙏 Благодарности

API модулей и адаптер повторяют Hikka (AGPL-3.0) — спасибо её авторам. Используются Telethon и aiogram.

📄 Лицензия

AGPL-3.0, см. LICENSE. Как помочь проекту — CONTRIBUTING.md, уязвимости — SECURITY.md.