NeboAI
NeboAI
Kezdés

Alkalmazások építése a Nebóhoz

Adjon új szuperképességeket az MI-nek. Eszközök, csatornák, átjárók, felhasználói felületi panelek — bármi, amit el tud képzelni, natív binárissá fordítva.

Áttekintés

Mi a Nebo

A Nebo egy személyes asztali MI-asszisztens — egy folyamatosan futó MI-munkatárs, amely a digitális életét kezeli. Gondoljon a Nebóra úgy, mint egy okostelefonra: egy erőteljes platform, amely az alkalmazásai révén válik igazán átalakító erejűvé.

A Nebo önmagában is rátermett MI-munkatárs memóriával, ütemezéssel, webes böngészéssel, fájlkezeléssel és parancssori hozzáféréssel. Az igazi áttörést azonban az alkalmazások jelentik. Ahogy egy okostelefon ereje az alkalmazás-ökoszisztémájából fakad, úgy a Nebo ereje is azokból az alkalmazásokból ered, amelyek kibővítik a képességeit.

Mik az alkalmazások

A Nebo-alkalmazások önálló, előre lefordított egységek, rendkívüli funkcionalitással. Minden alkalmazás új szuperképességet ad a Nebónak — naptárkezelés, e-mailek osztályozása, projektkövetés, otthonautomatizálás, pénzügyi elemzés — bármit, amit egy fejlesztő el tud képzelni.

Az alkalmazások rendkívüli erőt adnak, nagyon biztonságos módon. Minden alkalmazás homokozóban fut, alapértelmezetten tiltó engedélyekkel. Csak ahhoz fér hozzá, amit a manifestje deklarál, és amit a felhasználó jóváhagy.

A felület 100%-ban beszélgetésalapú. A felhasználók nem külön képernyőkön vagy irányítópultokon kezelik az alkalmazásokat. A Nebóval beszélnek, a Nebo pedig az alkalmazás eszközeivel végzi el a dolgokat. „Mi van holnap a naptáramban?” — a Nebo meghívja a naptáralkalmazást. „Hozz létre egy megbeszélést Sarah-val délután 3-ra” — a Nebo meghívja a naptáralkalmazást. A felhasználó sosem hagyja el a beszélgetést.

Az alkalmazások opcionálisan beállítási felületet is biztosíthatnak — egy konfigurációs panelt, amely a Nebo beépített böngészőablakában nyílik meg. Itt adják meg a felhasználók az API-kulcsokat, kapcsolják be és ki a funkciókat, és konfigurálják az alkalmazást. A beállítási felületet a manifest settings tömbje vezérli (a Nebo automatikusan megjeleníti az űrlapot), vagy az alkalmazás a ui képességgel saját, teljesen egyedi felületet is adhat.

Az alkalmazások lecserélik és kibővítik a Nebo beépített képességeit. A Nebo alapvető platformeszközökkel érkezik (helyi naptár-hozzáférés, képernyőképek stb.). Ha telepít egy naptáralkalmazást, az lecseréli a beépített naptáreszközt, és annak bővített változata lesz — helyi + felhő + összesítés + elérhetőség-ellenőrzés.

Csak lefordított kód

A Nebo szigorú szabályt alkalmaz: csak lefordított binárisok engedélyezettek. Minden alkalmazásnak natív, lefordított futtatható fájlnak kell lennie.

ÁllapotNyelvek
TámogatottGo (ajánlott), Rust, C/C++, Zig
ElutasítottPython, Node.js, Ruby, Java, .NET, shell szkriptek

Indoklás:

  • Az MI önmódosításának megakadályozása — Egy parancssori hozzáféréssel rendelkező MI-munkatárs futás közben módosíthatná egy értelmezett szkript viselkedését. A lefordított binárisok az aláírás után megváltoztathatatlanok.
  • Az aláírás sértetlensége — Az Ed25519-aláírások a bináris nyers bájtjait fedik le. Egy aláírt bináris nem módosítható az aláírás érvénytelenítése nélkül.
  • A homokozó kikényszerítése — A bináris formátum ellenőrzése (ELF/Mach-O/PE mágikus bájtok) gyors és megbízható kapu.

Gyors kezdés

Az SDK telepítése

A hivatalos SDK-k elvégzik a gRPC-szerver teljes beállítását, a jelkezelést és a protokollok áthidalását. Önnek csak a kezelőinterfészeket kell implementálnia.

Go (ajánlott):

go get github.com/neboloop/nebo-sdk-go

Rust (hamarosan):

# Coming soon
[dependencies]
nebo-sdk = "0.1"

C/C++ (hamarosan):

# Coming soon — Add as a CMake subdirectory or copy headers from sdk/c/include/

Az alkalmazáskönyvtár szerkezete

Az alkalmazások a Nebo-adatkönyvtár apps/ alkönyvtárában találhatók:

~/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)

Minimális alkalmazás ellenőrzőlistája

  1. Hozza létre a manifest.json fájlt a id, name, version, provides mezőkkel
  2. Írjon egy TOOL.md fájlt, amely leírja, hogyan használja az MI-munkatárs az eszközét
  3. Telepítse az SDK-t (go get github.com/neboloop/nebo-sdk-go)
  4. Implementálja a képességéhez tartozó kezelőinterfészt (ToolHandler, ChannelHandler stb.)
  5. Regisztrálja a kezelőt, és hívja meg az app.Run() függvényt
  6. Építsen natív binárist (go build -o binary .)
  7. Helyezze a binárist + manifest.json + TOOL.md fájlokat az apps/<your-app-id>/ könyvtárba
  8. A Nebo automatikusan felismeri és elindítja

Konfiguráció

manifest.json

Minden alkalmazáshoz szükséges egy 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
        }
    ]
}

Kötelező mezők:

MezőLeírás
idFordított domain formátumú azonosító (pl. com.mycompany.myapp)
nameEmber által olvasható név
versionSemver karakterlánc
providesLegalább egy képesség (lásd lent)

Opcionális mezők:

MezőAlapértelmezésLeírás
runtime"local""local" vagy "remote"
protocol"grpc"Csak a "grpc" támogatott
permissions[]Mihez kell hozzáférnie az alkalmazásnak
description""A felhasználói felületen jelenik meg
settings[]Konfigurálható beállítások (a Beállítások felületen jelennek meg)
oauth[]OAuth-szolgáltatói követelmények (lásd az OAuth szakaszt lent)

Képességek

Deklarálja, mit biztosít az alkalmazása:

KépességgRPC-szolgáltatásLeírás
gatewayGatewayServiceLLM-modellek útválasztása
tool:<name>ToolServiceEgy elnevezett eszköz az MI-munkatárs számára
channel:<name>ChannelServiceEgy üzenetküldő csatorna
commCommServiceKommunikáció MI-munkatársak között
uiUIServiceEgyedi felhasználói felület HTTP-proxyval
scheduleScheduleServiceEgyedi ütemezés
visionToolServiceKépfeldolgozás
browserToolServiceBöngészőautomatizálás

Egy alkalmazás több képességet is biztosíthat. Például egy alkalmazás egyszerre adhat eszközt és felhasználói felületi panelt.

Engedélyek

Az engedélyek szabályozzák, mihez fér hozzá az alkalmazás. Alapértelmezés szerint tiltva — ha nincs deklarálva, az alkalmazás nem használhatja.

ElőtagPéldákLeírás
network:network:outbound, network:*Hálózati hozzáférés
filesystem:filesystem:read, filesystem:writeFájlrendszer-hozzáférés
memory:memory:read, memory:writeHozzáférés az MI-munkatárs memóriájához
session:session:readBeszélgetési munkamenetek
tool:tool:shell, tool:fileMás eszközök használata
shell:shell:execShell-parancsok futtatása
channel:channel:send, channel:*Csatornaműveletek
comm:comm:send, comm:*Kommunikáció MI-munkatársak között
model:model:chatHozzáférés MI-modellekhez
user:user:tokenA felhasználói JWT fogadása a kérésekben
schedule:schedule:createCron-feladatok kezelése
database:database:queryAdatbázis-hozzáférés
storage:storage:read, storage:writeTartós tárhely
context:context:readHozzáférés az MI-munkatárs kontextusához
subagent:subagent:spawnAlágens-műveletek
lane:lane:enqueueSávműveletek
notification:notification:sendLeküldéses értesítések
embedding:embedding:searchHozzáférés vektoros beágyazásokhoz
skill:skill:invokeKészségek meghívása
advisor:advisor:consultHozzáférés a tanácsadó rendszerhez
mcp:mcp:connectHozzáférés MCP-szerverekhez
voice:voice:recordHang- és audió-hozzáférés
browser:browser:navigateBöngészőautomatizálás
oauth:oauth:google, oauth:*Hozzáférés OAuth-tokenekhez
settings:settings:readHozzáférés a beállításokhoz
capability:capability:registerKépességek regisztrálása

A helyettesítő karakteres engedélyek támogatottak: a network:* bármely network: engedélyellenőrzésre illeszkedik.

Beállítások

A beállítások a Nebo felületén, az alkalmazás beállítási paneljén jelennek meg. A Nebo az adatbázisban tárolja őket, és amikor változnak, a Configure RPC-n keresztül elküldi őket az alkalmazásnak.

A beállítási sémája megjelenik a NeboAI alkalmazásbolti listaelemében. Azoknál az alkalmazásoknál, amelyeknek kötelező beállításai nincsenek konfigurálva, „Beállítás szükséges” jelvény látható a felületen.

TípusLeírás
textEgysoros szövegbevitel
passwordMaszkolt szövegbevitel
toggleLogikai be/ki kapcsoló
selectLegördülő lista előre megadott lehetőségekkel
numberSzámbevitel
urlURL-bevitel ellenőrzéssel
{
    "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"}
    ]
}

OAuth-követelmények

Az alkalmazások deklarálhatják az OAuth-szolgáltatói követelményeiket. A Nebo OAuth-közvetítője kezeli a teljes folyamatot — az alkalmazások automatikusan megkapják a tokeneket a Configure RPC-n keresztül.

{
    "oauth": [
        {
            "provider": "google",
            "scopes": ["https://www.googleapis.com/auth/calendar"]
        }
    ]
}
MezőLeírás
providerOAuth-szolgáltató: "google", "microsoft", "github"
scopesAz alkalmazás által igényelt OAuth-hatókörök tömbje

Amikor a felhasználó telepíti az alkalmazást, a Nebo felkéri, hogy engedélyezze a szükséges OAuth-hatóköröket. Az alkalmazás a Configure RPC-n keresztül kapja meg a frissített tokeneket, anélkül hogy maga kezelné az OAuth-folyamatot.

Környezeti változók

Az alkalmazás folyamata megtisztított környezetet kap. Minden titkos adatot eltávolítunk. Ezeket kapja:

VáltozóÉrték
NEBO_APP_DIRAz alkalmazás telepítési könyvtára
NEBO_APP_SOCKA létrehozandó Unix-socket elérési útja
NEBO_APP_IDAz alkalmazás azonosítója a manifestből
NEBO_APP_NAMEAz alkalmazás neve a manifestből
NEBO_APP_VERSIONAz alkalmazás verziója a manifestből
NEBO_APP_DATAAz alkalmazás data/ könyvtárának elérési útja
PATHRendszer PATH (változatlanul továbbítva)
HOMEA felhasználó saját könyvtára (változatlanul továbbítva)
TMPDIRIdeiglenes könyvtár (változatlanul továbbítva)

Fontos: A binárisnak létre kell hoznia egy gRPC-szervert, amely a NEBO_APP_SOCK helyen lévő Unix-socketen figyel. A Nebo legfeljebb 10 másodpercig vár, hogy ez a socket megjelenjen.

Az alkalmazás indítási sorrendje

  1. A Nebo beolvassa és ellenőrzi a manifest.json fájlt
  2. Megkeresi a binary vagy app futtatható fájlt az alkalmazáskönyvtárban
  3. Ellenőrzi a .quarantined jelölőt (karanténba helyezett alkalmazást nem indít el)
  4. Visszavonás-ellenőrzés (csak a NeboAI által terjesztett alkalmazásoknál)
  5. Aláírás-ellenőrzés (csak a NeboAI által terjesztett alkalmazásoknál, fejlesztői módban kimarad)
  6. Bináris ellenőrzése (elutasítja a szimbolikus linkeket, szkripteket, nem futtatható és túlméretes fájlokat)
  7. Eltávolítja az előző futásból maradt elavult socketet
  8. Létrehozza a data/ könyvtárat a homokozós tárhelyhez
  9. Beállítja az alkalmazásonkénti naplófájlokat (logs/stdout.log, logs/stderr.log)
  10. Elindítja a binárist megtisztított környezettel és folyamatcsoport-elszigeteléssel
  11. Megvárja, hogy megjelenjen a Unix-socket (exponenciális visszalépés, legfeljebb 10 másodperc)
  12. gRPC-vel csatlakozik a Unix-socketen keresztül
  13. A provides alapján képességspecifikus gRPC-klienseket hoz létre
  14. Állapotellenőrzést futtat
  15. Regisztrálja a képességeket az MI-munkatársnál (eszközök, átjáró, comm stb.)

Eszközalkalmazások

Deklarálja a "provides": ["tool:my_tool_name"] értéket a manifestben.

A STRAP minta

Minden Nebo-eszközalkalmazásnak a sémájához és a végrehajtás útválasztásához kötelező a STRAP (Single Tool Resource Action Pattern) mintát használnia. Ugyanezt a mintát használja a Nebo belsőleg is, hogy több mint 35 különálló eszközt 4 tartományi eszközbe vonjon össze — ez kb. 80%-kal csökkenti az LLM kontextusterhelését.

Alapötlet: Több eszköz regisztrálása helyett (get_events, check_availability, suggest_slots) regisztráljon EGY eszközt action (és opcionálisan resource) mezőkkel, amelyek a megfelelő kezelőhöz irányítanak.

Egyerőforrásos példa (naptár):

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")

Többerőforrásos példa (projektkezelő):

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")

Sémaszabályok:

  1. Mindig legyen egy action mező kötelező string enumként
  2. Csak akkor adjon hozzá resource mezőt (kötelező string enum), ha az eszköze több különböző erőforrástípust kezel
  3. Minden más mező műveletspecifikus paraméter
  4. Az action enum leírásában szerepeljen az összes elérhető művelet

Miért fontos a STRAP:

  • Az LLM-ek egyszer megtanulják az action útválasztási mintát, és minden műveletre általánosítják
  • Az eszközdefiníciók a kontextus kb. 6%-át foglalják el — a STRAP ezt 80%-kal csökkenti
  • Az új műveletek csak enum-bővítések, nem új eszközregisztrációk
  • Hosztolt és helyi modelleken egyformán működik

Go-példa — Számológép eszköz

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": []
}

Építés és telepítés:

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/

Rust-példa

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(())
}

C-példa

#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;
}

Csatornaalkalmazások

Deklarálja a "provides": ["channel:my_channel"] és a "permissions": ["channel:send"] értéket.

A csatornaalkalmazások külső üzenetküldő platformokat (Telegram, Discord, Slack stb.) kötnek össze a Nebo MI-munkatársával. Amikor egy felhasználó üzenetet küld a külső platformon, az alkalmazása a Receive segítségével továbbítja azt a Nebónak. Amikor az MI-munkatárs válaszolni szeretne, a Nebo meghívja az alkalmazása Send metódusát.

Hogyan működik

  1. A Nebo meghívja az ID() függvényt, hogy megkapja a csatornája egyedi azonosítóját
  2. A Nebo meghívja a Connect() függvényt az alkalmazása beállításaiból származó konfigurációval
  3. A Nebo megnyit egy Receive() streamet — az alkalmazása elküldi a bejövő üzeneteket, valahányszor egy felhasználó üzenetet ír a botnak
  4. A bejövő üzenetek az MI-munkatárs fő beszélgetési sávjába kerülnek
  5. Amikor az MI-munkatárs üzenetet szeretne küldeni, a Nebo meghívja a Send() függvényt a v1 üzenetborítékkal
  6. Leállításkor a Nebo meghívja a Disconnect() függvényt

v1 üzenetboríték

Minden csatornaüzenet — bejövő és kimenő egyaránt — a közös üzenetborítékot használja:

{
  "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"
}
MezőTípusLeírás
message_idUUID v7Időrendezett egyedi azonosító
channel_id{type}:{platform_id}Útválasztható csatornaazonosító
senderobjectBot-identitás — név, szerepkör, botId
textstringÜzenettörzs
attachmentsarrayFájlok, képek, hang
reply_toUUID v7A szülőüzenet azonosítója a szálkezeléshez
actionsarrayInteraktív gombok/billentyűzetek
platform_databytesÁtlátszatlan továbbítás platformspecifikus funkciókhoz
timestampISO 8601A közzétevő állítja be

Kétrétegű felépítés: A közös mezők (text, attachments, reply_to, actions) a munkatársak által kezdeményezett üzenetküldés 90%-át lefedik. A platformspecifikus funkciók a platform_data mezőbe kerülnek — a bővítménye ezeket képezi le a natív platformformátumra és vissza.

Beszélgetési streamek

A csatornaüzenetek az elszigetelés érdekében csatornánkénti beszélgetési streameken haladnak:

neboai/bot/{botID}/channels/{channelType}/inbound    # messages from users → agent
neboai/bot/{botID}/channels/{channelType}/outbound   # messages from agent → channel

Go-példa — Telegram-csatorna

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
        }
    ]
}

További képességek

Comm alkalmazás

Deklarálja a "provides": ["comm"] és a "permissions": ["comm:*"] értéket. A comm alkalmazások lehetővé teszik az MI-munkatársak közötti kommunikációt.

MezőLeírás
fromA küldő munkatárs azonosítója
toA címzett munkatárs azonosítója
topicÜzenet témája/csatornája
type"message", "mention", "proposal", "command", "info", "task"
contentÜzenettörzs

Fő viselkedések:

  • A Register bejelenti ezt az MI-munkatársat a hálózaton a képességeivel együtt
  • A Subscribe/Unsubscribe kezeli a témákra való feliratkozásokat
  • A Receive streameli a bejövő üzeneteket (szerveroldali streamelés, ugyanúgy, mint a csatornáknál)
  • Egyszerre csak egy comm alkalmazás lehet aktív

Átjáróalkalmazás

Az átjáróalkalmazás az LLM-kéréseket modellekhez irányítja. Deklarálja a "provides": ["gateway"] és a "permissions": ["network:outbound", "user:token"] értéket.

A GatewayRequest tartalmazza az üzeneteket, az eszközöket, a rendszerpromptot, a maximális tokenszámot, a hőmérsékletet és egy UserContext objektumot (JWT-tokent, ha a user:token engedély meg van adva).

GatewayEvent típusok:

TípusTartalomLeírás
"text"SzövegrészletStreamelt szövegtoken
"tool_call"JSONA modell eszközt szeretne hívni
"thinking"SzövegrészletKiterjesztett gondolkodás/érvelés
"error"HibaüzenetValami hiba történt
"done"ÜresA stream befejeződött

UI-alkalmazás

A UI-alkalmazás egyedi konfigurációs felületet biztosít, amely a Nebo beépített böngészőablakában nyílik meg. Deklarálja a "provides": ["ui"] értéket. Az automatikus beállítási űrlappal ellentétben (amelyet a Nebo a settings manifestből jelenít meg) a UI-alkalmazás saját, teljes HTML/CSS/JS frontendet szolgál ki.

Az alkalmazása egy ui/ könyvtárat tartalmaz statikus webes erőforrásokkal (HTML, CSS, JS — jellemzően egy SPA index.html fájllal). A Nebo közvetlenül kiszolgálja ezeket a fájlokat, az API-hívásokat pedig gRPC-n keresztül továbbítja az alkalmazásnak.

Elérési útMechanizmusCél
GET /api/v1/apps/{id}/ui/*Statikus fájlszerverKiszolgálja a fájlokat az ui/ könyvtárból (SPA-tartalék: index.html)
ANY /api/v1/apps/{id}/api/*gRPC-proxyA HTTP-kéréseket az alkalmazása UIService.HandleRequest() metódusához továbbítja

Az SDK egy szabványos net/http.ServeMux köré épül, így hagyományos Go HTTP-kezelőket írhat — a gRPC-áthidalást az SDK automatikusan elvégzi.

Go-példa — Irányítópult felület:

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())
}

Az ui/index.html fetch-hívásokat indít a /api/v1/apps/com.example.dashboard/api/status címre, amelyek a mux kezelőjéhez kerülnek továbbításra.

Ütemezőalkalmazás

Az ütemezőalkalmazás a Nebo beépített cron-ütemezőjét váltja le. Deklarálja a "provides": ["schedule"] és a "permissions": ["schedule:create"] értéket.

Amikor az ütemezőalkalmazása elindul, a Nebo minden ütemezést az alapértelmezett cron-motor helyett az Ön alkalmazásán keresztül irányít. Ha az alkalmazása összeomlik, a Nebo automatikusan visszaáll a beépített motorra.

  • Az alkalmazása birtokolja az ütemezések állapotát — amíg egy ütemezőalkalmazás aktív, a Nebo nem tárol ütemezéseket a saját adatbázisában
  • Szabványos CRUD: Create, Get, List, Update, Delete, Enable, Disable
  • A Triggers szerveroldali streamelő RPC — az alkalmazása indítóüzenetet küld, valahányszor egy ütemezés aktiválódik
  • Egyszerre csak egy ütemezőalkalmazás lehet aktív

Több képességű alkalmazások

Egy alkalmazás több képességet is biztosíthat. Például egy irányítópult-alkalmazás eszközzel és felhasználói felülettel is:

{
    "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())

Csomagolás

.napp formátum

A NeboAI-on keresztüli terjesztéshez csomagolja az alkalmazását .napp fájlba (tar.gz archívum):

cd com.example.myapp/
tar -czf myapp-1.0.0.napp manifest.json binary signatures.json TOOL.md

Kötelező fájlok:

FájlMax. méretLeírás
manifest.json1 MBAz alkalmazás metaadatai
binary vagy app500 MBFuttatható fájl
signatures.json1 MBEd25519-aláírások
TOOL.md1 MBEszközutasítások az MI-munkatárs számára

Biztonsági szabályok kicsomagoláskor:

  • Nincs könyvtárbejárás (a ../ elutasítva)
  • Nincsenek szimbolikus linkek (elutasítva)
  • Nincsenek abszolút elérési utak (elutasítva)
  • Csak engedélyezőlistán szereplő fájlnevek fogadhatók el

Aláírások

A NeboAI Ed25519-cel írja alá az alkalmazásokat. A signatures.json formátuma:

{
    "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>"
}

Fejlesztői módban (ha nincs NeboAI URL konfigurálva) az aláírás-ellenőrzés teljesen kimarad. Helyi fejlesztéshez nincs szüksége signatures.json fájlra.

Közzététel

Ha az alkalmazása helyben működik, tegye közzé a NeboAI-on keresztül, hogy minden Nebo-felhasználóhoz eljusson.

Fejlesztői fiók beállítása

  1. Regisztráljon NeboAI-fiókot itt: POST /api/v1/owners/register
  2. Jelentkezzen be, hogy JWT-tokent kapjon: POST /api/v1/owners/login
  3. Hozzon létre fejlesztői fiókot: POST /api/v1/developer/accounts

A beküldés folyamata

draft → pending_review → [approved] → published
                       → [rejected] → draft (fix and resubmit)

1. lépés: Az alkalmazás létrehozása

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"
  }'

2. lépés: A platformbinárisok feltöltése

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"

Platformonként egy binárist töltsön fel: darwin-arm64, darwin-amd64, linux-amd64, linux-arm64.

3. lépés: Beküldés ellenőrzésre

curl -X POST https://neboai.com/api/v1/developer/apps/{id}/submit \
  -H "Authorization: Bearer $TOKEN"

Az ellenőrzés folyamata

  1. Automatikus vizsgálat — a binárisokat a VirusTotal vizsgálja át
  2. Adminisztrátori ellenőrzés — a NeboAI csapata átnézi a metaadatokat, a manifestet és a vizsgálati eredményeket
  3. Jóváhagyáskor — a NeboAI Ed25519-cel aláírja és közzéteszi az alkalmazást
  4. Elutasításkor — megkapja az indoklást, és javítás után újra beküldheti

Az ellenőrzés célzott ideje: <24 óra.

Frissítések kiadása

  1. Frissítse az alkalmazás verzióját: PUT /api/v1/developer/apps/{id} az új verzióval
  2. Töltsön fel új binárisokat minden platformra
  3. Küldje be újra ellenőrzésre

Minden frissítés ugyanazon az ellenőrzési folyamaton megy át. A korábbi verziók az új verzió jóváhagyásáig elérhetők maradnak.

Bolti metaadatok

MezőLeírás
categorypl. productivity, communication, developer-tools
iconAz alkalmazásikon URL-je
visibilitypublic vagy private
descriptionLehet hosszabb és gazdagabb, mint a manifestben szereplő leírás

Fejlesztői munkafolyamat

Helyi fejlesztés

Helyi fejlesztéshez nincs szükség csomagolásra:

  1. Hozza létre az alkalmazás könyvtárát:
    mkdir -p ~/Library/Application\ Support/Nebo/apps/com.example.myapp
  2. Írja meg a manifest.json fájlt és a kódot
  3. Fordítsa le a binárisát:
    go build -o ~/Library/Application\ Support/Nebo/apps/com.example.myapp/binary .
  4. A Nebo automatikusan észleli az új könyvtárat (vagy indítsa újra a Nebót)
  5. Kódmódosítás után építse újra a binárist — a fájlfigyelő újraindítja az alkalmazást

Naplók megtekintése

Az alkalmazás stdout/stderr kimenete alkalmazásonkénti naplófájlokba kerül:

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

Tartós adatok

Használja a data/ könyvtárat (a NEBO_APP_DATA környezeti változóként is elérhető) minden olyan fájlhoz, amelyet az alkalmazásának meg kell őriznie. Ez a könyvtár túléli az alkalmazásfrissítéseket és a karantént.

Hibakeresési tippek

  • Ha az alkalmazása nem indul el, keresse a hibákat a logs/stderr.log fájlban
  • Győződjön meg róla, hogy a bináris futtatható (chmod +x binary)
  • Győződjön meg róla, hogy a NEBO_APP_SOCK szerinti Unix-socket elérési úton figyel
  • A socketnek az indítástól számított 10 másodpercen belül készen kell állnia
  • Tároláshoz a NEBO_APP_DATA változót használja, ne beégetett elérési utakat
  • A hibakeresési naplózáshoz írjon az stderr-re (a logs/stderr.log fájlba kerül)

Ellenőrzés

# 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

Eltávolítás

nebo apps uninstall com.example.myapp

Készségek

Mik a készségek

A készségek olyan utasításkészletek, amelyek meghatározzák, hogyan viselkedik a Nebo egy beszélgetés során. Amikor egy készség aktív, a tartalma közvetlenül a rendszerpromptba kerül — és az adott munkamenetre irányítja az MI-munkatárs hangnemét, módszertanát, szakterületi tudását és eszközhasználatát.

A készségek nem kódok. YAML-metaadatokkal ellátott markdown-dokumentumok. Nincs fordítás, nincs bináris, nincs gRPC. A készség egy SKILL.md fájl egy könyvtárban. Ennyi.

A készségek kontextusfüggők és ideiglenesek. Akkor aktiválódnak, amikor relevánsak (indítóegyezés vagy kézi betöltés révén), néhány körig megmaradnak, és lejárnak, amikor már nincs rájuk szükség. Így az MI-munkatárs kontextusa karcsú marad — csak az az útmutatás van a promptban, amely éppen most számít.

A készségek kiegészítik az alkalmazásokat. Az alkalmazások futtatható képességeket adnak (eszközöket, csatornákat, átjárókat). A készségek összehangolási útmutatást adnak — hogyan lehet ezeket az eszközöket hatékonyan használni. Egy naptáralkalmazás lehetővé teszi, hogy a Nebo eseményeket olvasson és írjon. Egy „megbeszélésre készülés” készség megmondja a Nebónak, hogyan készüljön fel a megbeszélésekre a naptáralkalmazás, az e-mail és a webes keresés együttes használatával.

Készségek és alkalmazások

KészségekAlkalmazások
FormátumMarkdown (SKILL.md)Lefordított bináris (.napp)
FuttatásA rendszerpromptba injektálvaHomokozóban futó folyamat gRPC-n keresztül
Mit biztosítViselkedési útmutatás, módszertanEszközök, csatornák, felhasználói felületi panelek
ÉlettartamMunkamenethez kötött, TTL-alapú lejáratMindig fut
LétrehozásEgy markdown-fájl megírásaMegírás, fordítás, aláírás, csomagolás
BiztonságNincs szükség engedélyekreAlapértelmezetten tiltó homokozó

Gyors kezdés

Hozzon létre egy könyvtárat a Nebo-készségek mappájában egy SKILL.md fájllal:

~/Library/Application Support/Nebo/skills/   # macOS
~/.config/nebo/skills/                        # Linux
%AppData%\Nebo\skills\                        # Windows
mkdir -p ~/.config/nebo/skills/my-skill

Írjon egy SKILL.md fájlt:

---
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.

A Nebo az fsnotify segítségével figyeli a készségek könyvtárát. A készsége azonnal elérhető — nincs szükség újraindításra. Mondjon valamit, ami egy indítóra illeszkedik, és automatikusan aktiválódik.

Vagy kérje meg közvetlenül a Nebót: „Hozz létre egy készséget blogbejegyzések írásához” — a Nebo megírja Önnek a SKILL.md fájlt.

A SKILL.md formátuma

Minden készség egyetlen SKILL.md fájl, két résszel: a --- jelölők közötti YAML-fejléccel és egy markdown-törzzsel (a rendszerpromptba injektált tényleges utasításokkal).

MezőKötelezőAlapértelmezésLeírás
nameIgen—Egyedi azonosító (ebből lesz a slug)
descriptionIgen—Egysoros leírás, amely a készségkatalógusban jelenik meg
versionNem"1.0.0"Semver a frissítések követéséhez
authorNem—A készség szerzője
priorityNem0Magasabb = előbb illeszkedik (100+ a kritikus felülírásokhoz)
max_turnsNem4Inaktív körök száma az automatikus lejáratig
triggersNem[]Kifejezések, amelyek automatikusan aktiválják ezt a készséget (kis- és nagybetűtől független részkarakterlánc-egyezés)
toolsNem[]Eszközök, amelyeket ez a készség várhatóan használ (tájékoztató jellegű)
dependenciesNem[]Más készségek, amelyeknek telepítve kell lenniük
tagsNem[]Kategorizáláshoz és felfedezéshez
platformNem[]Támogatott platformok: macos, linux, windows (üres = mind)

Hogyan aktiválódnak a készségek

A készségek kétfázisú aktiválási modellt követnek: előbb jelzés, aztán meghívás.

1. fázis: Indítóegyezés — Valahányszor a felhasználó üzenetet küld, a Nebo minden regisztrált készséget átvizsgál indítóegyezések után. Az illeszkedő készségek jelzésként jelennek meg a rendszerpromptban. Az MI-munkatárs látja a jelzést, és eldönti, meghívja-e a készséget.

2. fázis: Meghívás — Az MI-munkatárs így hív meg egy készséget:

skill(name: "code-review")

Ez eszközeredményként visszaadja a teljes SKILL.md sablont, rögzíti a meghívást, és a következő körökben újra beilleszti a sablont a rendszerpromptba.

TTL és lejárat:

  • Automatikusan illeszkedő készségek: 4 inaktív kör (a max_turns mezővel állítható)
  • Kézzel betöltött készségek: 6 inaktív kör
  • Az újbóli meghívás nullázza az időzítőt
  • Szigorú felső határ: munkamenetenként legfeljebb 4 aktív készség
  • Tokenkeret: az aktív készségek együttes tartalma legfeljebb 16 000 karakter

Készségek kezelése

Az MI-munkatárs a skill eszközzel kezelheti a készségeket:

MűveletLeírásPélda
catalogAz összes elérhető készség listázásaskill(action: "catalog")
loadAktiválás erre a munkamenetreskill(name: "code-review", action: "load")
unloadKészség deaktiválásaskill(name: "code-review", action: "unload")
createÚj készség létrehozása a lemezenskill(action: "create", content: "...")
updateMeglévő készség frissítéseskill(name: "my-skill", action: "update", content: "...")
deleteKészség törlése a lemezrőlskill(name: "my-skill", action: "delete")

Jó készségek írása

Egy jó készségsablonban ezek vannak:

  1. Egyértelmű címsor — megmondja az MI-munkatársnak, milyen üzemmódban van
  2. Alapelvek — a nem alku tárgyát képező viselkedési szabályok
  3. Módszertan — lépésről lépésre haladó megközelítés a gyakori helyzetekre
  4. Példák — konkrét felhasználói üzenet–válasz minták
  5. Ellenpéldák — mit NE tegyen (a modellek jól tanulnak a negatív példákból)

Tipp: Minden készség egy dolgot csináljon jól. Ne hozzon létre „általános programozás” készséget — hozza létre a code-review, a debugging és az api-design készséget külön-külön. Az MI-munkatársnak egyszerre több is lehet aktív.

Beépített készségek

A Nebo beépített készségekkel érkezik a gyakori felhasználási esetekre:

KészségPrioritásLeírás
onboarding100Új felhasználó üdvözlése és profiladatok gyűjtése
best-friend50Személyiségkészség — laza, hűséges, őszinte beszéd
debugging25Rendszerezett hibakeresési módszertan
api-design15A RESTful API-tervezés bevált gyakorlatai
code-review10Strukturált kódellenőrzés súlyossági szintekkel
database-expert10Adatbázis-tervezés, lekérdezések, optimalizálás
git-workflow10Git-elágaztatás, commitok, PR-munkafolyamatok
security-audit10Biztonsági elemzés és sebezhetőségek felderítése

Ezek egyszerre hasznos alapértelmezések és referencia-megvalósítások a saját készségei létrehozásához.

Referencia

Proto-fájlok

A proto-fájlok a proto/apps/v0/ helyen találhatók. Az SDK-k előre generált kóddal érkeznek, így a szokásos fejlesztéshez nincs szüksége protocra.

FájlSzolgáltatásFő RPC-k
v0/common.proto(csak üzenetek)HealthCheckRequest/Response, SettingsMap, UserContext, Empty
v0/tool.protoToolServiceName, Description, Schema, Execute, RequiresApproval, Configure
v0/channel.protoChannelServiceID, Connect, Disconnect, Send, Receive (stream), Configure
v0/comm.protoCommServiceName, Version, Connect, Disconnect, Send, Subscribe, Register, Receive (stream), Configure
v0/gateway.protoGatewayServiceHealthCheck, Stream (stream), Poll, Cancel, Configure
v0/ui.protoUIServiceHealthCheck, HandleRequest, Configure
v0/schedule.protoScheduleServiceHealthCheck, Create, Get, List, Update, Delete, Enable, Disable, Trigger, History, Triggers (stream), Configure

Minden szolgáltatás tartalmazza a HealthCheck és a Configure RPC-t. Az SDK mindkettőt automatikusan kezeli.

Csatorna proto-típusok

ÜzenettípusLeírás
ChannelSendRequestKimenő üzenetboríték message_id, channelId, sender, text, attachments, reply_to, actions, platform_data mezőkkel
ChannelSendResponsePlatformüzenet-azonosító a szálkezeléshez
InboundMessageBejövő üzenetboríték az összes közös mezővel + időbélyeggel
MessageSenderBot-identitás (name, role, botId) — a közvetítő egészíti ki
AttachmentFájl-, kép- vagy hangmelléklet (type, url, filename, size)
MessageActionInteraktív gomb- vagy billentyűzetművelet (label, callback_id)

Bot-identitás és szerepkörök

A Nebo botjai háromtengelyű identitásmodellel rendelkeznek:

  • creature — Mi a bot (archetípus): „Gyors észjárású stratéga”, „Aprólékos kutató”
  • role — Milyen viszonyban áll a felhasználóval (kapcsolat): „Barát”, „COO”, „Mentor”
  • vibe — Az energiája (kommunikációs stílus): „Laza, de határozott véleményű”, „Meleg és bátorító”

Amikor a csatornabővítménye kimenő üzenetet kap, a sender mező tartalmazza a bot name és role értékét. Ezzel formázza meg a megjelenített nevet a platformja számára. A szerepkör nem beosztás — hanem a kapcsolatot leíró jelző. A „Barát”, a „Fiú” és a „Mentor” ugyanúgy érvényes szerepkör, mint a „COO” és a „DevLead”.