Riešenie problémov¶

Diagnostický log editora nesie každý dôležitý riadok. Vo Windows je v %LOCALAPPDATA%/MTE/log/. Po spustení editora sa pozrite do najnovšieho súboru.

„Python plugins disabled“¶

Existujú štyri podoby; presná správa vám povie, o ktorú ide.

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

Neutrálne — hostiteľ sa chystá hľadať Python v premennej PATH. Je to v poriadku, pokiaľ po tom nenasleduje „no Python interpreter found“.

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

Premennú MTE_PYTHON ste nastavili na cestu s oddeľovačom priečinkov, ale súbor na tejto ceste chýba. Náprava: nasmerujte ju na skutočný python.exe.

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

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

Premennú MTE_PYTHON ste nastavili na samotný názov (bez oddeľovača), ale tento názov nie je v PATH. Náprava: buď priečinok pridajte do PATH, alebo použite vyššie uvedený tvar s úplnou cestou.

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

V PATH nie je ani MTE_PYTHON, ani žiadny zo štandardných názvov danej platformy (py.exe, python.exe, python3.exe vo Windows; python3 na macOS a Linuxe). Nainštalujte Python 3.9+ a buď ho pridajte do PATH, alebo nastavte MTE_PYTHON.

Z toho istého shellu, z akého ste spustili editor, si overte, čo PATH aktuálne vidí:

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

„python worker script … not found“¶

Editor zaznamená:

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

Skript hostiteľa pracovného procesu (mte_python_host.py) nie je vedľa spustiteľného súboru. Stáva sa to pri spustení zostavy editora, ktorej sa preskočil krok POST_BUILD s prípravou priečinka Python/. Zostavte znova:

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

Po zostavení overte, že súbor existuje:

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

Zásuvný modul je vypísaný, ale nenačítaný¶

Otvorte stránku Zásuvné moduly (Predvoľby → Zásuvné moduly). Bežné príčiny:

Príznak	Riadok v logu	Príčina
Značka nezhody `apiVersion` vedľa názvu	`PythonPluginBackend: not loading '…': apiVersion does not match host 1.`	Váš `plugin.json` deklaruje inú hodnotu `apiVersion`, než akú bežiaci editor podporuje.
Zásuvný modul sa javí zosivený	`PythonPluginBackend: '…' is disabled; listed but not loaded.`	Niekto ho vypol na stránke Zásuvné moduly. Zapnite ho znova a reštartujte.
Chýba úplne	`PythonPluginBackend: skipping '…': module '…/main.py' does not declare a top-level 'def register(...)'.`	Statická kontrola váš modul odmietla. Presuňte `register` na najvyššiu úroveň (stĺpec 0).
Chýba úplne	`PythonPluginBackend: skipping '…': module file '…' is missing or unreadable.`	`plugin.json.module` je `"main"`, ale vedľa nie je žiadny `main.py`.
Chýba úplne	`PythonPluginBackend: skipping '…': plugin.json missing required field 'id'.`	Doplňte `id`.

Príkaz sa nevyvolá¶

Klikli ste na položku ponuky alebo stlačili skratku, ale nič sa nestalo.

Pozrite sa, či sú v logu riadky [python:<your.id>] … z vašich volaní ctx.log.info(...). Ak chýbajú, zavolanie sa k pracovnému procesu nikdy nedostalo.
Pozrite sa na riadky [worker stderr] …. Výnimky vnútri vášho zavolania pristanú tam.
Overte, že id príkazu vo volaní add_item doslovne zodpovedá vášmu command(id=...) — porovnanie reťazcov je presné.

Chyby „worker died“¶

Hostiteľ zaznamená:

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

Podproces Pythonu sa skončil. Nad týmto riadkom hľadajte stderr z pracovného procesu — Python vypisuje výpisy zásobníka na stderr a hostiteľ ich preposiela ako [worker stderr] …. Pád takmer vždy zodpovedá nezachytenej výnimke v register() alebo v zavolaní, ktoré sa rekurzívne vrátilo do C API Pythonu.

Opravte kód a reštartujte editor. Hostiteľ spadnutý pracovný proces automaticky nereštartuje.

Príprava virtuálneho prostredia zlyhala (modul je vypísaný, ale nenačítaný)¶

Zásuvný modul, ktorý deklaruje pyRequires, dostane pri prvom spustení pripravené virtuálne prostredie. Keď to zlyhá, log nesie dôvod:

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 ...

Bežné príčiny: chýbajúca sieť pri prvom spustení, zle napísaná požiadavka, balík bez wheelu pre používateľovu verziu Pythonu. Odstráňte príčinu a reštartujte — príprava sa pri každom spustení opakuje, kým sa nepodarí (prostredie sa označí za dokončené až na konci). Ak chcete vynútiť čisté vytvorenie nanovo, odstráňte <AppLocalData>/PluginVenv/<plugin-id>/. Počítače bez siete môžu namiesto toho dodať vopred zostavené venv/ vnútri balíka — pozri Balenie.

Inštalátor môj `.mteplugin` odmietol¶

Každé odmietnutie prichádza s konkrétnou správou v dialógu; tie bežné sú:

Správa hovorí…	Náprava
chýba povinné pole `'module'`	Pridajte do `plugin.json` `"module": "main"`.
žiadny modul Pythonu (súbor .py)	Archív neobsahuje žiadny `.py` — zabalili ste správny priečinok?
neobsahuje deklarovaný modul Pythonu `'X.py'`	`module` v `plugin.json` nezodpovedá názvu súboru v archíve.
nedeklaruje `def register(...)` na najvyššej úrovni	To isté pravidlo ako pri vyhľadávaní: `def register(` sa musí začínať v stĺpci 0 súboru `<module>.py`.
cieli na verziu API N	Zostavte znova voči aktuálnej hodnote `apiVersion` (pozri plugin.json).
nebezpečná cesta / príliš veľké / príliš veľa súborov	Archív narazil na bezpečnostnú poistku — zabaľte ho jednoducho (žiadne položky s `..`, menej než 256 MiB po rozbalení).

Balík sa overuje oproti dočasnej kópii, takže odmietnutá inštalácia sa existujúceho zásuvného modulu nikdy nedotkne.

Vôbec sa nič nezaznamenáva¶

Overte, či je váš obslužný kód naozaj nainštalovaný. register(ctx) beží presne raz na zásuvný modul a spustenie editora. Ak register nie je definovaný na najvyššej úrovni modulu, statická kontrola modul odmietne skôr, než sa vôbec načíta (pozri „Zásuvný modul je vypísaný, ale nenačítaný“ vyššie).

Do svojho register pridajte riadok pri štarte:

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

Ak to v logu nevidíte, pracovný proces váš register nespúšťa — dôvod hľadajte v skorších riadkoch logu.

Kam sa pozrieť ďalej¶

Log na strane editora: %LOCALAPPDATA%/MTE/log/…
Stderr pracovného procesu: ten istý log, označený [worker stderr]
Referencia: API ctx, Udalosti, plugin.json
Poznámky k návrhu: PYTHON_PLUGIN_ARCHITECTURE.md (koreň repozitára)