Visão geral
O que é o Nebo
O Nebo é um assistente pessoal de IA para computador — um funcionário de IA sempre ativo que gere a sua vida digital. Pense no Nebo como pensa num smartphone: uma plataforma poderosa que se torna transformadora graças às suas apps.
Por si só, o Nebo é um funcionário de IA competente, com memória, agendamento, navegação na web, gestão de ficheiros e acesso à shell. Mas o verdadeiro salto vem das apps. Tal como o poder de um smartphone vem do seu ecossistema de apps, o poder do Nebo vem das apps que alargam o que ele consegue fazer.
O que são as apps
As apps do Nebo são unidades autónomas e pré-compiladas de funcionalidades incríveis. Cada app dá ao Nebo um novo superpoder — gestão de calendário, triagem de email, acompanhamento de projetos, domótica, análise financeira — tudo o que um programador conseguir imaginar.
As apps dão um poder incrível de forma muito segura. Cada app corre numa sandbox com permissões negadas por predefinição. Só pode aceder ao que o seu manifesto declara e o utilizador aprova.
A interface é 100% conversacional. Os utilizadores não interagem com as apps através de ecrãs ou painéis separados. Falam com o Nebo, e o Nebo usa as ferramentas da app para fazer as coisas. «O que tenho no calendário amanhã?» — o Nebo chama a app de calendário. «Marca uma reunião com a Sara às 3 da tarde» — o Nebo chama a app de calendário. O utilizador nunca sai da conversa.
As apps podem, opcionalmente, oferecer uma interface de definições — um painel de configuração que abre na janela de navegador integrada do Nebo. É aqui que os utilizadores introduzem chaves de API, ativam funcionalidades e configuram a app. A interface de definições é gerada a partir da matriz settings do manifesto (o Nebo apresenta o formulário automaticamente), ou a app pode fornecer a sua própria interface totalmente personalizada através da capacidade ui.
As apps substituem e alargam as capacidades integradas do Nebo. O Nebo vem com ferramentas básicas da plataforma (acesso ao calendário local, capturas de ecrã, etc.). Quando instala uma app de calendário, ela substitui a ferramenta de calendário integrada e torna-se um superconjunto — local + nuvem + agregação + verificação de disponibilidade.
Política de apenas compilados
O Nebo aplica uma política rigorosa de apenas binários compilados. Todas as apps têm de ser executáveis nativos compilados.
| Estado | Linguagens |
|---|---|
| Suportadas | Go (recomendado), Rust, C/C++, Zig |
| Rejeitadas | Python, Node.js, Ruby, Java, .NET, scripts de shell |
Justificação:
- Prevenção da automodificação da IA — Um funcionário de IA com acesso à shell poderia alterar o comportamento de um script interpretado em tempo de execução. Os binários compilados são imutáveis depois de assinados.
- Integridade da assinatura — As assinaturas Ed25519 cobrem os bytes brutos do binário. Um binário assinado não pode ser alterado sem invalidar a assinatura.
- Aplicação da sandbox — A validação do formato binário (magic bytes ELF/Mach-O/PE) é uma barreira rápida e fiável.
Início rápido
Instalar o SDK
Os SDKs oficiais tratam de toda a configuração do servidor gRPC, do tratamento de sinais e da ponte de protocolos. Só tem de implementar as interfaces de handler.
Go (recomendado):
go get github.com/neboloop/nebo-sdk-go Rust (brevemente):
# Coming soon
[dependencies]
nebo-sdk = "0.1" C/C++ (brevemente):
# Coming soon — Add as a CMake subdirectory or copy headers from sdk/c/include/ Estrutura de diretórios da app
As apps ficam no subdiretório apps/ do seu diretório de dados do Nebo:
~/Library/Application Support/Nebo/apps/ # macOS
~/.config/nebo/apps/ # Linux
%AppData%\Nebo\apps\ # Windows
apps/
com.example.myapp/
manifest.json # Required: app metadata
binary # Required: executable (or named "app")
signatures.json # Required for NeboAI distribution, optional in dev
TOOL.md # Required: tool instructions for the agent
data/ # Auto-created: app's sandboxed storage
logs/ # Auto-created: stdout.log, stderr.log
ui/ # Optional: static UI assets (HTML/CSS/JS) Lista de verificação de uma app mínima
- Crie o
manifest.jsoncomid,name,version,provides - Escreva um
TOOL.mdque descreva como o funcionário de IA deve usar a sua ferramenta - Instale o SDK (
go get github.com/neboloop/nebo-sdk-go) - Implemente a interface de handler da sua capacidade (
ToolHandler,ChannelHandler, etc.) - Registe o handler e chame
app.Run() - Compile um binário nativo (
go build -o binary .) - Coloque o binário + manifest.json + TOOL.md no diretório
apps/<your-app-id>/ - O Nebo deteta-o e inicia-o automaticamente
Configuração
manifest.json
Todas as apps precisam de um manifest.json:
{
"id": "com.example.myapp",
"name": "My App",
"version": "1.0.0",
"description": "What this app does",
"runtime": "local",
"protocol": "grpc",
"provides": ["tool:my_tool"],
"permissions": ["network:outbound"],
"settings": [
{
"key": "api_key",
"title": "API Key",
"type": "password",
"required": true,
"description": "Your API key for the service",
"secret": true
}
]
} Campos obrigatórios:
| Campo | Descrição |
|---|---|
id | Identificador em domínio invertido (por exemplo, com.mycompany.myapp) |
name | Nome legível |
version | Cadeia semver |
provides | Pelo menos uma capacidade (ver abaixo) |
Campos opcionais:
| Campo | Predefinição | Descrição |
|---|---|---|
runtime | "local" | "local" ou "remote" |
protocol | "grpc" | Só é suportado "grpc" |
permissions | [] | Aquilo a que a app precisa de aceder |
description | "" | Apresentado na interface |
settings | [] | Definições configuráveis (apresentadas na interface de Definições) |
oauth | [] | Requisitos de fornecedor OAuth (ver a secção OAuth abaixo) |
Capacidades
Declare o que a sua app fornece:
| Capacidade | Serviço gRPC | Descrição |
|---|---|---|
gateway | GatewayService | Encaminhamento de modelos LLM |
tool:<name> | ToolService | Uma ferramenta com nome para o funcionário de IA |
channel:<name> | ChannelService | Um canal de mensagens |
comm | CommService | Comunicação entre funcionários de IA |
ui | UIService | Interface personalizada com proxy HTTP |
schedule | ScheduleService | Agendamento personalizado |
vision | ToolService | Processamento de visão |
browser | ToolService | Automação do navegador |
Uma app pode fornecer várias capacidades. Por exemplo, uma app pode fornecer uma ferramenta e um painel de interface.
Permissões
As permissões controlam aquilo a que a app pode aceder. Tudo é negado por predefinição — se não estiver declarado, a app não o pode usar.
| Prefixo | Exemplos | Descrição |
|---|---|---|
network: | network:outbound, network:* | Acesso à rede |
filesystem: | filesystem:read, filesystem:write | Acesso ao sistema de ficheiros |
memory: | memory:read, memory:write | Acesso à memória do funcionário de IA |
session: | session:read | Sessões de conversa |
tool: | tool:shell, tool:file | Usar outras ferramentas |
shell: | shell:exec | Execução de comandos de shell |
channel: | channel:send, channel:* | Operações de canal |
comm: | comm:send, comm:* | Comunicação entre funcionários de IA |
model: | model:chat | Acesso a modelos de IA |
user: | user:token | Receber o JWT do utilizador nos pedidos |
schedule: | schedule:create | Gestão de tarefas cron |
database: | database:query | Acesso à base de dados |
storage: | storage:read, storage:write | Armazenamento persistente |
context: | context:read | Acesso ao contexto do funcionário de IA |
subagent: | subagent:spawn | Operações de subagentes |
lane: | lane:enqueue | Operações de lanes |
notification: | notification:send | Notificações push |
embedding: | embedding:search | Acesso a embeddings vetoriais |
skill: | skill:invoke | Invocação de skills |
advisor: | advisor:consult | Acesso ao sistema de conselheiros |
mcp: | mcp:connect | Acesso a servidores MCP |
voice: | voice:record | Acesso a voz/áudio |
browser: | browser:navigate | Automação do navegador |
oauth: | oauth:google, oauth:* | Acesso a tokens OAuth |
settings: | settings:read | Acesso às definições |
capability: | capability:register | Registo de capacidades |
São suportadas permissões com caráter universal: network:* corresponde a qualquer verificação de permissão network:.
Definições
As definições aparecem na interface do Nebo, no painel de definições da app. O Nebo guarda-as na base de dados e envia-as para a sua app através do RPC Configure sempre que mudam.
O esquema das suas definições é incluído na listagem da app na loja da NeboAI. As apps com definições obrigatórias por configurar mostram um selo «Precisa de configuração» na interface.
| Tipo | Descrição |
|---|---|
text | Campo de texto de uma linha |
password | Campo de texto oculto |
toggle | Interruptor booleano ligado/desligado |
select | Lista pendente com opções predefinidas |
number | Campo numérico |
url | Campo de URL com validação |
{
"key": "region",
"title": "Region",
"type": "select",
"required": true,
"default": "us-east-1",
"options": [
{"label": "US East", "value": "us-east-1"},
{"label": "EU West", "value": "eu-west-1"}
]
} Requisitos de OAuth
As apps podem declarar requisitos de fornecedor OAuth. O broker OAuth do Nebo trata de todo o fluxo — as apps recebem os tokens automaticamente através do RPC Configure.
{
"oauth": [
{
"provider": "google",
"scopes": ["https://www.googleapis.com/auth/calendar"]
}
]
} | Campo | Descrição |
|---|---|
provider | Fornecedor OAuth: "google", "microsoft", "github" |
scopes | Matriz dos âmbitos OAuth de que a app precisa |
Quando o utilizador instala a app, o Nebo pede-lhe que autorize os âmbitos OAuth necessários. A app recebe tokens atualizados através do RPC Configure sem ter de tratar ela própria do fluxo OAuth.
Variáveis de ambiente
O processo da sua app recebe um ambiente higienizado. Todos os segredos são removidos. Recebe:
| Variável | Valor |
|---|---|
NEBO_APP_DIR | Diretório de instalação da app |
NEBO_APP_SOCK | Caminho para o socket Unix a criar |
NEBO_APP_ID | ID da app indicado no manifesto |
NEBO_APP_NAME | Nome da app indicado no manifesto |
NEBO_APP_VERSION | Versão da app indicada no manifesto |
NEBO_APP_DATA | Caminho para o diretório data/ da app |
PATH | PATH do sistema (transmitido tal como está) |
HOME | Diretório pessoal do utilizador (transmitido tal como está) |
TMPDIR | Diretório temporário (transmitido tal como está) |
Importante: O seu binário tem de criar um servidor gRPC à escuta no socket Unix em NEBO_APP_SOCK. O Nebo espera até 10 segundos que este socket apareça.
Sequência de arranque da app
- O Nebo lê o
manifest.jsone valida-o - Procura o executável
binaryouappno diretório da app - Verifica se existe o marcador
.quarantined(recusa iniciar apps em quarentena) - Verificação de revogação (apenas apps distribuídas pela NeboAI)
- Verificação da assinatura (apenas apps distribuídas pela NeboAI; ignorada em desenvolvimento)
- Validação do binário (rejeita ligações simbólicas, scripts, ficheiros não executáveis e ficheiros demasiado grandes)
- Limpa o socket antigo da execução anterior
- Cria o diretório
data/para armazenamento isolado - Configura ficheiros de registo por app (
logs/stdout.log,logs/stderr.log) - Inicia o binário com um ambiente higienizado e isolamento do grupo de processos
- Espera que o socket Unix apareça (backoff exponencial, máximo de 10 segundos)
- Liga-se por gRPC através do socket Unix
- Cria clientes gRPC específicos de cada capacidade com base em
provides - Executa a verificação de estado
- Regista as capacidades junto do funcionário de IA (ferramentas, gateway, comm, etc.)
Apps de ferramentas
Declare "provides": ["tool:my_tool_name"] no seu manifesto.
O padrão STRAP
Todas as apps de ferramentas do Nebo têm de usar o STRAP (Single Tool Resource Action Pattern) no seu esquema e no encaminhamento da execução. É o mesmo padrão que o Nebo usa internamente para reunir mais de 35 ferramentas individuais em 4 ferramentas de domínio — reduzindo a sobrecarga de contexto do LLM em cerca de 80%.
Ideia central: Em vez de registar várias ferramentas (get_events, check_availability, suggest_slots), registe UMA ferramenta com campos action (e, opcionalmente, resource) que encaminham para o handler certo.
Exemplo com um só recurso (calendário):
calendar(action: "get_events", start: "2025-01-15T09:00:00Z", end: "2025-01-16T00:00:00Z")
calendar(action: "next_event")
calendar(action: "check_availability", start: "...", end: "...")
calendar(action: "suggest_slots", duration_minutes: 30, preferred_time: "morning") Exemplo com vários recursos (gestor de projetos):
project(resource: "task", action: "create", title: "Ship v2", assignee: "alice")
project(resource: "task", action: "list", status: "open")
project(resource: "milestone", action: "create", name: "Beta", deadline: "2025-03-01")
project(resource: "milestone", action: "list") Regras do esquema:
- Inclua sempre um campo
actioncomo enum de cadeia obrigatório - Adicione um campo
resource(enum de cadeia obrigatório) apenas se a sua ferramenta gerir vários tipos de recurso distintos - Todos os outros campos são parâmetros específicos de cada ação
- A descrição do enum
actiondeve listar todas as ações disponíveis
Porque é que o STRAP importa:
- Os LLMs aprendem o padrão de encaminhamento por
actionuma vez e generalizam-no a todas as operações - As definições de ferramentas consomem cerca de 6% do contexto — o STRAP reduz isso em 80%
- Novas operações são apenas novos valores no enum, não novos registos de ferramentas
- Funciona da mesma forma com modelos alojados e locais
Exemplo em Go — Ferramenta de calculadora
package main
import (
"context"
"encoding/json"
"fmt"
"log"
nebo "github.com/neboloop/nebo-sdk-go"
)
type Calculator struct{}
func (c *Calculator) Name() string { return "calculator" }
func (c *Calculator) Description() string { return "Performs arithmetic calculations." }
func (c *Calculator) Schema() json.RawMessage {
return nebo.NewSchema("add", "subtract", "multiply", "divide").
Number("a", "First operand", true).
Number("b", "Second operand", true).
Build()
}
func (c *Calculator) Execute(_ context.Context, input json.RawMessage) (string, error) {
var in struct {
Action string `json:"action"`
A float64 `json:"a"`
B float64 `json:"b"`
}
if err := json.Unmarshal(input, &in); err != nil {
return "", fmt.Errorf("invalid input: %w", err)
}
var result float64
switch in.Action {
case "add":
result = in.A + in.B
case "subtract":
result = in.A - in.B
case "multiply":
result = in.A * in.B
case "divide":
if in.B == 0 {
return "", fmt.Errorf("division by zero")
}
result = in.A / in.B
default:
return "", fmt.Errorf("unknown action: %s", in.Action)
}
return fmt.Sprintf("%g %s %g = %g", in.A, in.Action, in.B, result), nil
}
func main() {
app, err := nebo.New()
if err != nil {
log.Fatal(err)
}
app.RegisterTool(&Calculator{})
log.Fatal(app.Run())
} manifest.json:
{
"id": "com.example.calculator",
"name": "Calculator",
"version": "1.0.0",
"description": "Arithmetic calculator tool for the agent",
"runtime": "local",
"protocol": "grpc",
"provides": ["tool:calculator"],
"permissions": []
} Compilar e instalar:
go build -o binary .
mkdir -p ~/Library/Application\ Support/Nebo/apps/com.example.calculator
cp binary manifest.json ~/Library/Application\ Support/Nebo/apps/com.example.calculator/ Exemplo em Rust
use async_trait::async_trait;
use nebo_sdk::{NeboApp, NeboError, SchemaBuilder};
use nebo_sdk::tool::ToolHandler;
use serde::Deserialize;
use serde_json::Value;
struct Calculator;
#[derive(Deserialize)]
struct Input { action: String, a: f64, b: f64 }
#[async_trait]
impl ToolHandler for Calculator {
fn name(&self) -> &str { "calculator" }
fn description(&self) -> &str { "Performs arithmetic calculations." }
fn schema(&self) -> Value {
SchemaBuilder::new(&["add", "subtract", "multiply", "divide"])
.number("a", "First operand", true)
.number("b", "Second operand", true)
.build()
}
async fn execute(&self, input: Value) -> Result<String, NeboError> {
let i: Input = serde_json::from_value(input)
.map_err(|e| NeboError::Execution(e.to_string()))?;
let r = match i.action.as_str() {
"add" => i.a + i.b,
"subtract" => i.a - i.b,
"multiply" => i.a * i.b,
"divide" => {
if i.b == 0.0 {
return Err(NeboError::Execution("division by zero".into()));
}
i.a / i.b
}
other => return Err(NeboError::Execution(format!("unknown action: {other}"))),
};
Ok(format!("{} {} {} = {}", i.a, i.action, i.b, r))
}
}
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
NeboApp::new()?.register_tool(Calculator).run().await?;
Ok(())
} Exemplo em C
#include <nebo/nebo.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
static int calculator_execute(const char *input_json, char **output, int *is_error) {
/* Parse JSON, compute result, set *output */
*output = strdup("2 add 3 = 5");
*is_error = 0;
return 0;
}
int main(void) {
const char *actions[] = {"add", "subtract", "multiply", "divide", NULL};
nebo_schema_builder_t *sb = nebo_schema_new(actions);
nebo_schema_number(sb, "a", "First operand", 1);
nebo_schema_number(sb, "b", "Second operand", 1);
char *schema = nebo_schema_build(sb);
nebo_schema_free(sb);
nebo_tool_handler_t calculator = {
.name = "calculator",
.description = "Performs arithmetic calculations.",
.schema = schema,
.execute = calculator_execute,
};
nebo_app_t *app = nebo_app_new();
nebo_app_register_tool(app, &calculator);
int ret = nebo_app_run(app);
free(schema);
return ret;
} Apps de canal
Declare "provides": ["channel:my_channel"] e "permissions": ["channel:send"].
As apps de canal ligam plataformas de mensagens externas (Telegram, Discord, Slack, etc.) ao funcionário de IA do Nebo. Quando um utilizador envia uma mensagem na plataforma externa, a sua app transmite-a ao Nebo através de Receive. Quando o funcionário de IA quer responder, o Nebo chama o Send da sua app.
Como funciona
- O Nebo chama
ID()para obter o identificador único do seu canal - O Nebo chama
Connect()com a configuração das definições da sua app - O Nebo abre um stream
Receive()— a sua app envia as mensagens recebidas sempre que um utilizador escreve ao bot - As mensagens recebidas são encaminhadas para a lane de conversa principal do funcionário de IA
- Quando o funcionário de IA quer enviar uma mensagem, o Nebo chama
Send()com o envelope de mensagem v1 - Ao encerrar, o Nebo chama
Disconnect()
Envelope de mensagem v1
Todas as mensagens de canal — recebidas e enviadas — usam o envelope de mensagem comum:
{
"message_id": "01953f8a-...",
"channel_id": "telegram:12345",
"sender": { "name": "Alex", "role": "COO", "bot_id": "uuid" },
"text": "Q3 numbers look good...",
"attachments": [{ "type": "image", "url": "https://...", "filename": "chart.png", "size": 45000 }],
"reply_to": "01953f89-...",
"actions": [{ "label": "Approve", "callback_id": "approve_q3" }],
"platform_data": null,
"timestamp": "2026-02-12T15:10:00Z"
} | Campo | Tipo | Descrição |
|---|---|---|
message_id | UUID v7 | ID único ordenado no tempo |
channel_id | {type}:{platform_id} | Identificador de canal encaminhável |
sender | object | Identidade do bot — nome, função, botId |
text | string | Corpo da mensagem |
attachments | array | Ficheiros, imagens, áudio |
reply_to | UUID v7 | ID da mensagem principal, para conversas em fio |
actions | array | Botões/teclados interativos |
platform_data | bytes | Dados opacos transmitidos tal como estão, para funcionalidades específicas da plataforma |
timestamp | ISO 8601 | Definido pelo editor |
Design em duas camadas: Os campos comuns (text, attachments, reply_to, actions) cobrem 90% das mensagens iniciadas por funcionários. As funcionalidades específicas da plataforma vão em platform_data — o seu plugin converte-as de e para o formato nativo da plataforma.
Streams de conversa
As mensagens de canal são encaminhadas por streams de conversa separados para cada canal, para garantir o isolamento:
neboai/bot/{botID}/channels/{channelType}/inbound # messages from users → agent
neboai/bot/{botID}/channels/{channelType}/outbound # messages from agent → channel Exemplo em Go — Canal de Telegram
package main
import (
"context"
"encoding/json"
"fmt"
"log"
"time"
"github.com/google/uuid"
tgbot "github.com/go-telegram/bot"
nebo "github.com/neboloop/nebo-sdk-go"
)
type Telegram struct {
bot *tgbot.Bot
messages chan nebo.ChannelEnvelope
cancel context.CancelFunc
}
func (t *Telegram) ID() string { return "telegram" }
func (t *Telegram) Connect(_ context.Context, config map[string]string) error {
token := config["bot_token"]
if token == "" {
return fmt.Errorf("bot_token is required")
}
botCtx, cancel := context.WithCancel(context.Background())
t.cancel = cancel
bot, err := tgbot.New(token, tgbot.WithDefaultHandler(
func(bCtx context.Context, b *tgbot.Bot, update *tgbot.Update) {
if update.Message == nil {
return
}
env := nebo.ChannelEnvelope{
MessageID: uuid.Must(uuid.NewV7()).String(),
ChannelID: fmt.Sprintf("telegram:%d", update.Message.Chat.ID),
Text: update.Message.Text,
Timestamp: time.Unix(int64(update.Message.Date), 0).UTC(),
}
t.messages <- env
},
))
if err != nil {
return err
}
t.bot = bot
go bot.Start(botCtx)
return nil
}
func (t *Telegram) Send(ctx context.Context, env nebo.ChannelEnvelope) (string, error) {
if t.bot == nil {
return "", fmt.Errorf("not connected")
}
chatID := env.ChannelID[len("telegram:"):]
params := &tgbot.SendMessageParams{
ChatID: chatID,
Text: env.Text,
}
msg, err := t.bot.SendMessage(ctx, params)
if err != nil {
return "", err
}
return fmt.Sprintf("%d", msg.MessageID), nil
}
func (t *Telegram) Receive(_ context.Context) (<-chan nebo.ChannelEnvelope, error) {
return t.messages, nil
}
func (t *Telegram) Disconnect(_ context.Context) error {
if t.cancel != nil {
t.cancel()
}
return nil
}
func main() {
app, err := nebo.New()
if err != nil {
log.Fatal(err)
}
app.RegisterChannel(&Telegram{
messages: make(chan nebo.ChannelEnvelope, 100),
})
log.Fatal(app.Run())
} manifest.json:
{
"id": "com.example.telegram",
"name": "Telegram",
"version": "1.0.0",
"description": "Telegram messaging channel for Nebo",
"runtime": "local",
"protocol": "grpc",
"provides": ["channel:telegram"],
"permissions": ["channel:send", "network:outbound"],
"settings": [
{
"key": "bot_token",
"title": "Bot Token",
"type": "password",
"required": true,
"description": "Telegram bot token from @BotFather",
"secret": true
}
]
} Mais capacidades
App Comm
Declare "provides": ["comm"] e "permissions": ["comm:*"]. As apps comm permitem a comunicação entre funcionários de IA.
| Campo | Descrição |
|---|---|
from | ID do funcionário remetente |
to | ID do funcionário destinatário |
topic | Tópico/canal da mensagem |
type | "message", "mention", "proposal", "command", "info", "task" |
content | Corpo da mensagem |
Comportamentos principais:
Registeranuncia este funcionário de IA na rede, com as suas capacidadesSubscribe/Unsubscribegerem as subscrições de tópicosReceivetransmite as mensagens recebidas (streaming do servidor, tal como nos canais)- Só pode estar ativa uma app comm de cada vez
App de gateway
Uma app de gateway encaminha pedidos de LLM para os modelos. Declare "provides": ["gateway"] e "permissions": ["network:outbound", "user:token"].
GatewayRequest contém mensagens, ferramentas, prompt de sistema, máximo de tokens, temperatura e um UserContext (token JWT, se a permissão user:token for concedida).
Tipos de GatewayEvent:
| Tipo | Conteúdo | Descrição |
|---|---|---|
"text" | Fragmento de texto | Token de texto em streaming |
"tool_call" | JSON | O modelo quer chamar uma ferramenta |
"thinking" | Fragmento de texto | Pensamento/raciocínio alargado |
"error" | Mensagem de erro | Algo correu mal |
"done" | Vazio | O stream terminou |
App de interface
Uma app de interface fornece uma interface de configuração personalizada que abre na janela de navegador integrada do Nebo. Declare "provides": ["ui"]. Ao contrário do formulário de definições automático (que o Nebo gera a partir do settings do seu manifesto), uma app de interface serve o seu próprio frontend completo em HTML/CSS/JS.
A sua app inclui um diretório ui/ com recursos web estáticos (HTML, CSS, JS — normalmente uma SPA com index.html). O Nebo serve estes ficheiros diretamente e encaminha as chamadas à API para a sua app por gRPC.
| Caminho | Mecanismo | Finalidade |
|---|---|---|
GET /api/v1/apps/{id}/ui/* | Servidor de ficheiros estáticos | Serve ficheiros do seu diretório ui/ (com recurso a index.html para a SPA) |
ANY /api/v1/apps/{id}/api/* | Proxy gRPC | Encaminha os pedidos HTTP para o UIService.HandleRequest() da sua app |
O SDK envolve um net/http.ServeMux padrão, por isso escreve handlers HTTP normais em Go — o SDK trata automaticamente da ponte gRPC.
Exemplo em Go — Interface de painel:
package main
import (
"encoding/json"
"log"
"net/http"
nebo "github.com/neboloop/nebo-sdk-go"
)
type Dashboard struct {
mux *http.ServeMux
}
func NewDashboard() *Dashboard {
d := &Dashboard{mux: http.NewServeMux()}
d.mux.HandleFunc("GET /status", func(w http.ResponseWriter, r *http.Request) {
json.NewEncoder(w).Encode(map[string]string{"status": "ok"})
})
d.mux.HandleFunc("POST /action", func(w http.ResponseWriter, r *http.Request) {
var req map[string]string
json.NewDecoder(r.Body).Decode(&req)
json.NewEncoder(w).Encode(map[string]string{"result": "done"})
})
return d
}
func (d *Dashboard) Handler() *http.ServeMux { return d.mux }
func main() {
app, err := nebo.New()
if err != nil {
log.Fatal(err)
}
app.RegisterUI(NewDashboard())
log.Fatal(app.Run())
} O seu ui/index.html faria chamadas fetch para /api/v1/apps/com.example.dashboard/api/status, que são encaminhadas para o seu handler mux.
App de agendamento
Uma app de agendamento substitui o agendador cron integrado do Nebo. Declare "provides": ["schedule"] e "permissions": ["schedule:create"].
Quando a sua app de agendamento arranca, o Nebo encaminha todo o agendamento pela sua app em vez do motor cron predefinido. Se a sua app falhar, o Nebo volta automaticamente ao motor integrado.
- A sua app é dona do estado dos agendamentos — o Nebo não guarda agendamentos na sua própria base de dados enquanto houver uma app de agendamento ativa
- CRUD padrão:
Create,Get,List,Update,Delete,Enable,Disable Triggersé um RPC com streaming do servidor — a sua app envia uma mensagem de disparo sempre que um agendamento é acionado- Só pode estar ativa uma app de agendamento de cada vez
Apps com várias capacidades
Uma app pode fornecer várias capacidades. Por exemplo, uma app de painel com uma ferramenta e uma interface:
{
"id": "com.example.dashboard",
"name": "Dashboard",
"version": "1.0.0",
"provides": ["tool:dashboard_query", "ui"],
"permissions": ["network:outbound"]
} app, _ := nebo.New()
app.RegisterTool(&dashboardTool{})
app.RegisterUI(&dashboardUI{})
log.Fatal(app.Run()) Empacotamento
Formato .napp
Para distribuir através da NeboAI, empacote a sua app como um ficheiro .napp (um arquivo tar.gz):
cd com.example.myapp/
tar -czf myapp-1.0.0.napp manifest.json binary signatures.json TOOL.md Ficheiros obrigatórios:
| Ficheiro | Tamanho máximo | Descrição |
|---|---|---|
manifest.json | 1 MB | Metadados da app |
binary ou app | 500 MB | Executável |
signatures.json | 1 MB | Assinaturas Ed25519 |
TOOL.md | 1 MB | Instruções da ferramenta para o funcionário de IA |
Regras de segurança durante a extração:
- Sem travessia de caminhos (
../é rejeitado) - Sem ligações simbólicas (rejeitadas)
- Sem caminhos absolutos (rejeitados)
- Só são aceites nomes de ficheiro da lista permitida
Assinaturas
A NeboAI assina as apps com Ed25519. O formato do signatures.json:
{
"key_id": "a1b2c3d4",
"algorithm": "ed25519",
"manifest_signature": "<base64 signature of raw manifest.json bytes>",
"binary_sha256": "<hex SHA256 of binary>",
"binary_signature": "<base64 signature of raw binary bytes>"
} No modo de desenvolvimento (sem URL da NeboAI configurado), a verificação da assinatura é totalmente ignorada. Não precisa de signatures.json para o desenvolvimento local.
Publicação
Quando a sua app funcionar localmente, publique-a através da NeboAI para a distribuir a todos os utilizadores do Nebo.
Configuração da conta de programador
- Registe uma conta NeboAI em
POST /api/v1/owners/register - Inicie sessão para obter um token JWT:
POST /api/v1/owners/login - Crie uma conta de programador:
POST /api/v1/developer/accounts
Fluxo de submissão
draft → pending_review → [approved] → published
→ [rejected] → draft (fix and resubmit) Passo 1: Criar a app
curl -X POST https://neboai.com/api/v1/developer/apps \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "My App",
"version": "1.0.0",
"description": "What it does",
"category": "productivity",
"visibility": "public"
}' Passo 2: Carregar os binários das plataformas
curl -X POST https://neboai.com/api/v1/developer/apps/{id}/binaries \
-H "Authorization: Bearer $TOKEN" \
-F "binary=@myapp-darwin-arm64" \
-F "platform=darwin-arm64" Carregue um binário por plataforma: darwin-arm64, darwin-amd64, linux-amd64, linux-arm64.
Passo 3: Submeter para revisão
curl -X POST https://neboai.com/api/v1/developer/apps/{id}/submit \
-H "Authorization: Bearer $TOKEN" Processo de revisão
- Análise automática — os binários são analisados pelo VirusTotal
- Revisão pela administração — a equipa da NeboAI revê os metadados, o manifesto e os resultados da análise
- Se for aprovada — a NeboAI assina a app com Ed25519 e publica-a
- Se for rejeitada — recebe o motivo e pode corrigir e voltar a submeter
Tempo de revisão previsto: <24 horas.
Publicar atualizações
- Atualize a versão da app:
PUT /api/v1/developer/apps/{id}com a nova versão - Carregue novos binários para cada plataforma
- Submeta novamente para revisão
Cada atualização passa pelo mesmo processo de revisão. As versões anteriores continuam disponíveis até a nova versão ser aprovada.
Metadados da loja
| Campo | Descrição |
|---|---|
category | por exemplo, productivity, communication, developer-tools |
icon | URL do ícone da app |
visibility | public ou private |
description | Pode ser mais longa e mais rica do que a descrição do manifesto |
Fluxo de desenvolvimento
Desenvolvimento local
Não é preciso empacotar para o desenvolvimento local:
- Crie o diretório da sua app:
mkdir -p ~/Library/Application\ Support/Nebo/apps/com.example.myapp - Escreva o seu
manifest.jsone o código - Compile o seu binário:
go build -o ~/Library/Application\ Support/Nebo/apps/com.example.myapp/binary . - O Nebo deteta automaticamente o novo diretório (ou reinicie o Nebo)
- Depois de alterar o código, volte a compilar o binário — o observador de ficheiros reinicia a app
Ver os registos
O stdout/stderr da app é guardado em ficheiros de registo por app:
tail -f ~/Library/Application\ Support/Nebo/apps/com.example.myapp/logs/stdout.log
tail -f ~/Library/Application\ Support/Nebo/apps/com.example.myapp/logs/stderr.log Dados persistentes
Use o diretório data/ (também disponível na variável de ambiente NEBO_APP_DATA) para quaisquer ficheiros que a sua app precise de manter. Este diretório sobrevive às atualizações da app e à quarentena.
Dicas de depuração
- Se a sua app não arrancar, verifique se há erros em
logs/stderr.log - Confirme que o binário é executável (
chmod +x binary) - Confirme que está à escuta no caminho do socket Unix indicado em
NEBO_APP_SOCK - O socket tem de estar pronto nos 10 segundos seguintes ao arranque
- Use
NEBO_APP_DATApara o armazenamento, e não caminhos fixos no código - Escreva no stderr para registos de depuração (guardados em
logs/stderr.log)
Verificação
# List installed apps
nebo apps list
# Check running apps via the web UI Settings > Apps
# Or check the apps directory for running sockets
ls ~/Library/Application\ Support/Nebo/apps/*/app.sock Desinstalação
nebo apps uninstall com.example.myapp Skills
O que são as skills
As skills são conjuntos de instruções que moldam o comportamento do Nebo durante uma conversa. Quando uma skill está ativa, o seu conteúdo é injetado diretamente no prompt de sistema — orientando o tom, a metodologia, os conhecimentos especializados e o uso de ferramentas do funcionário de IA nessa sessão.
As skills não são código. São documentos markdown com metadados YAML. Sem compilação, sem binário, sem gRPC. Uma skill é um ficheiro SKILL.md num diretório. Mais nada.
As skills são contextuais e temporárias. Ativam-se quando são relevantes (por correspondência de gatilhos ou carregamento manual), mantêm-se durante algumas interações e expiram quando deixam de ser necessárias. Assim, o contexto do funcionário de IA mantém-se leve — no prompt só está a orientação que importa naquele momento.
As skills complementam as apps. As apps fornecem capacidades executáveis (ferramentas, canais, gateways). As skills fornecem orientação de orquestração — como usar bem essas ferramentas. Uma app de calendário dá ao Nebo a capacidade de ler e escrever eventos. Uma skill de «preparação de reuniões» diz ao Nebo como se preparar para reuniões usando em conjunto essa app de calendário, o email e a pesquisa na web.
Skills vs. apps
| Skills | Apps | |
|---|---|---|
| Formato | Markdown (SKILL.md) | Binário compilado (.napp) |
| Execução | Injetadas no prompt de sistema | Processo em sandbox através de gRPC |
| Fornecem | Orientação de comportamento, metodologia | Ferramentas, canais, painéis de interface |
| Duração | Limitadas à sessão, expiram por TTL | Sempre em execução |
| Criação | Escrever um ficheiro markdown | Escrever, compilar, assinar, empacotar |
| Segurança | Não precisam de permissões | Sandbox com tudo negado por predefinição |
Início rápido
Crie um diretório na pasta de skills do Nebo com um ficheiro SKILL.md:
~/Library/Application Support/Nebo/skills/ # macOS
~/.config/nebo/skills/ # Linux
%AppData%\Nebo\skills\ # Windows mkdir -p ~/.config/nebo/skills/my-skill Escreva um SKILL.md:
---
name: my-skill
description: One-line description of what this skill does
version: "1.0.0"
triggers:
- keyword that activates this skill
- another trigger phrase
---
# My Skill
Instructions for Nebo when this skill is active.
Tell the agent what to do, how to approach problems,
what tools to use, and what tone to take. O Nebo vigia o diretório de skills com fsnotify. A sua skill fica disponível de imediato — sem reiniciar. Diga algo que corresponda a um gatilho e ela ativa-se automaticamente.
Ou peça diretamente ao Nebo: «Cria uma skill para escrever artigos de blogue» — o Nebo escreve o ficheiro SKILL.md por si.
Formato do SKILL.md
Cada skill é um único ficheiro SKILL.md com duas partes: frontmatter YAML entre marcadores --- e um corpo em markdown (as instruções propriamente ditas, injetadas no prompt de sistema).
| Campo | Obrigatório | Predefinição | Descrição |
|---|---|---|---|
name | Sim | — | Identificador único (torna-se o slug) |
description | Sim | — | Descrição de uma linha apresentada no catálogo de skills |
version | Não | "1.0.0" | Semver para acompanhar atualizações |
author | Não | — | Autor da skill |
priority | Não | 0 | Mais alto = corresponde primeiro (100+ para substituições críticas) |
max_turns | Não | 4 | Interações sem atividade antes da expiração automática |
triggers | Não | [] | Expressões que ativam esta skill automaticamente (correspondência de subcadeia, sem distinguir maiúsculas) |
tools | Não | [] | Ferramentas que esta skill espera usar (informativo) |
dependencies | Não | [] | Outras skills que têm de estar instaladas |
tags | Não | [] | Para categorização e descoberta |
platform | Não | [] | Plataformas suportadas: macos, linux, windows (vazio = todas) |
Como se ativam as skills
As skills seguem um modelo de ativação em duas fases: sugestão e depois invocação.
Fase 1: Correspondência de gatilhos — Sempre que um utilizador envia uma mensagem, o Nebo procura correspondências de gatilhos em todas as skills registadas. As skills correspondentes aparecem como sugestões no prompt de sistema. O funcionário de IA vê a sugestão e decide se invoca a skill.
Fase 2: Invocação — O funcionário de IA invoca uma skill chamando:
skill(name: "code-review") Isto devolve o modelo SKILL.md completo como resultado da ferramenta, regista a invocação e volta a injetar o modelo no prompt de sistema nas interações seguintes.
TTL e expiração:
- Skills ativadas automaticamente: 4 interações sem atividade (configurável com
max_turns) - Skills carregadas manualmente: 6 interações sem atividade
- Voltar a invocar reinicia o temporizador
- Limite máximo: 4 skills ativas por sessão
- Orçamento de tokens: o conteúdo combinado das skills ativas está limitado a 16,000 carateres
Gerir skills
O funcionário de IA pode gerir skills através da ferramenta skill:
| Ação | Descrição | Exemplo |
|---|---|---|
catalog | Listar todas as skills disponíveis | skill(action: "catalog") |
load | Ativar nesta sessão | skill(name: "code-review", action: "load") |
unload | Desativar uma skill | skill(name: "code-review", action: "unload") |
create | Criar uma nova skill no disco | skill(action: "create", content: "...") |
update | Atualizar uma skill existente | skill(name: "my-skill", action: "update", content: "...") |
delete | Eliminar uma skill do disco | skill(name: "my-skill", action: "delete") |
Escrever boas skills
Um bom modelo de skill tem:
- Um título claro — diz ao funcionário de IA em que modo está
- Princípios centrais — as regras de comportamento inegociáveis
- Metodologia — abordagem passo a passo para os cenários comuns
- Exemplos — padrões concretos de mensagem do utilizador e resposta
- Antipadrões — o que NÃO fazer (os modelos aprendem bem com exemplos negativos)
Dica: Cada skill deve fazer uma coisa bem feita. Não crie uma skill de «programação geral» — crie code-review, debugging e api-design como skills separadas. O funcionário de IA pode ter várias ativas em simultâneo.
Skills incluídas
O Nebo vem com skills incluídas para os casos de uso mais comuns:
| Skill | Prioridade | Descrição |
|---|---|---|
onboarding | 100 | Boas-vindas a novos utilizadores e recolha do perfil |
best-friend | 50 | Skill de personalidade — descontraída, leal, sem rodeios |
debugging | 25 | Metodologia de depuração sistemática |
api-design | 15 | Boas práticas de design de APIs RESTful |
code-review | 10 | Revisão de código estruturada com níveis de gravidade |
database-expert | 10 | Design de bases de dados, consultas, otimização |
git-workflow | 10 | Ramificações Git, commits, fluxos de PR |
security-audit | 10 | Análise de segurança e deteção de vulnerabilidades |
Servem tanto de predefinições úteis como de implementações de referência para criar as suas próprias skills.
Referência
Ficheiros proto
Os ficheiros proto ficam em proto/apps/v0/. Os SDKs incluem código pré-gerado, por isso não precisa do protoc no desenvolvimento normal.
| Ficheiro | Serviço | RPCs principais |
|---|---|---|
v0/common.proto | (apenas mensagens) | HealthCheckRequest/Response, SettingsMap, UserContext, Empty |
v0/tool.proto | ToolService | Name, Description, Schema, Execute, RequiresApproval, Configure |
v0/channel.proto | ChannelService | ID, Connect, Disconnect, Send, Receive (stream), Configure |
v0/comm.proto | CommService | Name, Version, Connect, Disconnect, Send, Subscribe, Register, Receive (stream), Configure |
v0/gateway.proto | GatewayService | HealthCheck, Stream (stream), Poll, Cancel, Configure |
v0/ui.proto | UIService | HealthCheck, HandleRequest, Configure |
v0/schedule.proto | ScheduleService | HealthCheck, Create, Get, List, Update, Delete, Enable, Disable, Trigger, History, Triggers (stream), Configure |
Todos os serviços incluem os RPCs HealthCheck e Configure. O SDK trata de ambos automaticamente.
Tipos proto de canal
| Tipo de mensagem | Descrição |
|---|---|
ChannelSendRequest | Envelope de mensagem enviada com message_id, channelId, sender, text, attachments, reply_to, actions, platform_data |
ChannelSendResponse | ID da mensagem na plataforma, para conversas em fio |
InboundMessage | Envelope de mensagem recebida com todos os campos comuns + timestamp |
MessageSender | Identidade do bot (name, role, botId) — enriquecida pelo broker |
Attachment | Anexo de ficheiro/imagem/áudio (type, url, filename, size) |
MessageAction | Ação de botão/teclado interativo (label, callback_id) |
Identidade e funções dos bots
Os bots do Nebo têm um modelo de identidade com três eixos:
- creature — O que o bot é (arquétipo): «Estratega de raciocínio rápido», «Investigador meticuloso»
- role — Como se relaciona com o utilizador (relação): «Amigo», «COO», «Mentor»
- vibe — A sua energia (estilo de comunicação): «Descontraído mas com opinião», «Caloroso e encorajador»
Quando o seu plugin de canal recebe uma mensagem a enviar, o campo sender contém o name e o role do bot. Use-os para formatar o nome apresentado na sua plataforma. A função não é um cargo — descreve uma relação. «Amigo», «Filho» e «Mentor» são funções válidas, tal como «COO» e «DevLead».