Paketierung und Installation¶

Ein Python-Plugin ist ein Ordner mit einer plugin.json und einem Python-Modul. Installieren lässt es sich auf zwei Wegen: als .mteplugin-Archiv über den Installer des Editors (empfohlen) oder von Hand als Ordner in ein Plugin-Verzeichnis gelegt.

Mit der Vorlage starten

Ein kopierfertiger Starter liegt im Repo unter Python/templates/plugin-template-python/ — drei Dateien (plugin.json, main.py, README.md) plus eine Claude-gerichtete CLAUDE.md. Benennen Sie den Ordner nach dem Kurznamen Ihres Plugins um, ändern Sie vier Felder in plugin.json und beginnen Sie mit register(ctx). Das installierte SDK liefert dieselbe Vorlage unter share/MTEPluginSDK/plugin-template-python/.

Aufbau des Plugin-Ordners¶

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

Alles, was das Plugin braucht, muss in diesem Ordner liegen. Unter-Importe funktionieren, müssen aber flach sein — gepunktete module-Namen in plugin.json sind eine künftige Erweiterung.

Zusätzliche Dateien (README, LICENSE) sind erlaubt — der Host ignoriert, was er nicht kennt.

`.mteplugin`-Pakete (empfohlen)¶

Zippen Sie die Dateien des Plugins und geben Sie dem Archiv die Endung .mteplugin (ein schlichtes .zip funktioniert auch). Beide Formen werden akzeptiert:

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

Der einzelne Hüllordner — das natürliche Ergebnis des Zippens eines Ordners — wird wegnormalisiert: Das Plugin installiert immer nach <Plugins>/<id>/, geschlüsselt über die Manifest-id, nie über den Ordnernamen des Archivs. Deshalb ersetzt die Installation von Version 2 eines Plugins die Version 1, statt daneben zu liegen.

Installieren über Einstellungen → Plugins → Installieren…, dann den Editor neu starten.

Nur vertrauenswürdige Pakete installieren

Der Installer prüft, dass ein Paket strukturell in Ordnung ist (siehe unten) — er macht ein nicht vertrauenswürdiges Plugin nicht sicher. Einmal geladen, läuft ein Plugin mit demselben Zugriff auf Ihre Dateien, Einstellungen und Ihr Netzwerk wie der Editor und ist nicht gesandboxt. Die statische register(...)-Prüfung führt bei der Installation keinen Code aus, aber der Code des Plugins läuft beim nächsten Start sehr wohl. Behandeln Sie eine .mteplugin (und alle mitgelieferten Konfigurations-/JSON-Dateien) wie ein unbekanntes Programm: nur aus vertrauenswürdiger Quelle installieren. Die volle Warnung: Plugins.

Was der Installer validiert¶

Das Paket wird vollständig an einer Wegwerfkopie validiert, bevor irgendwas auf der Festplatte angefasst wird — ein schlechtes Paket kann eine bestehende Installation nie stören:

plugin.json parst, hat eine id, apiVersion passt zum Editor, entry ist "python", und module ist vorhanden.
Die Archivliste ist sicher: keine absoluten oder ..-Pfade, höchstens 10 000 Einträge, höchstens 256 MiB entpackt, und mindestens eine .py-Datei.
Nach dem Entpacken in ein Arbeitsverzeichnis existiert die deklarierte <module>.py und deklariert ein def register(...) auf oberster Ebene — dieselbe statische Prüfung wie bei der Erkennung. Bei der Installation wird kein Python-Code ausgeführt.

Jeder Fehler erzeugt einen verständlichen Fehlerdialog und lässt die Plugins des Editors unberührt.

Aktualisieren und Deinstallieren¶

Die Installation eines Pakets, dessen id bereits installiert ist, ersetzt es. Ist das Plugin gerade geladen, wird die Aktualisierung vorgemerkt und beim nächsten Start angewendet.
Deinstallieren über dieselbe Einstellungsseite; auch das Entfernen geschieht beim nächsten Start, solange nichts geladen ist.
Mitgelieferte (eingebaute) Plugins lassen sich nicht durch ein installiertes Paket mit derselben id übersteuern.

Installation von Hand (Ordner ablegen)¶

Der Editor entdeckt Plugins bei jedem Start in zwei Verzeichnissen:

Mitgeliefert — neben der Programmdatei, unter <exe-dir>/Plugins/. Eingebaute Plugins (z. B. HelloPython) liegen hier.
Benutzer — pro Benutzer, beschreibbar. Unter Windows ist das %LOCALAPPDATA%/MTE/Plugins/, unter macOS ~/Library/Application Support/MTE/Plugins/, unter Linux ~/.local/share/MTE/Plugins/.

Beide Verzeichnisse werden gescannt. Taucht dieselbe id in beiden auf, gewinnt das erste Vorkommen (mitgeliefert hat Vorrang). Neue Ordner werden mit einem Editor-Neustart übernommen — Hot-Reload wird nicht unterstützt.

Zwei zulässige Layouts¶

Der Scan sucht plugin.json entweder direkt im Plugin-Verzeichnis (lose) oder in einer Ebene unmittelbarer Unterordner (Ordner pro Plugin):

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

Der Ordner pro Plugin ist das empfohlene Layout; diese Form erzeugt auch der Installer.

Abhängigkeiten (`pyRequires`)¶

plugin.json darf pip-Requirements als Inline-Array deklarieren:

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

Beim ersten Start des Plugins provisioniert der Editor eine virtuelle Umgebung unter <AppLocalData>/PluginVenv/<id>/ (python -m venv + pip install, was dieses eine Mal Netzzugriff braucht) und führt den Worker des Plugins unter dem Interpreter dieser venv aus. Spätere Starts verwenden sie wieder; eine Änderung von pyRequires provisioniert automatisch neu (die venv trägt einen Stempel der Requirements, für die sie gebaut wurde).

Provisionierungsfehler (kein Netz, ein vertipptes Requirement) lassen das Plugin gelistet, aber nicht geladen, mit dem pip-Fehler im Protokoll; der nächste Start versucht es erneut.
Das Deinstallieren eines Plugins entfernt seine venv mitsamt dem Plugin-Ordner (eine venv ist abgeleitetes Datenmaterial — bei einer Neuinstallation wird sie aus pyRequires neu gebaut).

Offline- / abgeschottete Maschinen¶

Liefern Sie eine vorgebaute venv im Paket mit, als Ordner venv/ in der Plugin-Wurzel. Ist sie vorhanden, gewinnt sie gegen alles — pip läuft nie. Bauen Sie sie auf einer Maschine mit gleichem OS/gleicher Architektur, denn venvs sind nicht plattformübergreifend portabel.

Vendoring (kleine Pure-Python-Abhängigkeiten)¶

Für ein einzelnes Pure-Python-Modul funktioniert Vendoring im Plugin-Ordner weiterhin und umgeht die venv-Maschinerie ganz:

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

import your_dep

Deklarierte Berechtigungen¶

plugin.json darf ein permissions-Array tragen (z. B. ["network"]). Die Plugins-Einstellungsseite zeigt es in einer schreibgeschützten Spalte Berechtigungen, damit Nutzer sehen, was ein Plugin über sich selbst deklariert. Es ist eine Deklaration, keine Durchsetzung — Sandboxing ist künftige Arbeit.

Wohin beschreibbare Daten gehören¶

Das Plugin-Verzeichnis enthält Code. Laufzeitdaten (Caches, Benutzerkonfiguration, Indizes) gehören in ein separates, vom Host verwaltetes Datenverzeichnis pro Plugin — ctx.data_dir() liefert dessen absoluten Pfad. Schreiben Sie zur Laufzeit NICHT aus Ihrer .py in das Plugin-Verzeichnis; die Deinstallation entfernt den ganzen Ordner <Plugins>/<id>/, und Schreibvorgänge anderswo im Plugin-Baum werden nie aufgeräumt.

Auf andere Maschinen ausrollen¶

Verschicken Sie die .mteplugin-Datei — sie ist in sich geschlossen und wird auf der Empfängerseite validiert. Ein Zip/Tarball/git-clone des Ordners in das Benutzer-Plugin-Verzeichnis funktioniert ebenfalls.

Aktivieren / Deaktivieren¶

Die Plugins-Einstellungsseite listet jedes entdeckte Plugin (nativ + Python gemeinsam) mit denselben Herkunfts-/Statusspalten. Das Deaktivieren eines Plugins hält es gelistet, verhindert aber den Aufruf seiner Fabrik beim Start — es wird kein Worker gestartet. Wieder aktivieren und neu starten bringt es zurück.