Rozwiązywanie problemów¶

Log diagnostyczny edytora niesie każdą istotną linię. Na Windows leży w %LOCALAPPDATA%/MTE/log/. Po uruchomieniu edytora zajrzyj do najnowszego pliku.

„Python plugins disabled"¶

Cztery odmiany; dokładny komunikat mówi, która to.

`PluginHost: MTE_PYTHON is not set; falling back to PATH.`¶

Neutralny — host zaraz poszuka Pythona w PATH. W porządku, chyba że zaraz po nim idzie „no Python interpreter found".

`PluginHost: MTE_PYTHON path '<value>' does not exist.`¶

Ustawiłeś MTE_PYTHON na ścieżkę z separatorem katalogów, ale pliku pod tą ścieżką nie ma. Naprawa: wskaż prawdziwy python.exe.

$env:MTE_PYTHON = "C:\Users\me\AppData\Local\Programs\Python\Python313\python.exe"

`PluginHost: MTE_PYTHON='<name>' not found on PATH.`¶

Ustawiłeś MTE_PYTHON na gołą nazwę (bez separatora), ale tej nazwy nie ma w PATH. Naprawa: dodaj folder do PATH albo użyj formy pełnej ścieżki powyżej.

`PluginHost: no Python interpreter found (…); Python plugins disabled.`¶

Ani MTE_PYTHON, ani żadna ze standardowych nazw platformy (py.exe, python.exe, python3.exe na Windows; python3 na macOS/Linux) nie jest w PATH. Zainstaluj Pythona 3.9+ i dodaj go do PATH albo ustaw MTE_PYTHON.

Sprawdź, co aktualnie widzi PATH, z tej samej powłoki, z której uruchomiłeś edytor:

(Get-Command py.exe -ErrorAction SilentlyContinue).Source
(Get-Command python.exe -ErrorAction SilentlyContinue).Source

„python worker script … not found"¶

Edytor loguje:

PluginHost: python worker script '<path>' not found; Python plugins disabled.

Skrypt hosta workera (mte_python_host.py) nie leży obok exe. Zdarza się przy buildzie edytora, w którym pominięto krok POST_BUILD stage'ujący Python/. Przebuduj:

cmake --build Build\.cmake\x64-debug --target ModularTextEditor --config Debug

Potwierdź po buildzie, że plik istnieje:

Test-Path Build\MTE_Windows_d\Python\host\mte_python_host.py

Wtyczka na liście, ale nie załadowana¶

Otwórz stronę Wtyczek (Preferencje → Wtyczki). Częste przyczyny:

Objaw	Linia w logu	Przyczyna
Znacznik niezgodności `apiVersion` obok nazwy	`PythonPluginBackend: not loading '…': apiVersion does not match host 1.`	Twój `plugin.json` deklaruje inny `apiVersion`, niż wspiera działający edytor.
Wtyczka wyszarzona	`PythonPluginBackend: '…' is disabled; listed but not loaded.`	Ktoś ją wyłączył na stronie Wtyczek. Włącz ponownie i zrestartuj.
Całkiem nieobecna	`PythonPluginBackend: skipping '…': module '…/main.py' does not declare a top-level 'def register(...)'.`	Statyczna sonda odrzuciła Twój moduł. Przenieś `register` na najwyższy poziom (kolumna 0).
Całkiem nieobecna	`PythonPluginBackend: skipping '…': module file '…' is missing or unreadable.`	`plugin.json.module` to `"main"`, ale obok nie ma `main.py`.
Całkiem nieobecna	`PythonPluginBackend: skipping '…': plugin.json missing required field 'id'.`	Dodaj `id`.

Polecenie nie odpala¶

Kliknąłeś pozycję menu / nacisnąłeś skrót i nic się nie stało.

Sprawdź linie [python:<twoje.id>] … z Twoich ctx.log.info(...). Jeśli ich brak, callback nigdy nie dotarł do workera.
Sprawdź linie [worker stderr] …. Wyjątki wewnątrz callbacku lądują tam.
Potwierdź, że id polecenia w wywołaniu add_item odpowiada Twojemu command(id=...) co do znaku — porównanie łańcuchów jest dokładne.

Błędy „worker died"¶

Host loguje:

… worker exited with code N
… worker crashed (code N)

Podproces Pythona się zakończył. Popatrz powyżej tej linii na stderr workera — Python wypisuje tracebacki na stderr, a host przekazuje je jako [worker stderr] …. Awaria niemal zawsze odpowiada nieobsłużonemu wyjątkowi w register() albo w callbacku, który zawinął się w C API Pythona.

Napraw kod i zrestartuj edytor. Host nie restartuje automatycznie zawieszonego workera.

Provisioning venv nie powiódł się (wtyczka na liście, ale nie załadowana)¶

Wtyczka deklarująca pyRequires dostaje środowisko wirtualne przy pierwszym uruchomieniu. Gdy to się nie uda, log niesie powód:

PluginHost: 'org.example.x' needs a venv (no venv provisioned yet).
PythonRuntime: provisioning venv at '...' (1 requirement(s)); ...
PluginHost: venv provisioning for 'org.example.x' failed: pip install
failed: ... No matching distribution found for no-such-package ...

Częste przyczyny: brak sieci przy pierwszym starcie, literówka w wymaganiu, pakiet bez wheela dla wersji Pythona użytkownika. Usuń przyczynę i zrestartuj — provisioning ponawia się przy każdym starcie aż do sukcesu (venv jest oznaczany jako kompletny dopiero na końcu). Aby wymusić czystą przebudowę, usuń <AppLocalData>/PluginVenv/<plugin-id>/. Maszyny offline mogą zamiast tego dostarczyć w pakiecie zbudowany wcześniej venv/ — zobacz Pakowanie.

Instalator odrzucił mój `.mteplugin`¶

Każde odrzucenie przychodzi z konkretnym komunikatem okna; najczęstsze:

Komunikat mówi…	Naprawa
missing the required `'module'` field	Dodaj `"module": "main"` do `plugin.json`.
no Python module (.py file)	Archiwum nie ma żadnego `.py` — spakowałeś właściwy folder?
does not contain the declared Python module `'X.py'`	`module` w `plugin.json` nie odpowiada nazwie pliku w archiwum.
does not declare a top-level `def register(...)`	Ta sama reguła co przy wykrywaniu: `def register(` musi zaczynać się w kolumnie 0 pliku `<module>.py`.
targets API version N	Przebuduj pod bieżący `apiVersion` (zobacz plugin.json).
unsafe path / too large / too many files	Archiwum potknęło się o bezpiecznik — spakuj je zwyczajnie (bez wpisów `..`, < 256 MiB po rozpakowaniu).

Pakiet jest walidowany na kopii roboczej, więc odrzucona instalacja nigdy nie dotyka istniejącej wtyczki.

Nic w ogóle się nie loguje¶

Potwierdź, że Twój handler naprawdę jest zainstalowany. register(ctx) wykonuje się dokładnie raz na wtyczkę na uruchomienie edytora. Jeśli register nie jest zdefiniowany na najwyższym poziomie modułu, statyczna sonda odrzuca wtyczkę, zanim w ogóle się załaduje (zobacz „Wtyczka na liście, ale nie załadowana" wyżej).

Dodaj linię startową do swojego register:

def register(ctx):
    ctx.log.info("wordcount: register() ran")
    # …

Jeśli nie widzisz tego w logu, worker nie wykonuje Twojego register — sprawdź wcześniejsze logi po powód.

Gdzie patrzeć dalej¶

Log po stronie edytora: %LOCALAPPDATA%/MTE/log/…
Stderr workera: ten sam log, znacznik [worker stderr]
Dokumentacja: API ctx, Zdarzenia, plugin.json
Notatki projektowe: PYTHON_PLUGIN_ARCHITECTURE.md (korzeń repo)