> For the complete documentation index, see [llms.txt](https://raito-kyokai.gitbook.io/catalib/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://raito-kyokai.gitbook.io/catalib/nachalo-raboty/concepts.md).

# Как это устроено

Понимание модели нужно, чтобы не бороться с инструментом.

## Однофайловая модель exteraGram

exteraGram (форк Telegram) исполняет плагины через **Chaquopy** — встроенный CPython 3.11. Движок (`PythonPluginsEngine`) загружает плагин так:

1. ставит pip-зависимости из `__requirements__` (только pure-Python wheels);
2. обновляет кеши импорта;
3. выполняет `importlib.import_module("<plugin_id>")`;
4. находит подкласс `BasePlugin`, инстанцирует его, вызывает `on_plugin_load()`.

Плагином считается **только файл верхнего уровня** `<plugin_id>.py`. Метаданные (`__id__`, `__name__`, ...) читаются статически через `ast` — значения обязаны быть **строковыми литералами**. Установка и распространение для конечного пользователя — однофайловые.

## Что делает catalib

catalib превращает дерево исходников в один такой файл. Внутрь выходного файла встраивается компактный загрузчик на `sys.meta_path`, который регистрирует исходные модули плагина в памяти. Благодаря этому:

* обычные `import` и относительные импорты внутри плагина работают без изменений;
* трейсбеки указывают на исходные файлы (через `linecache`);
* наружу уходит один валидный файл.

Механизм подтверждён эмпирически на реальном устройстве под Chaquopy 3.11.

## Две среды исполнения

В проекте catalib (и в собранном плагине) сосуществуют две среды:

| Среда                  | Где исполняется                      | Что туда входит                                                                            |
| ---------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------ |
| **Среда инструмента**  | CPython 3.11+ на машине разработчика | `catalib.cli`, `catalib.manifest`, `catalib.bundler`, `catalib.deploy`, `catalib.scaffold` |
| **Встраиваемая среда** | Chaquopy 3.11 на устройстве          | `catalib.runtime` (загрузчик), `catalib.support` (мини-фреймворк)                          |

Встраиваемый код зависит **только** от стандартной библиотеки и SDK exteraGram — никаких `typer`/`watchfiles`. Это жёсткая граница, она проверяется тестом и важна: на устройстве пакета `catalib` нет, поэтому `catalib.support` **вендорится** (вшивается) в собранный файл.

## Структура собранного файла

```python
# 1. Литералы метаданных (читает exteraGram через AST)
__id__ = "my_plugin"
__name__ = "My Plugin"
__version__ = "1.0.0"
__app_version__ = ">=12.5.1"

# 2. Встроенный загрузчик (исходник catalib.runtime.bootstrap)
class _CatalibLoader: ...
class _CatalibFinder: ...
def catalib_install(...): ...

# 3. Таблица встроенных исходников
_CATALIB_SOURCES = {
    "my_plugin.plugin": ("<исходник>", False, "<my_plugin>/plugin.py"),
    "catalib.support":  ("<исходник>", True,  "<catalib-vendor>/..."),
    ...
}
_CATALIB_ENTRY = "my_plugin.plugin"

# 4. Активация
catalib_install("my_plugin", globals(), _CATALIB_SOURCES, _CATALIB_ENTRY)
```

Когда exteraGram импортирует `my_plugin`, `catalib_install`:

* регистрирует finder в `sys.meta_path`;
* делает модуль пакетом, восстанавливает его идентичность;
* импортирует точку входа (она тянет свои подмодули через finder);
* поднимает класс плагина на верхний уровень, чтобы движок его нашёл.

Подробности — в разделе [Как работает сборка](/catalib/vnutrennee-ustroistvo/how-it-works.md).

## Изоляция плагинов

Все модули плагина регистрируются под уникальным именем-пакетом `<plugin_id>` (он уникален в exteraGram). Вендоренные `catalib.*` имеют общее имя между плагинами, поэтому загрузчик при каждой загрузке вычищает устаревшие вендоренные копии из общего `sys.modules` — свежий бандл не затеняется кодом из прошлого деплоя.

## Канал доставки

Прямой `adb push` в приватный каталог плагинов **запрещён** без root. Штатный канал — встроенный **dev server** exteraGram (TCP 42690). catalib использует его для `catalib watch --deploy`. Подробнее — [Подготовка устройства](/catalib/deploi/device-setup.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://raito-kyokai.gitbook.io/catalib/nachalo-raboty/concepts.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.