NeboAI
NeboAI
Começar

Plugins

Um plugin dá aos funcionários algo sobre que agir: um serviço online, um sistema de gestão ou um programa no computador. Cria-o como um binário de linha de comandos e descreve-o com um manifesto plugin.json. Os funcionários chamam os seus comandos, e o Nebo trata da instalação, das contas por funcionário e das atualizações.

Como funcionam os plugins

Um plugin é um executável mais um manifesto. O Nebo não mantém nenhum processo do plugin em execução entre chamadas. Sempre que um funcionário usa o plugin, o Nebo inicia o binário com um comando e argumentos, espera que termine e devolve a saída ao funcionário.

  • Os comandos são argumentos. O funcionário escolhe um comando, como notes search, e argumentos com nome. O Nebo passa cada argumento como --name value. Não há shell, por isso pipes e redirecionamentos nunca se aplicam.
  • A saída é o stdout. Escreva os resultados no stdout. JSON funciona bem.
  • A entrada padrão está fechada nas chamadas normais. Os hooks, as rotas e os fornecedores de chat usam o stdin; consulte a referência do plugin.json.

Cada plugin instalado e ativado aparece aos funcionários como uma ferramenta chamada plugin__<slug>. Um funcionário chama-a assim:

{
  "command": "notes search",
  "args": { "query": "quarterly plan", "limit": "5" },
  "display": "Search notes for the quarterly plan"
}

O Nebo executa:

notes-sync notes search --query "quarterly plan" --limit 5
ParâmetroTipoSignificado
commandcadeia de texto, obrigatórioO comando do plugin e quaisquer palavras posicionais.
argsobjeto de cadeias de textoArgumentos com nome. Cada um passa a --key value.
timeoutintegerSegundos de espera. Por omissão 120, limitado por permissions.maxTimeoutSeconds do manifesto.
displaystringA frase que o proprietário vê quando a chamada precisa de aprovação.

Crie o seu primeiro plugin

Escreva um binário em qualquer linguagem que leia o comando a partir dos argumentos e imprima um resultado. Depois coloque-o ao lado de um plugin.json na pasta de plugins do utilizador de um bot.

<data>/user/plugins/notes-sync/
├── plugin.json      # runtime manifest
├── notes-sync       # your binary, named after the slug
└── skills/          # optional: skills that teach employees to use it
    └── notes-sync/
        └── SKILL.md
{
  "id": "notes-sync",
  "slug": "notes-sync",
  "name": "Notes Sync",
  "version": "0.1.0",
  "description": "Search, read and create notes in Example Notes.",
  "platforms": {}
}

id, slug, name, version e platforms são obrigatórios. Na pasta de plugins do utilizador, o mapa platforms pode estar vazio: o Nebo procura um binário com o nome do slug ao lado do plugin.json e depois em target/release/ e target/debug/. Quando publica, a loja preenche platforms para cada binário que carregar.

<data> é ~/Library/Application Support/Nebo no macOS, %APPDATA%\Nebo no Windows e ~/.local/share/nebo no Linux, ou o valor de NEBO_HOME. Um plugin na pasta do utilizador substitui um plugin da loja com o mesmo slug, o que faz dela o sítio certo para testar uma nova compilação.

Ensine os funcionários a usá-lo

Coloque uma pasta skills/ ao lado do plugin.json. Cada skill nela fica disponível para todos os funcionários enquanto o plugin estiver instalado, e indica automaticamente o plugin como dependência. Use a skill para dizer que comandos existem, o que devolvem e quando usar cada um. Nomeie as skills mais úteis em entrySkills para que a descrição da ferramenta do plugin aponte primeiro para elas.

A página da loja é um ficheiro à parte, PLUGIN.md. O Nebo não o lê em tempo de execução; é a página que as pessoas veem antes de instalar. Consulte Lançar um plugin.

Ambiente

Cada chamada herda o ambiente do bot, sem as variáveis do carregador e de injeção na shell, e acrescenta estes valores. As entradas posteriores prevalecem.

VariávelValor
Chaves de auth.envValores por omissão do manifesto.
<SLUG>_BINCaminho do binário deste plugin e de cada plugin de que depende. O slug passa a maiúsculas, com os hífenes trocados por sublinhados.
NEBO_DATA_DIRA pasta de dados do próprio plugin, <data>/appdata/plugins/<slug>/. É também a pasta de trabalho e sobrevive à desinstalação.
PATHPrimeiro as pastas dos plugins, depois o caminho herdado.
DefiniçõesValores que o proprietário guardou para os campos de configSchema.
NEBO_AGENT_IDO funcionário que faz a chamada.
profileDirEnvA pasta da conta para este funcionário e conta, quando o plugin suporta contas.

permissions.envAllow e permissions.envDeny restringem o que o plugin herda do bot. Nunca removem as variáveis de autenticação do próprio plugin.

Contas e credenciais

Um plugin que inicia sessão num serviço deve ter uma conta por funcionário. O contabilista inicia sessão com o acesso das finanças e o assistente com o seu próprio, e nenhum vê os tokens do outro. Declara isto no manifesto; o Nebo trata do resto.

"auth": {
  "type": "env",
  "label": "Example Notes account",
  "env": { "EXAMPLE_NOTES_TOKEN": "" },
  "commands": { "login": "auth login", "status": "auth status", "logout": "auth logout" },
  "profileDirEnv": "EXAMPLE_NOTES_CONFIG_DIR"
},
"capabilities": {
  "configSchema": [
    { "key": "EXAMPLE_NOTES_TOKEN", "label": "API token", "fieldType": "password", "secret": true, "required": true }
  ]
}
  1. auth.env dá nome às credenciais. capabilities.configSchema atribui-lhes etiquetas e define a ordem no formulário de ligação.
  2. auth.profileDirEnv dá nome à variável que o seu plugin lê para obter a pasta de credenciais. O Nebo cria uma pasta para cada funcionário e conta e define essa variável em cada chamada.
  3. Quando o proprietário liga uma conta, o Nebo executa o seu comando login com os valores que o proprietário escreveu e com a pasta da conta definida. O seu plugin guarda nessa pasta o que precisar. O Nebo não guarda os valores.
  4. O seu comando status imprime JSON como {"authenticated": true}. Quando um token expira, o Nebo executa refresh, se o tiver declarado.

Para um início de sessão no navegador, defina type como oauth_cli e faça com que login imprima ou abra o URL de início de sessão do fornecedor. Os funcionários nunca iniciam sessão sozinhos: quando uma chamada precisa de sessão iniciada, o proprietário vê um cartão de ligação. Um funcionário com várias contas escolhe uma acrescentando --account <label> a um comando. O Nebo remove essa flag antes de o seu binário a ver.

Dê o nome do serviço, não da forma. O nome de um plugin diz a que se liga, como "Example Notes". Nunca ponha "CLI" no nome de um plugin; para os funcionários e os proprietários é uma ligação, não uma linha de comandos.

A seguir