Paketering och installation¶

En Python-insticksmodul är en mapp med en plugin.json och en Python-modul. Du kan installera en på två sätt: paketera den som ett .mteplugin-arkiv och använda redigerarens installerare (rekommenderat), eller lägga mappen för hand i en insticksmodulskatalog.

Börja från mallen

En startpunkt som går att kopiera finns i Python/templates/plugin-template-python/ i repositoriet — tre filer (plugin.json, main.py, README.md) plus en CLAUDE.md riktad till Claude. Byt namn på mappen till din insticksmoduls korta namn, redigera fyra fält i plugin.json, och börja skriva register(ctx). Det installerade SDK:t levererar samma mall under share/MTEPluginSDK/plugin-template-python/.

Insticksmodulsmappens layout¶

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

Allt insticksmodulen behöver måste ligga inuti den här mappen. Delimporter fungerar men måste vara platta — module-namn med punkter i plugin.json är en framtida utvidgning.

Du får lägga till extra filer (README, LICENSE) — värden ignorerar det den inte känner igen.

`.mteplugin`-paket (rekommenderat)¶

Komprimera insticksmodulens filer och ge arkivet filtillägget .mteplugin (en vanlig .zip fungerar också). Båda formerna godtas:

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

Den enda omslutande mappen — det naturliga resultatet av att komprimera en mapp — normaliseras bort: insticksmodulen installeras alltid till <Plugins>/<id>/, nycklad av manifestets id, aldrig av arkivets mappnamn. Det är också därför att installera version 2 av en modul ersätter version 1 i stället för att ställa sig bredvid den.

Installera den via Inställningar → Insticksmoduler → Installera insticksmodul... och starta om redigeraren.

Installera bara paket du litar på

Installeraren kontrollerar att ett paket är strukturellt sunt (se nedan) — den gör inte en obetrodd insticksmodul säker att köra. När den väl lästs in körs en insticksmodul med samma åtkomst till dina filer, inställningar och ditt nätverk som redigeraren, och den körs inte i sandlåda. Den statiska sonden för register(...) kör ingen kod vid installationen, men modulens kod körs vid nästa start. Behandla en .mteplugin (och varje konfigurations- eller JSON-fil den levererar) som ett okänt program: installera den bara från en källa du litar på. Se Insticksmoduler för hela varningen.

Vad installeraren validerar¶

Paketet valideras fullständigt mot en engångskopia innan något på disken rörs — ett dåligt paket kan aldrig störa en befintlig installation:

plugin.json går att tolka, har ett id, apiVersion stämmer med redigeraren, entry är "python", och module finns.
Arkivlistan är säker: inga absoluta sökvägar och inga med .., högst 10 000 poster, högst 256 MiB uppackat, och minst en .py-fil.
Efter uppackning till en tillfällig katalog finns den deklarerade <module>.py och deklarerar ett def register(...) på toppnivå — samma statiska sond som upptäckten använder. Ingen Python-kod körs vid installationen.

Varje misslyckande ger en läsbar feldialog och lämnar redigerarens insticksmoduler orörda.

Uppdatera och avinstallera¶

Att installera ett paket vars id redan är installerat ersätter det. Är den modulen inläst just då ställs uppdateringen i ordning och tillämpas vid nästa start.
Avinstallera från samma inställningssida; även borttagningen sker vid nästa start, medan inget är inläst.
Medföljande (inbyggda) insticksmoduler kan inte åsidosättas av ett installerat paket med samma id.

Installera för hand (lägga dit en mapp)¶

Redigeraren upptäcker insticksmoduler i två kataloger vid varje start:

Medföljande — bredvid den körbara filen, i <exe-dir>/Plugins/. Här bor de inbyggda modulerna (till exempel HelloPython).
Användare — per användare, skrivbar. På Windows är det %LOCALAPPDATA%/MTE/Plugins/, på macOS ~/Library/Application Support/MTE/Plugins/, på Linux ~/.local/share/MTE/Plugins/.

Båda katalogerna genomsöks. Förekommer samma id i båda vinner den första förekomsten (medföljande har företräde). Starta om redigeraren för att plocka upp nya mappar — omladdning under körning stöds inte.

Två godtagbara layouter¶

Genomsökningen letar efter plugin.json antingen direkt i insticksmodulskatalogen (löst) eller inuti en nivå av direkt underkatalog (mapp per insticksmodul):

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

Mappen per insticksmodul är den rekommenderade layouten; det är den form installeraren producerar.

Beroenden (`pyRequires`)¶

plugin.json får deklarera pip-krav som en inbäddad vektor:

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

Vid insticksmodulens första start ställer redigeraren i ordning en virtuell miljö i <AppLocalData>/PluginVenv/<id>/ (python -m venv + pip install, vilket kräver nätverksåtkomst den enda gången) och kör modulens arbetare under den venvens tolk. Senare starter återanvänder den; att ändra pyRequires ställer i ordning på nytt automatiskt (venven bär en stämpel av de krav den byggdes för).

Misslyckanden vid iordningställandet (inget nätverk, ett felstavat krav) lämnar modulen listad men inte inläst, med pip-felet i loggen; nästa start försöker igen.
Att avinstallera en insticksmodul tar bort dess venv tillsammans med modulmappen (en venv är härledda data — den byggs om från pyRequires om du någonsin installerar om).

Maskiner utan nätverk / med hårda restriktioner¶

Leverera en förbyggd venv inuti paketet som en mapp venv/ i modulens rot. Finns den vinner den över allt — pip körs då aldrig. Bygg den på en maskin med samma operativsystem och arkitektur, eftersom venvar inte är portabla mellan plattformar.

Medleverans (små beroenden i ren Python)¶

För en enda modul i ren Python fungerar medleverans inuti modulmappen fortfarande och undviker venv-maskineriet helt:

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

import your_dep

Deklarerade rättigheter¶

plugin.json får bära en vektor permissions (till exempel ["network"]). Inställningssidan Insticksmoduler visar den i en skrivskyddad kolumn Behörigheter så att användare kan se vad en modul deklarerar om sig själv. Det är en deklaration, inte ett upprätthållande — sandlådan är framtida arbete.

Var skrivbara data hamnar¶

Insticksmodulskatalogen innehåller kod. Data under körning (cachar, konfiguration per användare, index) hamnar i en separat datakatalog per insticksmodul som värden hanterar — ctx.data_dir() returnerar dess absoluta sökväg. Skriv INTE i insticksmodulskatalogen från din .py under körning; avinstallation tar bort hela mappen <Plugins>/<id>/, och skrivningar gjorda på andra ställen i insticksmodulsträdet städas aldrig.

Distribuera till andra maskiner¶

Leverera filen .mteplugin — den är självförsörjande och valideras i mottagarens ände. En zip, tarball eller git-klon av mappen till insticksmodulskatalogen per användare fungerar också.

Aktivera / inaktivera¶

Inställningssidan Insticksmoduler listar varje upptäckt modul (inhemska + Python, tillsammans) med samma kolumner för ursprung och status. Att inaktivera en modul håller den listad men hindrar dess fabrik från att anropas vid start — ingen arbetare startas. Aktivera den igen och starta om för att få tillbaka den.