Menu
1/9 Visão geralTodas as páginas

Tutoriais · Plugins

Criando plugins para o Jarvis ADE

O que é um plugin, o que ele pode contribuir (agentes, skills, servidores MCP, temas, configurações e integrações) e como as peças se encaixam.

Nesta página

O que é um plugin

Um plugin do Jarvis ADE é uma pasta (ou um .zip, um repositório git ou um pacote npm que vira uma pasta depois de extraído) com um arquivo ade.plugin.json na raiz. Esse manifesto é o único arquivo que o app realmente lê; o resto da pasta é copiado como está.

O manifesto contribui capacidades ao app: agentes, skills, servidores MCP, temas, e — nas duas contribuições de runtime — um formulário de configurações e um processo auxiliar (o sidecar) que recebe os eventos das missões e do quadro kanban.

Pasta / pacote do plugin

folder, .zip, git ou npm — o que você publica

ade.plugin.jsonskills/integrations/themes/
importarvalida o manifesto e copia; nada é executado

Jarvis ADE (app desktop)

lê o manifesto e distribui cada contribuição

agentsskillsmcpServersthemessettingsintegrations
JSON linesstdin: eventos · stdout: mensagens

Sidecar (processo filho)

o único código do plugin que roda — só com o plugin ativado

node integrations/…ADE_PLUGIN_SETTINGSADE_PLUGIN_DATA_DIR
Em verde, as duas contribuições de runtime (v2): settings (formulário que o usuário preenche) e integrations (o sidecar). Agentes, skills, servidores MCP e temas são declarativos.

O que um plugin pode contribuir

Cada chave de contributes é opcional e independente das outras. Um manifesto com "contributes": {} é válido — só não entrega nada além do próprio nome.

Contribuições possíveis de um plugin
ChaveO que entregaRoda código do plugin?
agentsAgentes com adapter, modelo, esforço e system prompt próprios.Não
skillsPastas com um SKILL.md, copiadas junto com o plugin.Não
mcpServersDeclaração (command/args/env) de servidores MCP. O instalador só valida o formato; nunca executa o comando.Não, na instalação
themesUm arquivo CSS por tema, referenciado por caminho relativo.Não
settingsCampos que o usuário preenche na tela de plugins (chave de API, IDs, opções).Não
integrationsSidecars: processos filhos que o app inicia e alimenta com eventos em JSON lines.Sim — o único caso, e só com o plugin ativado e as configurações obrigatórias preenchidas

Regra de ouro: instalar nunca executa código

Importar um plugin valida o ade.plugin.json (com o schema real, antes de copiar qualquer coisa) e copia a pasta para userData/plugins/<id>. Um manifesto inválido é recusado inteiro — nunca há cópia parcial. Reimportar o mesmo id substitui a versão anterior e mantém as configurações que o usuário já preencheu.

Origens de instalação
OrigemO que o instalador faz
folderCopia a pasta.
zipExtrai com unzip numa pasta temporária e segue como folder.
gitgit clone --depth 1 numa pasta temporária. O manifesto pode estar na raiz ou até duas pastas abaixo (repositórios/zips com uma pasta-mãe).
npmnpm install --prefix <tmp> --no-save --ignore-scripts <pacote> numa pasta temporária, e copia somente node_modules/<pacote>. O manifesto precisa estar na raiz do pacote.

Onde as coisas ficam

  • Arquivos do plugin: userData/plugins/<id> — é o diretório de trabalho (cwd) do sidecar, então args: ["integrations/echo.mjs"] é relativo a ele.
  • Dados do sidecar: userData/plugin-data/<id>/<integração>, exposto na variável ADE_PLUGIN_DATA_DIR. O app cria a pasta antes de iniciar o processo.
  • Valores das configurações: guardados como texto no estado do app, por plugin.
  • Requisito na máquina do usuário: o command da integração (por exemplo node) é executado direto — precisa existir no PATH.

A trilha de tutoriais

Leia na ordem, ou pule direto para o que precisa:

  1. 02Seu primeiro pluginPasso a passo do plugin de exemplo hello-ade: manifesto, sidecar, skill, teste local sem o ADE e importação pelo Marketplace.
  2. 03ManifestoTodos os campos do ade.plugin.json, com o que é obrigatório, as restrições de cada um e os erros que o instalador devolve.
  3. 04Protocolo do sidecarComo um sidecar conversa com o Jarvis ADE: variáveis de ambiente, mensagens de entrada e saída em JSON lines, ciclo de vida, restart e backoff.
  4. 05Configurações e segredosOs quatro tipos de configuração, como os valores chegam ao sidecar e o padrão de ação “faça agora” com boolean e trava anti-repetição.
  5. 06Boas práticasSem dependências em runtime, pasta de dados, logs, idempotência e as armadilhas que mais derrubam plugins.
  6. 07Publicar no GitHub e npmLayout do repositório, package.json, npm publish e um workflow do GitHub Actions que publica a cada tag.
  7. 08Registrar no MarketplaceCrie seu handle de publisher, envie o plugin, entenda as checagens automáticas, a aprovação, as revisões e as avaliações.
  8. 09Instalar via CLIOs comandos npx jarvis-ade plugins: add, search, info, init e validate.

Antes de começar

  • Jarvis ADE instalado (download).
  • Node.js 18 ou superior, se o seu plugin tiver um sidecar — o exemplo hello-ade exige só isso.