Campos de nível superior
| Campo | Tipo | Obrigatório | Significado |
|---|---|---|---|
id | string | sim | O identificador do plugin na loja. Use o slug durante o desenvolvimento. |
slug | string | sim | Identificador 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. |
name | string | sim | Nome de exibição. Diga o nome do serviço ao qual ele se conecta. |
version | string | sim | Versão semântica, como 0.1.0. |
platforms | map | sim | Chave de plataforma para o binário. Veja Plataformas. |
description | string | não | Uma frase para pessoas e funcionários. |
author | string | não | Nome do publicador. |
category | string | não | Ajuda os funcionários a encontrar o plugin. |
triggers | lista de strings | não | Palavras que descrevem quando o plugin se aplica. Usadas nas dicas de busca. |
entrySkills | lista de strings | não | Skills incluídas a citar primeiro na descrição da ferramenta do plugin. |
dependencies | lista de {name, version, optional} | não | Outros plugins que este executa. version tem padrão "*"; optional, false. Os caminhos <SLUG>_BIN deles são definidos em toda chamada. |
auth | object | não | Login e contas. Veja Autenticação. |
capabilities | object | não | configSchema, hooks, commands, routes, providers. |
permissions | object | não | Filtragem do ambiente e o limite máximo de tempo. |
events | list | não | Observadores que alimentam os fluxos de trabalho dos funcionários. |
interfaceBindings | map | não | Operações tipadas que o plugin oferece. |
channel | object | não | Uma ponte persistente com um serviço de mensagens. |
setup | object | não | Um 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": "" }
} | Campo | Significado |
|---|---|
binaryName | O nome do arquivo executável. Adicione .exe no Windows. |
sha256 | Hash do binário. Verificado na instalação. |
signature | Assinatura do binário. Verificada na instalação quando há uma chave de assinatura disponível. |
size | Tamanho em bytes. |
downloadUrl | Onde o Nebo baixa o pacote. |
Autenticação
| Campo | Significado |
|---|---|
type | oauth_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. |
env | Mapa 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.login | Faz login. Obrigatório, a menos que type seja env. Roda com a pasta da conta definida. |
commands.status | Imprime um JSON que informa se a conta está conectada. |
commands.refresh | Renova um token sem interação. |
commands.logout | Faz logout. Só o proprietário pode executá-lo. |
profileDirEnv | Variá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, description | Texto do cartão de conexão. |
help | {url, urlLabel, text} exibido durante a conexão. |
publicRedirect | Defina 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.
| Campo | Tipo | Padrão | Significado |
|---|---|---|---|
key | string | obrigatório | Nome da variável de ambiente. |
label | string | obrigatório | Rótulo do campo. |
description | string | "" | Texto de ajuda. |
fieldType | string | "string" | Tipo de entrada, como string, number, boolean, select ou password. |
default | string | nenhum | Valor pré-preenchido. |
required | boolean | false | O plugin só fica pronto quando o valor é definido. |
secret | boolean | false | O valor fica mascarado quando é lido de volta. |
options | lista de strings | nenhum | Opções para select. |
permissions
| Campo | Padrão | Significado |
|---|---|---|
envAllow | [] | Variáveis herdadas que o plugin pode ver. Vazio permite todas. |
envDeny | [] | Variáveis herdadas que são sempre removidas. |
maxTimeoutSeconds | 300 | Limite máximo para o tempo limite de qualquer chamada. |
network | false | Declara 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"
}
] | Campo | Significado |
|---|---|
name | Nome do evento, sem o slug. Obrigatório. |
command | Argumentos que iniciam o observador. Obrigatório. {{key}} é substituído pelos valores de entrada do funcionário. |
description | O que causa o evento. |
multiplexed | Quando 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}"
} | Marcador | Expande 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.
| Campo | Padrão | Significado |
|---|---|---|
hook | obrigatório | Um 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. |
command | obrigatório | Argumentos para o seu binário. |
priority | 100 | O menor roda primeiro. |
timeoutMs | 500 | Tempo 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.
| Campo | Padrão | Significado |
|---|---|---|
command | obrigatório | Argumentos que iniciam a ponte. |
name, description | "" | Exibido nas configurações. |
restartDelaySecs | 5 | Espera antes de reiniciar após uma falha. |
shared | false | Uma 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. |
needsLocalApi | false | Entrega à 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 etapa | Campos |
|---|---|
form | title, description, fields |
generate | title, description, command, args, outputFormat (yaml, json, toml, text), buttonLabel. Mostra a saída do comando para ser copiada. |
external | title, description, url, urlLabel, instructions |
credentials | title, 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.