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 inicial, final ou duplo. Dá nome à ferramenta plugin__<slug> e à variável <SLUG>_BIN. |
name | string | sim | Nome apresentado. Indique o serviço a que se liga. |
version | string | sim | Versão semântica, como 0.1.0. |
platforms | map | sim | Chave da plataforma para o binário. Consulte Plataformas. |
description | string | não | Uma frase para pessoas e funcionários. |
author | string | não | Nome do editor. |
category | string | não | Ajuda os funcionários a encontrar o plugin. |
triggers | lista de cadeias de texto | não | Palavras que descrevem quando o plugin se aplica. Usadas nas sugestões de pesquisa. |
entrySkills | lista de cadeias de texto | não | Skills incluídas a nomear primeiro na descrição da ferramenta do plugin. |
dependencies | lista de {name, version, optional} | não | Outros plugins que este executa. version é "*" por omissão; optional é false. Os caminhos <SLUG>_BIN são definidos em cada chamada. |
auth | object | não | Início de sessão e contas. Consulte 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 disponibiliza. |
channel | object | não | Uma ponte permanente para um serviço de mensagens. |
setup | object | não | Um 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": "" }
} | Campo | Significado |
|---|---|
binaryName | O nome do ficheiro executável. Acrescente .exe no Windows. |
sha256 | Hash do binário. Verificado na instalação. |
signature | Assinatura do binário. Verificada na instalação quando existe uma chave de assinatura. |
size | Tamanho em bytes. |
downloadUrl | Onde o Nebo transfere o pacote. |
Autenticação
| Campo | Significado |
|---|---|
type | oauth_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. |
env | Mapa 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.login | Inicia sessão. Obrigatório a menos que type seja env. Corre com a pasta da conta definida. |
commands.status | Imprime JSON que indica se a conta tem sessão iniciada. |
commands.refresh | Renova um token sem interação. |
commands.logout | Termina a sessão. Só o proprietário a pode executar. |
profileDirEnv | Variável que recebe uma pasta de credenciais separada para cada funcionário e conta. Sem ela, o plugin tem uma única conta partilhada. |
label, description | Texto no cartão de ligação. |
help | {url, urlLabel, text} apresentado durante a ligação. |
publicRedirect | Defina 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.
| Campo | Tipo | Por omissão | Significado |
|---|---|---|---|
key | string | obrigatório | Nome da variável de ambiente. |
label | string | obrigatório | Etiqueta 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 estiver definido. |
secret | boolean | false | O valor fica oculto quando é lido de volta. |
options | lista de cadeias de texto | nenhum | Opções para select. |
permissions
| Campo | Por omissã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 de espera de qualquer chamada. |
network | false | Declara 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"
}
] | 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 provoca o evento. |
multiplexed | Quando é 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}"
} | Marcador | Expande 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.
| Campo | Por omissão | Significado |
|---|---|---|
hook | obrigatório | Um 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. |
command | obrigatório | Argumentos para o seu binário. |
priority | 100 | O mais baixo corre primeiro. |
timeoutMs | 500 | Limite 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.
| Campo | Por omissão | Significado |
|---|---|---|
command | obrigatório | Argumentos que iniciam a ponte. |
name, description | "" | Apresentado nas definiçõ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 | Dá à 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 passo | Campos |
|---|---|
form | title, description, fields |
generate | title, description, command, args, outputFormat (yaml, json, toml, text), buttonLabel. Mostra a saída do comando para copiar. |
external | title, description, url, urlLabel, instructions |
credentials | title, 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.