NeboAI
NeboAI
Zacznij

Twórz aplikacje dla Nebo

Daj swojej AI nowe supermoce. Narzędzia, kanały, bramy, panele UI — wszystko, co możesz sobie wyobrazić, skompilowane do natywnego pliku binarnego.

Przegląd

Czym jest Nebo

Nebo to osobisty asystent AI na komputer — stale działający pracownik AI, który zarządza Twoim cyfrowym życiem. Myśl o Nebo tak jak o smartfonie: to potężna platforma, która dzięki aplikacjom zmienia wszystko.

Samo Nebo jest sprawnym pracownikiem AI z pamięcią, harmonogramem, przeglądaniem internetu, zarządzaniem plikami i dostępem do powłoki. Prawdziwy przełom dają jednak aplikacje. Tak jak siła smartfona bierze się z ekosystemu aplikacji, tak siła Nebo bierze się z aplikacji, które rozszerzają jego możliwości.

Czym są aplikacje

Aplikacje Nebo to samodzielne, wstępnie skompilowane moduły o ogromnych możliwościach. Każda aplikacja daje Nebo nową supermoc — zarządzanie kalendarzem, sortowanie poczty, śledzenie projektów, automatyzację domu, analizę finansową — wszystko, co deweloper może sobie wyobrazić.

Aplikacje dają ogromne możliwości w bardzo bezpieczny sposób. Każda aplikacja działa w piaskownicy z uprawnieniami domyślnie zablokowanymi. Ma dostęp tylko do tego, co deklaruje jej manifest i co zatwierdzi użytkownik.

Interfejs jest w 100% konwersacyjny. Użytkownicy nie korzystają z aplikacji przez osobne ekrany czy pulpity. Rozmawiają z Nebo, a Nebo używa narzędzi aplikacji, żeby załatwić sprawę. „Co mam jutro w kalendarzu?” — Nebo wywołuje aplikację kalendarza. „Umów spotkanie z Sarą o 3 po południu” — Nebo wywołuje aplikację kalendarza. Użytkownik nigdy nie opuszcza rozmowy.

Aplikacje mogą opcjonalnie udostępniać interfejs ustawień — panel konfiguracji otwierany we wbudowanym oknie przeglądarki Nebo. Tu użytkownicy wpisują klucze API, włączają funkcje i konfigurują aplikację. Interfejs ustawień opiera się na tablicy settings w manifeście (Nebo automatycznie renderuje formularz) albo aplikacja może dostarczyć własny, w pełni niestandardowy interfejs przez funkcję ui.

Aplikacje zastępują i rozszerzają wbudowane możliwości Nebo. Nebo ma podstawowe narzędzia platformy (dostęp do lokalnego kalendarza, zrzuty ekranu itp.). Gdy zainstalujesz aplikację kalendarza, zastępuje ona wbudowane narzędzie kalendarza i staje się jego nadzbiorem — lokalnie + chmura + agregacja + sprawdzanie dostępności.

Zasada: tylko kod skompilowany

Nebo stosuje ścisłą zasadę dopuszczania wyłącznie skompilowanych plików binarnych. Wszystkie aplikacje muszą być natywnymi, skompilowanymi plikami wykonywalnymi.

StatusJęzyki
ObsługiwaneGo (zalecany), Rust, C/C++, Zig
OdrzucanePython, Node.js, Ruby, Java, .NET, skrypty powłoki

Uzasadnienie:

  • Ochrona przed samomodyfikacją AI — pracownik AI z dostępem do powłoki mógłby w trakcie działania zmienić zachowanie interpretowanego skryptu. Skompilowane pliki binarne po podpisaniu są niezmienne.
  • Integralność podpisu — podpisy Ed25519 obejmują surowe bajty pliku binarnego. Podpisanego pliku binarnego nie da się zmienić bez unieważnienia podpisu.
  • Egzekwowanie piaskownicy — walidacja formatu binarnego (magiczne bajty ELF/Mach-O/PE) to szybka i niezawodna bramka.

Szybki start

Zainstaluj SDK

Oficjalne SDK obsługują całą konfigurację serwera gRPC, obsługę sygnałów i mostkowanie protokołu. Ty tylko implementujesz interfejsy obsługi.

Go (zalecany):

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

Rust (wkrótce):

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

C/C++ (wkrótce):

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

Struktura katalogu aplikacji

Aplikacje znajdują się w podkatalogu apps/ katalogu danych 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 kontrolna minimalnej aplikacji

  1. Utwórz manifest.json z polami id, name, version, provides
  2. Napisz TOOL.md z opisem, jak pracownik AI ma używać Twojego narzędzia
  3. Zainstaluj SDK (go get github.com/neboloop/nebo-sdk-go)
  4. Zaimplementuj interfejs obsługi dla swojej funkcji (ToolHandler, ChannelHandler itd.)
  5. Zarejestruj obsługę i wywołaj app.Run()
  6. Zbuduj natywny plik binarny (go build -o binary .)
  7. Umieść plik binarny + manifest.json + TOOL.md w katalogu apps/<your-app-id>/
  8. Nebo automatycznie wykrywa i uruchamia aplikację

Konfiguracja

manifest.json

Każda aplikacja wymaga pliku 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
        }
    ]
}

Pola wymagane:

PoleOpis
idIdentyfikator w odwróconej notacji domenowej (np. com.mycompany.myapp)
nameNazwa czytelna dla człowieka
versionCiąg w formacie semver
providesCo najmniej jedna funkcja (zobacz niżej)

Pola opcjonalne:

PoleDomyślnieOpis
runtime"local""local" lub "remote"
protocol"grpc"Obsługiwane jest tylko "grpc"
permissions[]Do czego aplikacja potrzebuje dostępu
description""Wyświetlane w interfejsie
settings[]Konfigurowalne ustawienia (renderowane w interfejsie ustawień)
oauth[]Wymagania dostawcy OAuth (zobacz sekcję OAuth niżej)

Funkcje

Zadeklaruj, co udostępnia Twoja aplikacja:

FunkcjaUsługa gRPCOpis
gatewayGatewayServiceRouting modeli LLM
tool:<name>ToolServiceNazwane narzędzie dla pracownika AI
channel:<name>ChannelServiceKanał komunikacji
commCommServiceKomunikacja między pracownikami AI
uiUIServiceNiestandardowy interfejs z proxy HTTP
scheduleScheduleServiceNiestandardowe planowanie
visionToolServicePrzetwarzanie obrazu
browserToolServiceAutomatyzacja przeglądarki

Aplikacja może udostępniać wiele funkcji. Na przykład jedna aplikacja może udostępniać zarówno narzędzie, jak i panel UI.

Uprawnienia

Uprawnienia określają, do czego aplikacja ma dostęp. Domyślnie wszystko jest zablokowane — jeśli coś nie zostało zadeklarowane, aplikacja nie może z tego korzystać.

PrefiksPrzykładyOpis
network:network:outbound, network:*Dostęp do sieci
filesystem:filesystem:read, filesystem:writeDostęp do systemu plików
memory:memory:read, memory:writeDostęp do pamięci pracownika AI
session:session:readSesje rozmów
tool:tool:shell, tool:fileUżywanie innych narzędzi
shell:shell:execWykonywanie poleceń powłoki
channel:channel:send, channel:*Operacje na kanałach
comm:comm:send, comm:*Komunikacja między pracownikami AI
model:model:chatDostęp do modeli AI
user:user:tokenOdbieranie tokena JWT użytkownika w żądaniach
schedule:schedule:createZarządzanie zadaniami cron
database:database:queryDostęp do bazy danych
storage:storage:read, storage:writeTrwała pamięć masowa
context:context:readDostęp do kontekstu pracownika AI
subagent:subagent:spawnOperacje na subagentach
lane:lane:enqueueOperacje na torach
notification:notification:sendPowiadomienia push
embedding:embedding:searchDostęp do osadzeń wektorowych
skill:skill:invokeWywoływanie umiejętności
advisor:advisor:consultDostęp do systemu doradcy
mcp:mcp:connectDostęp do serwera MCP
voice:voice:recordDostęp do głosu/dźwięku
browser:browser:navigateAutomatyzacja przeglądarki
oauth:oauth:google, oauth:*Dostęp do tokenów OAuth
settings:settings:readDostęp do ustawień
capability:capability:registerRejestracja funkcji

Obsługiwane są uprawnienia wieloznaczne: network:* pasuje do każdego sprawdzenia uprawnienia network:.

Ustawienia

Ustawienia pojawiają się w interfejsie Nebo w panelu ustawień aplikacji. Nebo zapisuje je w bazie danych i wysyła do Twojej aplikacji przez RPC Configure, gdy się zmienią.

Schemat Twoich ustawień trafia do wpisu aplikacji w sklepie NeboAI. Aplikacje z nieskonfigurowanymi wymaganymi ustawieniami mają w interfejsie plakietkę „Wymaga konfiguracji”.

TypOpis
textJednowierszowe pole tekstowe
passwordMaskowane pole tekstowe
togglePrzełącznik włącz/wyłącz
selectLista rozwijana z gotowymi opcjami
numberPole liczbowe
urlPole URL z walidacją
{
    "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"}
    ]
}

Wymagania OAuth

Aplikacje mogą deklarować wymagania dostawcy OAuth. Broker OAuth w Nebo obsługuje cały proces — aplikacje otrzymują tokeny automatycznie przez RPC Configure.

{
    "oauth": [
        {
            "provider": "google",
            "scopes": ["https://www.googleapis.com/auth/calendar"]
        }
    ]
}
PoleOpis
providerDostawca OAuth: "google", "microsoft", "github"
scopesTablica zakresów OAuth potrzebnych aplikacji

Gdy użytkownik instaluje aplikację, Nebo prosi go o autoryzację wymaganych zakresów OAuth. Aplikacja otrzymuje odświeżone tokeny przez RPC Configure i sama nie obsługuje procesu OAuth.

Zmienne środowiskowe

Proces Twojej aplikacji otrzymuje oczyszczone środowisko. Wszystkie sekrety są usuwane. Dostajesz:

ZmiennaWartość
NEBO_APP_DIRKatalog instalacji aplikacji
NEBO_APP_SOCKŚcieżka do gniazda Unix, które trzeba utworzyć
NEBO_APP_IDID aplikacji z manifestu
NEBO_APP_NAMENazwa aplikacji z manifestu
NEBO_APP_VERSIONWersja aplikacji z manifestu
NEBO_APP_DATAŚcieżka do katalogu data/ aplikacji
PATHSystemowa zmienna PATH (przekazywana bez zmian)
HOMEKatalog domowy użytkownika (przekazywany bez zmian)
TMPDIRKatalog tymczasowy (przekazywany bez zmian)

Ważne: Twój plik binarny musi utworzyć serwer gRPC nasłuchujący na gnieździe Unix pod NEBO_APP_SOCK. Nebo czeka do 10 sekund, aż to gniazdo się pojawi.

Sekwencja uruchamiania aplikacji

  1. Nebo odczytuje manifest.json i go waliduje
  2. Znajduje plik wykonywalny binary lub app w katalogu aplikacji
  3. Sprawdza znacznik .quarantined (nie uruchamia aplikacji poddanych kwarantannie)
  4. Sprawdzenie unieważnienia (tylko aplikacje dystrybuowane przez NeboAI)
  5. Weryfikacja podpisu (tylko aplikacje dystrybuowane przez NeboAI, pomijana w trybie deweloperskim)
  6. Walidacja pliku binarnego (odrzuca dowiązania symboliczne, skrypty, pliki niewykonywalne i zbyt duże pliki)
  7. Usuwa nieaktualne gniazdo z poprzedniego uruchomienia
  8. Tworzy katalog data/ na dane w piaskownicy
  9. Konfiguruje pliki logów dla każdej aplikacji (logs/stdout.log, logs/stderr.log)
  10. Uruchamia plik binarny z oczyszczonym środowiskiem i izolacją grupy procesów
  11. Czeka, aż pojawi się gniazdo Unix (wykładnicze opóźnienie, maks. 10 sekund)
  12. Łączy się przez gRPC po gnieździe Unix
  13. Tworzy klientów gRPC dla poszczególnych funkcji na podstawie provides
  14. Przeprowadza kontrolę stanu
  15. Rejestruje funkcje u pracownika AI (narzędzia, bramę, komunikację itd.)

Aplikacje narzędziowe

Zadeklaruj "provides": ["tool:my_tool_name"] w swoim manifeście.

Wzorzec STRAP

Wszystkie aplikacje narzędziowe Nebo muszą używać wzorca STRAP (Single Tool Resource Action Pattern) w swoim schemacie i routingu wykonania. To ten sam wzorzec, którego Nebo używa wewnętrznie, by połączyć ponad 35 pojedynczych narzędzi w 4 narzędzia domenowe — co zmniejsza obciążenie kontekstu LLM o około 80%.

Główna idea: zamiast rejestrować wiele narzędzi (get_events, check_availability, suggest_slots), zarejestruj JEDNO narzędzie z polami action (i opcjonalnie resource), które kierują do właściwej obsługi.

Przykład z jednym zasobem (kalendarz):

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

Przykład z wieloma zasobami (menedżer projektów):

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

Zasady schematu:

  1. Zawsze dodawaj pole action jako wymagany enum typu string
  2. Dodaj pole resource (wymagany enum typu string) tylko wtedy, gdy Twoje narzędzie zarządza wieloma różnymi typami zasobów
  3. Wszystkie pozostałe pola to parametry specyficzne dla akcji
  4. Opis enuma action powinien wymieniać wszystkie dostępne akcje

Dlaczego STRAP ma znaczenie:

  • Modele LLM uczą się wzorca routingu action raz i uogólniają go na wszystkie operacje
  • Definicje narzędzi zajmują ok. 6% kontekstu — STRAP zmniejsza to o 80%
  • Nowe operacje to tylko nowe wartości enuma, a nie nowe rejestracje narzędzi
  • Działa tak samo w modelach hostowanych i lokalnych

Przykład w Go — narzędzie kalkulatora

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

Zbuduj i zainstaluj:

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/

Przykład w 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(())
}

Przykład w 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;
}

Aplikacje kanałów

Zadeklaruj "provides": ["channel:my_channel"] i "permissions": ["channel:send"].

Aplikacje kanałów łączą zewnętrzne platformy komunikacyjne (Telegram, Discord, Slack itd.) z pracownikiem AI w Nebo. Gdy użytkownik wysyła wiadomość na zewnętrznej platformie, Twoja aplikacja przesyła ją strumieniowo do Nebo przez Receive. Gdy pracownik AI chce odpowiedzieć, Nebo wywołuje Send Twojej aplikacji.

Jak to działa

  1. Nebo wywołuje ID(), aby pobrać unikalny identyfikator Twojego kanału
  2. Nebo wywołuje Connect() z konfiguracją z ustawień Twojej aplikacji
  3. Nebo otwiera strumień Receive() — Twoja aplikacja wysyła wiadomości przychodzące za każdym razem, gdy użytkownik napisze do bota
  4. Wiadomości przychodzące trafiają na główny tor rozmowy pracownika AI
  5. Gdy pracownik AI chce wysłać wiadomość, Nebo wywołuje Send() z kopertą wiadomości v1
  6. Przy zamykaniu Nebo wywołuje Disconnect()

Koperta wiadomości v1

Wszystkie wiadomości kanałów — przychodzące i wychodzące — używają wspólnej koperty wiadomości:

{
  "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"
}
PoleTypOpis
message_idUUID v7Unikalne ID uporządkowane w czasie
channel_id{type}:{platform_id}Identyfikator kanału umożliwiający routing
senderobjectTożsamość bota — nazwa, rola, botId
textstringTreść wiadomości
attachmentsarrayPliki, obrazy, dźwięk
reply_toUUID v7ID wiadomości nadrzędnej dla wątków
actionsarrayInteraktywne przyciski/klawiatury
platform_databytesNieprzezroczyste dane przekazywane dla funkcji specyficznych dla platformy
timestampISO 8601Ustawiane przez wydawcę

Konstrukcja dwuwarstwowa: wspólne pola (text, attachments, reply_to, actions) obejmują 90% wiadomości inicjowanych przez pracowników. Funkcje specyficzne dla platformy trafiają do platform_data — Twoja wtyczka mapuje je do i z natywnego formatu platformy.

Strumienie rozmów

Wiadomości kanałów są przesyłane osobnymi strumieniami rozmów dla każdego kanału, co zapewnia izolację:

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

Przykład w Go — kanał 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
        }
    ]
}

Więcej funkcji

Aplikacja komunikacyjna

Zadeklaruj "provides": ["comm"] i "permissions": ["comm:*"]. Aplikacje komunikacyjne umożliwiają komunikację między pracownikami AI.

PoleOpis
fromID pracownika nadawcy
toID pracownika odbiorcy
topicTemat/kanał wiadomości
type"message", "mention", "proposal", "command", "info", "task"
contentTreść wiadomości

Kluczowe zachowania:

  • Register ogłasza tego pracownika AI w sieci wraz z jego funkcjami
  • Subscribe/Unsubscribe zarządzają subskrypcjami tematów
  • Receive przesyła strumieniowo wiadomości przychodzące (strumieniowanie po stronie serwera, tak jak w kanałach)
  • Jednocześnie może być aktywna tylko jedna aplikacja komunikacyjna

Aplikacja bramy

Aplikacja bramy kieruje żądania LLM do modeli. Zadeklaruj "provides": ["gateway"] i "permissions": ["network:outbound", "user:token"].

GatewayRequest zawiera wiadomości, narzędzia, prompt systemowy, maksymalną liczbę tokenów, temperaturę oraz UserContext (token JWT, jeśli przyznano uprawnienie user:token).

Typy GatewayEvent:

TypZawartośćOpis
"text"Fragment tekstuStrumieniowany token tekstu
"tool_call"JSONModel chce wywołać narzędzie
"thinking"Fragment tekstuRozszerzone myślenie/rozumowanie
"error"Komunikat błęduCoś poszło nie tak
"done"PusteStrumień zakończony

Aplikacja UI

Aplikacja UI udostępnia niestandardowy interfejs konfiguracji, który otwiera się we wbudowanym oknie przeglądarki Nebo. Zadeklaruj "provides": ["ui"]. W odróżnieniu od automatycznego formularza ustawień (który Nebo renderuje na podstawie settings w manifeście) aplikacja UI serwuje własny, pełny frontend HTML/CSS/JS.

Twoja aplikacja zawiera katalog ui/ ze statycznymi zasobami webowymi (HTML, CSS, JS — zwykle SPA z index.html). Nebo serwuje te pliki bezpośrednio i przekazuje wywołania API do Twojej aplikacji przez gRPC.

ŚcieżkaMechanizmPrzeznaczenie
GET /api/v1/apps/{id}/ui/*Serwer plików statycznychSerwuje pliki z Twojego katalogu ui/ (dla SPA awaryjnie index.html)
ANY /api/v1/apps/{id}/api/*Proxy gRPCPrzekazuje żądania HTTP do UIService.HandleRequest() Twojej aplikacji

SDK opakowuje standardowy net/http.ServeMux, więc piszesz zwykłe procedury obsługi HTTP w Go — SDK automatycznie zajmuje się mostkowaniem gRPC.

Przykład w Go — interfejs pulpitu:

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

Twój plik ui/index.html wykonywałby wywołania fetch do /api/v1/apps/com.example.dashboard/api/status, które są przekazywane do procedury obsługi mux.

Aplikacja harmonogramu

Aplikacja harmonogramu zastępuje wbudowany harmonogram cron w Nebo. Zadeklaruj "provides": ["schedule"] i "permissions": ["schedule:create"].

Gdy Twoja aplikacja harmonogramu się uruchomi, Nebo kieruje całe planowanie przez nią zamiast przez domyślny silnik cron. Jeśli aplikacja ulegnie awarii, Nebo automatycznie wraca do wbudowanego silnika.

  • Twoja aplikacja jest właścicielem stanu harmonogramów — gdy aplikacja harmonogramu jest aktywna, Nebo nie przechowuje harmonogramów we własnej bazie danych
  • Standardowe CRUD: Create, Get, List, Update, Delete, Enable, Disable
  • Triggers to RPC ze strumieniowaniem po stronie serwera — Twoja aplikacja wysyła komunikat wyzwalacza za każdym razem, gdy uruchamia się harmonogram
  • Jednocześnie może być aktywna tylko jedna aplikacja harmonogramu

Aplikacje z wieloma funkcjami

Aplikacja może udostępniać wiele funkcji. Na przykład aplikacja pulpitu z narzędziem i interfejsem 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())

Pakowanie

Format .napp

Aby dystrybuować aplikację przez NeboAI, spakuj ją jako plik .napp (archiwum tar.gz):

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

Wymagane pliki:

PlikMaks. rozmiarOpis
manifest.json1 MBMetadane aplikacji
binary lub app500 MBPlik wykonywalny
signatures.json1 MBPodpisy Ed25519
TOOL.md1 MBInstrukcje narzędzia dla pracownika AI

Zasady bezpieczeństwa podczas rozpakowywania:

  • Bez przechodzenia po ścieżkach (../ jest odrzucane)
  • Bez dowiązań symbolicznych (odrzucane)
  • Bez ścieżek bezwzględnych (odrzucane)
  • Akceptowane są tylko nazwy plików z listy dozwolonych

Podpisy

NeboAI podpisuje aplikacje kluczem Ed25519. Format pliku 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>"
}

W trybie deweloperskim (bez skonfigurowanego adresu URL NeboAI) weryfikacja podpisu jest całkowicie pomijana. Do lokalnego programowania nie potrzebujesz pliku signatures.json.

Publikowanie

Gdy Twoja aplikacja działa lokalnie, opublikuj ją przez NeboAI, aby trafiła do wszystkich użytkowników Nebo.

Konfiguracja konta dewelopera

  1. Zarejestruj konto NeboAI pod POST /api/v1/owners/register
  2. Zaloguj się, aby uzyskać token JWT: POST /api/v1/owners/login
  3. Utwórz konto dewelopera: POST /api/v1/developer/accounts

Proces zgłoszenia

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

Krok 1: Utwórz aplikację

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: Prześlij pliki binarne dla platform

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"

Prześlij po jednym pliku binarnym dla każdej platformy: darwin-arm64, darwin-amd64, linux-amd64, linux-arm64.

Krok 3: Wyślij do weryfikacji

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

Proces weryfikacji

  1. Automatyczne skanowanie — pliki binarne są skanowane przez VirusTotal
  2. Weryfikacja przez administratora — zespół NeboAI sprawdza metadane, manifest i wyniki skanowania
  3. Po zatwierdzeniu — NeboAI podpisuje aplikację kluczem Ed25519 i ją publikuje
  4. Po odrzuceniu — otrzymujesz powód i możesz poprawić aplikację oraz wysłać ją ponownie

Docelowy czas weryfikacji: <24 godziny.

Publikowanie aktualizacji

  1. Zaktualizuj wersję aplikacji: PUT /api/v1/developer/apps/{id} z nową wersją
  2. Prześlij nowe pliki binarne dla każdej platformy
  3. Ponownie wyślij do weryfikacji

Każda aktualizacja przechodzi ten sam proces weryfikacji. Poprzednie wersje pozostają dostępne, dopóki nowa wersja nie zostanie zatwierdzona.

Metadane w sklepie

PoleOpis
categorynp. productivity, communication, developer-tools
iconURL ikony aplikacji
visibilitypublic lub private
descriptionMoże być dłuższy i bogatszy niż opis w manifeście

Proces deweloperski

Programowanie lokalne

Do lokalnego programowania pakowanie nie jest wymagane:

  1. Utwórz katalog aplikacji:
    mkdir -p ~/Library/Application\ Support/Nebo/apps/com.example.myapp
  2. Napisz swój manifest.json i kod
  3. Zbuduj plik binarny:
    go build -o ~/Library/Application\ Support/Nebo/apps/com.example.myapp/binary .
  4. Nebo automatycznie wykrywa nowy katalog (lub uruchom Nebo ponownie)
  5. Po zmianach w kodzie przebuduj plik binarny — obserwator plików uruchomi aplikację ponownie

Przeglądanie logów

Wyjście stdout/stderr aplikacji jest zapisywane w plikach logów dla każdej aplikacji:

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

Trwałe dane

Używaj katalogu data/ (dostępnego też jako zmienna środowiskowa NEBO_APP_DATA) dla wszystkich plików, które Twoja aplikacja musi przechowywać. Ten katalog przetrwa aktualizacje aplikacji i kwarantannę.

Wskazówki dotyczące debugowania

  • Jeśli aplikacja się nie uruchamia, sprawdź błędy w logs/stderr.log
  • Upewnij się, że plik binarny jest wykonywalny (chmod +x binary)
  • Upewnij się, że nasłuchujesz na ścieżce gniazda Unix z NEBO_APP_SOCK
  • Gniazdo musi być gotowe w ciągu 10 sekund od uruchomienia
  • Do przechowywania danych używaj NEBO_APP_DATA, a nie zakodowanych na sztywno ścieżek
  • Komunikaty debugowania wypisuj na stderr (są zapisywane w logs/stderr.log)

Weryfikacja

# 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

Odinstalowywanie

nebo apps uninstall com.example.myapp

Umiejętności

Czym są umiejętności

Umiejętności to zestawy instrukcji, które kształtują zachowanie Nebo podczas rozmowy. Gdy umiejętność jest aktywna, jej treść trafia bezpośrednio do promptu systemowego — kierując tonem pracownika AI, jego metodologią, wiedzą dziedzinową i użyciem narzędzi w tej sesji.

Umiejętności to nie kod. To dokumenty Markdown z metadanymi YAML. Bez kompilacji, bez pliku binarnego, bez gRPC. Umiejętność to plik SKILL.md w katalogu. I tyle.

Umiejętności są kontekstowe i tymczasowe. Włączają się, gdy są potrzebne (przez dopasowanie wyzwalacza lub ręczne załadowanie), działają przez kilka tur i wygasają, gdy przestają być potrzebne. Dzięki temu kontekst pracownika AI pozostaje oszczędny — w prompcie są tylko wskazówki ważne w danej chwili.

Umiejętności uzupełniają aplikacje. Aplikacje dają funkcje wykonywalne (narzędzia, kanały, bramy). Umiejętności dają wskazówki koordynacyjne — jak skutecznie używać tych narzędzi. Aplikacja kalendarza pozwala Nebo odczytywać i zapisywać wydarzenia. Umiejętność „przygotowanie do spotkania” mówi Nebo, jak przygotować się do spotkań, łącząc aplikację kalendarza, pocztę i wyszukiwanie w internecie.

Umiejętności a aplikacje

UmiejętnościAplikacje
FormatMarkdown (SKILL.md)Skompilowany plik binarny (.napp)
Środowisko uruchomienioweWstrzykiwane do promptu systemowegoProces w piaskownicy przez gRPC
DostarczaWskazówki dotyczące zachowania, metodologięNarzędzia, kanały, panele UI
Czas życiaW obrębie sesji, wygasanie na podstawie TTLZawsze uruchomione
TworzenieNapisz plik MarkdownNapisz, skompiluj, podpisz, spakuj
BezpieczeństwoNie wymaga uprawnieńPiaskownica z domyślną blokadą

Szybki start

Utwórz katalog w folderze umiejętności Nebo z plikiem SKILL.md:

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

Napisz plik 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 obserwuje katalog umiejętności za pomocą fsnotify. Twoja umiejętność jest dostępna od razu — bez ponownego uruchamiania. Napisz coś, co pasuje do wyzwalacza, a włączy się automatycznie.

Możesz też poprosić Nebo bezpośrednio: „Utwórz umiejętność do pisania wpisów na bloga” — Nebo napisze plik SKILL.md za Ciebie.

Format SKILL.md

Każda umiejętność to jeden plik SKILL.md z dwiema częściami: nagłówkiem YAML między znacznikami --- i treścią w Markdown (właściwymi instrukcjami wstrzykiwanymi do promptu systemowego).

PoleWymaganeDomyślnieOpis
nameTak—Unikalny identyfikator (staje się slugiem)
descriptionTak—Jednowierszowy opis wyświetlany w katalogu umiejętności
versionNie"1.0.0"Semver do śledzenia aktualizacji
authorNie—Autor umiejętności
priorityNie0Wyższa wartość = dopasowanie w pierwszej kolejności (100+ dla krytycznych nadpisań)
max_turnsNie4Liczba tur bez aktywności przed automatycznym wygaśnięciem
triggersNie[]Frazy, które automatycznie włączają tę umiejętność (dopasowanie podciągu bez rozróżniania wielkości liter)
toolsNie[]Narzędzia, których ta umiejętność ma używać (informacyjnie)
dependenciesNie[]Inne umiejętności, które muszą być zainstalowane
tagsNie[]Do kategoryzacji i wyszukiwania
platformNie[]Obsługiwane platformy: macos, linux, windows (puste = wszystkie)

Jak włączają się umiejętności

Umiejętności włączają się w dwóch fazach: najpierw podpowiedź, potem wywołanie.

Faza 1: dopasowanie wyzwalaczy — za każdym razem, gdy użytkownik wysyła wiadomość, Nebo sprawdza wszystkie zarejestrowane umiejętności pod kątem pasujących wyzwalaczy. Pasujące umiejętności pojawiają się jako podpowiedzi w prompcie systemowym. Pracownik AI widzi podpowiedź i decyduje, czy wywołać umiejętność.

Faza 2: wywołanie — pracownik AI wywołuje umiejętność, używając:

skill(name: "code-review")

Zwraca to pełny szablon SKILL.md jako wynik narzędzia, zapisuje wywołanie i ponownie wstrzykuje szablon do promptu systemowego w kolejnych turach.

TTL i wygasanie:

  • Umiejętności dopasowane automatycznie: 4 tury bez aktywności (konfigurowalne przez max_turns)
  • Umiejętności załadowane ręcznie: 6 tur bez aktywności
  • Ponowne wywołanie resetuje licznik
  • Twardy limit: maksymalnie 4 aktywne umiejętności na sesję
  • Budżet tokenów: łączna treść aktywnych umiejętności ograniczona do 16 000 znaków

Zarządzanie umiejętnościami

Pracownik AI może zarządzać umiejętnościami za pomocą narzędzia skill:

AkcjaOpisPrzykład
catalogWyświetl wszystkie dostępne umiejętnościskill(action: "catalog")
loadWłącz na tę sesjęskill(name: "code-review", action: "load")
unloadWyłącz umiejętnośćskill(name: "code-review", action: "unload")
createUtwórz nową umiejętność na dyskuskill(action: "create", content: "...")
updateZaktualizuj istniejącą umiejętnośćskill(name: "my-skill", action: "update", content: "...")
deleteUsuń umiejętność z dyskuskill(name: "my-skill", action: "delete")

Jak pisać dobre umiejętności

Dobry szablon umiejętności ma:

  1. Jasny nagłówek — mówi pracownikowi AI, w jakim trybie działa
  2. Podstawowe zasady — reguły zachowania, które nie podlegają negocjacji
  3. Metodologię — podejście krok po kroku w typowych sytuacjach
  4. Przykłady — konkretne wzorce: wiadomość użytkownika i odpowiedź
  5. Antywzorce — czego NIE robić (modele dobrze uczą się na negatywnych przykładach)

Wskazówka: każda umiejętność powinna robić dobrze jedną rzecz. Nie twórz umiejętności „programowanie ogólne” — utwórz code-review, debugging, api-design jako osobne umiejętności. Pracownik AI może mieć kilka aktywnych jednocześnie.

Wbudowane umiejętności

Nebo ma wbudowane umiejętności obejmujące typowe zastosowania:

UmiejętnośćPriorytetOpis
onboarding100Powitanie nowego użytkownika i zbieranie profilu
best-friend50Umiejętność osobowości — swobodnie, lojalnie, szczerze
debugging25Systematyczna metodologia debugowania
api-design15Dobre praktyki projektowania API RESTful
code-review10Uporządkowany przegląd kodu z poziomami ważności
database-expert10Projektowanie baz danych, zapytania, optymalizacja
git-workflow10Gałęzie Git, commity, przepływy pracy z PR
security-audit10Analiza bezpieczeństwa i wykrywanie podatności

Służą zarówno jako przydatne ustawienia domyślne, jak i wzorcowe implementacje do tworzenia własnych umiejętności.

Dokumentacja

Pliki proto

Pliki proto znajdują się w proto/apps/v0/. SDK zawierają wstępnie wygenerowany kod, więc przy zwykłym programowaniu nie potrzebujesz protoc.

PlikUsługaKluczowe RPC
v0/common.proto(tylko wiadomości)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żda usługa zawiera RPC HealthCheck i Configure. SDK obsługuje oba automatycznie.

Typy proto kanałów

Typ wiadomościOpis
ChannelSendRequestKoperta wiadomości wychodzącej z polami message_id, channelId, sender, text, attachments, reply_to, actions, platform_data
ChannelSendResponseID wiadomości na platformie do tworzenia wątków
InboundMessageKoperta wiadomości przychodzącej ze wszystkimi wspólnymi polami + znacznikiem czasu
MessageSenderTożsamość bota (name, role, botId) — uzupełniana przez brokera
AttachmentZałącznik: plik/obraz/dźwięk (type, url, filename, size)
MessageActionInteraktywna akcja przycisku/klawiatury (label, callback_id)

Tożsamość i role botów

Boty Nebo mają model tożsamości oparty na trzech osiach:

  • creature — czym bot jest (archetyp): „Bystry strateg”, „Skrupulatny badacz”
  • role — jaka jest jego relacja z użytkownikiem: „Przyjaciel”, „Dyrektor operacyjny”, „Mentor”
  • vibe — jego energia (styl komunikacji): „Wyluzowany, ale z własnym zdaniem”, „Ciepły i dodający otuchy”

Gdy Twoja wtyczka kanału otrzymuje wiadomość wychodzącą, pole sender zawiera name i role bota. Użyj ich do sformatowania wyświetlanej nazwy na swojej platformie. Rola to nie stanowisko — to opis relacji. „Przyjaciel”, „Syn” i „Mentor” to prawidłowe role, obok „COO” i „DevLead”.