Como os plugins funcionam
Um plugin é um executável mais um manifesto. O Nebo não mantém nenhum processo de plugin rodando entre as chamadas. Sempre que um funcionário usa o plugin, o Nebo inicia o binário com um comando e argumentos, espera ele encerrar e devolve a saída ao funcionário.
- Comandos são argumentos. O funcionário escolhe um comando, como
notes search, e argumentos nomeados. O Nebo passa cada argumento como--name value. Não há shell, então pipes e redirecionamentos nunca se aplicam. - A saída é o stdout. Escreva os resultados no stdout. JSON funciona bem.
- A entrada padrão fica fechada nas chamadas comuns. Hooks, rotas e provedores de chat usam o stdin; veja a referência do plugin.json.
Todo plugin instalado e ativado aparece para os funcionários como uma ferramenta chamada plugin__<slug>. Um funcionário a chama 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âmetro | Tipo | Significado |
|---|---|---|
command | string, obrigatório | O comando do plugin e as palavras posicionais. |
args | objeto de strings | Argumentos nomeados. Cada um vira --key value. |
timeout | integer | Segundos de espera. Padrão 120, limitado por permissions.maxTimeoutSeconds do manifesto. |
display | string | A frase que o proprietário vê quando a chamada precisa de aprovação. |
Crie seu primeiro plugin
Escreva, em qualquer linguagem, um binário que leia o comando a partir dos argumentos e imprima um resultado. Depois coloque-o ao lado de um plugin.json no diretório de plugins do usuário 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. No diretório de plugins do usuário, o mapa platforms pode ficar 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 você publica, a loja preenche platforms para cada binário que você enviar.
<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 no diretório do usuário substitui um plugin da loja com o mesmo slug, o que faz dele o lugar 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 lista o plugin como dependência automaticamente. Use a skill para dizer quais comandos existem, o que eles retornam e quando usar cada um. Cite as skills mais úteis em entrySkills para que a descrição da ferramenta do plugin aponte para elas primeiro.
A página da loja é um arquivo separado, o PLUGIN.md. O Nebo não o lê em tempo de execução; é a página que as pessoas veem antes de instalar. Veja Como publicar um plugin.
Ambiente
Cada chamada herda o ambiente do bot, sem as variáveis de loader e de injeção de shell, e depois adiciona estes valores. As entradas posteriores prevalecem.
| Variável | Valor |
|---|---|
Chaves de auth.env | Padrões do manifesto. |
<SLUG>_BIN | Caminho do binário deste plugin e de cada plugin do qual ele depende. O slug fica em maiúsculas, com hífens trocados por sublinhados. |
NEBO_DATA_DIR | A pasta de dados do próprio plugin, <data>/appdata/plugins/<slug>/. Ela também é o diretório de trabalho e é mantida quando o plugin é desinstalado. |
PATH | Primeiro as pastas de plugins, depois o caminho herdado. |
| Configurações | Valores que o proprietário salvou para os campos de configSchema. |
NEBO_AGENT_ID | O funcionário que faz a chamada. |
profileDirEnv | A pasta da conta deste funcionário e desta conta, quando o plugin suporta contas. |
permissions.envAllow e permissions.envDeny restringem o que o plugin herda do bot. Elas nunca removem as próprias variáveis de autenticação do plugin.
Contas e credenciais
Um plugin que faz login em um serviço deve manter uma conta por funcionário. O contador entra com o login do financeiro e o assistente com o próprio login, e nenhum vê os tokens do outro. Você declara isso no manifesto; o Nebo faz o 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 }
]
} auth.envnomeia as credenciais.capabilities.configSchemaas rotula e define a ordem delas no formulário de conexão.auth.profileDirEnvnomeia a variável que o seu plugin lê para encontrar a pasta de credenciais. O Nebo cria uma pasta para cada funcionário e conta e define essa variável em toda chamada.- Quando o proprietário conecta uma conta, o Nebo executa o seu comando
logincom os valores que o proprietário digitou e com a pasta da conta definida. O seu plugin salva o que precisar nessa pasta. O Nebo não guarda os valores. - Seu comando
statusimprime um JSON como{"authenticated": true}. Quando um token expira, o Nebo executarefresh, se você tiver declarado um.
Para um login pelo navegador, defina type como oauth_cli e faça o login imprimir ou abrir a URL de login do provedor. Os funcionários nunca fazem login sozinhos: quando uma chamada precisa de login, o proprietário vê um cartão de conexão. Um funcionário com várias contas escolhe uma adicionando --account <label> a um comando. O Nebo remove essa flag antes que o seu binário a veja.
Dê o nome do serviço, não do formato. O nome de um plugin diz ao que ele se conecta, como "Example Notes". Nunca coloque "CLI" no nome de um plugin; para funcionários e proprietários, ele é uma conexão, não uma linha de comando.
Próximos passos
- Referência do plugin.json: todos os campos, incluindo eventos, hooks e operações tipadas.
- Como publicar um plugin: plataformas, binários, assinatura e atualizações.
- Publicação: o fluxo da loja para todo tipo de item.