Solução de problemas¶

O log de diagnóstico do editor carrega toda linha relevante. No Windows ele está em %LOCALAPPDATA%/MTE/log/. Veja o arquivo mais recente depois de iniciar o editor.

"Python plugins disabled"¶

Quatro variantes; a mensagem exata diz qual delas.

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

Neutro — o host está prestes a procurar o Python no PATH. Tudo bem, a menos que seja seguido por "no Python interpreter found".

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

Você definiu o MTE_PYTHON com um caminho contendo um separador de diretório, mas o arquivo naquele caminho está faltando. Solução: aponte para o python.exe real.

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

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

Você definiu o MTE_PYTHON com um nome simples (sem separador), mas aquele nome não está no PATH. Solução: ou acrescente a pasta ao PATH, ou use a forma de caminho completo acima.

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

Nem o MTE_PYTHON nem nenhum dos nomes padrão da plataforma (py.exe, python.exe, python3.exe no Windows; python3 no macOS/Linux) está no PATH. Instale o Python 3.9+ e acrescente-o ao PATH ou defina o MTE_PYTHON.

Verifique o que o PATH enxerga no momento, a partir do mesmo shell de onde você iniciou o editor:

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

"python worker script … not found"¶

O editor registra:

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

O script host do trabalhador (mte_python_host.py) não está ao lado do executável. Isso acontece ao rodar um build do editor cujo passo POST_BUILD de preparo de Python/ foi pulado. Recompile:

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

Confirme que o arquivo existe depois do build:

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

Plugin listado, mas não carregado¶

Abra a página de plug-ins (Preferências → Plug-ins). Causas comuns:

Sintoma	Linha no log	Causa
Marca de divergência de `apiVersion` ao lado do nome	`PythonPluginBackend: not loading '…': apiVersion does not match host 1.`	O seu `plugin.json` declara um `apiVersion` diferente do que o editor em execução suporta.
O plugin aparece esmaecido	`PythonPluginBackend: '…' is disabled; listed but not loaded.`	Alguém o desativou na página de Plugins. Reative e reinicie.
Ausente por completo	`PythonPluginBackend: skipping '…': module '…/main.py' does not declare a top-level 'def register(...)'.`	A sondagem estática rejeitou seu módulo. Mova `register` para o nível superior (coluna 0).
Ausente por completo	`PythonPluginBackend: skipping '…': module file '…' is missing or unreadable.`	O `plugin.json.module` é `"main"`, mas não há `main.py` ao lado dele.
Ausente por completo	`PythonPluginBackend: skipping '…': plugin.json missing required field 'id'.`	Acrescente `id`.

O comando não dispara¶

Você clicou no item de menu / pressionou o atalho, mas nada aconteceu.

Procure linhas [python:<your.id>] … do seu ctx.log.info(...). Se estiverem faltando, a retrochamada nunca chegou ao trabalhador.
Procure linhas [worker stderr] …. Exceções dentro da sua retrochamada param ali.
Confirme que o id de comando na sua chamada a add_item coincide literalmente com o seu command(id=...) — a comparação de cadeias é exata.

Erros de "worker died"¶

O host registra:

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

O subprocesso Python terminou. Procure acima daquela linha o stderr do trabalhador — o Python imprime rastreamentos em stderr e o host os encaminha como [worker stderr] …. Uma falha quase sempre corresponde a uma exceção não capturada em register() ou em uma retrochamada que reentrou na API C do Python.

Recupere-se corrigindo o código e reiniciando o editor. O host não reinicia automaticamente um trabalhador que falhou.

Provisionamento do ambiente virtual falhou (plugin listado, mas não carregado)¶

Um plugin que declara pyRequires recebe um ambiente virtual provisionado na primeira inicialização dele. Quando isso falha, o log carrega o motivo:

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

Causas comuns: sem rede na primeira inicialização, um requisito escrito errado, um pacote sem wheel para a versão do Python do usuário. Corrija a causa e reinicie — o provisionamento tenta de novo a cada inicialização até dar certo (o ambiente virtual só é carimbado como completo no fim). Para forçar uma reconstrução limpa, apague <AppLocalData>/PluginVenv/<plugin-id>/. Máquinas offline podem distribuir um venv/ pré-construído dentro do pacote — veja Empacotamento.

O instalador recusou meu `.mteplugin`¶

Toda recusa vem com uma mensagem de caixa de diálogo específica; as comuns:

A mensagem diz…	Solução
falta o campo obrigatório `'module'`	Acrescente `"module": "main"` ao `plugin.json`.
nenhum módulo Python (arquivo .py)	O arquivo compactado não tem `.py` algum — você compactou a pasta certa?
não contém o módulo Python declarado `'X.py'`	O `module` no `plugin.json` não coincide com o nome de arquivo no compactado.
não declara um `def register(...)` de nível superior	A mesma regra da descoberta: `def register(` precisa começar na coluna 0 de `<module>.py`.
mira a versão N da API	Recompile contra o `apiVersion` atual (veja plugin.json).
caminho inseguro / grande demais / arquivos demais	O compactado esbarrou em uma proteção — reempacote de forma simples (sem entradas `..`, menos de 256 MiB descompactado).

O pacote é validado contra uma cópia temporária, então uma instalação recusada nunca toca em um plugin existente.

Nada está sendo registrado¶

Confirme que o seu manipulador está de fato instalado. register(ctx) roda exatamente uma vez por plugin por inicialização do editor. Se register não estiver definido no nível superior do módulo, a sondagem estática rejeita o plugin antes de ele chegar a ser carregado (veja "Plugin listado, mas não carregado", acima).

Acrescente uma linha de inicialização ao seu register:

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

Se você não vir isso no log, o trabalhador não está executando o seu register — verifique os logs anteriores para saber o motivo.

Onde olhar a seguir¶

Log do lado do editor: %LOCALAPPDATA%/MTE/log/…
Stderr do trabalhador: o mesmo log, marcado como [worker stderr]
Referência: API ctx, Eventos, plugin.json
Notas de design: PYTHON_PLUGIN_ARCHITECTURE.md (raiz do repositório)