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.
| Status | Języki |
|---|---|
| Obsługiwane | Go (zalecany), Rust, C/C++, Zig |
| Odrzucane | Python, 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
- Utwórz
manifest.jsonz polamiid,name,version,provides - Napisz
TOOL.mdz opisem, jak pracownik AI ma używać Twojego narzędzia - Zainstaluj SDK (
go get github.com/neboloop/nebo-sdk-go) - Zaimplementuj interfejs obsługi dla swojej funkcji (
ToolHandler,ChannelHandleritd.) - Zarejestruj obsługę i wywołaj
app.Run() - Zbuduj natywny plik binarny (
go build -o binary .) - Umieść plik binarny + manifest.json + TOOL.md w katalogu
apps/<your-app-id>/ - 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:
| Pole | Opis |
|---|---|
id | Identyfikator w odwróconej notacji domenowej (np. com.mycompany.myapp) |
name | Nazwa czytelna dla człowieka |
version | Ciąg w formacie semver |
provides | Co najmniej jedna funkcja (zobacz niżej) |
Pola opcjonalne:
| Pole | Domyślnie | Opis |
|---|---|---|
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:
| Funkcja | Usługa gRPC | Opis |
|---|---|---|
gateway | GatewayService | Routing modeli LLM |
tool:<name> | ToolService | Nazwane narzędzie dla pracownika AI |
channel:<name> | ChannelService | Kanał komunikacji |
comm | CommService | Komunikacja między pracownikami AI |
ui | UIService | Niestandardowy interfejs z proxy HTTP |
schedule | ScheduleService | Niestandardowe planowanie |
vision | ToolService | Przetwarzanie obrazu |
browser | ToolService | Automatyzacja 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ć.
| Prefiks | Przykłady | Opis |
|---|---|---|
network: | network:outbound, network:* | Dostęp do sieci |
filesystem: | filesystem:read, filesystem:write | Dostęp do systemu plików |
memory: | memory:read, memory:write | Dostęp do pamięci pracownika AI |
session: | session:read | Sesje rozmów |
tool: | tool:shell, tool:file | Używanie innych narzędzi |
shell: | shell:exec | Wykonywanie poleceń powłoki |
channel: | channel:send, channel:* | Operacje na kanałach |
comm: | comm:send, comm:* | Komunikacja między pracownikami AI |
model: | model:chat | Dostęp do modeli AI |
user: | user:token | Odbieranie tokena JWT użytkownika w żądaniach |
schedule: | schedule:create | Zarządzanie zadaniami cron |
database: | database:query | Dostęp do bazy danych |
storage: | storage:read, storage:write | Trwała pamięć masowa |
context: | context:read | Dostęp do kontekstu pracownika AI |
subagent: | subagent:spawn | Operacje na subagentach |
lane: | lane:enqueue | Operacje na torach |
notification: | notification:send | Powiadomienia push |
embedding: | embedding:search | Dostęp do osadzeń wektorowych |
skill: | skill:invoke | Wywoływanie umiejętności |
advisor: | advisor:consult | Dostęp do systemu doradcy |
mcp: | mcp:connect | Dostęp do serwera MCP |
voice: | voice:record | Dostęp do głosu/dźwięku |
browser: | browser:navigate | Automatyzacja przeglądarki |
oauth: | oauth:google, oauth:* | Dostęp do tokenów OAuth |
settings: | settings:read | Dostęp do ustawień |
capability: | capability:register | Rejestracja 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”.
| Typ | Opis |
|---|---|
text | Jednowierszowe pole tekstowe |
password | Maskowane pole tekstowe |
toggle | Przełącznik włącz/wyłącz |
select | Lista rozwijana z gotowymi opcjami |
number | Pole liczbowe |
url | Pole 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"]
}
]
} | Pole | Opis |
|---|---|
provider | Dostawca OAuth: "google", "microsoft", "github" |
scopes | Tablica 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:
| Zmienna | Wartość |
|---|---|
NEBO_APP_DIR | Katalog instalacji aplikacji |
NEBO_APP_SOCK | Ścieżka do gniazda Unix, które trzeba utworzyć |
NEBO_APP_ID | ID aplikacji z manifestu |
NEBO_APP_NAME | Nazwa aplikacji z manifestu |
NEBO_APP_VERSION | Wersja aplikacji z manifestu |
NEBO_APP_DATA | Ścieżka do katalogu data/ aplikacji |
PATH | Systemowa zmienna PATH (przekazywana bez zmian) |
HOME | Katalog domowy użytkownika (przekazywany bez zmian) |
TMPDIR | Katalog 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
- Nebo odczytuje
manifest.jsoni go waliduje - Znajduje plik wykonywalny
binarylubappw katalogu aplikacji - Sprawdza znacznik
.quarantined(nie uruchamia aplikacji poddanych kwarantannie) - Sprawdzenie unieważnienia (tylko aplikacje dystrybuowane przez NeboAI)
- Weryfikacja podpisu (tylko aplikacje dystrybuowane przez NeboAI, pomijana w trybie deweloperskim)
- Walidacja pliku binarnego (odrzuca dowiązania symboliczne, skrypty, pliki niewykonywalne i zbyt duże pliki)
- Usuwa nieaktualne gniazdo z poprzedniego uruchomienia
- Tworzy katalog
data/na dane w piaskownicy - Konfiguruje pliki logów dla każdej aplikacji (
logs/stdout.log,logs/stderr.log) - Uruchamia plik binarny z oczyszczonym środowiskiem i izolacją grupy procesów
- Czeka, aż pojawi się gniazdo Unix (wykładnicze opóźnienie, maks. 10 sekund)
- Łączy się przez gRPC po gnieździe Unix
- Tworzy klientów gRPC dla poszczególnych funkcji na podstawie
provides - Przeprowadza kontrolę stanu
- 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:
- Zawsze dodawaj pole
actionjako wymagany enum typu string - Dodaj pole
resource(wymagany enum typu string) tylko wtedy, gdy Twoje narzędzie zarządza wieloma różnymi typami zasobów - Wszystkie pozostałe pola to parametry specyficzne dla akcji
- Opis enuma
actionpowinien wymieniać wszystkie dostępne akcje
Dlaczego STRAP ma znaczenie:
- Modele LLM uczą się wzorca routingu
actionraz 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
- Nebo wywołuje
ID(), aby pobrać unikalny identyfikator Twojego kanału - Nebo wywołuje
Connect()z konfiguracją z ustawień Twojej aplikacji - Nebo otwiera strumień
Receive()— Twoja aplikacja wysyła wiadomości przychodzące za każdym razem, gdy użytkownik napisze do bota - Wiadomości przychodzące trafiają na główny tor rozmowy pracownika AI
- Gdy pracownik AI chce wysłać wiadomość, Nebo wywołuje
Send()z kopertą wiadomości v1 - 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"
} | Pole | Typ | Opis |
|---|---|---|
message_id | UUID v7 | Unikalne ID uporządkowane w czasie |
channel_id | {type}:{platform_id} | Identyfikator kanału umożliwiający routing |
sender | object | Tożsamość bota — nazwa, rola, botId |
text | string | Treść wiadomości |
attachments | array | Pliki, obrazy, dźwięk |
reply_to | UUID v7 | ID wiadomości nadrzędnej dla wątków |
actions | array | Interaktywne przyciski/klawiatury |
platform_data | bytes | Nieprzezroczyste dane przekazywane dla funkcji specyficznych dla platformy |
timestamp | ISO 8601 | Ustawiane 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.
| Pole | Opis |
|---|---|
from | ID pracownika nadawcy |
to | ID pracownika odbiorcy |
topic | Temat/kanał wiadomości |
type | "message", "mention", "proposal", "command", "info", "task" |
content | Treść wiadomości |
Kluczowe zachowania:
Registerogłasza tego pracownika AI w sieci wraz z jego funkcjamiSubscribe/Unsubscribezarządzają subskrypcjami tematówReceiveprzesył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:
| Typ | Zawartość | Opis |
|---|---|---|
"text" | Fragment tekstu | Strumieniowany token tekstu |
"tool_call" | JSON | Model chce wywołać narzędzie |
"thinking" | Fragment tekstu | Rozszerzone myślenie/rozumowanie |
"error" | Komunikat błędu | Coś poszło nie tak |
"done" | Puste | Strumień 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żka | Mechanizm | Przeznaczenie |
|---|---|---|
GET /api/v1/apps/{id}/ui/* | Serwer plików statycznych | Serwuje pliki z Twojego katalogu ui/ (dla SPA awaryjnie index.html) |
ANY /api/v1/apps/{id}/api/* | Proxy gRPC | Przekazuje żą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 Triggersto 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:
| Plik | Maks. rozmiar | Opis |
|---|---|---|
manifest.json | 1 MB | Metadane aplikacji |
binary lub app | 500 MB | Plik wykonywalny |
signatures.json | 1 MB | Podpisy Ed25519 |
TOOL.md | 1 MB | Instrukcje 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
- Zarejestruj konto NeboAI pod
POST /api/v1/owners/register - Zaloguj się, aby uzyskać token JWT:
POST /api/v1/owners/login - 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
- Automatyczne skanowanie — pliki binarne są skanowane przez VirusTotal
- Weryfikacja przez administratora — zespół NeboAI sprawdza metadane, manifest i wyniki skanowania
- Po zatwierdzeniu — NeboAI podpisuje aplikację kluczem Ed25519 i ją publikuje
- Po odrzuceniu — otrzymujesz powód i możesz poprawić aplikację oraz wysłać ją ponownie
Docelowy czas weryfikacji: <24 godziny.
Publikowanie aktualizacji
- Zaktualizuj wersję aplikacji:
PUT /api/v1/developer/apps/{id}z nową wersją - Prześlij nowe pliki binarne dla każdej platformy
- 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
| Pole | Opis |
|---|---|
category | np. productivity, communication, developer-tools |
icon | URL ikony aplikacji |
visibility | public lub private |
description | Może być dłuższy i bogatszy niż opis w manifeście |
Proces deweloperski
Programowanie lokalne
Do lokalnego programowania pakowanie nie jest wymagane:
- Utwórz katalog aplikacji:
mkdir -p ~/Library/Application\ Support/Nebo/apps/com.example.myapp - Napisz swój
manifest.jsoni kod - Zbuduj plik binarny:
go build -o ~/Library/Application\ Support/Nebo/apps/com.example.myapp/binary . - Nebo automatycznie wykrywa nowy katalog (lub uruchom Nebo ponownie)
- 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ści | Aplikacje | |
|---|---|---|
| Format | Markdown (SKILL.md) | Skompilowany plik binarny (.napp) |
| Środowisko uruchomieniowe | Wstrzykiwane do promptu systemowego | Proces w piaskownicy przez gRPC |
| Dostarcza | Wskazówki dotyczące zachowania, metodologię | Narzędzia, kanały, panele UI |
| Czas życia | W obrębie sesji, wygasanie na podstawie TTL | Zawsze uruchomione |
| Tworzenie | Napisz plik Markdown | Napisz, skompiluj, podpisz, spakuj |
| Bezpieczeństwo | Nie 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).
| Pole | Wymagane | Domyślnie | Opis |
|---|---|---|---|
name | Tak | — | Unikalny identyfikator (staje się slugiem) |
description | Tak | — | Jednowierszowy opis wyświetlany w katalogu umiejętności |
version | Nie | "1.0.0" | Semver do śledzenia aktualizacji |
author | Nie | — | Autor umiejętności |
priority | Nie | 0 | Wyższa wartość = dopasowanie w pierwszej kolejności (100+ dla krytycznych nadpisań) |
max_turns | Nie | 4 | Liczba tur bez aktywności przed automatycznym wygaśnięciem |
triggers | Nie | [] | Frazy, które automatycznie włączają tę umiejętność (dopasowanie podciągu bez rozróżniania wielkości liter) |
tools | Nie | [] | Narzędzia, których ta umiejętność ma używać (informacyjnie) |
dependencies | Nie | [] | Inne umiejętności, które muszą być zainstalowane |
tags | Nie | [] | Do kategoryzacji i wyszukiwania |
platform | Nie | [] | 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:
| Akcja | Opis | Przykład |
|---|---|---|
catalog | Wyświetl wszystkie dostępne umiejętności | skill(action: "catalog") |
load | Włącz na tę sesję | skill(name: "code-review", action: "load") |
unload | Wyłącz umiejętność | skill(name: "code-review", action: "unload") |
create | Utwórz nową umiejętność na dysku | skill(action: "create", content: "...") |
update | Zaktualizuj istniejącą umiejętność | skill(name: "my-skill", action: "update", content: "...") |
delete | Usuń umiejętność z dysku | skill(name: "my-skill", action: "delete") |
Jak pisać dobre umiejętności
Dobry szablon umiejętności ma:
- Jasny nagłówek — mówi pracownikowi AI, w jakim trybie działa
- Podstawowe zasady — reguły zachowania, które nie podlegają negocjacji
- Metodologię — podejście krok po kroku w typowych sytuacjach
- Przykłady — konkretne wzorce: wiadomość użytkownika i odpowiedź
- 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ść | Priorytet | Opis |
|---|---|---|
onboarding | 100 | Powitanie nowego użytkownika i zbieranie profilu |
best-friend | 50 | Umiejętność osobowości — swobodnie, lojalnie, szczerze |
debugging | 25 | Systematyczna metodologia debugowania |
api-design | 15 | Dobre praktyki projektowania API RESTful |
code-review | 10 | Uporządkowany przegląd kodu z poziomami ważności |
database-expert | 10 | Projektowanie baz danych, zapytania, optymalizacja |
git-workflow | 10 | Gałęzie Git, commity, przepływy pracy z PR |
security-audit | 10 | Analiza 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.
| Plik | Usługa | Kluczowe RPC |
|---|---|---|
v0/common.proto | (tylko wiadomości) | HealthCheckRequest/Response, SettingsMap, UserContext, Empty |
v0/tool.proto | ToolService | Name, Description, Schema, Execute, RequiresApproval, Configure |
v0/channel.proto | ChannelService | ID, Connect, Disconnect, Send, Receive (stream), Configure |
v0/comm.proto | CommService | Name, Version, Connect, Disconnect, Send, Subscribe, Register, Receive (stream), Configure |
v0/gateway.proto | GatewayService | HealthCheck, Stream (stream), Poll, Cancel, Configure |
v0/ui.proto | UIService | HealthCheck, HandleRequest, Configure |
v0/schedule.proto | ScheduleService | HealthCheck, Create, Get, List, Update, Delete, Enable, Disable, Trigger, History, Triggers (stream), Configure |
Każda usługa zawiera RPC HealthCheck i Configure. SDK obsługuje oba automatycznie.
Typy proto kanałów
| Typ wiadomości | Opis |
|---|---|
ChannelSendRequest | Koperta wiadomości wychodzącej z polami message_id, channelId, sender, text, attachments, reply_to, actions, platform_data |
ChannelSendResponse | ID wiadomości na platformie do tworzenia wątków |
InboundMessage | Koperta wiadomości przychodzącej ze wszystkimi wspólnymi polami + znacznikiem czasu |
MessageSender | Tożsamość bota (name, role, botId) — uzupełniana przez brokera |
Attachment | Załącznik: plik/obraz/dźwięk (type, url, filename, size) |
MessageAction | Interaktywna 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”.