NeboAI
NeboAI
Começar

Referência do plugin.json

O plugin.json é o manifesto que o Nebo lê para instalar e executar um plugin. As chaves usam camelCase. Esta página lista todos os campos que o Nebo lê hoje e o que cada um faz.

Campos de nível superior

CampoTipoObrigatórioSignificado
idstringsimO identificador do plugin na loja. Use o slug durante o desenvolvimento.
slugstringsimIdentificador estável. [a-z0-9-], no máximo 64 caracteres, sem hífen no início, no fim ou duplicado. Dá nome à ferramenta plugin__<slug> e à variável <SLUG>_BIN.
namestringsimNome de exibição. Diga o nome do serviço ao qual ele se conecta.
versionstringsimVersão semântica, como 0.1.0.
platformsmapsimChave de plataforma para o binário. Veja Plataformas.
descriptionstringnãoUma frase para pessoas e funcionários.
authorstringnãoNome do publicador.
categorystringnãoAjuda os funcionários a encontrar o plugin.
triggerslista de stringsnãoPalavras que descrevem quando o plugin se aplica. Usadas nas dicas de busca.
entrySkillslista de stringsnãoSkills incluídas a citar primeiro na descrição da ferramenta do plugin.
dependencieslista de {name, version, optional}nãoOutros plugins que este executa. version tem padrão "*"; optional, false. Os caminhos <SLUG>_BIN deles são definidos em toda chamada.
authobjectnãoLogin e contas. Veja Autenticação.
capabilitiesobjectnãoconfigSchema, hooks, commands, routes, providers.
permissionsobjectnãoFiltragem do ambiente e o limite máximo de tempo.
eventslistnãoObservadores que alimentam os fluxos de trabalho dos funcionários.
interfaceBindingsmapnãoOperações tipadas que o plugin oferece.
channelobjectnãoUma ponte persistente com um serviço de mensagens.
setupobjectnãoUm assistente de configuração passo a passo.

O Nebo valida as instalações feitas pela loja: as regras do slug, uma versão semântica, pelo menos uma plataforma, um binaryName sem separadores de caminho nem .., um comando login, a menos que auth.type seja env, nomes de eventos e comandos não vazios e templates de binding que possam ser interpretados. Plugins no diretório de plugins do usuário não passam pela validação.

Plataformas

As chaves são darwin-arm64, darwin-amd64, linux-arm64, linux-amd64, windows-arm64 e windows-amd64. Cada entrada tem os cinco campos abaixo. Quando você publica, a loja grava o hash, o tamanho, a assinatura e a URL de download reais, então deixe-os vazios no arquivo que você enviar.

"platforms": {
  "darwin-arm64":  { "binaryName": "notes-sync",     "sha256": "", "signature": "", "size": 0, "downloadUrl": "" },
  "linux-amd64":   { "binaryName": "notes-sync",     "sha256": "", "signature": "", "size": 0, "downloadUrl": "" },
  "windows-amd64": { "binaryName": "notes-sync.exe", "sha256": "", "signature": "", "size": 0, "downloadUrl": "" }
}
CampoSignificado
binaryNameO nome do arquivo executável. Adicione .exe no Windows.
sha256Hash do binário. Verificado na instalação.
signatureAssinatura do binário. Verificada na instalação quando há uma chave de assinatura disponível.
sizeTamanho em bytes.
downloadUrlOnde o Nebo baixa o pacote.

Autenticação

CampoSignificado
typeoauth_cli para um login pelo navegador conduzido pelo plugin; env para credenciais digitadas como valores; neboai para receber o token NeboAI do proprietário em toda chave de auth.env que termina em _TOKEN.
envMapa de nome de variável para valor padrão. Também são os únicos nomes de credencial que o Nebo passa para login.
commands.loginFaz login. Obrigatório, a menos que type seja env. Roda com a pasta da conta definida.
commands.statusImprime um JSON que informa se a conta está conectada.
commands.refreshRenova um token sem interação.
commands.logoutFaz logout. Só o proprietário pode executá-lo.
profileDirEnvVariável que recebe uma pasta de credenciais separada para cada funcionário e conta. Sem ela, o plugin mantém uma única conta compartilhada.
label, descriptionTexto do cartão de conexão.
help{url, urlLabel, text} exibido durante a conexão.
publicRedirectDefina true quando o provedor recusar redirecionamentos para http://localhost; nesse caso, o login passa pelo redirecionamento público do NeboAI.

O Nebo lê o primeiro valor encontrado entre authenticated, isAuthenticated, logged_in, loggedIn ou token_valid na saída de status. Um token_error não vazio, ou o valor none em credential_source, auth_method, storage ou status, significa desconectado. O comando de status tem 45 segundos.

{"authenticated": true, "account": "finance@example.com"}

configSchema

capabilities.configSchema descreve os valores que um proprietário define para o plugin. Cada valor chega ao binário como uma variável de ambiente com o nome dado por key. Para chaves de credencial também listadas em auth.env, o schema rotula os campos do formulário de conexão de cada funcionário.

CampoTipoPadrãoSignificado
keystringobrigatórioNome da variável de ambiente.
labelstringobrigatórioRótulo do campo.
descriptionstring""Texto de ajuda.
fieldTypestring"string"Tipo de entrada, como string, number, boolean, select ou password.
defaultstringnenhumValor pré-preenchido.
requiredbooleanfalseO plugin só fica pronto quando o valor é definido.
secretbooleanfalseO valor fica mascarado quando é lido de volta.
optionslista de stringsnenhumOpções para select.

permissions

CampoPadrãoSignificado
envAllow[]Variáveis herdadas que o plugin pode ver. Vazio permite todas.
envDeny[]Variáveis herdadas que são sempre removidas.
maxTimeoutSeconds300Limite máximo para o tempo limite de qualquer chamada.
networkfalseDeclara o uso de rede. Apenas informativo; não é aplicado.

events

Um evento é um observador de longa duração. O Nebo o inicia quando o fluxo de trabalho de um funcionário o observa e o reinicia se ele encerrar. Cada linha que o observador escreve no stdout é um evento. Em tempo de execução, o nome do evento recebe o slug como prefixo, então note.created vira notes-sync.note.created.

"events": [
  {
    "name": "note.created",
    "description": "A note was created in the watched notebook.",
    "command": "watch --notebook {{notebook}} --format ndjson"
  }
]
CampoSignificado
nameNome do evento, sem o slug. Obrigatório.
commandArgumentos que iniciam o observador. Obrigatório. {{key}} é substituído pelos valores de entrada do funcionário.
descriptionO que causa o evento.
multiplexedQuando true, um único observador emite vários tipos de evento e cada linha traz um campo "event".

Os fluxos de trabalho assinam eventos com um gatilho watch. Veja Gatilhos.

interfaceBindings

Um binding associa uma operação de interface a um dos seus comandos. Cada binding vira uma ferramenta tipada para os funcionários, com o nome da operação em minúsculas e com pontos e hífens trocados por sublinhados: notes.search vira notes_search. Os bindings são a forma como um plugin atende às capacidades que um funcionário exige; veja Capacidades.

"interfaceBindings": {
  "notes.search": "notes search --query {query} {tag[]:--tag} {limit?:--limit}",
  "invoice.create": "invoices create --amount {amount_cents:cents->dollars}"
}
MarcadorExpande para
{field}O valor do campo como uma única palavra. O campo não é passado também como flag.
{field[]:--flag}Um par --flag <item> para cada item de um campo de lista.
{field?:--flag}--flag <value> quando o campo está presente; nada quando está ausente.
{field:cents->dollars}Um valor inteiro em centavos, escrito em dólares.

Campos de entrada que um template não cita são acrescentados como --field value. Marcadores de lista e opcionais precisam ser palavras inteiras. Uma operação que exige aprovação não pode ser acessada chamando o mesmo comando por plugin__<slug>.

Hooks, comandos de barra e rotas

"capabilities": {
  "hooks": [
    { "hook": "tool.post_execute", "hookType": "filter", "command": "hook redact", "priority": 50, "timeoutMs": 500 }
  ],
  "commands": [
    { "name": "notes", "description": "Show today's notes", "command": "notes today", "slash": true }
  ],
  "routes": [
    { "path": "/callback", "method": "GET", "command": "http callback" }
  ]
}

hooks

Um hook executa seu comando em um ponto do turno de um funcionário. O Nebo grava um payload JSON no stdin. A saída de um hook action é ignorada. Um hook filter retorna {"payload": ..., "handled": false}; "handled": true interrompe os hooks seguintes. Erros e tempos esgotados mantêm o payload anterior e nunca bloqueiam o turno. Depois de três falhas seguidas, o hook fica pausado por cinco minutos.

CampoPadrãoSignificado
hookobrigatórioUm destes: tool.pre_execute, tool.post_execute, message.post_receive, session.message_append, steering.generate, agent.turn, agent.should_continue.
hookType"action"action ou filter.
commandobrigatórioArgumentos para o seu binário.
priority100O menor roda primeiro.
timeoutMs500Tempo limite em milissegundos.

commands

Com "slash": true, digitar /name args no chat executa command args diretamente, sem o funcionário. A saída é a resposta. O tempo limite é de 30 segundos.

routes

Uma rota responde a requisições HTTP em /api/v1/plugins/<slug>/api/<path> no bot, identificadas por path e method. O corpo da requisição vai para o stdin, e o seu stdout é a resposta. O tempo limite é de 30 segundos.

providers

Um provedor adiciona uma fonte de modelos de chat. Declare id, displayName, providerType, modelsCommand e chatCommand. O Nebo envia uma requisição de chat como JSON no stdin para chatCommand e lê os eventos transmitidos como JSON delimitado por linha no stdout, por até 300 segundos. Hoje só o streaming de chat é usado.

channel

Um canal faz a ponte com um serviço de mensagens. O Nebo mantém command em execução, lê as mensagens recebidas pelo stdout dele e escreve as respostas no stdin dele, ambos como JSON delimitado por linha.

CampoPadrãoSignificado
commandobrigatórioArgumentos que iniciam a ponte.
name, description""Exibido nas configurações.
restartDelaySecs5Espera antes de reiniciar após uma falha.
sharedfalseUma ponte para todos os funcionários; as mensagens são encaminhadas pelo nome do funcionário e as respostas levam a identidade de cada funcionário.
needsLocalApifalseEntrega à ponte o endereço da API local do bot, um token e o id do funcionário. Fica desativado, a menos que você precise.

setup

Um assistente de configuração guia o dono por etapas que um único formulário não dá conta de cobrir. Os valores das etapas form preenchem {{key}} nos argumentos generate seguintes. Os valores das etapas credentials são salvos como variáveis de ambiente do plugin.

"setup": {
  "title": "Connect Example Chat",
  "steps": [
    { "kind": "form", "title": "Bot name", "fields": [ { "key": "bot_name", "label": "Name", "required": true } ] },
    { "kind": "generate", "title": "App manifest", "command": "manifest", "args": ["--name", "{{bot_name}}"], "outputFormat": "yaml" },
    { "kind": "external", "title": "Create the app", "url": "https://example.com/apps", "urlLabel": "Open admin" },
    { "kind": "credentials", "title": "Paste the token", "fields": [ { "key": "EXAMPLE_CHAT_TOKEN", "label": "Token", "inputType": "password", "required": true } ], "verifyCommand": "auth status" }
  ]
}
Tipo de etapaCampos
formtitle, description, fields
generatetitle, description, command, args, outputFormat (yaml, json, toml, text), buttonLabel. Mostra a saída do comando para ser copiada.
externaltitle, description, url, urlLabel, instructions
credentialstitle, description, fields, verifyCommand. A etapa é concluída quando verifyCommand é bem-sucedido.

Os campos têm key, label, default, placeholder, maxLength, help, inputType (text, textarea, password) e required.