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.
| Stav | Jazyky |
|---|---|
| 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
- Vytvorte
manifest.jsons poľamiid,name,version,provides - Napíšte
TOOL.md, ktorý opisuje, ako má AI zamestnanec váš nástroj používať - Nainštalujte SDK (
go get github.com/neboloop/nebo-sdk-go) - Implementujte rozhranie handlera pre svoju schopnosť (
ToolHandler,ChannelHandleratď.) - Zaregistrujte handler a zavolajte
app.Run() - Zostavte natívny binárny súbor (
go build -o binary .) - Umiestnite binárny súbor + manifest.json + TOOL.md do adresára
apps/<your-app-id>/ - 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:
| Pole | Popis |
|---|---|
id | Identifikátor v tvare obrátenej domény (napr. com.mycompany.myapp) |
name | Čitateľný názov |
version | Reťazec Semver |
provides | Aspoň jedna schopnosť (pozri nižšie) |
Voliteľné polia:
| Pole | Predvolené | 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 gRPC | Popis |
|---|---|---|
gateway | GatewayService | Smerovanie modelov LLM |
tool:<name> | ToolService | Pomenovaný nástroj pre AI zamestnanca |
channel:<name> | ChannelService | Kanál na posielanie správ |
comm | CommService | Komunikácia medzi AI zamestnancami |
ui | UIService | Vlastné UI s HTTP proxy |
schedule | ScheduleService | Vlastné plánovanie |
vision | ToolService | Spracovanie obrazu |
browser | ToolService | Automatizá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ť.
| Predpona | Príklady | Popis |
|---|---|---|
network: | network:outbound, network:* | Prístup k sieti |
filesystem: | filesystem:read, filesystem:write | Prístup k súborovému systému |
memory: | memory:read, memory:write | Prístup k pamäti AI zamestnanca |
session: | session:read | Relácie konverzácie |
tool: | tool:shell, tool:file | Používanie iných nástrojov |
shell: | shell:exec | Spúšťanie príkazov shellu |
channel: | channel:send, channel:* | Operácie s kanálmi |
comm: | comm:send, comm:* | Komunikácia medzi AI zamestnancami |
model: | model:chat | Prístup k modelom AI |
user: | user:token | Prijímanie JWT používateľa v požiadavkách |
schedule: | schedule:create | Správa úloh cron |
database: | database:query | Prístup k databáze |
storage: | storage:read, storage:write | Trvalé úložisko |
context: | context:read | Prístup ku kontextu AI zamestnanca |
subagent: | subagent:spawn | Operácie so subagentmi |
lane: | lane:enqueue | Operácie s pruhmi |
notification: | notification:send | Push upozornenia |
embedding: | embedding:search | Prístup k vektorovým embeddingom |
skill: | skill:invoke | Vyvolávanie zručností |
advisor: | advisor:consult | Prístup k systému poradcov |
mcp: | mcp:connect | Prístup k serveru MCP |
voice: | voice:record | Prístup k hlasu/zvuku |
browser: | browser:navigate | Automatizácia prehliadača |
oauth: | oauth:google, oauth:* | Prístup k tokenom OAuth |
settings: | settings:read | Prístup k nastaveniam |
capability: | capability:register | Registrá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ť“.
| Typ | Popis |
|---|---|
text | Jednoriadkové textové pole |
password | Maskované textové pole |
toggle | Logický prepínač zap./vyp. |
select | Rozbaľovací zoznam s preddefinovanými možnosťami |
number | Číselné pole |
url | Pole 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"]
}
]
} | Pole | Popis |
|---|---|
provider | Poskytovateľ OAuth: "google", "microsoft", "github" |
scopes | Pole 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_DIR | Inštalačný adresár aplikácie |
NEBO_APP_SOCK | Cesta k soketu Unix, ktorý treba vytvoriť |
NEBO_APP_ID | ID aplikácie z manifestu |
NEBO_APP_NAME | Názov aplikácie z manifestu |
NEBO_APP_VERSION | Verzia aplikácie z manifestu |
NEBO_APP_DATA | Cesta k adresáru data/ aplikácie |
PATH | Systémová PATH (prenesená) |
HOME | Domovský adresár používateľa (prenesený) |
TMPDIR | Doč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
- Nebo prečíta
manifest.jsona overí ho - Nájde spustiteľný súbor
binaryaleboappv adresári aplikácie - Skontroluje značku
.quarantined(aplikácie v karanténe odmietne spustiť) - Kontrola odvolania (len aplikácie distribuované cez NeboAI)
- Overenie podpisu (len aplikácie distribuované cez NeboAI, vo vývoji sa preskakuje)
- Overenie binárneho súboru (odmietne symbolické odkazy, skripty, nespustiteľné a príliš veľké súbory)
- Vyčistí zastaraný soket z predchádzajúceho behu
- Vytvorí adresár
data/pre úložisko v sandboxe - Nastaví súbory protokolov pre každú aplikáciu (
logs/stdout.log,logs/stderr.log) - Spustí binárny súbor s očisteným prostredím a izoláciou skupiny procesov
- Čaká na objavenie soketu Unix (exponenciálne odďaľovanie, najviac 10 sekúnd)
- Pripojí sa cez gRPC na sokete Unix
- Vytvorí klientov gRPC pre konkrétne schopnosti podľa
provides - Spustí kontrolu stavu
- 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:
- Vždy zahrňte pole
actionako povinný reťazcový enum - Pole
resource(povinný reťazcový enum) pridajte len vtedy, ak váš nástroj spravuje viacero odlišných typov zdrojov - Všetky ostatné polia sú parametre špecifické pre akciu
- Popis enumu
actionby mal uvádzať všetky dostupné akcie
Prečo na STRAP záleží:
- LLM sa vzor smerovania
actionnauč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
- Nebo zavolá
ID()a získa jedinečný identifikátor vášho kanála - Nebo zavolá
Connect()s konfiguráciou z nastavení vašej aplikácie - Nebo otvorí stream
Receive()— vaša aplikácia posiela prichádzajúce správy vždy, keď používateľ napíše botovi - Prichádzajúce správy sa smerujú do hlavného konverzačného pruhu AI zamestnanca
- Keď chce AI zamestnanec poslať správu, Nebo zavolá
Send()s obálkou správy v1 - 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"
} | Pole | Typ | Popis |
|---|---|---|
message_id | UUID v7 | Jedinečné ID zoradené podľa času |
channel_id | {type}:{platform_id} | Smerovateľný identifikátor kanála |
sender | object | Identita bota — meno, rola, botId |
text | string | Telo správy |
attachments | array | Súbory, obrázky, zvuk |
reply_to | UUID v7 | ID nadradenej správy pre vlákna |
actions | array | Interaktívne tlačidlá/klávesnice |
platform_data | bytes | Nepriehľadný prenos pre funkcie špecifické pre platformu |
timestamp | ISO 8601 | Nastavuje 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.
| Pole | Popis |
|---|---|
from | ID odosielajúceho zamestnanca |
to | ID prijímajúceho zamestnanca |
topic | Téma/kanál správy |
type | "message", "mention", "proposal", "command", "info", "task" |
content | Telo správy |
Kľúčové správanie:
Registerohlási tohto AI zamestnanca v sieti spolu s jeho schopnosťamiSubscribe/Unsubscribespravujú odbery témReceivestreamuje 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:
| Typ | Obsah | Popis |
|---|---|---|
"text" | Časť textu | Streamovaný textový token |
"tool_call" | JSON | Model chce zavolať nástroj |
"thinking" | Časť textu | Rozšírené premýšľanie/uvažovanie |
"error" | Chybová správa | Niečo sa pokazilo |
"done" | Prázdne | Stream 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.
| Cesta | Mechanizmus | Účel |
|---|---|---|
GET /api/v1/apps/{id}/ui/* | Server statických súborov | Poskytuje súbory z vášho adresára ui/ (záložné presmerovanie SPA na index.html) |
ANY /api/v1/apps/{id}/api/* | Proxy gRPC | Presmerú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 Triggersje 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úbor | Max. veľkosť | Popis |
|---|---|---|
manifest.json | 1 MB | Metadáta aplikácie |
binary alebo app | 500 MB | Spustiteľný súbor |
signatures.json | 1 MB | Podpisy Ed25519 |
TOOL.md | 1 MB | Pokyny 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
- Zaregistrujte si účet NeboAI na
POST /api/v1/owners/register - Prihláste sa a získajte token JWT:
POST /api/v1/owners/login - 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
- Automatická kontrola — binárne súbory sa skenujú cez VirusTotal
- Kontrola administrátorom — tím NeboAI skontroluje metadáta, manifest a výsledky skenovania
- Po schválení — NeboAI podpíše aplikáciu pomocou Ed25519 a publikuje ju
- Po zamietnutí — dostanete dôvod a môžete to opraviť a odoslať znova
Cieľový čas kontroly: <24 hodín.
Vydávanie aktualizácií
- Aktualizujte verziu aplikácie:
PUT /api/v1/developer/apps/{id}s novou verziou - Nahrajte nové binárne súbory pre každú platformu
- 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
| Pole | Popis |
|---|---|
category | napr. produktivita, komunikácia, nástroje pre vývojárov |
icon | URL ikony aplikácie |
visibility | public alebo private |
description | Môže byť dlhší/bohatší ako popis v manifeste |
Vývojový postup
Lokálny vývoj
Na lokálny vývoj netreba nič baliť:
- Vytvorte adresár aplikácie:
mkdir -p ~/Library/Application\ Support/Nebo/apps/com.example.myapp - Napíšte
manifest.jsona kód - Zostavte binárny súbor:
go build -o ~/Library/Application\ Support/Nebo/apps/com.example.myapp/binary . - Nebo nový adresár automaticky rozpozná (alebo reštartujte Nebo)
- 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čnosti | Aplikácie | |
|---|---|---|
| Formát | Markdown (SKILL.md) | Skompilovaný binárny súbor (.napp) |
| Beh | Vložené do systémového promptu | Proces v sandboxe cez gRPC |
| Poskytuje | Usmernenie správania, metodika | Nástroje, kanály, panely UI |
| Životnosť | V rámci relácie, vypršanie podľa TTL | Vždy spustené |
| Vytvorenie | Napíšte súbor v Markdowne | Napísať, skompilovať, podpísať, zabaliť |
| Zabezpečenie | Nie sú potrebné žiadne oprávnenia | Sandbox 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).
| Pole | Povinné | Predvolené | Popis |
|---|---|---|---|
name | Áno | — | Jedinečný identifikátor (stane sa z neho slug) |
description | Áno | — | Jednoriadkový popis zobrazený v katalógu zručností |
version | Nie | "1.0.0" | Semver na sledovanie aktualizácií |
author | Nie | — | Autor zručnosti |
priority | Nie | 0 | Vyššie = zhoduje sa skôr (100+ pre kritické prepísania) |
max_turns | Nie | 4 | Počet ťahov nečinnosti pred automatickým vypršaním |
triggers | Nie | [] | Frázy, ktoré túto zručnosť automaticky aktivujú (zhoda podreťazca bez ohľadu na veľkosť písmen) |
tools | Nie | [] | Nástroje, ktoré má táto zručnosť používať (informatívne) |
dependencies | Nie | [] | Ďalšie zručnosti, ktoré musia byť nainštalované |
tags | Nie | [] | Na kategorizáciu a vyhľadávanie |
platform | Nie | [] | 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:
| Akcia | Popis | Príklad |
|---|---|---|
catalog | Zobraziť všetky dostupné zručnosti | skill(action: "catalog") |
load | Aktivovať pre túto reláciu | skill(name: "code-review", action: "load") |
unload | Deaktivovať zručnosť | skill(name: "code-review", action: "unload") |
create | Vytvoriť novú zručnosť na disku | skill(action: "create", content: "...") |
update | Aktualizovať existujúcu zručnosť | skill(name: "my-skill", action: "update", content: "...") |
delete | Odstrániť zručnosť z disku | skill(name: "my-skill", action: "delete") |
Písanie dobrých zručností
Dobrá šablóna zručnosti má:
- Jasný nadpis — povie AI zamestnancovi, v akom režime je
- Základné zásady — nespochybniteľné pravidlá správania
- Metodiku — postup krok za krokom pre bežné situácie
- Príklady — konkrétne vzory od správy používateľa po odpoveď
- 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ť | Priorita | Popis |
|---|---|---|
onboarding | 100 | Privítanie nového používateľa a zber profilu |
best-friend | 50 | Zručnosť osobnosti — uvoľnená, verná, úprimná reč |
debugging | 25 | Systematická metodika ladenia |
api-design | 15 | Osvedčené postupy návrhu RESTful API |
code-review | 10 | Štruktúrovaná kontrola kódu s úrovňami závažnosti |
database-expert | 10 | Návrh databáz, dotazy, optimalizácia |
git-workflow | 10 | Vetvenie v Gite, commity, postupy PR |
security-audit | 10 | Bezpeč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úbor | Služba | Kľúčové RPC |
|---|---|---|
v0/common.proto | (len správy) | 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ždá služba obsahuje RPC HealthCheck a Configure. SDK obe zvládne automaticky.
Typy Proto pre kanály
| Typ správy | Popis |
|---|---|
ChannelSendRequest | Obálka odchádzajúcej správy s message_id, channelId, sender, text, attachments, reply_to, actions, platform_data |
ChannelSendResponse | ID správy platformy pre vlákna |
InboundMessage | Obálka prichádzajúcej správy so všetkými spoločnými poľami + časová pečiatka |
MessageSender | Identita bota (name, role, botId) — doplnená sprostredkovateľom |
Attachment | Príloha súboru/obrázka/zvuku (type, url, filename, size) |
MessageAction | Akcia 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“.