NeboAI
NeboAI
Začať

Vytvárajte aplikácie pre Nebo

Dajte svojej AI nové superschopnosti. Nástroje, kanály, brány, panely UI — čokoľvek si predstavíte, skompilované do natívneho binárneho súboru.

Prehľad

Čo je Nebo

Nebo je osobný AI asistent pre počítač — neustále bežiaci AI zamestnanec, ktorý spravuje váš digitálny život. Predstavte si Nebo ako smartfón: výkonnú platformu, ktorá sa stáva prelomovou vďaka svojim aplikáciám.

Samotné Nebo je schopný AI zamestnanec s pamäťou, plánovaním, prehliadaním webu, správou súborov a prístupom k shellu. Skutočný prelom však prinášajú aplikácie. Tak ako sila smartfónu pochádza z jeho ekosystému aplikácií, sila Nebo pochádza z aplikácií, ktoré rozširujú jeho možnosti.

Čo sú aplikácie

Aplikácie Nebo sú samostatné, vopred skompilované jednotky neuveriteľnej funkčnosti. Každá aplikácia dáva Nebo novú superschopnosť — správu kalendára, triedenie e-mailov, sledovanie projektov, automatizáciu domácnosti, finančnú analýzu — čokoľvek si vývojár dokáže predstaviť.

Aplikácie poskytujú neuveriteľný výkon veľmi bezpečným spôsobom. Každá aplikácia beží v sandboxe s oprávneniami predvolene zakázanými. Má prístup len k tomu, čo deklaruje jej manifest a čo schváli používateľ.

Rozhranie je stopercentne konverzačné. Používatelia s aplikáciami nepracujú cez samostatné obrazovky ani dashboardy. Rozprávajú sa s Nebo a Nebo používa nástroje aplikácie, aby vybavilo veci. „Čo mám zajtra v kalendári?“ — Nebo zavolá aplikáciu kalendára. „Vytvor stretnutie so Sarah o 3 popoludní“ — Nebo zavolá aplikáciu kalendára. Používateľ nikdy neopustí konverzáciu.

Aplikácie môžu voliteľne poskytovať UI nastavení — konfiguračný panel, ktorý sa otvorí vo vstavanom okne prehliadača Nebo. Tu používatelia zadávajú kľúče API, zapínajú funkcie a konfigurujú aplikáciu. UI nastavení riadi pole settings v manifeste (Nebo vykreslí formulár automaticky), alebo aplikácia môže poskytnúť vlastné úplné UI prostredníctvom schopnosti ui.

Aplikácie nahrádzajú a rozširujú vstavané schopnosti Nebo. Nebo sa dodáva so základnými nástrojmi platformy (prístup k lokálnemu kalendáru, snímky obrazovky atď.). Keď nainštalujete aplikáciu kalendára, nahradí vstavaný nástroj kalendára a stane sa jeho nadmnožinou — lokálne + cloud + agregácia + kontrola dostupnosti.

Zásada len kompilovaného kódu

Nebo presadzuje prísnu zásadu len kompilovaných binárnych súborov. Všetky aplikácie musia byť natívne skompilované spustiteľné súbory.

StavJazyky
PodporovanéGo (odporúčané), Rust, C/C++, Zig
OdmietnutéPython, Node.js, Ruby, Java, .NET, shellové skripty

Zdôvodnenie:

  • Zabránenie samoúprave AI — AI zamestnanec s prístupom k shellu by mohol za behu zmeniť správanie interpretovaného skriptu. Skompilované binárne súbory sú po podpísaní nemenné.
  • Integrita podpisu — Podpisy Ed25519 pokrývajú surové bajty binárneho súboru. Podpísaný binárny súbor nemožno zmeniť bez toho, aby sa podpis stal neplatným.
  • Vynútenie sandboxu — Overenie formátu binárneho súboru (magické bajty ELF/Mach-O/PE) je rýchla a spoľahlivá brána.

Rýchly štart

Inštalácia SDK

Oficiálne SDK zvládnu celé nastavenie servera gRPC, spracovanie signálov aj premostenie protokolu. Vy len implementujete rozhrania handlerov.

Go (odporúčané):

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

Rust (čoskoro):

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

C/C++ (čoskoro):

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

Štruktúra adresára aplikácie

Aplikácie sa nachádzajú v podadresári apps/ vášho dátového adresára 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)

Kontrolný zoznam minimálnej aplikácie

  1. Vytvorte manifest.json s poľami id, name, version, provides
  2. Napíšte TOOL.md, ktorý opisuje, ako má AI zamestnanec váš nástroj používať
  3. Nainštalujte SDK (go get github.com/neboloop/nebo-sdk-go)
  4. Implementujte rozhranie handlera pre svoju schopnosť (ToolHandler, ChannelHandler atď.)
  5. Zaregistrujte handler a zavolajte app.Run()
  6. Zostavte natívny binárny súbor (go build -o binary .)
  7. Umiestnite binárny súbor + manifest.json + TOOL.md do adresára apps/<your-app-id>/
  8. Nebo ju automaticky nájde a spustí

Konfigurácia

manifest.json

Každá aplikácia vyžaduje 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
        }
    ]
}

Povinné polia:

PolePopis
idIdentifikátor v tvare obrátenej domény (napr. com.mycompany.myapp)
nameČitateľný názov
versionReťazec Semver
providesAspoň jedna schopnosť (pozri nižšie)

Voliteľné polia:

PolePredvolenéPopis
runtime"local""local" alebo "remote"
protocol"grpc"Podporované je len "grpc"
permissions[]K čomu aplikácia potrebuje prístup
description""Zobrazuje sa v UI
settings[]Konfigurovateľné nastavenia (vykreslené v UI nastavení)
oauth[]Požiadavky na poskytovateľa OAuth (pozri sekciu OAuth nižšie)

Schopnosti

Deklarujte, čo vaša aplikácia poskytuje:

SchopnosťSlužba gRPCPopis
gatewayGatewayServiceSmerovanie modelov LLM
tool:<name>ToolServicePomenovaný nástroj pre AI zamestnanca
channel:<name>ChannelServiceKanál na posielanie správ
commCommServiceKomunikácia medzi AI zamestnancami
uiUIServiceVlastné UI s HTTP proxy
scheduleScheduleServiceVlastné plánovanie
visionToolServiceSpracovanie obrazu
browserToolServiceAutomatizácia prehliadača

Aplikácia môže poskytovať viacero schopností. Napríklad aplikácia môže poskytovať nástroj aj panel UI.

Oprávnenia

Oprávnenia určujú, k čomu má aplikácia prístup. Predvolene zakázané — ak niečo nie je deklarované, aplikácia to nemôže použiť.

PredponaPríkladyPopis
network:network:outbound, network:*Prístup k sieti
filesystem:filesystem:read, filesystem:writePrístup k súborovému systému
memory:memory:read, memory:writePrístup k pamäti AI zamestnanca
session:session:readRelácie konverzácie
tool:tool:shell, tool:filePoužívanie iných nástrojov
shell:shell:execSpúšťanie príkazov shellu
channel:channel:send, channel:*Operácie s kanálmi
comm:comm:send, comm:*Komunikácia medzi AI zamestnancami
model:model:chatPrístup k modelom AI
user:user:tokenPrijímanie JWT používateľa v požiadavkách
schedule:schedule:createSpráva úloh cron
database:database:queryPrístup k databáze
storage:storage:read, storage:writeTrvalé úložisko
context:context:readPrístup ku kontextu AI zamestnanca
subagent:subagent:spawnOperácie so subagentmi
lane:lane:enqueueOperácie s pruhmi
notification:notification:sendPush upozornenia
embedding:embedding:searchPrístup k vektorovým embeddingom
skill:skill:invokeVyvolávanie zručností
advisor:advisor:consultPrístup k systému poradcov
mcp:mcp:connectPrístup k serveru MCP
voice:voice:recordPrístup k hlasu/zvuku
browser:browser:navigateAutomatizácia prehliadača
oauth:oauth:google, oauth:*Prístup k tokenom OAuth
settings:settings:readPrístup k nastaveniam
capability:capability:registerRegistrácia schopností

Podporované sú oprávnenia so zástupnými znakmi: network:* zodpovedá akejkoľvek kontrole oprávnenia network:.

Nastavenia

Nastavenia sa zobrazujú v UI Nebo v paneli nastavení aplikácie. Nebo ich ukladá do databázy a pri zmene ich posiela vašej aplikácii cez RPC Configure.

Vaša schéma nastavení je súčasťou zápisu v obchode aplikácií NeboAI. Aplikácie s nenakonfigurovanými povinnými nastaveniami zobrazujú v UI odznak „Treba nastaviť“.

TypPopis
textJednoriadkové textové pole
passwordMaskované textové pole
toggleLogický prepínač zap./vyp.
selectRozbaľovací zoznam s preddefinovanými možnosťami
numberČíselné pole
urlPole URL s overením
{
    "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"}
    ]
}

Požiadavky OAuth

Aplikácie môžu deklarovať požiadavky na poskytovateľa OAuth. Sprostredkovateľ OAuth v Nebo zvládne celý tok — aplikácie dostávajú tokeny automaticky cez RPC Configure.

{
    "oauth": [
        {
            "provider": "google",
            "scopes": ["https://www.googleapis.com/auth/calendar"]
        }
    ]
}
PolePopis
providerPoskytovateľ OAuth: "google", "microsoft", "github"
scopesPole rozsahov OAuth, ktoré aplikácia potrebuje

Keď používateľ aplikáciu nainštaluje, Nebo ho vyzve, aby autorizoval požadované rozsahy OAuth. Aplikácia dostáva obnovené tokeny cez RPC Configure bez toho, aby sama riešila tok OAuth.

Premenné prostredia

Proces vašej aplikácie dostane očistené prostredie. Všetky tajné údaje sú odstránené. Dostanete:

PremennáHodnota
NEBO_APP_DIRInštalačný adresár aplikácie
NEBO_APP_SOCKCesta k soketu Unix, ktorý treba vytvoriť
NEBO_APP_IDID aplikácie z manifestu
NEBO_APP_NAMENázov aplikácie z manifestu
NEBO_APP_VERSIONVerzia aplikácie z manifestu
NEBO_APP_DATACesta k adresáru data/ aplikácie
PATHSystémová PATH (prenesená)
HOMEDomovský adresár používateľa (prenesený)
TMPDIRDočasný adresár (prenesený)

Dôležité: Váš binárny súbor musí vytvoriť server gRPC, ktorý počúva na sokete Unix v NEBO_APP_SOCK. Nebo čaká na objavenie tohto soketu až 10 sekúnd.

Postup spustenia aplikácie

  1. Nebo prečíta manifest.json a overí ho
  2. Nájde spustiteľný súbor binary alebo app v adresári aplikácie
  3. Skontroluje značku .quarantined (aplikácie v karanténe odmietne spustiť)
  4. Kontrola odvolania (len aplikácie distribuované cez NeboAI)
  5. Overenie podpisu (len aplikácie distribuované cez NeboAI, vo vývoji sa preskakuje)
  6. Overenie binárneho súboru (odmietne symbolické odkazy, skripty, nespustiteľné a príliš veľké súbory)
  7. Vyčistí zastaraný soket z predchádzajúceho behu
  8. Vytvorí adresár data/ pre úložisko v sandboxe
  9. Nastaví súbory protokolov pre každú aplikáciu (logs/stdout.log, logs/stderr.log)
  10. Spustí binárny súbor s očisteným prostredím a izoláciou skupiny procesov
  11. Čaká na objavenie soketu Unix (exponenciálne odďaľovanie, najviac 10 sekúnd)
  12. Pripojí sa cez gRPC na sokete Unix
  13. Vytvorí klientov gRPC pre konkrétne schopnosti podľa provides
  14. Spustí kontrolu stavu
  15. Zaregistruje schopnosti u AI zamestnanca (nástroje, brána, komunikácia atď.)

Nástrojové aplikácie

Deklarujte v manifeste "provides": ["tool:my_tool_name"].

Vzor STRAP

Všetky nástrojové aplikácie Nebo musia pre svoju schému a smerovanie vykonávania používať STRAP (Single Tool Resource Action Pattern). Je to ten istý vzor, ktorý Nebo interne používa na zlúčenie 35+ samostatných nástrojov do 4 doménových nástrojov — čím znižuje réžiu kontextu LLM približne o 80 %.

Hlavná myšlienka: Namiesto registrácie viacerých nástrojov (get_events, check_availability, suggest_slots) zaregistrujte JEDEN nástroj s poľami action (a voliteľne resource), ktoré smerujú k správnemu handleru.

Príklad s jedným zdrojom (kalendá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")

Príklad s viacerými zdrojmi (projektový manažér):

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

Pravidlá schémy:

  1. Vždy zahrňte pole action ako povinný reťazcový enum
  2. Pole resource (povinný reťazcový enum) pridajte len vtedy, ak váš nástroj spravuje viacero odlišných typov zdrojov
  3. Všetky ostatné polia sú parametre špecifické pre akciu
  4. Popis enumu action by mal uvádzať všetky dostupné akcie

Prečo na STRAP záleží:

  • LLM sa vzor smerovania action naučia raz a zovšeobecnia ho na všetky operácie
  • Definície nástrojov zaberajú ~6 % kontextu — STRAP to zníži o 80 %
  • Nové operácie sú len pridané hodnoty enumu, nie nové registrácie nástrojov
  • Funguje rovnako pri hostovaných aj lokálnych modeloch

Príklad v Go — nástroj Kalkulačka

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

Zostavenie a inštalácia:

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/

Príklad v Ruste

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

Príklad v 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;
}

Kanálové aplikácie

Deklarujte "provides": ["channel:my_channel"] a "permissions": ["channel:send"].

Kanálové aplikácie premosťujú externé komunikačné platformy (Telegram, Discord, Slack atď.) s AI zamestnancom Nebo. Keď používateľ pošle správu na externej platforme, vaša aplikácia ju streamuje do Nebo cez Receive. Keď chce AI zamestnanec odpovedať, Nebo zavolá Send vašej aplikácie.

Ako to funguje

  1. Nebo zavolá ID() a získa jedinečný identifikátor vášho kanála
  2. Nebo zavolá Connect() s konfiguráciou z nastavení vašej aplikácie
  3. Nebo otvorí stream Receive() — vaša aplikácia posiela prichádzajúce správy vždy, keď používateľ napíše botovi
  4. Prichádzajúce správy sa smerujú do hlavného konverzačného pruhu AI zamestnanca
  5. Keď chce AI zamestnanec poslať správu, Nebo zavolá Send() s obálkou správy v1
  6. Pri vypínaní Nebo zavolá Disconnect()

Obálka správy v1

Všetky správy kanála — prichádzajúce aj odchádzajúce — používajú spoločnú obálku správy:

{
  "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"
}
PoleTypPopis
message_idUUID v7Jedinečné ID zoradené podľa času
channel_id{type}:{platform_id}Smerovateľný identifikátor kanála
senderobjectIdentita bota — meno, rola, botId
textstringTelo správy
attachmentsarraySúbory, obrázky, zvuk
reply_toUUID v7ID nadradenej správy pre vlákna
actionsarrayInteraktívne tlačidlá/klávesnice
platform_databytesNepriehľadný prenos pre funkcie špecifické pre platformu
timestampISO 8601Nastavuje vydavateľ

Dvojvrstvový návrh: Spoločné polia (text, prílohy, reply_to, akcie) pokrývajú 90 % správ iniciovaných zamestnancom. Funkcie špecifické pre platformu patria do platform_data — váš doplnok ich mapuje z natívneho formátu platformy a doň.

Konverzačné streamy

Správy kanála sa kvôli izolácii smerujú cez samostatné konverzačné streamy pre každý kanál:

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

Príklad v Go — kanál 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
        }
    ]
}

Ďalšie schopnosti

Komunikačná aplikácia

Deklarujte "provides": ["comm"] a "permissions": ["comm:*"]. Komunikačné aplikácie umožňujú komunikáciu medzi AI zamestnancami.

PolePopis
fromID odosielajúceho zamestnanca
toID prijímajúceho zamestnanca
topicTéma/kanál správy
type"message", "mention", "proposal", "command", "info", "task"
contentTelo správy

Kľúčové správanie:

  • Register ohlási tohto AI zamestnanca v sieti spolu s jeho schopnosťami
  • Subscribe/Unsubscribe spravujú odbery tém
  • Receive streamuje prichádzajúce správy (streamovanie zo servera, rovnako ako pri kanáloch)
  • Naraz môže byť aktívna len jedna komunikačná aplikácia

Aplikácia brány

Aplikácia brány smeruje požiadavky LLM k modelom. Deklarujte "provides": ["gateway"] a "permissions": ["network:outbound", "user:token"].

GatewayRequest obsahuje správy, nástroje, systémový prompt, maximum tokenov, teplotu a UserContext (token JWT, ak je udelené oprávnenie user:token).

Typy GatewayEvent:

TypObsahPopis
"text"Časť textuStreamovaný textový token
"tool_call"JSONModel chce zavolať nástroj
"thinking"Časť textuRozšírené premýšľanie/uvažovanie
"error"Chybová správaNiečo sa pokazilo
"done"PrázdneStream je dokončený

Aplikácia UI

Aplikácia UI poskytuje vlastné konfiguračné rozhranie, ktoré sa otvorí vo vstavanom okne prehliadača Nebo. Deklarujte "provides": ["ui"]. Na rozdiel od automatického formulára nastavení (ktorý Nebo vykreslí z vášho manifestu settings) aplikácia UI poskytuje vlastný úplný frontend v HTML/CSS/JS.

Vaša aplikácia obsahuje adresár ui/ so statickými webovými súbormi (HTML, CSS, JS — zvyčajne SPA s index.html). Nebo tieto súbory poskytuje priamo a volania API presmerúva do vašej aplikácie cez gRPC.

CestaMechanizmusÚčel
GET /api/v1/apps/{id}/ui/*Server statických súborovPoskytuje súbory z vášho adresára ui/ (záložné presmerovanie SPA na index.html)
ANY /api/v1/apps/{id}/api/*Proxy gRPCPresmerúva požiadavky HTTP na UIService.HandleRequest() vašej aplikácie

SDK obaľuje štandardný net/http.ServeMux, takže píšete bežné handlery HTTP v Go — premostenie gRPC SDK vyrieši automaticky.

Príklad v Go — UI dashboardu:

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

Váš ui/index.html by volal fetch na /api/v1/apps/com.example.dashboard/api/status, čo sa presmeruje do vášho handlera mux.

Plánovacia aplikácia

Plánovacia aplikácia nahrádza vstavaný plánovač cron v Nebo. Deklarujte "provides": ["schedule"] a "permissions": ["schedule:create"].

Keď sa vaša plánovacia aplikácia spustí, Nebo smeruje všetko plánovanie cez vašu aplikáciu namiesto predvoleného enginu cron. Ak vaša aplikácia spadne, Nebo sa automaticky vráti k vstavanému enginu.

  • Vaša aplikácia vlastní stav plánov — keď je aktívna plánovacia aplikácia, Nebo neukladá plány do vlastnej DB
  • Štandardné CRUD: Create, Get, List, Update, Delete, Enable, Disable
  • Triggers je RPC so streamovaním zo servera — vaša aplikácia pošle správu spúšťača vždy, keď sa plán spustí
  • Naraz môže byť aktívna len jedna plánovacia aplikácia

Aplikácie s viacerými schopnosťami

Aplikácia môže poskytovať viacero schopností. Napríklad aplikácia dashboardu s nástrojom aj UI:

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

Balenie

Formát .napp

Na distribúciu cez NeboAI zabaľte svoju aplikáciu ako súbor .napp (archív tar.gz):

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

Povinné súbory:

SúborMax. veľkosťPopis
manifest.json1 MBMetadáta aplikácie
binary alebo app500 MBSpustiteľný súbor
signatures.json1 MBPodpisy Ed25519
TOOL.md1 MBPokyny k nástroju pre AI zamestnanca

Bezpečnostné pravidlá pri rozbaľovaní:

  • Žiadne prechádzanie ciest (../ sa odmietne)
  • Žiadne symbolické odkazy (odmietnuté)
  • Žiadne absolútne cesty (odmietnuté)
  • Prijímajú sa len povolené názvy súborov

Podpisy

NeboAI podpisuje aplikácie pomocou Ed25519. Formát 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>"
}

V režime vývoja (bez nakonfigurovanej URL NeboAI) sa overenie podpisu úplne preskakuje. Na lokálny vývoj signatures.json nepotrebujete.

Publikovanie

Keď vaša aplikácia funguje lokálne, publikujte ju cez NeboAI na distribúciu všetkým používateľom Nebo.

Nastavenie účtu vývojára

  1. Zaregistrujte si účet NeboAI na POST /api/v1/owners/register
  2. Prihláste sa a získajte token JWT: POST /api/v1/owners/login
  3. Vytvorte účet vývojára: POST /api/v1/developer/accounts

Postup odoslania

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

Krok 1: Vytvorte aplikáciu

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

Krok 2: Nahrajte binárne súbory pre platformy

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"

Nahrajte jeden binárny súbor pre každú platformu: darwin-arm64, darwin-amd64, linux-amd64, linux-arm64.

Krok 3: Odošlite na kontrolu

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

Proces kontroly

  1. Automatická kontrola — binárne súbory sa skenujú cez VirusTotal
  2. Kontrola administrátorom — tím NeboAI skontroluje metadáta, manifest a výsledky skenovania
  3. Po schválení — NeboAI podpíše aplikáciu pomocou Ed25519 a publikuje ju
  4. Po zamietnutí — dostanete dôvod a môžete to opraviť a odoslať znova

Cieľový čas kontroly: <24 hodín.

Vydávanie aktualizácií

  1. Aktualizujte verziu aplikácie: PUT /api/v1/developer/apps/{id} s novou verziou
  2. Nahrajte nové binárne súbory pre každú platformu
  3. Znova odošlite na kontrolu

Každá aktualizácia prechádza rovnakým procesom kontroly. Predchádzajúce verzie zostávajú dostupné, kým nová verzia nie je schválená.

Metadáta v obchode

PolePopis
categorynapr. produktivita, komunikácia, nástroje pre vývojárov
iconURL ikony aplikácie
visibilitypublic alebo private
descriptionMôže byť dlhší/bohatší ako popis v manifeste

Vývojový postup

Lokálny vývoj

Na lokálny vývoj netreba nič baliť:

  1. Vytvorte adresár aplikácie:
    mkdir -p ~/Library/Application\ Support/Nebo/apps/com.example.myapp
  2. Napíšte manifest.json a kód
  3. Zostavte binárny súbor:
    go build -o ~/Library/Application\ Support/Nebo/apps/com.example.myapp/binary .
  4. Nebo nový adresár automaticky rozpozná (alebo reštartujte Nebo)
  5. Po zmenách v kóde znova zostavte binárny súbor — sledovač súborov aplikáciu reštartuje

Zobrazenie protokolov

Stdout/stderr aplikácie sa zachytávajú do súborov protokolov pre každú aplikáciu:

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

Trvalé dáta

Na všetky súbory, ktoré musí vaša aplikácia uchovávať, použite adresár data/ (dostupný aj ako premenná prostredia NEBO_APP_DATA). Tento adresár prežije aktualizácie aplikácie aj karanténu.

Tipy na ladenie

  • Ak sa vaša aplikácia nespustí, pozrite si chyby v logs/stderr.log
  • Skontrolujte, či je binárny súbor spustiteľný (chmod +x binary)
  • Uistite sa, že počúvate na ceste k soketu Unix z NEBO_APP_SOCK
  • Soket musí byť pripravený do 10 sekúnd od spustenia
  • Na úložisko používajte NEBO_APP_DATA, nie pevne zadané cesty
  • Ladiace výpisy píšte do stderr (zachytávajú sa v logs/stderr.log)

Overenie

# 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

Odinštalovanie

nebo apps uninstall com.example.myapp

Zručnosti

Čo sú zručnosti

Zručnosti sú súbory pokynov, ktoré formujú správanie Nebo počas konverzácie. Keď je zručnosť aktívna, jej obsah sa vloží priamo do systémového promptu — a usmerňuje tón AI zamestnanca, jeho metodiku, odborné znalosti a používanie nástrojov počas danej relácie.

Zručnosti nie sú kód. Sú to dokumenty v Markdowne s metadátami YAML. Žiadna kompilácia, žiadny binárny súbor, žiadne gRPC. Zručnosť je súbor SKILL.md v adresári. To je všetko.

Zručnosti sú kontextové a dočasné. Aktivujú sa, keď sú relevantné (cez zhodu so spúšťačom alebo ručné načítanie), pretrvajú niekoľko ťahov a vypršia, keď už nie sú potrebné. Kontext AI zamestnanca tak zostáva štíhly — v prompte je len usmernenie, na ktorom práve záleží.

Zručnosti dopĺňajú aplikácie. Aplikácie poskytujú spustiteľné schopnosti (nástroje, kanály, brány). Zručnosti poskytujú usmernenie na orchestráciu — ako tieto nástroje efektívne používať. Aplikácia kalendára dáva Nebo schopnosť čítať a zapisovať udalosti. Zručnosť „príprava na stretnutie“ hovorí Nebo, ako sa pripraviť na stretnutia pomocou tejto aplikácie kalendára, e-mailu a vyhľadávania na webe spolu.

Zručnosti vs. aplikácie

ZručnostiAplikácie
FormátMarkdown (SKILL.md)Skompilovaný binárny súbor (.napp)
BehVložené do systémového promptuProces v sandboxe cez gRPC
PoskytujeUsmernenie správania, metodikaNástroje, kanály, panely UI
ŽivotnosťV rámci relácie, vypršanie podľa TTLVždy spustené
VytvorenieNapíšte súbor v MarkdowneNapísať, skompilovať, podpísať, zabaliť
ZabezpečenieNie sú potrebné žiadne oprávneniaSandbox s predvoleným zákazom

Rýchly štart

Vytvorte v priečinku zručností Nebo adresár so súborom SKILL.md:

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

Napíšte 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.

Nebo sleduje adresár zručností pomocou fsnotify. Vaša zručnosť je k dispozícii okamžite — bez reštartu. Povedzte niečo, čo zodpovedá spúšťaču, a aktivuje sa automaticky.

Alebo požiadajte Nebo priamo: „Vytvor zručnosť na písanie blogových príspevkov“ — Nebo za vás napíše súbor SKILL.md.

Formát SKILL.md

Každá zručnosť je jeden súbor SKILL.md s dvoma časťami: frontmatter YAML medzi značkami --- a telo v Markdowne (samotné pokyny vkladané do systémového promptu).

PolePovinnéPredvolenéPopis
nameÁno—Jedinečný identifikátor (stane sa z neho slug)
descriptionÁno—Jednoriadkový popis zobrazený v katalógu zručností
versionNie"1.0.0"Semver na sledovanie aktualizácií
authorNie—Autor zručnosti
priorityNie0Vyššie = zhoduje sa skôr (100+ pre kritické prepísania)
max_turnsNie4Počet ťahov nečinnosti pred automatickým vypršaním
triggersNie[]Frázy, ktoré túto zručnosť automaticky aktivujú (zhoda podreťazca bez ohľadu na veľkosť písmen)
toolsNie[]Nástroje, ktoré má táto zručnosť používať (informatívne)
dependenciesNie[]Ďalšie zručnosti, ktoré musia byť nainštalované
tagsNie[]Na kategorizáciu a vyhľadávanie
platformNie[]Podporované platformy: macos, linux, windows (prázdne = všetky)

Ako sa zručnosti aktivujú

Zručnosti sa aktivujú v dvoch fázach: najprv náznak, potom vyvolanie.

Fáza 1: Zhoda so spúšťačom — Zakaždým, keď používateľ pošle správu, Nebo prehľadá všetky zaregistrované zručnosti a hľadá zhody so spúšťačmi. Zodpovedajúce zručnosti sa objavia ako náznaky v systémovom prompte. AI zamestnanec náznak uvidí a rozhodne sa, či zručnosť vyvolá.

Fáza 2: Vyvolanie — AI zamestnanec vyvolá zručnosť zavolaním:

skill(name: "code-review")

Vráti sa celá šablóna SKILL.md ako výsledok nástroja, vyvolanie sa zaznamená a šablóna sa v ďalších ťahoch znova vloží do systémového promptu.

TTL a vypršanie:

  • Automaticky zhodné zručnosti: 4 ťahy nečinnosti (nastaviteľné cez max_turns)
  • Ručne načítané zručnosti: 6 ťahov nečinnosti
  • Opätovné vyvolanie vynuluje časovač
  • Pevný limit: najviac 4 aktívne zručnosti na reláciu
  • Rozpočet tokenov: spoločný obsah aktívnych zručností je obmedzený na 16,000 znakov

Správa zručností

AI zamestnanec môže spravovať zručnosti cez nástroj skill:

AkciaPopisPríklad
catalogZobraziť všetky dostupné zručnostiskill(action: "catalog")
loadAktivovať pre túto reláciuskill(name: "code-review", action: "load")
unloadDeaktivovať zručnosťskill(name: "code-review", action: "unload")
createVytvoriť novú zručnosť na diskuskill(action: "create", content: "...")
updateAktualizovať existujúcu zručnosťskill(name: "my-skill", action: "update", content: "...")
deleteOdstrániť zručnosť z diskuskill(name: "my-skill", action: "delete")

Písanie dobrých zručností

Dobrá šablóna zručnosti má:

  1. Jasný nadpis — povie AI zamestnancovi, v akom režime je
  2. Základné zásady — nespochybniteľné pravidlá správania
  3. Metodiku — postup krok za krokom pre bežné situácie
  4. Príklady — konkrétne vzory od správy používateľa po odpoveď
  5. Antivzory — čo NEROBIŤ (modely sa dobre učia z negatívnych príkladov)

Tip: Každá zručnosť by mala robiť jednu vec dobre. Nevytvárajte zručnosť „všeobecné programovanie“ — vytvorte code-review, debugging, api-design ako samostatné zručnosti. AI zamestnanec ich môže mať aktívnych viac naraz.

Pribalené zručnosti

Nebo sa dodáva s pribalenými zručnosťami pre bežné prípady použitia:

ZručnosťPrioritaPopis
onboarding100Privítanie nového používateľa a zber profilu
best-friend50Zručnosť osobnosti — uvoľnená, verná, úprimná reč
debugging25Systematická metodika ladenia
api-design15Osvedčené postupy návrhu RESTful API
code-review10Štruktúrovaná kontrola kódu s úrovňami závažnosti
database-expert10Návrh databáz, dotazy, optimalizácia
git-workflow10Vetvenie v Gite, commity, postupy PR
security-audit10Bezpečnostná analýza a odhaľovanie zraniteľností

Slúžia ako užitočné predvoľby aj ako referenčné implementácie na tvorbu vlastných zručností.

Referencia

Súbory Proto

Súbory Proto sa nachádzajú v proto/apps/v0/. SDK obsahujú vopred vygenerovaný kód, takže pri bežnom vývoji protoc nepotrebujete.

SúborSlužbaKľúčové RPC
v0/common.proto(len správy)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

Každá služba obsahuje RPC HealthCheck a Configure. SDK obe zvládne automaticky.

Typy Proto pre kanály

Typ správyPopis
ChannelSendRequestObálka odchádzajúcej správy s message_id, channelId, sender, text, attachments, reply_to, actions, platform_data
ChannelSendResponseID správy platformy pre vlákna
InboundMessageObálka prichádzajúcej správy so všetkými spoločnými poľami + časová pečiatka
MessageSenderIdentita bota (name, role, botId) — doplnená sprostredkovateľom
AttachmentPríloha súboru/obrázka/zvuku (type, url, filename, size)
MessageActionAkcia interaktívneho tlačidla/klávesnice (label, callback_id)

Identita a roly botov

Boty Nebo majú trojosový model identity:

  • creature — Čím bot je (archetyp): „Bystrý stratég“, „Dôkladný výskumník“
  • role — Aký má vzťah k používateľovi: „Priateľ“, „COO“, „Mentor“
  • vibe — Jeho energia (štýl komunikácie): „Pokojný, ale s vlastným názorom“, „Vrúcny a povzbudzujúci“

Keď váš kanálový doplnok dostane odchádzajúcu správu, pole sender obsahuje name a role bota. Podľa toho naformátujte zobrazované meno pre svoju platformu. Rola nie je pracovná pozícia — opisuje vzťah. „Priateľ“, „Syn“ a „Mentor“ sú platné roly rovnako ako „COO“ a „DevLead“.