Řešení potíží¶

Diagnostický protokol editoru nese každý podstatný řádek. Ve Windows je v %LOCALAPPDATA%/MTE/log/. Po spuštění editoru se podívejte do nejnovějšího souboru.

»Python plugins disabled«¶

Čtyři varianty; která z nich, říká přesná zpráva.

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

Neutrální — hostitel se chystá hledat Python v PATH. V pořádku, pokud po ní nenásleduje »no Python interpreter found«.

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

Nastavili jste MTE_PYTHON na cestu s oddělovačem adresářů, ale soubor na oné cestě chybí. Náprava: nasměrujte ji na skutečný python.exe.

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

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

Nastavili jste MTE_PYTHON na holý název (bez oddělovače), ale ten název v PATH není. Náprava: buď složku do PATH přidejte, nebo použijte výše uvedený tvar s úplnou cestou.

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

V PATH není ani MTE_PYTHON, ani žádný z názvů obvyklých pro danou platformu (py.exe, python.exe, python3.exe ve Windows; python3 na macOS a v Linuxu). Nainstalujte Python 3.9+ a buď jej přidejte do PATH, nebo nastavte MTE_PYTHON.

Z téhož shellu, ze kterého jste editor spustili, ověřte, co PATH právě 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 hostitele pracovníka (mte_python_host.py) není vedle spustitelného souboru. Stává se to při spuštění sestavení editoru, u něhož byl krok POST_BUILD pro přípravu Python/ přeskočen. Sestavte znovu:

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

Po sestavení potvrďte, že soubor existuje:

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

Modul je uvedený, ale nenačtený¶

Otevřete stránku Zásuvné moduly (Předvolby → Zásuvné moduly). Běžné příčiny:

Příznak	Řádek v protokolu	Příčina
Vedle názvu značka o neshodě `apiVersion`	`PythonPluginBackend: not loading '…': apiVersion does not match host 1.`	Váš `plugin.json` deklaruje jinou `apiVersion`, než jakou běžící editor podporuje.
Modul vypadá zašedle	`PythonPluginBackend: '…' is disabled; listed but not loaded.`	Někdo jej vypnul na stránce Zásuvné moduly. Zapněte jej a restartujte.
Zcela chybí	`PythonPluginBackend: skipping '…': module '…/main.py' does not declare a top-level 'def register(...)'.`	Statická sonda váš modul odmítla. Přesuňte `register` na nejvyšší úroveň (sloupec 0).
Zcela chybí	`PythonPluginBackend: skipping '…': module file '…' is missing or unreadable.`	`plugin.json.module` je `"main"`, ale žádné `main.py` vedle něj není.
Zcela chybí	`PythonPluginBackend: skipping '…': plugin.json missing required field 'id'.`	Přidejte `id`.

Příkaz se nespustí¶

Klikli jste na položku nabídky nebo stiskli zkratku, ale nic se nestalo.

Hledejte řádky [python:<your.id>] … z vašeho ctx.log.info(...). Pokud chybí, zavolání se k pracovníkovi nikdy nedostalo.
Hledejte řádky [worker stderr] …. Výjimky uvnitř vašeho zavolání končí tam.
Potvrďte, že id příkazu ve vašem volání add_item odpovídá command(id=...) doslova — porovnání řetězců je přesné.

Chyby »worker died«¶

Hostitel zaznamená:

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

Podproces Pythonu skončil. Nad tímto řádkem hledejte stderr od pracovníka — Python tiskne výpisy zásobníku na stderr a hostitel je předává jako [worker stderr] …. Pád téměř vždy odpovídá nezachycené výjimce ve register() nebo v zavolání, které se rekurzivně vrátilo do rozhraní C v Pythonu.

Zotavte se opravou kódu a restartem editoru. Hostitel spadlého pracovníka automaticky nerestartuje.

Příprava virtuálního prostředí selhala (modul uvedený, ale nenačtený)¶

Modul, který deklaruje pyRequires, dostane při prvním spuštění připravené virtuální prostředí. Když to selže, nese protokol 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 ...

Běžné příčiny: při prvním spuštění není síť, překlepnutý požadavek, balíček bez wheelu pro verzi Pythonu daného uživatele. Příčinu odstraňte a restartujte — příprava se opakuje při každém spuštění, dokud neuspěje (prostředí se označí za hotové až na konci). Chcete-li vynutit čisté sestavení znovu, smažte <AppLocalData>/PluginVenv/<plugin-id>/. Stroje bez sítě mohou místo toho dodat předem sestavené venv/ uvnitř balíčku — viz Balení.

Instalátor můj `.mteplugin` odmítl¶

Každé odmítnutí přichází s konkrétní zprávou v okně; ty běžné:

Zpráva říká…	Náprava
chybí povinné pole `'module'`	Přidejte do `plugin.json` `"module": "main"`.
žádný modul Pythonu (soubor .py)	Archiv nemá vůbec žádné `.py` — zazipovali jste správnou složku?
neobsahuje deklarovaný modul Pythonu `'X.py'`	`module` v `plugin.json` neodpovídá názvu souboru v archivu.
nedeklaruje `def register(...)` na nejvyšší úrovni	Totéž pravidlo jako při hledání: `def register(` musí začínat ve sloupci 0 souboru `<module>.py`.
míří na verzi rozhraní N	Sestavte znovu proti aktuální `apiVersion` (viz plugin.json).
nebezpečná cesta / příliš velké / příliš mnoho souborů	Archiv narazil na bezpečnostní pojistku — zabalte jej prostě znovu (žádné položky s `..`, po rozbalení pod 256 MiB).

Balíček se ověřuje proti pracovní kopii, takže odmítnutá instalace se stávajícího modulu nikdy nedotkne.

Vůbec se nic nezaznamenává¶

Potvrďte, že je vaše obsluha skutečně nainstalována. register(ctx) běží právě jednou na modul a spuštění editoru. Není-li register definována na nejvyšší úrovni modulu, odmítne modul statická sonda dřív, než se vůbec načte (viz »Modul je uvedený, ale nenačtený« výše).

Přidejte do svého register řádek při startu:

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

Pokud to v protokolu nevidíte, pracovník váš register nespouští — důvod hledejte v dřívějších protokolech.

Kam se podívat dál¶

Protokol na straně editoru: %LOCALAPPDATA%/MTE/log/…
Stderr pracovníka: tentýž protokol, označený [worker stderr]
Reference: rozhraní ctx, události, plugin.json
Poznámky k návrhu: PYTHON_PLUGIN_ARCHITECTURE.md (kořen repozitáře)