Přehled
Co je Nebo
Nebo je osobní AI asistent pro počítač — neustále běžící AI zaměstnanec, který spravuje váš digitální život. Představte si Nebo jako chytrý telefon: výkonnou platformu, která se díky svým aplikacím stává převratnou.
Sám o sobě je Nebo schopný AI zaměstnanec s pamětí, plánováním, prohlížením webu, správou souborů a přístupem k shellu. Skutečný potenciál ale odemykají aplikace. Stejně jako síla chytrého telefonu pochází z ekosystému aplikací, síla Nebo pochází z aplikací, které rozšiřují, co dokáže.
Co jsou aplikace
Aplikace Nebo jsou samostatné, předkompilované celky s neuvěřitelnými funkcemi. Každá aplikace dává Nebo novou superschopnost — správu kalendáře, třídění e-mailů, sledování projektů, automatizaci domácnosti, finanční analýzu — cokoli si vývojář dokáže představit.
Aplikace poskytují obrovský výkon velmi bezpečným způsobem. Každá aplikace běží v sandboxu s oprávněními, která jsou ve výchozím stavu zakázaná. Má přístup jen k tomu, co deklaruje její manifest a co uživatel schválí.
Rozhraní je ze 100 % konverzační. Uživatelé s aplikacemi nepracují přes samostatné obrazovky nebo nástěnky. Mluví s Nebo a Nebo používá nástroje aplikace, aby věci vyřídil. „Co mám zítra v kalendáři?“ — Nebo zavolá aplikaci kalendáře. „Vytvoř schůzku se Sarah ve 3pm“ — Nebo zavolá aplikaci kalendáře. Uživatel konverzaci nikdy neopustí.
Aplikace mohou volitelně poskytovat UI nastavení — konfigurační panel, který se otevře ve vestavěném okně prohlížeče Nebo. Tady uživatelé zadávají klíče API, zapínají funkce a konfigurují aplikaci. UI nastavení vychází z pole settings v manifestu (Nebo formulář vykreslí automaticky), nebo může aplikace poskytnout vlastní plně přizpůsobené UI přes schopnost ui.
Aplikace nahrazují a rozšiřují vestavěné schopnosti Nebo. Nebo se dodává se základními nástroji platformy (přístup k místnímu kalendáři, snímky obrazovky atd.). Když nainstalujete aplikaci kalendáře, nahradí vestavěný nástroj kalendáře a stane se jeho nadmnožinou — místní + cloud + agregace + kontrola dostupnosti.
Zásada pouze kompilovaného kódu
Nebo vynucuje přísnou zásadu pouze kompilovaných binárních souborů. Všechny aplikace musí být nativní zkompilované spustitelné soubory.
| Stav | Jazyky |
|---|---|
| Podporováno | Go (doporučeno), Rust, C/C++, Zig |
| Odmítnuto | Python, Node.js, Ruby, Java, .NET, shellové skripty |
Zdůvodnění:
- Prevence sebemodifikace AI — AI zaměstnanec s přístupem k shellu by mohl za běhu změnit chování interpretovaného skriptu. Zkompilované binární soubory jsou po podepsání neměnné.
- Integrita podpisu — Podpisy Ed25519 pokrývají surové bajty binárního souboru. Podepsaný binární soubor nelze upravit, aniž by se podpis zneplatnil.
- Vynucení sandboxu — Ověření formátu binárního souboru (magic bytes ELF/Mach-O/PE) je rychlá a spolehlivá brána.
Rychlý start
Instalace SDK
Oficiální SDK řeší veškeré nastavení serveru gRPC, zpracování signálů i přemostění protokolu. Vy jen implementujete rozhraní handlerů.
Go (doporučeno):
go get github.com/neboloop/nebo-sdk-go Rust (již brzy):
# Coming soon
[dependencies]
nebo-sdk = "0.1" C/C++ (již brzy):
# Coming soon — Add as a CMake subdirectory or copy headers from sdk/c/include/ Struktura adresáře aplikace
Aplikace jsou v podadresáři apps/ vašeho datového adresáře 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í seznam minimální aplikace
- Vytvořte
manifest.jsons poliid,name,version,provides - Napište
TOOL.mds popisem, jak má AI zaměstnanec váš nástroj používat - Nainstalujte SDK (
go get github.com/neboloop/nebo-sdk-go) - Implementujte rozhraní handleru pro svou schopnost (
ToolHandler,ChannelHandleratd.) - Zaregistrujte handler a zavolejte
app.Run() - Sestavte nativní binární soubor (
go build -o binary .) - Umístěte binární soubor + manifest.json + TOOL.md do adresáře
apps/<your-app-id>/ - Nebo ji automaticky najde a spustí
Konfigurace
manifest.json
Každá aplikace 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á pole:
| Pole | Popis |
|---|---|
id | Identifikátor v obráceném doménovém tvaru (např. com.mycompany.myapp) |
name | Čitelný název |
version | Řetězec semver |
provides | Alespoň jedna schopnost (viz níže) |
Volitelná pole:
| Pole | Výchozí | Popis |
|---|---|---|
runtime | "local" | "local" nebo "remote" |
protocol | "grpc" | Podporováno je jen "grpc" |
permissions | [] | K čemu aplikace potřebuje přístup |
description | "" | Zobrazuje se v UI |
settings | [] | Konfigurovatelná nastavení (vykreslená v UI nastavení) |
oauth | [] | Požadavky na poskytovatele OAuth (viz část OAuth níže) |
Schopnosti
Deklarujte, co vaše aplikace poskytuje:
| Schopnost | Služba gRPC | Popis |
|---|---|---|
gateway | GatewayService | Směrování modelů LLM |
tool:<name> | ToolService | Pojmenovaný nástroj pro AI zaměstnance |
channel:<name> | ChannelService | Kanál pro zasílání zpráv |
comm | CommService | Komunikace mezi AI zaměstnanci |
ui | UIService | Vlastní UI s HTTP proxy |
schedule | ScheduleService | Vlastní plánování |
vision | ToolService | Zpracování obrazu |
browser | ToolService | Automatizace prohlížeče |
Aplikace může poskytovat více schopností. Může například poskytovat nástroj i panel UI.
Oprávnění
Oprávnění určují, k čemu má aplikace přístup. Ve výchozím stavu je vše zakázané — co není deklarováno, aplikace použít nemůže.
| Předpona | Příklady | Popis |
|---|---|---|
network: | network:outbound, network:* | Přístup k síti |
filesystem: | filesystem:read, filesystem:write | Přístup k souborovému systému |
memory: | memory:read, memory:write | Přístup k paměti AI zaměstnance |
session: | session:read | Konverzační relace |
tool: | tool:shell, tool:file | Používání jiných nástrojů |
shell: | shell:exec | Spouštění příkazů shellu |
channel: | channel:send, channel:* | Operace s kanály |
comm: | comm:send, comm:* | Komunikace mezi AI zaměstnanci |
model: | model:chat | Přístup k modelům AI |
user: | user:token | Příjem uživatelského JWT v požadavcích |
schedule: | schedule:create | Správa úloh cron |
database: | database:query | Přístup k databázi |
storage: | storage:read, storage:write | Trvalé úložiště |
context: | context:read | Přístup ke kontextu AI zaměstnance |
subagent: | subagent:spawn | Operace podagentů |
lane: | lane:enqueue | Operace s lanes |
notification: | notification:send | Push oznámení |
embedding: | embedding:search | Přístup k vektorovým embeddingům |
skill: | skill:invoke | Vyvolávání dovedností |
advisor: | advisor:consult | Přístup k systému poradců |
mcp: | mcp:connect | Přístup k serverům MCP |
voice: | voice:record | Přístup k hlasu/zvuku |
browser: | browser:navigate | Automatizace prohlížeče |
oauth: | oauth:google, oauth:* | Přístup k tokenům OAuth |
settings: | settings:read | Přístup k nastavení |
capability: | capability:register | Registrace schopností |
Podporována jsou zástupná oprávnění: network:* odpovídá každé kontrole oprávnění network:.
Nastavení
Nastavení se zobrazují v UI Nebo v panelu nastavení aplikace. Nebo je ukládá do databáze a při jejich změně je posílá vaší aplikaci přes RPC Configure.
Schéma vašich nastavení je součástí zápisu aplikace v obchodě NeboAI. Aplikace s nenakonfigurovanými povinnými nastaveními mají v UI štítek „Needs Setup“.
| Typ | Popis |
|---|---|
text | Jednořádkové textové pole |
password | Maskované textové pole |
toggle | Logický přepínač zapnuto/vypnuto |
select | Rozbalovací seznam s předdefinovanými možnostmi |
number | Číselné pole |
url | Pole pro URL s ověření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žadavky OAuth
Aplikace mohou deklarovat požadavky na poskytovatele OAuth. Celý tok řeší zprostředkovatel OAuth v Nebo — aplikace dostávají tokeny automaticky přes RPC Configure.
{
"oauth": [
{
"provider": "google",
"scopes": ["https://www.googleapis.com/auth/calendar"]
}
]
} | Pole | Popis |
|---|---|
provider | Poskytovatel OAuth: "google", "microsoft", "github" |
scopes | Pole rozsahů OAuth, které aplikace potřebuje |
Když uživatel aplikaci nainstaluje, Nebo ho vyzve k autorizaci požadovaných rozsahů OAuth. Aplikace dostává obnovené tokeny přes RPC Configure, aniž by sama musela řešit tok OAuth.
Proměnné prostředí
Proces vaší aplikace dostává vyčištěné prostředí. Všechna tajemství jsou odstraněna. Dostanete:
| Proměnná | Hodnota |
|---|---|
NEBO_APP_DIR | Instalační adresář aplikace |
NEBO_APP_SOCK | Cesta k Unixovému socketu, který se má vytvořit |
NEBO_APP_ID | ID aplikace z manifestu |
NEBO_APP_NAME | Název aplikace z manifestu |
NEBO_APP_VERSION | Verze aplikace z manifestu |
NEBO_APP_DATA | Cesta k adresáři data/ aplikace |
PATH | Systémová proměnná PATH (předává se) |
HOME | Domovský adresář uživatele (předává se) |
TMPDIR | Dočasný adresář (předává se) |
Důležité: Váš binární soubor musí vytvořit server gRPC, který naslouchá na Unixovém socketu v NEBO_APP_SOCK. Nebo čeká na objevení tohoto socketu až 10 sekund.
Pořadí spuštění aplikace
- Nebo načte
manifest.jsona ověří ho - Najde spustitelný soubor
binaryneboappv adresáři aplikace - Zkontroluje značku
.quarantined(aplikace v karanténě odmítne spustit) - Kontrola odvolání (jen aplikace distribuované přes NeboAI)
- Ověření podpisu (jen aplikace distribuované přes NeboAI, ve vývoji se přeskakuje)
- Ověření binárního souboru (odmítá symbolické odkazy, skripty, nespustitelné a příliš velké soubory)
- Vyčistí zastaralý socket z předchozího běhu
- Vytvoří adresář
data/pro izolované úložiště - Nastaví soubory logů pro každou aplikaci (
logs/stdout.log,logs/stderr.log) - Spustí binární soubor s vyčištěným prostředím a izolací skupiny procesů
- Čeká na objevení Unixového socketu (exponenciální čekání, maximálně 10 sekund)
- Připojí se přes gRPC po Unixovém socketu
- Vytvoří klienty gRPC pro jednotlivé schopnosti podle
provides - Spustí kontrolu stavu
- Zaregistruje schopnosti u AI zaměstnance (nástroje, brána, komunikace atd.)
Nástrojové aplikace
Deklarujte ve svém manifestu "provides": ["tool:my_tool_name"].
Vzor STRAP
Všechny nástrojové aplikace Nebo musí pro své schéma a směrování provádění používat STRAP (Single Tool Resource Action Pattern). Je to stejný vzor, který Nebo interně používá ke sloučení více než 35 jednotlivých nástrojů do 4 doménových nástrojů — snižuje zátěž kontextu LLM přibližně o 80 %.
Hlavní myšlenka: Místo registrace více nástrojů (get_events, check_availability, suggest_slots) zaregistrujte JEDEN nástroj s poli action (a volitelně resource), která směrují na správný handler.
Příklad s jedním prostředkem (kalendář):
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") Příklad s více prostředky (správce projektů):
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") Pravidla schématu:
- Vždy zahrňte pole
actionjako povinný výčet řetězců - Pole
resource(povinný výčet řetězců) přidejte jen tehdy, když váš nástroj spravuje více odlišných typů prostředků - Všechna ostatní pole jsou parametry specifické pro akci
- Popis výčtu
actionby měl uvádět všechny dostupné akce
Proč na STRAP záleží:
- LLM se vzor směrování
actionnaučí jednou a zobecní ho na všechny operace - Definice nástrojů spotřebují přibližně 6 % kontextu — STRAP to sníží o 80 %
- Nové operace jsou jen doplnění výčtu, ne registrace nových nástrojů
- Funguje stejně u hostovaných i místních modelů
Pří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": []
} Sestavení a instalace:
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/ Příklad v Rustu
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(())
} Pří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é aplikace
Deklarujte "provides": ["channel:my_channel"] a "permissions": ["channel:send"].
Kanálové aplikace přemosťují externí platformy pro zasílání zpráv (Telegram, Discord, Slack atd.) k AI zaměstnanci Nebo. Když uživatel pošle zprávu na externí platformě, vaše aplikace ji streamuje do Nebo přes Receive. Když chce AI zaměstnanec odpovědět, Nebo zavolá Send vaší aplikace.
Jak to funguje
- Nebo zavolá
ID()a získá jedinečný identifikátor vašeho kanálu - Nebo zavolá
Connect()s konfigurací z nastavení vaší aplikace - Nebo otevře stream
Receive()— vaše aplikace posílá příchozí zprávy pokaždé, když uživatel napíše botovi - Příchozí zprávy se směrují do hlavní konverzační lane AI zaměstnance
- Když chce AI zaměstnanec poslat zprávu, Nebo zavolá
Send()s obálkou zprávy v1 - Při vypínání Nebo zavolá
Disconnect()
Obálka zprávy v1
Všechny zprávy kanálu — příchozí i odchozí — používají společnou obálku zprá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 seřazené podle času |
channel_id | {type}:{platform_id} | Směrovatelný identifikátor kanálu |
sender | object | Identita bota — name, role, botId |
text | string | Tělo zprávy |
attachments | array | Soubory, obrázky, zvuk |
reply_to | UUID v7 | ID nadřazené zprávy pro vlákna |
actions | array | Interaktivní tlačítka/klávesnice |
platform_data | bytes | Neprůhledná data předávaná pro funkce konkrétní platformy |
timestamp | ISO 8601 | Nastavuje vydavatel |
Dvouvrstvý návrh: Společná pole (text, attachments, reply_to, actions) pokrývají 90 % zpráv iniciovaných zaměstnancem. Funkce konkrétní platformy patří do platform_data — váš plugin je převádí do nativního formátu platformy a zpět.
Konverzační streamy
Zprávy kanálu se kvůli izolaci směrují přes samostatné konverzační streamy pro každý kanál:
neboai/bot/{botID}/channels/{channelType}/inbound # messages from users → agent
neboai/bot/{botID}/channels/{channelType}/outbound # messages from agent → channel Pří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
}
]
} Další schopnosti
Komunikační aplikace
Deklarujte "provides": ["comm"] a "permissions": ["comm:*"]. Komunikační aplikace umožňují komunikaci mezi AI zaměstnanci.
| Pole | Popis |
|---|---|
from | ID odesílajícího zaměstnance |
to | ID přijímajícího zaměstnance |
topic | Téma/kanál zprávy |
type | "message", "mention", "proposal", "command", "info", "task" |
content | Tělo zprávy |
Klíčové chování:
Registerohlásí tohoto AI zaměstnance v síti i s jeho schopnostmiSubscribe/Unsubscribespravují odběry tématReceivestreamuje příchozí zprávy (streamování ze serveru, stejně jako u kanálů)- Aktivní může být vždy jen jedna komunikační aplikace
Aplikace brány
Aplikace brány směruje požadavky LLM na modely. Deklarujte "provides": ["gateway"] a "permissions": ["network:outbound", "user:token"].
GatewayRequest obsahuje zprávy, nástroje, systémový prompt, maximum tokenů, teplotu a UserContext (token JWT, pokud je uděleno oprávnění user:token).
Typy GatewayEvent:
| Typ | Obsah | Popis |
|---|---|---|
"text" | Část textu | Streamovaný textový token |
"tool_call" | JSON | Model chce zavolat nástroj |
"thinking" | Část textu | Rozšířené přemýšlení/uvažování |
"error" | Chybová zpráva | Něco se pokazilo |
"done" | Prázdné | Stream je dokončený |
Aplikace UI
Aplikace UI poskytuje vlastní konfigurační rozhraní, které se otevírá ve vestavěném okně prohlížeče Nebo. Deklarujte "provides": ["ui"]. Na rozdíl od automatického formuláře nastavení (který Nebo vykreslí z settings ve vašem manifestu) aplikace UI obsluhuje vlastní úplný frontend v HTML/CSS/JS.
Vaše aplikace obsahuje adresář ui/ se statickými webovými soubory (HTML, CSS, JS — obvykle SPA s index.html). Nebo tyto soubory obsluhuje přímo a volání API předává vaší aplikaci přes gRPC.
| Cesta | Mechanismus | Účel |
|---|---|---|
GET /api/v1/apps/{id}/ui/* | Statický souborový server | Obsluhuje soubory z vašeho adresáře ui/ (záložní SPA na index.html) |
ANY /api/v1/apps/{id}/api/* | Proxy gRPC | Předává požadavky HTTP do UIService.HandleRequest() vaší aplikace |
SDK obaluje standardní net/http.ServeMux, takže píšete běžné HTTP handlery v Go — přemostění gRPC SDK řeší automaticky.
Příklad v Go — UI nástěnky:
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, které se předají vašemu handleru mux.
Plánovací aplikace
Plánovací aplikace nahrazuje vestavěný plánovač cron v Nebo. Deklarujte "provides": ["schedule"] a "permissions": ["schedule:create"].
Když se vaše plánovací aplikace spustí, Nebo směruje veškeré plánování přes ni místo výchozího enginu cron. Pokud vaše aplikace spadne, Nebo se automaticky vrátí k vestavěnému enginu.
- Vaše aplikace vlastní stav plánů — když je plánovací aplikace aktivní, Nebo plány neukládá do vlastní databáze
- Standardní CRUD:
Create,Get,List,Update,Delete,Enable,Disable Triggersje RPC se streamováním ze serveru — vaše aplikace pošle zprávu spouštěče pokaždé, když se plán spustí- Aktivní může být vždy jen jedna plánovací aplikace
Aplikace s více schopnostmi
Aplikace může poskytovat více schopností. Například aplikace nástěnky s nástrojem i 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()) Balení
Formát .napp
Pro distribuci přes NeboAI zabalte aplikaci jako soubor .napp (archiv tar.gz):
cd com.example.myapp/
tar -czf myapp-1.0.0.napp manifest.json binary signatures.json TOOL.md Povinné soubory:
| Soubor | Max. velikost | Popis |
|---|---|---|
manifest.json | 1 MB | Metadata aplikace |
binary nebo app | 500 MB | Spustitelný soubor |
signatures.json | 1 MB | Podpisy Ed25519 |
TOOL.md | 1 MB | Pokyny k nástroji pro AI zaměstnance |
Bezpečnostní pravidla při rozbalování:
- Žádné procházení cest (
../se odmítá) - Žádné symbolické odkazy (odmítají se)
- Žádné absolutní cesty (odmítají se)
- Přijímají se jen povolené názvy souborů
Podpisy
NeboAI podepisuje aplikace pomocí 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>"
} Ve vývojovém režimu (bez nakonfigurované URL NeboAI) se ověření podpisu úplně přeskakuje. Pro místní vývoj signatures.json nepotřebujete.
Publikování
Jakmile vaše aplikace funguje místně, publikujte ji přes NeboAI k distribuci všem uživatelům Nebo.
Nastavení účtu vývojáře
- Zaregistrujte si účet NeboAI na
POST /api/v1/owners/register - Přihlaste se a získejte token JWT:
POST /api/v1/owners/login - Vytvořte účet vývojáře:
POST /api/v1/developer/accounts
Postup odeslání
draft → pending_review → [approved] → published
→ [rejected] → draft (fix and resubmit) Krok 1: Vytvořte aplikaci
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ární soubory pro 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ární soubor pro každou platformu: darwin-arm64, darwin-amd64, linux-amd64, linux-arm64.
Krok 3: Odešlete ke kontrole
curl -X POST https://neboai.com/api/v1/developer/apps/{id}/submit \
-H "Authorization: Bearer $TOKEN" Proces kontroly
- Automatická kontrola — binární soubory se prověřují přes VirusTotal
- Kontrola správcem — tým NeboAI zkontroluje metadata, manifest a výsledky prověření
- Po schválení — NeboAI aplikaci podepíše pomocí Ed25519 a zveřejní ji
- Po zamítnutí — dostanete důvod a můžete chybu opravit a odeslat znovu
Cílová doba kontroly: <24 hodin.
Vydávání aktualizací
- Aktualizujte verzi aplikace:
PUT /api/v1/developer/apps/{id}s novou verzí - Nahrajte nové binární soubory pro každou platformu
- Odešlete znovu ke kontrole
Každá aktualizace prochází stejným procesem kontroly. Předchozí verze zůstávají dostupné, dokud není nová verze schválena.
Metadata obchodu
| Pole | Popis |
|---|---|
category | např. productivity, communication, developer-tools |
icon | URL ikony aplikace |
visibility | public nebo private |
description | Může být delší a bohatší než popis v manifestu |
Vývojový postup
Místní vývoj
Pro místní vývoj není potřeba nic balit:
- Vytvořte adresář aplikace:
mkdir -p ~/Library/Application\ Support/Nebo/apps/com.example.myapp - Napište svůj
manifest.jsona kód - Sestavte binární soubor:
go build -o ~/Library/Application\ Support/Nebo/apps/com.example.myapp/binary . - Nebo nový adresář automaticky rozpozná (nebo Nebo restartujte)
- Po změnách kódu znovu sestavte binární soubor — sledování souborů aplikaci restartuje
Zobrazení logů
Výstupy stdout/stderr aplikace se zachytávají do souborů logů pro každou aplikaci:
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á data
Pro všechny soubory, které vaše aplikace potřebuje uchovat, použijte adresář data/ (dostupný také jako proměnná prostředí NEBO_APP_DATA). Tento adresář přečká aktualizace aplikace i karanténu.
Tipy pro ladění
- Pokud se vaše aplikace nespustí, zkontrolujte chyby v
logs/stderr.log - Ujistěte se, že je binární soubor spustitelný (
chmod +x binary) - Ujistěte se, že nasloucháte na cestě Unixového socketu z
NEBO_APP_SOCK - Socket musí být připravený do 10 sekund od spuštění
- Pro úložiště používejte
NEBO_APP_DATA, ne napevno zadané cesty - Ladicí výpisy pište na stderr (zachytávají se do
logs/stderr.log)
Ověření
# 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 Odinstalace
nebo apps uninstall com.example.myapp Dovednosti
Co jsou dovednosti
Dovednosti jsou sady pokynů, které určují, jak se Nebo během konverzace chová. Když je dovednost aktivní, její obsah se vloží přímo do systémového promptu — a řídí tón AI zaměstnance, jeho postup, odborné znalosti v oboru i používání nástrojů v dané relaci.
Dovednosti nejsou kód. Jsou to dokumenty v Markdownu s metadaty YAML. Žádná kompilace, žádný binární soubor, žádné gRPC. Dovednost je soubor SKILL.md v adresáři. Nic víc.
Dovednosti jsou kontextové a dočasné. Aktivují se, když jsou relevantní (shodou se spouštěčem nebo ručním načtením), vydrží několik tahů a vyprší, když už nejsou potřeba. Kontext AI zaměstnance tak zůstává štíhlý — v promptu jsou jen pokyny, na kterých právě záleží.
Dovednosti doplňují aplikace. Aplikace poskytují spustitelné schopnosti (nástroje, kanály, brány). Dovednosti poskytují pokyny pro orchestraci — jak tyto nástroje efektivně používat. Aplikace kalendáře dává Nebo možnost číst a zapisovat události. Dovednost „příprava na schůzku“ říká Nebo, jak se na schůzky připravit pomocí této aplikace kalendáře, e-mailu a vyhledávání na webu dohromady.
Dovednosti vs. aplikace
| Dovednosti | Aplikace | |
|---|---|---|
| Formát | Markdown (SKILL.md) | Zkompilovaný binární soubor (.napp) |
| Běh | Vkládá se do systémového promptu | Izolovaný proces přes gRPC |
| Poskytuje | Pokyny k chování, postup | Nástroje, kanály, panely UI |
| Životnost | V rámci relace, vypršení podle TTL | Běží stále |
| Vytvoření | Napsat soubor v Markdownu | Napsat, zkompilovat, podepsat, zabalit |
| Zabezpečení | Nejsou potřeba žádná oprávnění | Sandbox se vším zakázaným ve výchozím stavu |
Rychlý start
Vytvořte ve složce dovedností Nebo adresář se souborem SKILL.md:
~/Library/Application Support/Nebo/skills/ # macOS
~/.config/nebo/skills/ # Linux
%AppData%\Nebo\skills\ # Windows mkdir -p ~/.config/nebo/skills/my-skill Napiš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ář dovedností pomocí fsnotify. Vaše dovednost je k dispozici okamžitě — restart není potřeba. Řekněte něco, co odpovídá spouštěči, a aktivuje se automaticky.
Nebo požádejte Nebo přímo: „Vytvoř dovednost pro psaní blogových příspěvků“ — Nebo soubor SKILL.md napíše za vás.
Formát SKILL.md
Každá dovednost je jediný soubor SKILL.md o dvou částech: úvodní blok YAML mezi značkami --- a tělo v Markdownu (samotné pokyny vkládané do systémového promptu).
| Pole | Povinné | Výchozí | Popis |
|---|---|---|---|
name | Ano | — | Jedinečný identifikátor (stává se slugem) |
description | Ano | — | Jednořádkový popis zobrazený v katalogu dovedností |
version | Ne | "1.0.0" | Semver pro sledování aktualizací |
author | Ne | — | Autor dovednosti |
priority | Ne | 0 | Vyšší = shoduje se dřív (100+ pro kritická přepsání) |
max_turns | Ne | 4 | Počet tahů nečinnosti před automatickým vypršením |
triggers | Ne | [] | Fráze, které tuto dovednost automaticky aktivují (shoda podřetězce bez ohledu na velikost písmen) |
tools | Ne | [] | Nástroje, které tato dovednost očekává (informativní) |
dependencies | Ne | [] | Další dovednosti, které musí být nainstalované |
tags | Ne | [] | Pro kategorizaci a vyhledávání |
platform | Ne | [] | Podporované platformy: macos, linux, windows (prázdné = všechny) |
Jak se dovednosti aktivují
Dovednosti se aktivují ve dvou fázích: nejdřív nápověda, pak vyvolání.
Fáze 1: Shoda se spouštěčem — Pokaždé, když uživatel pošle zprávu, Nebo prohledá všechny registrované dovednosti a hledá shodu se spouštěči. Odpovídající dovednosti se objeví jako nápovědy v systémovém promptu. AI zaměstnanec nápovědu vidí a rozhodne, zda dovednost vyvolá.
Fáze 2: Vyvolání — AI zaměstnanec vyvolá dovednost voláním:
skill(name: "code-review") Tím se jako výsledek nástroje vrátí celá šablona SKILL.md, vyvolání se zaznamená a šablona se v dalších tazích znovu vkládá do systémového promptu.
TTL a vypršení:
- Automaticky spárované dovednosti: 4 tahy nečinnosti (nastavitelné přes
max_turns) - Ručně načtené dovednosti: 6 tahů nečinnosti
- Opětovné vyvolání časovač vynuluje
- Pevný strop: maximálně 4 aktivní dovednosti na relaci
- Rozpočet tokenů: obsah aktivních dovedností dohromady je omezený na 16,000 znaků
Správa dovedností
AI zaměstnanec může dovednosti spravovat pomocí nástroje skill:
| Akce | Popis | Příklad |
|---|---|---|
catalog | Vypsat všechny dostupné dovednosti | skill(action: "catalog") |
load | Aktivovat pro tuto relaci | skill(name: "code-review", action: "load") |
unload | Deaktivovat dovednost | skill(name: "code-review", action: "unload") |
create | Vytvořit novou dovednost na disku | skill(action: "create", content: "...") |
update | Aktualizovat existující dovednost | skill(name: "my-skill", action: "update", content: "...") |
delete | Smazat dovednost z disku | skill(name: "my-skill", action: "delete") |
Psaní dobrých dovedností
Dobrá šablona dovednosti obsahuje:
- Jasný nadpis — říká AI zaměstnanci, v jakém je režimu
- Základní zásady — nepřekročitelná pravidla chování
- Postup — krok za krokem pro běžné situace
- Příklady — konkrétní vzory zpráv uživatele a odpovědí
- Antivzory — co NEDĚLAT (modely se dobře učí z negativních příkladů)
Tip: Každá dovednost by měla dělat jednu věc dobře. Nevytvářejte dovednost „obecné programování“ — vytvořte code-review, debugging a api-design jako samostatné dovednosti. AI zaměstnanec jich může mít aktivních několik současně.
Přibalené dovednosti
Nebo se dodává s přibalenými dovednostmi pro běžné případy použití:
| Dovednost | Priorita | Popis |
|---|---|---|
onboarding | 100 | Uvítání nového uživatele a sběr profilu |
best-friend | 50 | Dovednost osobnosti — uvolněná, loajální, upřímná řeč |
debugging | 25 | Systematický postup ladění |
api-design | 15 | Osvědčené postupy návrhu RESTful API |
code-review | 10 | Strukturovaná revize kódu s úrovněmi závažnosti |
database-expert | 10 | Návrh databází, dotazy, optimalizace |
git-workflow | 10 | Větvení v Gitu, commity, postupy pro PR |
security-audit | 10 | Bezpečnostní analýza a odhalování zranitelností |
Slouží jako užitečné výchozí nastavení i jako referenční implementace pro tvorbu vlastních dovedností.
Reference
Soubory proto
Soubory proto jsou v proto/apps/v0/. SDK obsahují předgenerovaný kód, takže pro běžný vývoj nepotřebujete protoc.
| Soubor | Služba | Klíčová RPC |
|---|---|---|
v0/common.proto | (jen zprá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 obě řeší automaticky.
Typy proto pro kanály
| Typ zprávy | Popis |
|---|---|
ChannelSendRequest | Obálka odchozí zprávy s message_id, channelId, sender, text, attachments, reply_to, actions, platform_data |
ChannelSendResponse | ID zprávy na platformě pro vlákna |
InboundMessage | Obálka příchozí zprávy se všemi společnými poli + časovým razítkem |
MessageSender | Identita bota (name, role, botId) — doplňuje zprostředkovatel |
Attachment | Příloha se souborem/obrázkem/zvukem (type, url, filename, size) |
MessageAction | Akce interaktivního tlačítka/klávesnice (label, callback_id) |
Identita a role botů
Boti Nebo mají model identity se třemi osami:
- creature — Čím bot je (archetyp): „Bystrý stratég“, „Pečlivý výzkumník“
- role — Jaký má vztah k uživateli: „Přítel“, „COO“, „Mentor“
- vibe — Jeho energie (styl komunikace): „V klidu, ale s názorem“, „Vřelý a povzbuzující“
Když váš kanálový plugin přijme odchozí zprávu, pole sender obsahuje name a role bota. Podle nich naformátujte zobrazované jméno pro svou platformu. Role není pracovní pozice — popisuje vztah. „Přítel“, „Syn“ a „Mentor“ jsou platné role stejně jako „COO“ a „DevLead“.