Creazione dei pacchetti e installazione¶

Un plugin Python è una cartella con un plugin.json e un modulo Python. Puoi installarne uno in due modi: impacchettarlo come archivio .mteplugin e usare l'installer dell'editor (consigliato), oppure depositare la cartella a mano in una cartella di plugin.

Parti dal modello

Un punto di partenza pronto da copiare si trova in Python/templates/plugin-template-python/ nel repository: tre file (plugin.json, main.py, README.md) più un CLAUDE.md rivolto a Claude. Rinomina la cartella con il nome breve del tuo plugin, modifica quattro campi in plugin.json e comincia a scrivere register(ctx). L'SDK installato distribuisce lo stesso modello sotto share/MTEPluginSDK/plugin-template-python/.

Disposizione della cartella del plugin¶

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

Tutto ciò che serve al plugin deve stare dentro questa cartella. Le sotto-importazioni funzionano ma devono essere piatte: i nomi di module con punti in plugin.json sono un'estensione futura.

Puoi aggiungere altri file (README, LICENSE): l'host ignora ciò che non riconosce.

Pacchetti `.mteplugin` (consigliato)¶

Comprimi i file del plugin e dai all'archivio l'estensione .mteplugin (va bene anche un semplice .zip). Sono accettate entrambe le forme:

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

La singola cartella di involucro — il risultato naturale della compressione di una cartella — viene normalizzata via: il plugin si installa sempre in <Plugins>/<id>/, indicizzato dall'id del manifest, mai dal nome di cartella dell'archivio. È anche il motivo per cui installare la versione 2 di un plugin sostituisce la versione 1 invece di affiancarla.

Installalo tramite Preferenze → Estensioni → Installa estensione... e riavvia l'editor.

Installa solo pacchetti di cui ti fidi

L'installer verifica che un pacchetto sia strutturalmente sano (vedi sotto): non rende sicuro l'avvio di un plugin non fidato. Una volta caricato, un plugin gira con lo stesso accesso ai tuoi file, alle tue impostazioni e alla rete che ha l'editor, e non è confinato in una sandbox. La sonda statica di register(...) non esegue alcun codice al momento dell'installazione, ma il codice del plugin viene eseguito al lancio successivo. Tratta un .mteplugin (e qualsiasi file di configurazione o JSON che distribuisce) come un programma sconosciuto: installalo solo da una fonte di cui ti fidi. Vedi Plugin per l'avvertenza completa.

Che cosa valida l'installer¶

Il pacchetto viene validato integralmente su una copia usa e getta prima che venga toccato alcunché su disco: un pacchetto guasto non può mai disturbare un'installazione esistente:

plugin.json si analizza correttamente, ha un id, apiVersion corrisponde all'editor, entry è "python" e module è presente.
L'elenco dell'archivio è sicuro: nessun percorso di voce assoluto o con .., al massimo 10 000 voci, al massimo 256 MiB una volta estratto e almeno un file .py.
Dopo l'estrazione in una cartella temporanea, il <module>.py dichiarato esiste e dichiara un def register(...) di primo livello — la stessa sonda statica usata dall'individuazione. Al momento dell'installazione non viene eseguito alcun codice Python.

Qualsiasi fallimento produce una finestra di errore leggibile e lascia intatti i plugin dell'editor.

Aggiornare e disinstallare¶

Installare un pacchetto il cui id è già installato lo sostituisce. Se quel plugin è attualmente caricato, l'aggiornamento viene predisposto e applicato al lancio successivo.
Disinstalla dalla stessa pagina delle Preferenze; anche la rimozione avviene al lancio successivo, quando non è caricato nulla.
I plugin inclusi (integrati) non possono essere scavalcati da un pacchetto installato con lo stesso id.

Installare a mano (deposito di una cartella)¶

L'editor individua i plugin in due cartelle a ogni avvio:

Inclusi — accanto all'eseguibile, in <exe-dir>/Plugins/. Qui vivono i plugin integrati (per esempio HelloPython).
Utente — per utente, scrivibile. Su Windows è %LOCALAPPDATA%/MTE/Plugins/, su macOS ~/Library/Application Support/MTE/Plugins/, su Linux ~/.local/share/MTE/Plugins/.

Entrambe le cartelle vengono esaminate. Se lo stesso id compare in entrambe, vince la prima occorrenza (gli inclusi hanno la precedenza). Riavvia l'editor per raccogliere le nuove cartelle: la ricarica a caldo non è supportata.

Due disposizioni accettabili¶

La scansione cerca plugin.json o direttamente nella cartella dei plugin (sciolto) oppure dentro un livello di sottocartella immediata (cartella per plugin):

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

La cartella per plugin è la disposizione consigliata; è la forma che produce l'installer.

Dipendenze (`pyRequires`)¶

plugin.json può dichiarare requisiti pip come array in linea:

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

Al primo avvio del plugin l'editor predispone un ambiente virtuale in <AppLocalData>/PluginVenv/<id>/ (python -m venv + pip install, il che richiede quell'unica volta l'accesso alla rete) ed esegue il worker del plugin con l'interprete di quel venv. I lanci successivi lo riusano; cambiare pyRequires fa ripredisporre il venv automaticamente (il venv porta con sé un'impronta dei requisiti per cui è stato costruito).

I fallimenti nella predisposizione (niente rete, un requisito scritto male) lasciano il plugin elencato ma non caricato, con l'errore di pip nel log; il lancio successivo riprova.
Disinstallare un plugin ne rimuove il venv insieme alla cartella del plugin (un venv è dato derivato: viene ricostruito da pyRequires se mai lo reinstalli).

Macchine offline / a regime chiuso¶

Distribuisci un venv precostruito dentro il pacchetto, come cartella venv/ nella radice del plugin. Quando c'è, prevale su tutto: pip non viene mai eseguito. Costruiscilo su una macchina con lo stesso sistema operativo e la stessa architettura, perché i venv non sono portabili tra piattaforme.

Inclusione diretta (piccole dipendenze Python pure)¶

Per un singolo modulo Python puro, includerlo direttamente nella cartella del plugin funziona ancora ed evita del tutto il macchinario dei venv:

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

import your_dep

Permessi dichiarati¶

plugin.json può portare un array permissions (per esempio ["network"]). La pagina Plugin delle Preferenze lo mostra in una colonna Autorizzazioni di sola lettura, così che gli utenti possano vedere che cosa un plugin dichiara di sé. È una dichiarazione, non un'imposizione: il confinamento in sandbox è lavoro futuro.

Dove vanno i dati scrivibili¶

La cartella dei plugin contiene codice. I dati a tempo di esecuzione (cache, configurazione per utente, indici) vanno in una cartella dati separata per plugin gestita dall'host: ctx.data_dir() ne restituisce il percorso assoluto. NON scrivere nella cartella dei plugin dal tuo .py a tempo di esecuzione; la disinstallazione rimuove l'intera cartella <Plugins>/<id>/, e le scritture fatte altrove nell'albero dei plugin non vengono mai ripulite.

Distribuire su altre macchine¶

Distribuisci il file .mteplugin: è autosufficiente e viene validato all'arrivo. Funziona anche uno zip / tarball / git clone della cartella nella cartella dei plugin per utente.

Abilitare / disabilitare¶

La pagina Plugin delle Preferenze elenca ogni plugin individuato (nativi + Python, insieme) con le stesse colonne di origine e stato. Disabilitare un plugin lo mantiene elencato ma impedisce che la sua fabbrica venga invocata all'avvio: non viene avviato alcun worker. Riabilitalo e riavvia per riaverlo.