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 estão em camelCase. Esta página lista todos os campos que o Nebo lê atualmente 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 inicial, final ou duplo. Dá nome à ferramenta plugin__<slug> e à variável <SLUG>_BIN.
namestringsimNome apresentado. Indique o serviço a que se liga.
versionstringsimVersão semântica, como 0.1.0.
platformsmapsimChave da plataforma para o binário. Consulte Plataformas.
descriptionstringnãoUma frase para pessoas e funcionários.
authorstringnãoNome do editor.
categorystringnãoAjuda os funcionários a encontrar o plugin.
triggerslista de cadeias de textonãoPalavras que descrevem quando o plugin se aplica. Usadas nas sugestões de pesquisa.
entrySkillslista de cadeias de textonãoSkills incluídas a nomear primeiro na descrição da ferramenta do plugin.
dependencieslista de {name, version, optional}nãoOutros plugins que este executa. version é "*" por omissão; optional é false. Os caminhos <SLUG>_BIN são definidos em cada chamada.
authobjectnãoInício de sessão e contas. Consulte 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 disponibiliza.
channelobjectnãoUma ponte permanente para um serviço de mensagens.
setupobjectnãoUm assistente de configuração passo a passo.

O Nebo valida as instalações a partir da 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 modelos de associação que sejam interpretáveis. Os plugins na pasta de plugins do utilizador não são validados.

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 publica, a loja escreve o hash, o tamanho, a assinatura e o URL de transferência reais, por isso deixe-os vazios no ficheiro que carrega.

"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 ficheiro executável. Acrescente .exe no Windows.
sha256Hash do binário. Verificado na instalação.
signatureAssinatura do binário. Verificada na instalação quando existe uma chave de assinatura.
sizeTamanho em bytes.
downloadUrlOnde o Nebo transfere o pacote.

Autenticação

CampoSignificado
typeoauth_cli para um início de sessão no navegador gerido pelo plugin; env para credenciais introduzidas como valores; neboai para receber o token NeboAI do proprietário em todas as chaves de auth.env terminadas em _TOKEN.
envMapa de nome de variável para valor por omissão. São também os únicos nomes de credenciais que o Nebo passa a login.
commands.loginInicia sessão. Obrigatório a menos que type seja env. Corre com a pasta da conta definida.
commands.statusImprime JSON que indica se a conta tem sessão iniciada.
commands.refreshRenova um token sem interação.
commands.logoutTermina a sessão. Só o proprietário a pode executar.
profileDirEnvVariável que recebe uma pasta de credenciais separada para cada funcionário e conta. Sem ela, o plugin tem uma única conta partilhada.
label, descriptionTexto no cartão de ligação.
help{url, urlLabel, text} apresentado durante a ligação.
publicRedirectDefina true quando o fornecedor recusa redirecionamentos para http://localhost; o início de sessão passa então pelo redirecionamento público do NeboAI.

O Nebo lê o primeiro de authenticated, isAuthenticated, logged_in, loggedIn ou token_valid na saída de estado. Um token_error não vazio, ou o valor none em credential_source, auth_method, storage ou status, significa sessão terminada. O comando de estado 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 indicado em key. Para as chaves de credenciais também listadas em auth.env, o esquema dá nome aos campos do formulário de ligação de cada funcionário.

CampoTipoPor omissãoSignificado
keystringobrigatórioNome da variável de ambiente.
labelstringobrigatórioEtiqueta 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 estiver definido.
secretbooleanfalseO valor fica oculto quando é lido de volta.
optionslista de cadeias de textonenhumOpções para select.

permissions

CampoPor omissã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 de espera de qualquer chamada.
networkfalseDeclara a utilização da rede. Informativo; não é imposto.

events

Um evento é um observador de longa duração. O Nebo inicia-o quando o fluxo de trabalho de um funcionário o observa e reinicia-o se terminar. Cada linha que o observador escreve no stdout é um evento. O nome do evento recebe o slug como prefixo em tempo de execução, pelo que note.created passa a 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 provoca o evento.
multiplexedQuando é true, um único observador emite vários tipos de evento e cada linha leva um campo "event".

Os fluxos de trabalho subscrevem eventos com um acionador watch. Consulte Acionadores.

interfaceBindings

Uma associação liga uma operação de interface a um dos seus comandos. Cada associação torna-se uma ferramenta tipada para os funcionários, com o nome da operação em minúsculas e com pontos e hífenes trocados por sublinhados: notes.search passa a notes_search. As associações são a forma de um plugin cumprir as capacidades que um funcionário exige; consulte 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 é também passado 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 montante inteiro em cêntimos, escrito em dólares.

Os campos de entrada que um modelo não nomeia são acrescentados como --field value. Os marcadores de lista e opcionais têm de ser palavras inteiras. Uma operação que exige aprovação não pode ser alcançada chamando o mesmo comando através de 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 o seu comando num determinado momento do turno de um funcionário. O Nebo escreve um payload JSON no stdin. A saída de um hook action é ignorada. Um hook filter devolve {"payload": ..., "handled": false}; "handled": true interrompe os hooks seguintes. Os erros e os tempos limite mantêm o payload anterior e nunca bloqueiam o turno. Após três falhas seguidas, um hook fica em pausa durante cinco minutos.

CampoPor omissãoSignificado
hookobrigatórioUm de 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 mais baixo corre primeiro.
timeoutMs500Limite de tempo em milissegundos.

commands

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

routes

Uma rota responde a pedidos HTTP em /api/v1/plugins/<slug>/api/<path> no bot, com correspondência por path e method. O corpo do pedido vai para o stdin e o seu stdout é a resposta. O limite de tempo é de 30 segundos.

providers

Um fornecedor acrescenta uma fonte de modelos de chat. Declare id, displayName, providerType, modelsCommand e chatCommand. O Nebo envia um pedido de chat em JSON pelo stdin para chatCommand e lê eventos transmitidos como JSON delimitado por novas linhas no stdout, durante até 300 segundos. Atualmente só é usada a transmissão de chat.

channel

Um canal faz a ponte para um serviço de mensagens. O Nebo mantém command em execução, lê as mensagens recebidas do seu stdout e escreve as respostas no seu stdin, ambas como JSON delimitado por novas linhas.

CampoPor omissãoSignificado
commandobrigatórioArgumentos que iniciam a ponte.
name, description""Apresentado nas definiçõ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.
needsLocalApifalseDá à ponte o endereço da API local do bot, um token e o id do funcionário. Desligado, a menos que precise.

setup

Um assistente de configuração guia o proprietário por passos que um único formulário não consegue abranger. Os valores dos passos form preenchem {{key}} nos argumentos generate seguintes. Os valores dos passos credentials são guardados 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 passoCampos
formtitle, description, fields
generatetitle, description, command, args, outputFormat (yaml, json, toml, text), buttonLabel. Mostra a saída do comando para copiar.
externaltitle, description, url, urlLabel, instructions
credentialstitle, description, fields, verifyCommand. O passo fica concluído quando verifyCommand tem êxito.

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