Referência do `plugin.json`¶

Todo plugin Python declara a identidade, o ponto de entrada e o posicionamento na barra de menus em um arquivo plugin.json ao lado do main.py dele. Este é o mesmo esquema que o lado C++ usa; apenas os campos entry e module são específicos do Python.

Exemplo¶

{
  "id":          "org.example.wordcount",
  "name":        "Word Count",
  "version":     "1.0.0",
  "vendor":      "Example, Inc.",
  "description": "Counts words and characters in the active document.",
  "apiVersion":  1,
  "entry":       "python",
  "module":      "main",
  "pyRequires":  [],
  "order":       900,
  "menus": [
    { "title": "Plugins", "barPriority": 570, "itemPriority": 100 }
  ]
}

Campos¶

Obrigatórios¶

Campo	Tipo	Observações
`id`	cadeia	Identificador único em DNS reverso. Usado em toda parte — ativar/desativar, linhas de log, configurações por plugin. Não pode mudar entre versões.
`apiVersion`	inteiro	Precisa ser igual ao `MTE_PLUGIN_API_VERSION` do host. Atualmente `1`. Uma divergência aparece na página de Plugins e o plugin é listado, mas não carregado.
`entry`	cadeia	Precisa ser `"python"` para ser encaminhado pelo backend Python. `"native"` ou omitido encaminha pelo carregador do Qt.
`module`	cadeia	Nome do módulo Python que contém `register(ctx)`. Se for `"main"`, o trabalhador procura `main.py` dentro da pasta do plugin. Nomes de pacote com pontos (`"src.main"`) são uma extensão futura — a fase 1 suporta apenas nomes planos.

Opcionais¶

Campo	Tipo	Observações
`order`	inteiro	Ordem de carregamento entre plugins; menor carrega antes. `1000` por padrão. Empates resolvidos por `id`. `requires` tem precedência.
`requires`	array de cadeias	Ids dos plugins sem os quais este plugin não funciona (nativos ou Python, tanto faz), p. ex. `["org.mte.lsp"]` — não são pacotes pip, esses vão em `pyRequires`. Eles são iniciados antes deste plugin, seja qual for o `order`; quando algum está ausente, desativado, bloqueado pela licença ou não foi carregado, este plugin não é iniciado de forma alguma e Preferências → Plug-ins informa de qual ele precisa e por quê. Mesmo significado que para um plugin nativo.
`apiMinorVersion`	inteiro	A menor versão minor da API do host de que este plugin precisa (padrão `0`). Um plugin Python não tem um `info()` compilado, então esta é sua única declaração: informe a minor da chamada mais recente que você usa. Um host mais antigo lista o plugin como "Precisa de uma versão mais recente do OctoEdit" e não o inicia.
`menus`	array de objetos	Veja abaixo.
`pyRequires`	array de cadeias	Cadeias de requisitos do pip (p. ex. `["requests>=2.31"]`). Na primeira inicialização do plugin, o editor provisiona um ambiente virtual por plugin, instala esses pacotes com pip nele e executa o trabalhador do plugin sob ele (veja Empacotamento). Entradas que não são cadeias e as vazias são puladas.
`permissions`	array de cadeias	Declarações grosseiras de capacidade (p. ex. `["network"]`), exibidas em modo somente leitura na coluna Permissões de Preferências → Plug-ins, para que os usuários vejam o que um plugin diz fazer. Apenas declaração — ainda não é imposta.
`thirdParty`	array de objetos	Componentes de terceiros que o plugin embute, para atribuição na caixa de diálogo Sobre. Cada entrada: `name` (obrigatório), `license`, `url`, `file`. Distribua o texto de licença nomeado por `file` ao lado do plugin, sob `Plugins/Licenses/<id>/`. Veja abaixo.

`menus`¶

Cada entrada declara um menu de primeiro nível ao qual o plugin contribui e define a posição dele. Repita um objeto por menu de primeiro nível que você tocar (Tools, Plugins, Help, etc.).

"menus": [
  { "title": "Plugins", "barPriority": 570, "itemPriority": 100 }
]

Campo	Tipo	Observações
`title`	cadeia, obrigatório	O rótulo do menu de primeiro nível sob o qual o item vive (`Plugins`, `Tools`, …). Precisa coincidir com o segmento mais à esquerda dos caminhos que você passa a `ctx.menus.add_item()`.
`barPriority`	inteiro, opcional	Classificação da esquerda para a direita na barra de menus. Menor = mais à esquerda. Os menus do núcleo têm prioridades fixas espaçadas de 100 em 100 (Arquivo `100`, Editar `200`, …, Janela `600`); `570` põe o seu submenu perto da posição de `Plugins`. Repetido entre plugins que miram o mesmo menu de primeiro nível; o último vencer não importa, porque é idempotente.
`itemPriority`	inteiro, opcional	Classificação vertical de todo o bloco do seu plugin dentro do menu folha. `1000` por padrão. Menor = mais acima.

Você NÃO lista itens individuais aqui — esses são acrescentados por ctx.menus.add_item() em tempo de execução. menus trata apenas do posicionamento na barra de menus.

`thirdParty`¶

Declare qualquer componente de terceiros que o seu plugin embute, para que a caixa de diálogo Sobre possa atribuí-lo. Cada entrada:

"thirdParty": [
  { "name": "SomeLib", "license": "MIT",
    "url": "https://example.com/", "file": "SomeLib-LICENSE.txt" }
]

Campo	Tipo	Observações
`name`	cadeia, obrigatório	O componente. Entradas sem um nome não vazio são descartadas.
`license`	cadeia, opcional	Rótulo no estilo SPDX, p. ex. `MIT`, `LGPL-3.0`.
`url`	cadeia, opcional	Página do projeto/inicial.
`file`	cadeia, opcional	Nome base do texto de licença que você distribui, resolvido em `Plugins/Licenses/<your-plugin-id>/<file>`.

As licenças são suas: distribua-as com o pacote do seu plugin, sob Plugins/Licenses/<id>/. O editor lista os componentes e aponta os usuários para aquela pasta; ele não guarda textos de terceiros do seu plugin na pasta Licenses/ dele.

Sondagem estática¶

Na hora da descoberta — e de novo quando um pacote .mteplugin é instalado — o host lê module, abre <pluginDir>/<module>.py e confirma que ele contém um def register(...) de nível superior — nenhum código roda. O instalador rejeita um pacote que falhe com uma caixa de diálogo de erro; a descoberta pula o plugin em silêncio, com uma linha de erro no log:

PythonPluginBackend: skipping 'org.example.wordcount': module
'.../main.py' does not declare a top-level `def register(...)`.

Mantenha register na coluna 0 de uma linha começando por def register(.

Ordem de carregamento e posicionamento na barra de menus¶

Se o seu plugin contribui para Plugins com barPriority: 570, o menu aparece na classificação 570 da barra de menus. Dois plugins com valores de barPriority diferentes para o mesmo título competem: vence o que carregou por último, mas como os dois normalmente declaram a mesma classificação para um dado menu, isso não importa. Veja PLUGIN_ARCHITECTURE.md §13 para o modelo completo de ordenação.

O que NÃO pertence aqui¶

O host analisa os campos documentados acima e ignora todo o resto — não invente campos; uma chave desconhecida é peso morto em silêncio.

Campo	Tipo	Observações
`name`	cadeia	Nome legível exibido na página de Plugins.
`version`	cadeia	Versionamento semântico; livre no restante.
`vendor`	cadeia	Autor / organização. Exibido na página de Plugins.
`description`	cadeia	Uma ou duas linhas. Exibida na página de Plugins.

Referência do plugin.json¶