Dokumentacja `plugin.json`¶

Każda wtyczka w Pythonie deklaruje swoją tożsamość, punkt wejścia i umiejscowienie na pasku menu w pliku plugin.json obok swojego main.py. To ten sam schemat, którego używa strona C++; tylko pola entry i module są specyficzne dla Pythona.

Przykład¶

{
  "id":          "org.example.wordcount",
  "name":        "Word Count",
  "version":     "1.0.0",
  "vendor":      "Example, Inc.",
  "description": "Counts words and characters in the active document.",
  "apiVersion":  1,
  "entry":       "python",
  "module":      "main",
  "pyRequires":  [],
  "order":       900,
  "menus": [
    { "title": "Plugins", "barPriority": 570, "itemPriority": 100 }
  ]
}

Pola¶

Wymagane¶

Pole	Typ	Uwagi
`id`	string	Unikatowy identyfikator w formacie odwróconego DNS. Używany wszędzie — włączanie / wyłączanie, linie logu, ustawienia per wtyczka. Nie może się zmieniać między wersjami.
`apiVersion`	integer	Musi być równe hostowemu `MTE_PLUGIN_API_VERSION`. Obecnie `1`. Rozbieżność ujawnia się na stronie Wtyczki, a wtyczka jest wymieniona, ale nie ładowana.
`entry`	string	Musi być `"python"`, aby wtyczka trafiła do backendu Pythona. `"native"` lub brak kieruje przez loader Qt.
`module`	string	Nazwa modułu Pythona zawierającego `register(ctx)`. Przy `"main"` worker szuka `main.py` wewnątrz folderu wtyczki. Nazwy pakietowe z kropkami (`"src.main"`) to przyszłe rozszerzenie — faza 1 obsługuje tylko nazwy płaskie.

Zalecane¶

Pole	Typ	Uwagi
`name`	string	Czytelna dla człowieka nazwa wyświetlana na stronie Wtyczki.
`version`	string	Semver; poza tym dowolna forma.
`vendor`	string	Autor / organizacja. Pokazywane na stronie Wtyczki.
`description`	string	Jedna lub dwie linie. Pokazywane na stronie Wtyczki.

Opcjonalne¶

Pole	Typ	Uwagi
`order`	integer	Kolejność ładowania między wtyczkami; niższa ładuje się wcześniej. Domyślnie `1000`. Remisy rozstrzyga `id`.
`menus`	tablica obiektów	Zobacz poniżej.
`pyRequires`	tablica stringów	Stringi wymagań pip (np. `["requests>=2.31"]`). Przy pierwszym uruchomieniu wtyczki edytor przygotowuje wirtualne środowisko per wtyczka, instaluje do niego te pakiety pipem i uruchamia w nim workera wtyczki (zobacz Pakowanie). Wpisy niebędące stringami i puste są pomijane.
`permissions`	tablica stringów	Zgrubne deklaracje możliwości (np. `["network"]`), pokazywane tylko do odczytu w kolumnie Uprawnienia okna Preferencje → Wtyczki, aby użytkownicy widzieli, co wtyczka deklaruje. Wyłącznie deklaracja — jeszcze nieegzekwowana.
`thirdParty`	tablica obiektów	Komponenty zewnętrzne dołączane przez wtyczkę, do atrybucji w oknie O programie. Każdy wpis: `name` (wymagane), `license`, `url`, `file`. Dostarcz tekst licencji wskazany przez `file` obok wtyczki w `Plugins/Licenses/<id>/`. Zobacz poniżej.

`menus`¶

Każdy wpis deklaruje jedno menu najwyższego poziomu, do którego wtyczka kontrybuuje, i ustala jego pozycję. Powtórz po jednym obiekcie na każde menu najwyższego poziomu, którego dotykasz (Tools, Plugins, Help itd.).

"menus": [
  { "title": "Plugins", "barPriority": 570, "itemPriority": 100 }
]

Pole	Typ	Uwagi
`title`	string, wymagane	Etykieta menu najwyższego poziomu, pod którym żyje pozycja (`Plugins`, `Tools`, …). Musi odpowiadać skrajnie lewemu segmentowi ścieżek przekazywanych do `ctx.menus.add_item()`.
`barPriority`	integer, opcjonalne	Ranga od lewej do prawej na pasku menu. Niższa = bardziej w lewo. Menu rdzenia mają stałe priorytety rozstawione co 100 (Plik `100`, Edycja `200`, …, Window `600`); `570` umieszcza Twoje podmenu w okolicy pozycji `Plugins`. Powtarzane w wielu wtyczkach celujących w to samo menu najwyższego poziomu; „ostatni wygrywa" jest w porządku, bo operacja jest idempotentna.
`itemPriority`	integer, opcjonalne	Pionowa ranga całego bloku Twojej wtyczki wewnątrz menu-liścia. Domyślnie `1000`. Niższa = wyżej.

NIE wymieniasz tu pojedynczych pozycji — te dodaje w czasie działania ctx.menus.add_item(). menus dotyczy wyłącznie umiejscowienia na pasku menu.

`thirdParty`¶

Zadeklaruj każdy komponent zewnętrzny dołączany przez Twoją wtyczkę, aby okno O programie mogło go uznać. Każdy wpis:

"thirdParty": [
  { "name": "SomeLib", "license": "MIT",
    "url": "https://example.com/", "file": "SomeLib-LICENSE.txt" }
]

Pole	Typ	Uwagi
`name`	string, wymagane	Komponent. Wpisy bez niepustej nazwy są pomijane.
`license`	string, opcjonalne	Etykieta w stylu SPDX, np. `MIT`, `LGPL-3.0`.
`url`	string, opcjonalne	Strona projektu/domowa.
`file`	string, opcjonalne	Nazwa pliku dostarczanego tekstu licencji, rozwiązywana jako `Plugins/Licenses/<your-plugin-id>/<file>`.

Teksty licencji należą do Ciebie: dostarcz je z pakietem wtyczki w Plugins/Licenses/<id>/. Edytor wymienia komponenty i kieruje użytkowników do tego folderu; nie przechowuje tekstów zewnętrznych Twojej wtyczki we własnym folderze Licenses/.

Sonda statyczna¶

W momencie wykrywania — i ponownie przy instalacji pakietu .mteplugin — host czyta module, otwiera <pluginDir>/<module>.py i potwierdza, że zawiera on def register(...) najwyższego poziomu — żaden kod się nie wykonuje. Instalator odrzuca wadliwy pakiet oknem błędu; wykrywanie po cichu pomija wtyczkę z linią błędu w logu:

PythonPluginBackend: skipping 'org.example.wordcount': module
'.../main.py' does not declare a top-level `def register(...)`.

Trzymaj register w kolumnie 0 linii zaczynającej się od def register(.

Jeśli Twoja wtyczka kontrybuuje do Plugins z barPriority: 570, menu pojawia się na pasku menu z rangą 570. Dwie wtyczki z różnymi wartościami barPriority dla tego samego tytułu ścigają się: wygrywa ta załadowana jako ostatnia, ale ponieważ obie zwykle deklarują tę samą rangę dla danego menu, nie ma to znaczenia. Pełny model porządkowania: PLUGIN_ARCHITECTURE.md §13.

Co tu NIE należy¶

Host parsuje pola udokumentowane powyżej i ignoruje wszystko inne — nie wymyślaj pól; nieznany klucz to po cichu martwy balast.

Dokumentacja plugin.json¶