Плагины DevGram

Введение

Плагин — это файл .plugin (или .py) с классом-наследником BasePlugin. Внутри клиента работает встроенный Python 3.11 — код плагина выполняется прямо в приложении, без root и без внешнего Xposed-фреймворка.

Что умеет плагин:

• менять текст исходящих и входящих сообщений;
• добавлять пункты в меню сообщения и свою страницу настроек;
• показывать тосты, плашки и диалоги, читать/писать буфер и файлы;
• через хуки методов — переопределять поведение любого Java-метода клиента.

Требования

• DevGram для Android (Android 7.0+, arm64).
• Знание Python. Стандартная библиотека доступна; сторонние пакеты — нет.
• Любой текстовый редактор. Готовый файл сохраняй с расширением .plugin.

Первый плагин

from devgram import BasePlugin

class Hello(BasePlugin):
    id = "hello"
    name = "Привет DevGram"
    version = "1.0"
    author = "@you"

    def on_send_message(self, text):
        return text.replace(":love:", "❤️")

Сохрани как hello.plugin, отправь файл в чат и тапни по нему — появится карточка установки.

Метаданные

Атрибуты класса. Читаются без выполнения кода (через ast) — карточка установки безопасна.

Жизненный цикл

def on_load(self):     # один раз при загрузке — тут ставь хуки
    self.log("загружен")

def on_unload(self):   # при выгрузке / отключении
    pass

self.enabled — выключенный плагин остаётся загруженным, но события и хуки ему не приходят.

Страница настроек плагина

Верни строки из settings() — у плагина появится своя страница настроек. Значения храни через get_setting/set_setting.

def settings(self):
    return [
        ("header", "",      "Приветствие"),
        ("switch", "on",    "Включить"),
        ("text",   "greet", "Текст"),
        ("button", "reset", "Сбросить"),
    ]

def on_setting_click(self, key):
    if key == "reset":
        self.set_setting("greet", "")
        self.toast("Сброшено")

Сообщения

def on_send_message(self, text):
    # перед отправкой. return: str — новый текст | None — без изменений | False — отменить
    if text.strip() == "/id":
        return "Мой id: " + str(self.me())
    return None

def on_receive_message(self, text):
    # входящий текст — только чтение
    pass

Меню сообщения

Добавляй пункты в меню долгого тапа по сообщению.

def menu_items(self):
    return ["Реверс текста"]

def on_menu_click(self, label, message_text, dialog_id):
    self.alert("Реверс", message_text[::-1])

Апдейты (TL)

Переопредели on_update, чтобы получать сырые TL-апдейты (Java-объект TLRPC.Update). Читай поля через рефлексию. Диспетчер включается сам, только если метод переопределён.

def on_update(self, update):
    if type(update).__name__ == "TL_updateUserTyping":
        self.log("печатает: " + str(update.user_id))

client_utils

android_utils

Диалоги и плашки

self.toast("Готово")                 # короткий тост
self.bulletin("Скопировано")          # плашка в стиле Telegram
self.alert("Заголовок", "Текст")     # диалог с кнопкой OK

Настройки и файлы

# key-value, переживает перезапуск
n = int(self.get_setting("count", "0"))
self.set_setting("count", str(n + 1))

# файлы в личной папке плагина
self.write_file("data.txt", "hello")
data = self.read_file("data.txt")

Иконка плагина

Задай icon — URL картинки. DevGram скачает её и покажет как аватарку плагина в списке и в карточке установки.

    icon = "https://devgram.space/favicon.png"

Хуки методов — основы

Самое мощное: перехватывай любой Java-метод клиента и меняй его аргументы или результат. Хуки ставь в on_load, логику пиши в before_hook / after_hook.

def on_load(self):
    self.hook(
        "org.telegram.messenger.MessagesController",  # класс (FQN)
        "isPremiumUser",                             # метод, или "<init>" для конструктора
        "org.telegram.tgnet.TLRPC$User",             # типы аргументов…
    )

def after_hook(self, frame):
    frame.setResult(True)   # у всех «премиум» → True

self.hook(class, method, *param_types) возвращает True при успехе. Один плагин может ставить несколько хуков — все они зовут общие before_hook/after_hook (различай по frame.method).

Объект frame (CallFrame)

Типы аргументов

Передавай типы параметров строками, точно как в сигнатуре Java-метода.

• Примитивы: int, long, boolean, byte, char, short, float, double.
• Классы — по полному имени: java.lang.String, java.lang.CharSequence.
• Вложенные классы — через $: org.telegram.tgnet.TLRPC$User.

Примеры хуков

Менять аргумент (заголовок экрана)

def on_load(self):
    self.hook("org.telegram.ui.ActionBar.ActionBar", "setTitle",
              "java.lang.CharSequence", "android.graphics.drawable.Drawable")

def before_hook(self, frame):
    s = str(frame.args[0])
    if s and not s.startswith("✨"):
        frame.args[0] = "✨ " + s

Подменять результат (премиум)

def on_load(self):
    self.hook("org.telegram.messenger.MessagesController",
              "isPremiumUser", "org.telegram.tgnet.TLRPC$User")

def after_hook(self, frame):
    frame.setResult(True)

Полезные классы для хуков

Клиент основан на Telegram для Android — имена классов оттуда. Несколько удобных точек:

Визуальные эффекты

Хелперы для «стеклянных» и размытых панелей. Обычно зовутся из before_hook/after_hook, где view = frame.thisObject.

Пример: стеклянная шапка

def on_load(self):
    self.hook("org.telegram.ui.ActionBar.ActionBar", "setBackgroundColor", "int")

def before_hook(self, frame):
    frame.args[0] = 0x66121018          # полупрозрачная стеклянная тонировка
    self.blur(frame.thisObject, 18)   # матовость (Android 12+)

Визуальные эффекты

Хелперы для «стеклянных» и размытых панелей. Обычно зовутся из before_hook/after_hook, где view = frame.thisObject.

Пример: стеклянная шапка

def on_load(self):
    self.hook("org.telegram.ui.ActionBar.ActionBar", "setBackgroundColor", "int")

def before_hook(self, frame):
    frame.args[0] = 0x66121018          # полупрозрачная тонировка
    self.blur(frame.thisObject, 18)    # матовое стекло (Android 12+)

Прямой доступ к Android (jclass)

Плагин НЕ ограничен хуками и хелперами выше. Через Chaquopy доступен весь Java/Android-рантайм — по возможностям плагин равен Xposed-модулю, просто на Python.

from java import jclass   # любой класс Android SDK / Telegram

Доступны View, Canvas, Paint, Shader, RenderEffect, RuntimeShader (AGSL-шейдеры, Android 13+), WindowManager, Window. Хелперы blur/tint/round_corners — лишь обёртки над этим.

GPU-шейдер (AGSL) на View

from java import jclass

def before_hook(self, frame):
    view = frame.thisObject
    if jclass("android.os.Build$VERSION").SDK_INT >= 33:
        RS = jclass("android.graphics.RuntimeShader")
        RE = jclass("android.graphics.RenderEffect")
        agsl = ("uniform shader content;"
                "half4 main(float2 p){ half4 c = content.eval(p);"
                " return half4(c.rgb*0.85 + 0.06, c.a); }")
        view.setRenderEffect(RE.createRuntimeShaderEffect(RS(agsl), "content"))

Навешивается один раз — дальше шейдер крутится на GPU каждый кадр, Python не участвует.

Установка и распространение

• Отправь файл .plugin в чат или канал.
• Тап по файлу → карточка установки (имя, автор, значок проверки) → «Установить».
• Проверенные плагины из реестра DevGram помечаются зелёным значком «Проверено».
• Управление — «Настройки → DevGram → Плагины»: тумблеры, настройки, удаление, «Система плагинов» по кнопке i.

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

• Код плагина выполняется в приложении. Ставь плагины только из проверенных источников.
• «Безопасный режим» (Плагины → i) отключает все хуки, не удаляя плагины.
• Если плагин уронил клиент — при следующем запуске безопасный режим включается сам, а полный отчёт о сбое копируется в буфер и сохраняется в файл.

Справочник хуков

Полный пример

from devgram import BasePlugin

class Toolbox(BasePlugin):
    id = "toolbox"
    name = "Инструменты"
    version = "1.0"
    author = "@you"
    icon = "https://devgram.space/favicon.png"

    def on_send_message(self, text):
        t = text.strip()
        if t == "/id":
            return "Мой id: " + str(self.me())
        if t.startswith("/upper "):
            return t[7:].upper()
        return None

    def menu_items(self):
        return ["Скопировать id чата"]

    def on_menu_click(self, label, message_text, dialog_id):
        self.copy(str(dialog_id))
        self.bulletin("Скопировано")