KaguyaUserBot — асинхронный, легковесный модульный Telegram-клиент (ЮзерБот) с параллельной интеграцией бота-ассистента и динамической песочницей для плагинов.

---

1. Описание проекта и архитектура

KaguyaUserBot — это событийно-ориентированный фреймворк, построенный на базе библиотеки kurigram (высокопроизводительного форка pyrogram). Основная задача проекта — предоставить разработчикам и пользователям гибкую и изолированную среду для запуска юзерботов без необходимости развертывания тяжелых СУБД.

Ключевые архитектурные особенности:

• Архитектура микроядра: Основной клиент KaguyaClient выполняет роль легковесного ядра. Он отвечает за авторизацию, чтение глобальных настроек, поддержание сессии и маршрутизацию событий. Вся прикладная логика вынесена в изолированные динамические модули.
• Гибридный режим работы: Внутри одного Event Loop одновременно работают два клиента: юзербот (через MTProto) и бот-ассистент (через Bot API). Они взаимодействуют через общую базу данных и вызывают функции друг друга — это позволяет корректно работать инлайн-функционалу в чатах.
• Общая локальная БД: Вместо тяжелых серверов используется встроенная Key-Value БД на базе оптимизированного SQLite с асинхронной оберткой (asyncio.to_thread). Она автоматически удаляет устаревшие записи (через TTL) и позволяет удобно разделять данные по категориям.
• Мгновенное кэширование медиа: Для экономии трафика и ускорения рендеринга меню бот использует метод edit_media_cached. При первой отправке обложки с диска полученный от серверов Telegram file_id кэшируется. Все последующие вызовы меню используют этот ID, что позволяет быстро обновлять медиа.

---

2. Дисклеймер

ВНИМАНИЕ: Запуск юзерботов нарушает официальные Правила предоставления услуг Telegram (Terms of Service), так как автоматизирует действия в аккаунте через MTProto API.

• Автор проекта не несет ответственности за возможные блокировки или ограничения вашего аккаунта со стороны антиспам-алгоритмов Telegram.
• Клиент Kaguya мимикрирует под официальный Windows Desktop клиент, чтобы минимизировать риски обнаружения, однако полная безопасность не гарантируется.
• Безопасность модулей: Устанавливаемые модули выполняются в том же процессе, что и ядро, и имеют полный доступ к вашим файлам сессий (.session) и переменным окружения. Устанавливайте модули только из доверенных источников!

---

3. Установка и развертывание

Подготовка ключей

Для работы MTProto-клиента необходимо получить ключи API в Telegram:

1. Авторизуйтесь на сайте my.telegram.org.
2. Перейдите в раздел API Development Tools и создайте новое приложение.
3. Сохраните полученные значения параметров API_ID и API_HASH.

---

Запуск на Windows

Проект содержит готовый сценарий автоматического развертывания виртуального окружения venv и установки зависимостей в один клик.

1. Установите Python 3.11 или выше (при установке обязательно отметьте флаг «Add Python to PATH»).
2. Скачайте архив репозитория KaguyaUserBot и распакуйте его.
3. Запустите файл [Windows]Kaguya_run.bat.
4. Скрипт проверит окружение, установит зависимости и автоматически создаст пустой файл конфигурации .env в корне проекта.
5. Откройте файл .env в Блокноте и впишите туда свои ключи:

   API_ID=ваш_api_id
   API_HASH=ваш_api_hash

6. Сохраните файл и запустите [Windows]Kaguya_run.bat заново. Введите ваш номер телефона и код подтверждения из Telegram для создания сессии.
   • Примечание по компиляции: Библиотека ускорения шифрования tgcrypto требует компилятор C++ для сборки из исходников. Наш загрузчик [Windows]Kaguya_run.bat автоматически распознает ошибки компиляции, пропустит их и запустит бота на встроенных средствах шифрования Python без необходимости ставить компиляторы.

---

Запуск на Android

Для работы юзербота на смартфонах используется эмулятор терминала Termux.

1. Установите приложение Termux (рекомендуется сборка из F-Droid).
2. Запустите Termux и выполните команду для автоматической инициализации проекта:

   bash [Termux]Kaguya_run.sh

3. Скрипт самостоятельно установит пакеты python, git, развернет окружение и запустит установку библиотек построчно.
4. Скопируйте шаблон .env.example в рабочий файл настроек:

   cp .env.example .env

5. Настройте ключи API_ID и API_HASH внутри .env и запустите скрипт заново для авторизации.

---

Запуск на Ubuntu

Шаг 1. Подготовка сервера

Подключись к своему VPS по SSH и установи необходимые системные пакеты:

sudo apt update && sudo apt upgrade -y
sudo apt install python3 python3-venv python3-pip git nano -y

Шаг 2. Клонирование и настройка проекта

git clone https://github.com/cxvimba/KaguyaUserBot.git
cd KaguyaUserBot

Создай виртуальное окружение, активируй его и установи библиотеки:

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Скопируй шаблон настроек в рабочий файл конфигурации:

cp .env.example .env
nano .env

Впиши свои API_ID и API_HASH в открывшемся текстовом редакторе nano, сохрани изменения нажатием Ctrl+O ➔ Enter, а затем выйди через Ctrl+X.

Шаг 3. Первый запуск и авторизация

Запусти скрипт вручную один раз, чтобы пройти авторизацию в Telegram и сгенерировать файл сессии:

python3 main.py

Введи свой номер телефона и код подтверждения из Telegram. Как только Kaguya напишет, что успешно запущена — останови её комбинацией клавиш Ctrl + C.

Шаг 4. Настройка автозапуска 24/7 через Systemd (Рекомендуется)

Чтобы бот работал в фоновом режиме, не выключался при закрытии консоли и сам поднимался при перезагрузке сервера, настроим системную службу.

Создай файл службы:

sudo nano /etc/systemd/system/kaguya.service

Вставь туда следующий шаблон (замени /root/KaguyaUserBot на твой реальный путь к проекту, если он отличается):

[Unit]
Description=Kaguya UserBot Service
After=network.target

[Service]
Type=simple
WorkingDirectory=/root/KaguyaUserBot
ExecStart=/root/KaguyaUserBot/.venv/bin/python main.py
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

Сохрани файл (Ctrl+O ➔ Enter ➔ Ctrl+X). Теперь активируй и запусти службу:

sudo systemctl daemon-reload
sudo systemctl enable kaguya.service
sudo systemctl start kaguya.service

---

4. Интеграция бота-ассистента

Бот-ассистент обеспечивает вывод интерактивных клавиатур флагов и меню настроек.

1. Перейдите в чат с официальным ботом @BotFather и создайте нового бота (/newbot).
2. В меню настроек вашего нового бота перейдите в Bot Settings ➔ Inline Mode и включите его.
3. Там же перейдите в Inline Feedback и выберите значение 100% (обязательно для корректной работы Inline).
4. Напишите вашему юзерботу команду привязки:

   .токен <ваш_токен_из_BotFather>
   

5. Валидация на лету: Юзербот мгновенно запустит ассистента в фоне, отправит скрытый инлайн-запрос для проверки активности инлайн-режима и привяжет его к ядру.
   • Если инлайн-режим не был включен в BotFather, бот-помощник автоматически остановится, сотрет токен из базы во избежание сбоев и выведет в чат подробную пошаговую инфографику по исправлению проблемы.

---

5. Разработка модулей

Фреймворк Kaguya поддерживает два формата модулей в папке kaguya/modules/:

1. Одиночные .py файлы (простые утилиты).
2. Папки-пакеты (сложные модули с собственными ассетами, конфигами и подмодулями), содержащие на входе файл инициализации __init__.py.

---

Архитектура одиночного модуля

Любой модуль должен содержать класс, унаследованный от BaseModule.

class Ping(BaseModule):
    meta = ModuleInfo(
        name="Автоответчик",
        description="Сохраняет и выводит автоматические ответы в чатах",
        version="1.0.0",
        author="cxvimba",
        commands={
            "set_reply | задать_ответ": "Сохранить автоответ (формат: .set_reply слово | ответ)",
            "reply_list | ответы": "Показать все сохраненные ответы"
        }
    )

    @on_command(["set_reply", "задать_ответ"])
    async def set_reply_cmd(self, client: Client, message: Message):
        """Парсит аргументы и сохраняет автоответ в базу данных."""
        if len(message.command) < 2:
            await message.edit_text("❌ **Kaguya:** Формат: `.set_reply триггер | текст ответа`")
            return

        # Извлекаем текст после команды
        raw_text = message.text.split(maxsplit=1)[1]
        if "|" not in raw_text:
            await message.edit_text("❌ **Kaguya:** Разделяй триггер и ответ символом `|`")
            return

        trigger, reply_text = map(str.strip, raw_text.split("|", 1))

        # Подключаемся к категории "auto_responses" в нашей локальной БД diskcache
        db = self.client.db.get_category("auto_responses")
        
        # Сохраняем связку в базу
        await db.set(trigger.lower(), reply_text)
        await message.edit_text(f"✅ **Kaguya:** Автоответ на слово «{trigger}» успешно сохранен!")

---

Архитектура модуля-пакета

Чтобы Kaguya распознала папку как модуль-пакет, в ней должен присутствовать __init__.py. Все обработчики и команды могут быть вынесены в отдельные файлы (например, commands.py), а в __init__.py они просто импортируются и привязываются как атрибуты класса SystemModule:

# kaguya/core_modules/system/modules.py
@on_command(['modules', 'модули'])
async def list_modules(self, client: Client, message: Message):
    """Выводит список всех активных моделей."""
    count = len(self.client.loaded_modules)
    text = f'⚡️ <b>Kaguya UserBot</b> | 🌟 Модули: <code>{count}</code>\n\n'

    for idx, (path, mod) in enumerate(reversed(self.client.loaded_modules.items()), 1):
        text += f'{idx}. 📦 <b>{mod.meta.name}</b> <code>v{mod.meta.version}</code>\n'
        if mod.meta.author and mod.meta.author != 'Anonymous':
            text += f' └ <b>Автор:</b> {mod.meta.author}\n'
        text += '\n'

    await client.edit_media_cached(
        message=message,
        cache_key='modules_menu_file_id',
        local_path='assets/Kaguya_modules.png',
        caption=text
    )


# kaguya/core_modules/system/__init__.py
from kaguya.types import BaseModule, ModuleInfo
from .modules import list_modules, install_module
    
class SystemModule(BaseModule):
    meta = ModuleInfo(
        name='Система',
        description='Системные утилиты Kaguya',
        version='1.0.0',
        author='Anonymous',
        commands={
           'modules': 'Список модулей',
           'install': 'Установить модуль'
        }
    )
    
    # Привязка функций из внешних файлов как методы класса
    list_modules = list_modules
    install_module = install_module

---

Событийные декораторы:

• @on_command(command_name: str | list[str]) — Регистрирует команду юзербота. Поддерживает списки алиасов и регистронезависимость. Работает на базе кастомного динамического фильтра (префиксы берутся из оперативной памяти клиента).
• @on_assistant_command(command_name: str | list[str]) — Регистрирует текстовый обработчик команд внутри бота-ассистента (например, /start).
• @on_assistant_inline() — Обрабатывает входящие инлайн-запросы, отправленные боту-ассистенту.
• @on_assistant_callback(pattern: str) — Обрабатывает клики на кнопки ассистента с фильтрацией по префиксу callback_data.

---

Защита кнопок

Любые клики по кнопкам ассистента должны проходить верификацию на отправителя во избежание несанкционированного доступа посторонних участников чата:

# На примере системного переводчика
@on_assistant_callback('tr_')
async def translator_callback(self, client: Client, callback_query: CallbackQuery):
    settings = client.db.get_category('settings')
    owner_id = await settings.get('owner_id')

    # Блокировка несанкционированных кликов
    if callback_query.from_user.id != owner_id:
        await callback_query.answer(
            text='Kaguya: Эй, это не твоя панель управления!',
            show_alert=True
        )
        return

---

Статический анализатор кода

При динамической установке модулей через команду .установить (ответом на файл .py, .txt или .zip), ядро автоматически проверяет код на наличие заблокированных системных вызовов перед компиляцией.

Бот проверяет код на наличие следующих триггеров: eval(, exec(, __import__, os.system, subprocess, .session, session_path.

Если хотя бы один паттерн найден — установка прерывается, а временные файлы безопасно стираются с диска для предотвращения возможного заражения системы.

---

6. Часто задаваемые вопросы (FAQ)

---

В: Батник [Windows]Kaguya_run.bat выдает ошибку "Failed building wheel for tgcrypto". Бот запустится?

О: Да, запустится и будет работать абсолютно стабильно. Ошибка возникает потому что разработчики tgcrypto еще не скомпилировали готовые бинарные пакеты под Windows. Можно установить компилятор C++ и перезапустить скрипт.

---

В: Как мне добавить стороннюю библиотеку для моего собственного модуля?

О: Поскольку ядро Кагуи должно оставаться чистым и независимым, не нужно добавлять свои библиотеки в корневой requirements.txt. Вместо этого используй Python-паттерн обработки исключений импорта в начале своего модуля:

try:
    import some_library
except ImportError:
    raise ImportError("Для работы модуля требуется библиотека 'some_library'. Установи её командой: pip install some_library")

Наша песочница при попытке установить твой модуль через .установить безопасно перехватит этот ImportError и выведет твою инструкцию пользователю прямо в чат Telegram.

---

Мой бот-ассистент не реагирует на клики кнопок или инлайн-запросы. Что делать?

О: Самая частая причина — выключенный инлайн-режим в настройках самого бота в Telegram. Инструкция настройки Инлайн-режима описана в 4 разделе.

---

Как запустить Кагую на удаленном сервере 24/7?

О: Самый надежный способ запустить бота круглосуточно — использовать VPS под управлением Linux (Ubuntu/Debian). Подробный алгоритм запуска описан в тут.

---

Где хранятся настройки и кэш бота? Как их полностью сбросить?

О: Все данные хранятся в папке data/storage/ в виде высокоскоростных локальных баз SQLite diskcache.

• Если тебе нужно отвязать бота-помощника, используй команду .токен_удалить.
• Если ты хочешь полностью сбросить все настройки бота до заводских, просто останови бота в консоли и удали папку data/storage/ с диска. При следующем старте Кагуя создаст чистую базу автоматически.
• Если необходимо сбросить сессии, удали файлы .session в папке data/.