> 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/rukovodstvo/manifest.md).

# Манифест catalib.toml

Файл `catalib.toml` в корне проекта описывает метаданные плагина и параметры сборки. Формат — TOML, две секции: `[plugin]` и `[build]`.

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

```toml
[plugin]
id = "my_plugin"
name = "My Plugin"
version = "1.0.0"
description = "Что делает плагин"
author = "Ваше имя"
icon = "exteraPlugins/1"
min_version = ">=12.5.1"
requirements = ["tinydb", "mpmath"]

[build]
src = "src"
entry = "plugin"
out = "dist"
vendor = "auto"
```

## Секция `[plugin]`

| Ключ           | Обязателен | Формат / правило                       | Куда попадает                   |
| -------------- | ---------- | -------------------------------------- | ------------------------------- |
| `id`           | да         | 2–32 символа, `^[a-z][a-z0-9_]{1,31}$` | `__id__`, имя файла, имя модуля |
| `name`         | да         | непустая строка                        | `__name__`                      |
| `version`      | да         | `N[.N[.N[.N]]]` (например `1.0.0`)     | `__version__`                   |
| `description`  | нет        | строка                                 | `__description__`               |
| `author`       | нет        | строка                                 | `__author__`                    |
| `icon`         | нет        | строка (например `exteraPlugins/1`)    | `__icon__`                      |
| `min_version`  | нет        | ограничение версии приложения          | `__app_version__`               |
| `sdk_version`  | нет        | ограничение версии SDK                 | `__sdk_version__`               |
| `requirements` | нет        | список строк PEP 508                   | `__requirements__`              |

### `id`

Идентификатор обязан быть валидным именем Python-модуля: начинается со строчной латинской буквы, далее `[a-z0-9_]`, длина 2–32. Он же — имя выходного файла и имя импортируемого модуля. Дефис недопустим.

### `version`

От одного до четырёх числовых сегментов через точку: `1`, `1.0`, `1.2.3`, `1.2.3.4`. Суффиксы вроде `-beta` не допускаются (ограничение exteraGram).

### `min_version` и `sdk_version`

Ограничения вида `[оператор]версия`, операторы `>=`, `<=`, `==`, `>`, `<` (например `>=12.5.1`). `min_version` эмитится как канонический `__app_version__`. catalib **намеренно не эмитит** нестандартный `__min_version__` — на него exteraGram показывает отдельный экран несовместимости (см. [Подводные камни](/catalib/reshenie-problem/troubleshooting.md)).

`sdk_version` — жёсткий гейт против версии SDK на устройстве. Версии SDK в обиходе разные (встречались `1.4.3.3` и `1.4.4.1`); завышенное значение заблокирует установку на старых сборках. Если плагин использует только стабильные API, безопаснее **не задавать** `sdk_version`.

### `requirements`

Список зависимостей в формате PEP 508. exteraGram ставит **только pure-Python wheels**. Бинарные пакеты (`numpy`, `pandas`, `scipy`, `cryptography`, `opencv-*`) отклоняются на этапе сборки. Подробнее — [Зависимости](/catalib/rukovodstvo/dependencies.md).

## Секция `[build]`

| Ключ     | По умолчанию | Назначение                                        |
| -------- | ------------ | ------------------------------------------------- |
| `src`    | `"src"`      | каталог исходного дерева плагина                  |
| `entry`  | `"plugin"`   | модуль точки входа (относительное точечное имя)   |
| `out`    | `"dist"`     | каталог для собранных файлов                      |
| `vendor` | `"auto"`     | режим вендоринга `catalib`: `"auto"` или `"full"` |

`entry` — относительное имя модуля внутри `src` (например `plugin` → `src/plugin.py`, или `app.main` → `src/app/main.py`). В нём должен быть подкласс плагина.

### `vendor` — что из `catalib` попадает в сборку

* `"auto"` (по умолчанию) — **помодульный отбор** (tree-shaking): в файл вшиваются только модули `catalib.*`, которые плагин реально импортирует, плюс их транзитивные зависимости. Для `catalib.support` генерируется урезанный `__init__`. Это заметно уменьшает размер собранного плагина. Анализ статический и консервативный: при неоднозначных импортах (`import catalib.support` как объект, `from catalib.support import *`, несопоставимое имя, импорт `catalib` вне `catalib.support`) выполняется полный вендоринг с предупреждением — корректность важнее размера.
* `"full"` — вшить весь `catalib.support` (прежнее поведение). Нужно, если плагин обращается к подмодулям `catalib` динамически (через `importlib`/строки) — статический анализ такого не видит.

`catalib build` печатает сводку: сколько модулей `catalib` отобрано и отсечено, либо «полный» с причиной.

## Строгая валидация

Загрузчик манифеста строгий:

* отсутствие секции `[plugin]` или обязательных ключей — ошибка;
* неизвестный ключ в `[plugin]`/`[build]` — ошибка (защита от опечаток);
* неизвестная секция верхнего уровня — ошибка;
* неверный тип значения — ошибка с указанием поля.

Пример сообщения:

```
ManifestError: неизвестные ключи в [plugin]: verison
```

## Метаданные эмитятся литералами

Все строковые метаданные попадают в собранный файл **строковыми литералами** — это требование AST-парсера exteraGram. Поэтому значения задаются в `catalib.toml`, а не вычисляются в коде. Динамические `__id__ = get_id()` в исходниках недопустимы; catalib проверяет это статически (см. [Метаданные и валидация](/catalib/vnutrennee-ustroistvo/metadata-and-validation.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/rukovodstvo/manifest.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.