Balenie a inštalácia¶

Zásuvný modul v Pythone je priečinok so súborom plugin.json a modulom Pythonu. Nainštalovať ho môžete dvoma spôsobmi: zabaliť ho ako archív .mteplugin a použiť inštalátor editora (odporúčané), alebo priečinok ručne vložiť do niektorého priečinka zásuvných modulov.

Začnite od šablóny

Hotový základ na skopírovanie nájdete v repozitári v Python/templates/plugin-template-python/ — tri súbory (plugin.json, main.py, README.md) plus CLAUDE.md určený pre Clauda. Premenujte priečinok na krátky názov svojho modulu, upravte štyri polia v plugin.json a začnite písať register(ctx). Nainštalovaná sada SDK dodáva tú istú šablónu v share/MTEPluginSDK/plugin-template-python/.

Rozloženie priečinka zásuvného modulu¶

hello/
├── plugin.json      # required
└── main.py          # required; module name from plugin.json.module

Všetko, čo zásuvný modul potrebuje, musí byť vnútri tohto priečinka. Podriadené importy fungujú, ale musia byť ploché — bodkové názvy v poli module súboru plugin.json sú budúcim rozšírením.

Môžete pridať ďalšie súbory (README, LICENSE) — hostiteľ ignoruje, čo nerozpozná.

Balíky `.mteplugin` (odporúčané)¶

Zabaľte súbory zásuvného modulu do zipu a archívu dajte príponu .mteplugin (funguje aj obyčajné .zip). Prijímajú sa obidva tvary:

hello.mteplugin              hello.mteplugin
├── plugin.json              └── hello-1.0.0/        # any folder name
└── main.py                      ├── plugin.json
                                 └── main.py

Jediný obaľujúci priečinok — prirodzený výsledok zabalenia priečinka — sa normalizuje preč: zásuvný modul sa vždy inštaluje do <Plugins>/<id>/, podľa id z manifestu, nikdy nie podľa názvu priečinka v archíve. Aj preto inštalácia verzie 2 nahradí verziu 1, namiesto aby stála vedľa nej.

Nainštalujte ho cez Predvoľby → Zásuvné moduly → Nainštalovať zásuvný modul... a reštartujte editor.

Inštalujte iba balíky, ktorým dôverujete

Inštalátor overuje, či je balík štruktúrne v poriadku (pozri nižšie) — nerobí nedôveryhodný zásuvný modul bezpečným na spustenie. Po načítaní beží modul s rovnakým prístupom k vašim súborom, nastaveniam a sieti ako editor a nie je izolovaný. Statická kontrola register(...) pri inštalácii nespúšťa žiadny kód, ale kód modulu sa spustí pri ďalšom štarte. K súboru .mteplugin (a ku všetkým konfiguračným súborom či súborom JSON, ktoré so sebou nesie) pristupujte ako k neznámemu programu: inštalujte ho iba zo zdroja, ktorému dôverujete. Úplné upozornenie nájdete v časti Zásuvné moduly.

Čo inštalátor overuje¶

Balík sa úplne overí oproti jednorazovej kópii skôr, než sa čokoľvek na disku dotkne — zlý balík nikdy nemôže narušiť existujúcu inštaláciu:

plugin.json sa dá spracovať, má id, apiVersion zodpovedá editoru, entry je "python" a module je prítomné.
Výpis archívu je bezpečný: žiadne absolútne cesty ani položky s .., najviac 10 000 položiek, najviac 256 MiB po rozbalení a aspoň jeden súbor .py.
Po rozbalení do dočasného priečinka existuje deklarovaný <module>.py a deklaruje def register(...) na najvyššej úrovni — tá istá statická kontrola, akú používa vyhľadávanie. Pri inštalácii sa nespustí žiadny kód v Pythone.

Každé zlyhanie vyústi do čitateľného chybového dialógu a zásuvné moduly editora ostanú nedotknuté.

Aktualizácia a odinštalovanie¶

Inštaláciou balíka, ktorého id už je nainštalované, sa pôvodný modul nahradí. Ak je tento modul práve načítaný, aktualizácia sa pripraví a uplatní sa pri ďalšom spustení.
Odinštalovať sa dá z tej istej stránky Predvolieb; odstránenie prebehne takisto pri ďalšom spustení, keď nie je nič načítané.
Dodávané (vstavané) zásuvné moduly sa nedajú prekryť nainštalovaným balíkom s rovnakým id.

Ručná inštalácia (vložením priečinka)¶

Editor pri každom spustení hľadá zásuvné moduly v dvoch priečinkoch:

Dodávané — vedľa spustiteľného súboru, v <exe-dir>/Plugins/. Nachádzajú sa tu vstavané moduly (napríklad HelloPython).
Používateľské — pre daného používateľa, zapisovateľné. Vo Windows je to %LOCALAPPDATA%/MTE/Plugins/, na macOS ~/Library/Application Support/MTE/Plugins/, na Linuxe ~/.local/share/MTE/Plugins/.

Prehľadávajú sa obidva priečinky. Ak sa to isté id objaví v obidvoch, vyhráva prvý výskyt (dodávané majú prednosť). Nové priečinky sa prevezmú po reštarte editora — načítanie za behu nie je podporované.

Dve prijateľné rozloženia¶

Prehľadávanie hľadá plugin.json buď priamo v priečinku zásuvných modulov (voľne), alebo vnútri jednej úrovne priameho podpriečinka (priečinok na modul):

Plugins/
├── plugin.json         # loose -- one plugin at the top level
├── main.py
└── hello/              # per-plugin folder -- one plugin
    ├── plugin.json
    └── main.py

Odporúčaným rozložením je priečinok na modul; je to tvar, aký vytvára inštalátor.

Závislosti (`pyRequires`)¶

plugin.json môže deklarovať požiadavky pip ako vnorené pole:

"pyRequires": ["requests>=2.31"]

Pri prvom spustení zásuvného modulu editor pripraví virtuálne prostredie v <AppLocalData>/PluginVenv/<id>/ (python -m venv a pip install, čo si ten jeden raz vyžaduje prístup na sieť) a pracovný proces modulu spustí pod interpretom tohto prostredia. Ďalšie spustenia ho znova použijú; zmena pyRequires prostredie automaticky pripraví nanovo (prostredie nesie pečiatku požiadaviek, pre ktoré bolo vytvorené).

Zlyhanie prípravy (bez siete, preklep v požiadavke) ponechá zásuvný modul vypísaný, ale nenačítaný, s chybou z pipu v logu; pri ďalšom spustení sa to skúsi znova.
Odinštalovaním zásuvného modulu sa spolu s jeho priečinkom odstráni aj jeho virtuálne prostredie (prostredie je odvodenými údajmi — pri prípadnej opätovnej inštalácii sa vytvorí znova z pyRequires).

Počítače bez siete a s obmedzeniami¶

Dodajte vopred zostavené virtuálne prostredie vnútri balíka ako priečinok venv/ v koreni zásuvného modulu. Keď je prítomné, vyhráva nad všetkým — pip sa nikdy nespustí. Zostavte ho na počítači s rovnakým operačným systémom a architektúrou, keďže virtuálne prostredia nie sú medzi platformami prenosné.

Vloženie závislostí (malé závislosti čisto v Pythone)¶

Pri jednom module čisto v Pythone naďalej funguje jeho vloženie do priečinka zásuvného modulu, čím sa mechanizmu virtuálnych prostredí vyhnete úplne:

# main.py
import os, sys
sys.path.insert(0, os.path.join(os.path.dirname(__file__), "vendor"))

import your_dep

Deklarované oprávnenia¶

plugin.json môže niesť pole permissions (napríklad ["network"]). Stránka Zásuvné moduly v Predvoľbách ho zobrazuje v stĺpci Oprávnenia iba na čítanie, aby používatelia videli, čo o sebe zásuvný modul deklaruje. Je to deklarácia, nie vynucovanie — izolácia je prácou do budúcna.

Kam idú zapisovateľné údaje¶

Priečinok zásuvných modulov obsahuje kód. Údaje za behu (vyrovnávacie pamäte, používateľská konfigurácia, indexy) patria do samostatného dátového priečinka pre daný modul, ktorý spravuje hostiteľ — ctx.data_dir() vracia jeho absolútnu cestu. Z vášho súboru .py za behu do priečinka zásuvných modulov NEZAPISUJTE; odinštalovanie odstráni celý priečinok <Plugins>/<id>/ a zápisy urobené inde v strome zásuvných modulov sa nikdy neupratujú.

Nasadenie na iné počítače¶

Dodajte súbor .mteplugin — je samostatný a na prijímajúcej strane sa overí. Funguje aj zip, tarball či naklonovanie priečinka z gitu do používateľského priečinka zásuvných modulov.

Zapnutie a vypnutie¶

Stránka Zásuvné moduly v Predvoľbách vypisuje každý nájdený modul (natívne aj pythonovské spolu) s tými istými stĺpcami pôvodu a stavu. Vypnutie modulu ho ponechá vo výpise, ale zabráni tomu, aby sa pri spustení vyvolala jeho továreň — nespustí sa žiadny pracovný proces. Zapnite ho znova a reštartujte, čím ho vrátite späť.