NeboAI
NeboAI
Почати

Створюйте застосунки для Nebo

Дайте своєму ШІ нові суперсили. Інструменти, канали, шлюзи, панелі інтерфейсу — усе, що можна уявити, скомпільоване в нативний виконуваний файл.

Огляд

Що таке Nebo

Nebo — це персональний десктопний ШІ-асистент: ШІ-співробітник, що працює постійно й керує вашим цифровим життям. Думайте про Nebo так само, як про смартфон: це потужна платформа, яка стає по-справжньому корисною завдяки своїм застосункам.

Сам по собі Nebo — здібний ШІ-співробітник із пам’яттю, плануванням, переглядом вебсторінок, керуванням файлами й доступом до командного рядка. Але справжні можливості відкривають застосунки. Як сила смартфона — в його екосистемі застосунків, так і сила Nebo — в застосунках, що розширюють його можливості.

Що таке застосунки

Застосунки Nebo — це самодостатні попередньо скомпільовані модулі з неймовірною функціональністю. Кожен застосунок дає Nebo нову суперсилу — керування календарем, сортування пошти, відстеження проєктів, автоматизацію дому, фінансовий аналіз — усе, що може уявити розробник.

Застосунки дають неймовірні можливості в дуже безпечний спосіб. Кожен застосунок працює в пісочниці з дозволами, забороненими за замовчуванням. Він має доступ лише до того, що оголошено в його маніфесті й схвалено користувачем.

Інтерфейс на 100% розмовний. Користувачі не взаємодіють із застосунками через окремі екрани чи панелі. Вони говорять із Nebo, а Nebo використовує інструменти застосунку, щоб виконати роботу. «Що в мене в календарі на завтра?» — Nebo звертається до застосунку календаря. «Створи зустріч із Сарою о 15:00» — Nebo звертається до застосунку календаря. Користувач ніколи не виходить із розмови.

Застосунки можуть за бажанням мати інтерфейс налаштувань — панель конфігурації, що відкривається у вбудованому вікні браузера Nebo. Тут користувачі вводять ключі API, вмикають функції й налаштовують застосунок. Інтерфейс налаштувань будується з масиву settings у маніфесті (Nebo автоматично відображає форму), або застосунок може надати власний повністю кастомний інтерфейс через можливість ui.

Застосунки замінюють і розширюють вбудовані можливості Nebo. Nebo постачається з базовими інструментами платформи (доступ до локального календаря, знімки екрана тощо). Коли ви встановлюєте застосунок календаря, він замінює вбудований інструмент календаря й стає його розширеною версією — локальний + хмарний + агрегація + перевірка зайнятості.

Політика лише скомпільованих файлів

Nebo дотримується суворої політики лише скомпільованих виконуваних файлів. Усі застосунки мають бути нативними скомпільованими виконуваними файлами.

СтатусМови
ПідтримуютьсяGo (рекомендовано), Rust, C/C++, Zig
ВідхиляютьсяPython, Node.js, Ruby, Java, .NET, скрипти оболонки

Обґрунтування:

  • Запобігання самомодифікації ШІ — ШІ-співробітник із доступом до командного рядка міг би змінити поведінку інтерпретованого скрипту під час виконання. Скомпільовані виконувані файли незмінні після підписання.
  • Цілісність підпису — підписи Ed25519 охоплюють сирі байти виконуваного файлу. Підписаний файл не можна змінити, не зробивши підпис недійсним.
  • Захист пісочниці — перевірка формату виконуваного файлу (магічні байти ELF/Mach-O/PE) — швидкий і надійний фільтр.

Швидкий старт

Встановіть SDK

Офіційні SDK беруть на себе все налаштування gRPC-сервера, обробку сигналів і зв’язок протоколів. Вам потрібно лише реалізувати інтерфейси обробників.

Go (рекомендовано):

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

Rust (незабаром):

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

C/C++ (незабаром):

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

Структура каталогу застосунку

Застосунки зберігаються в підкаталозі apps/ вашого каталогу даних 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)

Контрольний список мінімального застосунку

  1. Створіть manifest.json з id, name, version, provides
  2. Напишіть TOOL.md з описом того, як ШІ-співробітник має використовувати ваш інструмент
  3. Встановіть SDK (go get github.com/neboloop/nebo-sdk-go)
  4. Реалізуйте інтерфейс обробника для своєї можливості (ToolHandler, ChannelHandler тощо)
  5. Зареєструйте обробник і викличте app.Run()
  6. Зберіть нативний виконуваний файл (go build -o binary .)
  7. Покладіть виконуваний файл + manifest.json + TOOL.md у каталог apps/<your-app-id>/
  8. Nebo автоматично знаходить і запускає його

Конфігурація

manifest.json

Кожному застосунку потрібен 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
        }
    ]
}

Обов’язкові поля:

ПолеОпис
idІдентифікатор у форматі зворотного домену (наприклад, com.mycompany.myapp)
nameЗрозуміла людині назва
versionРядок Semver
providesПринаймні одна можливість (див. нижче)

Необов’язкові поля:

ПолеЗа замовчуваннямОпис
runtime"local""local" або "remote"
protocol"grpc"Підтримується лише "grpc"
permissions[]До чого застосунку потрібен доступ
description""Показується в інтерфейсі
settings[]Налаштовувані параметри (відображаються в інтерфейсі налаштувань)
oauth[]Вимоги до провайдера OAuth (див. розділ OAuth нижче)

Можливості

Оголосіть, що надає ваш застосунок:

МожливістьgRPC-сервісОпис
gatewayGatewayServiceМаршрутизація моделей LLM
tool:<name>ToolServiceІменований інструмент для ШІ-співробітника
channel:<name>ChannelServiceКанал обміну повідомленнями
commCommServiceЗв’язок між ШІ-співробітниками
uiUIServiceКастомний інтерфейс з HTTP-проксі
scheduleScheduleServiceКастомне планування
visionToolServiceОбробка зображень
browserToolServiceАвтоматизація браузера

Застосунок може надавати кілька можливостей. Наприклад, застосунок може надавати і інструмент, і панель інтерфейсу.

Дозволи

Дозволи визначають, до чого застосунок має доступ. За замовчуванням усе заборонено — якщо дозвіл не оголошено, застосунок не може ним скористатися.

ПрефіксПрикладиОпис
network:network:outbound, network:*Доступ до мережі
filesystem:filesystem:read, filesystem:writeДоступ до файлової системи
memory:memory:read, memory:writeДоступ до пам’яті ШІ-співробітника
session:session:readСесії розмов
tool:tool:shell, tool:fileВикористання інших інструментів
shell:shell:execВиконання команд оболонки
channel:channel:send, channel:*Операції з каналами
comm:comm:send, comm:*Зв’язок між ШІ-співробітниками
model:model:chatДоступ до моделей ШІ
user:user:tokenОтримання JWT користувача в запитах
schedule:schedule:createКерування cron-завданнями
database:database:queryДоступ до бази даних
storage:storage:read, storage:writeПостійне сховище
context:context:readДоступ до контексту ШІ-співробітника
subagent:subagent:spawnОперації з субагентами
lane:lane:enqueueОперації з лініями
notification:notification:sendPush-сповіщення
embedding:embedding:searchДоступ до векторних ембедингів
skill:skill:invokeВиклик навичок
advisor:advisor:consultДоступ до системи радників
mcp:mcp:connectДоступ до MCP-серверів
voice:voice:recordДоступ до голосу й аудіо
browser:browser:navigateАвтоматизація браузера
oauth:oauth:google, oauth:*Доступ до токенів OAuth
settings:settings:readДоступ до налаштувань
capability:capability:registerРеєстрація можливостей

Підтримуються дозволи із символом підстановки: network:* відповідає будь-якій перевірці дозволу network:.

Налаштування

Налаштування з’являються в інтерфейсі Nebo на панелі налаштувань застосунку. Nebo зберігає їх у базі даних і надсилає вашому застосунку через RPC Configure, коли вони змінюються.

Ваша схема налаштувань входить до опису застосунку в магазині NeboAI. Застосунки з неналаштованими обов’язковими параметрами показують в інтерфейсі позначку «Потребує налаштування».

ТипОпис
textОднорядкове текстове поле
passwordПриховане текстове поле
toggleЛогічний перемикач увімк./вимк.
selectВипадний список із наперед заданими варіантами
numberЧислове поле
urlПоле URL з перевіркою
{
    "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"}
    ]
}

Вимоги OAuth

Застосунки можуть оголошувати вимоги до провайдера OAuth. Брокер OAuth у Nebo бере на себе весь процес — застосунки автоматично отримують токени через RPC Configure.

{
    "oauth": [
        {
            "provider": "google",
            "scopes": ["https://www.googleapis.com/auth/calendar"]
        }
    ]
}
ПолеОпис
providerПровайдер OAuth: "google", "microsoft", "github"
scopesМасив областей доступу OAuth, потрібних застосунку

Коли користувач встановлює застосунок, Nebo пропонує йому авторизувати потрібні області доступу OAuth. Застосунок отримує оновлені токени через RPC Configure, не обробляючи процес OAuth самостійно.

Змінні середовища

Процес вашого застосунку отримує очищене середовище. Усі секрети вилучено. Ви отримуєте:

ЗміннаЗначення
NEBO_APP_DIRКаталог встановлення застосунку
NEBO_APP_SOCKШлях до Unix-сокета, який треба створити
NEBO_APP_IDID застосунку з маніфесту
NEBO_APP_NAMEНазва застосунку з маніфесту
NEBO_APP_VERSIONВерсія застосунку з маніфесту
NEBO_APP_DATAШлях до каталогу data/ застосунку
PATHСистемний PATH (передається без змін)
HOMEДомашній каталог користувача (передається без змін)
TMPDIRТимчасовий каталог (передається без змін)

Важливо: ваш виконуваний файл має створити gRPC-сервер, що слухає Unix-сокет за адресою NEBO_APP_SOCK. Nebo чекає на появу цього сокета до 10 секунд.

Послідовність запуску застосунку

  1. Nebo читає manifest.json і перевіряє його
  2. Знаходить виконуваний файл binary або app у каталозі застосунку
  3. Перевіряє наявність маркера .quarantined (відмовляється запускати застосунки в карантині)
  4. Перевірка відкликання (лише для застосунків, поширюваних через NeboAI)
  5. Перевірка підпису (лише для застосунків, поширюваних через NeboAI; пропускається в режимі розробки)
  6. Перевірка виконуваного файлу (відхиляє символьні посилання, скрипти, невиконувані та завеликі файли)
  7. Прибирає застарілий сокет від попереднього запуску
  8. Створює каталог data/ для ізольованого сховища
  9. Налаштовує журнали для кожного застосунку (logs/stdout.log, logs/stderr.log)
  10. Запускає виконуваний файл з очищеним середовищем та ізоляцією групи процесів
  11. Чекає на появу Unix-сокета (експоненційна затримка, максимум 10 секунд)
  12. Підключається через gRPC по Unix-сокету
  13. Створює gRPC-клієнти для конкретних можливостей на основі provides
  14. Виконує перевірку стану
  15. Реєструє можливості в ШІ-співробітника (інструменти, шлюз, comm тощо)

Застосунки-інструменти

Оголосіть "provides": ["tool:my_tool_name"] у своєму маніфесті.

Патерн STRAP

Усі застосунки-інструменти Nebo мають використовувати STRAP (Single Tool Resource Action Pattern) для своєї схеми й маршрутизації виконання. Це той самий патерн, який Nebo використовує всередині, щоб об’єднати понад 35 окремих інструментів у 4 доменні інструменти — це зменшує навантаження на контекст LLM приблизно на 80%.

Основна ідея: замість реєстрації кількох інструментів (get_events, check_availability, suggest_slots) зареєструйте ОДИН інструмент із полями action (і за потреби resource), які спрямовують до потрібного обробника.

Приклад з одним ресурсом (календар):

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

Приклад із кількома ресурсами (менеджер проєктів):

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

Правила схеми:

  1. Завжди додавайте поле action як обов’язковий рядковий enum
  2. Додавайте поле resource (обов’язковий рядковий enum), лише якщо ваш інструмент керує кількома різними типами ресурсів
  3. Усі інші поля — параметри конкретної дії
  4. В описі enum action мають бути перелічені всі доступні дії

Чому STRAP важливий:

  • LLM один раз засвоюють патерн маршрутизації за action і узагальнюють його на всі операції
  • Визначення інструментів займають ~6% контексту — STRAP скорочує це на 80%
  • Нові операції — це лише нові значення enum, а не реєстрація нових інструментів
  • Працює однаково з хмарними й локальними моделями

Приклад на Go — інструмент «Калькулятор»

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

Збирання й встановлення:

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/

Приклад на 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(())
}

Приклад на 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;
}

Застосунки-канали

Оголосіть "provides": ["channel:my_channel"] і "permissions": ["channel:send"].

Застосунки-канали з’єднують зовнішні платформи обміну повідомленнями (Telegram, Discord, Slack тощо) з ШІ-співробітником Nebo. Коли користувач надсилає повідомлення на зовнішній платформі, ваш застосунок передає його потоком у Nebo через Receive. Коли ШІ-співробітник хоче відповісти, Nebo викликає Send вашого застосунку.

Як це працює

  1. Nebo викликає ID(), щоб отримати унікальний ідентифікатор вашого каналу
  2. Nebo викликає Connect() з конфігурацією з налаштувань вашого застосунку
  3. Nebo відкриває потік Receive() — ваш застосунок надсилає вхідні повідомлення щоразу, коли користувач пише боту
  4. Вхідні повідомлення спрямовуються в основну лінію розмови ШІ-співробітника
  5. Коли ШІ-співробітник хоче надіслати повідомлення, Nebo викликає Send() з конвертом повідомлення v1
  6. Під час завершення роботи Nebo викликає Disconnect()

Конверт повідомлення v1

Усі повідомлення каналів — вхідні й вихідні — використовують спільний конверт повідомлення:

{
  "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"
}
ПолеТипОпис
message_idUUID v7Унікальний ID, упорядкований за часом
channel_id{type}:{platform_id}Ідентифікатор каналу для маршрутизації
senderobjectІдентичність бота — name, role, botId
textstringТіло повідомлення
attachmentsarrayФайли, зображення, аудіо
reply_toUUID v7ID батьківського повідомлення для гілок
actionsarrayІнтерактивні кнопки й клавіатури
platform_databytesНепрозора передача даних для функцій конкретної платформи
timestampISO 8601Встановлює видавець

Дворівнева архітектура: спільні поля (text, attachments, reply_to, actions) покривають 90% повідомлень, ініційованих співробітником. Функції конкретної платформи передаються в platform_data — ваш плагін перетворює їх у нативний формат платформи й назад.

Потоки розмов

Повідомлення каналів передаються окремими потоками розмов для кожного каналу задля ізоляції:

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

Приклад на Go — канал 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
        }
    ]
}

Більше можливостей

Застосунок Comm

Оголосіть "provides": ["comm"] і "permissions": ["comm:*"]. Застосунки Comm забезпечують зв’язок між ШІ-співробітниками.

ПолеОпис
fromID співробітника-відправника
toID співробітника-отримувача
topicТема чи канал повідомлення
type"message", "mention", "proposal", "command", "info", "task"
contentТіло повідомлення

Основна поведінка:

  • Register оголошує цього ШІ-співробітника в мережі разом з його можливостями
  • Subscribe/Unsubscribe керують підписками на теми
  • Receive передає вхідні повідомлення потоком (серверний потік, як у каналах)
  • Одночасно може бути активним лише один застосунок Comm

Застосунок-шлюз

Застосунок-шлюз спрямовує запити LLM до моделей. Оголосіть "provides": ["gateway"] і "permissions": ["network:outbound", "user:token"].

GatewayRequest містить повідомлення, інструменти, системний промпт, максимальну кількість токенів, температуру й UserContext (токен JWT, якщо надано дозвіл user:token).

Типи GatewayEvent:

ТипВмістОпис
"text"Фрагмент текстуТокен тексту в потоці
"tool_call"JSONМодель хоче викликати інструмент
"thinking"Фрагмент текстуРозширене обдумування й міркування
"error"Повідомлення про помилкуЩось пішло не так
"done"ПорожньоПотік завершено

Застосунок UI

Застосунок UI надає кастомний інтерфейс конфігурації, що відкривається у вбудованому вікні браузера Nebo. Оголосіть "provides": ["ui"]. На відміну від автоматичної форми налаштувань (яку Nebo відображає з settings вашого маніфесту), застосунок UI віддає власний повноцінний фронтенд на HTML/CSS/JS.

Ваш застосунок постачається з каталогом ui/, що містить статичні вебресурси (HTML, CSS, JS — зазвичай SPA з index.html). Nebo віддає ці файли напряму й проксіює виклики API до вашого застосунку через gRPC.

ШляхМеханізмПризначення
GET /api/v1/apps/{id}/ui/*Сервер статичних файлівВіддає файли з вашого каталогу ui/ (для SPA — резервний перехід на index.html)
ANY /api/v1/apps/{id}/api/*gRPC-проксіПроксіює HTTP-запити до UIService.HandleRequest() вашого застосунку

SDK обгортає стандартний net/http.ServeMux, тож ви пишете звичайні HTTP-обробники Go — SDK автоматично бере на себе зв’язок із gRPC.

Приклад на Go — інтерфейс панелі:

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

Ваш ui/index.html робитиме виклики fetch до /api/v1/apps/com.example.dashboard/api/status, які проксіюються до вашого обробника mux.

Застосунок розкладу

Застосунок розкладу замінює вбудований планувальник cron у Nebo. Оголосіть "provides": ["schedule"] і "permissions": ["schedule:create"].

Коли ваш застосунок розкладу запускається, Nebo спрямовує все планування через ваш застосунок замість стандартного рушія cron. Якщо ваш застосунок аварійно завершиться, Nebo автоматично повернеться до вбудованого рушія.

  • Ваш застосунок володіє станом розкладу — коли застосунок розкладу активний, Nebo не зберігає розклади у власній БД
  • Стандартний CRUD: Create, Get, List, Update, Delete, Enable, Disable
  • Triggers — це RPC із серверним потоком: ваш застосунок надсилає повідомлення тригера щоразу, коли спрацьовує розклад
  • Одночасно може бути активним лише один застосунок розкладу

Застосунки з кількома можливостями

Застосунок може надавати кілька можливостей. Наприклад, застосунок панелі з інструментом та інтерфейсом:

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

Пакування

Формат .napp

Для поширення через NeboAI запакуйте свій застосунок у файл .napp (архів tar.gz):

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

Обов’язкові файли:

ФайлМакс. розмірОпис
manifest.json1 MBМетадані застосунку
binary або app500 MBВиконуваний файл
signatures.json1 MBПідписи Ed25519
TOOL.md1 MBІнструкції щодо інструменту для ШІ-співробітника

Правила безпеки під час розпакування:

  • Без обходу шляхів (../ відхиляється)
  • Без символьних посилань (відхиляються)
  • Без абсолютних шляхів (відхиляються)
  • Приймаються лише дозволені імена файлів

Підписи

NeboAI підписує застосунки за допомогою Ed25519. Формат 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>"
}

У режимі розробки (URL NeboAI не налаштовано) перевірка підпису повністю пропускається. Для локальної розробки signatures.json не потрібен.

Публікація

Коли ваш застосунок працює локально, опублікуйте його через NeboAI, щоб поширити серед усіх користувачів Nebo.

Налаштування акаунта розробника

  1. Зареєструйте акаунт NeboAI через POST /api/v1/owners/register
  2. Увійдіть, щоб отримати токен JWT: POST /api/v1/owners/login
  3. Створіть акаунт розробника: POST /api/v1/developer/accounts

Процес подання

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

Крок 1: створіть застосунок

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

Крок 2: завантажте виконувані файли для платформ

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"

Завантажте по одному виконуваному файлу на платформу: darwin-arm64, darwin-amd64, linux-amd64, linux-arm64.

Крок 3: надішліть на перевірку

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

Процес перевірки

  1. Автоматичне сканування — виконувані файли скануються через VirusTotal
  2. Перевірка адміністратором — команда NeboAI перевіряє метадані, маніфест і результати сканування
  3. У разі схвалення — NeboAI підписує застосунок за допомогою Ed25519 і публікує його
  4. У разі відхилення — ви отримуєте причину й можете виправити та надіслати повторно

Цільовий час перевірки: <24 годин.

Випуск оновлень

  1. Оновіть версію застосунку: PUT /api/v1/developer/apps/{id} з новою версією
  2. Завантажте нові виконувані файли для кожної платформи
  3. Знову надішліть на перевірку

Кожне оновлення проходить той самий процес перевірки. Попередні версії залишаються доступними, доки нову версію не схвалять.

Метадані магазину

ПолеОпис
categoryнаприклад, productivity, communication, developer-tools
iconURL значка застосунку
visibilitypublic або private
descriptionМоже бути довшим і детальнішим, ніж опис у маніфесті

Робочий процес розробки

Локальна розробка

Для локальної розробки пакування не потрібне:

  1. Створіть каталог застосунку:
    mkdir -p ~/Library/Application\ Support/Nebo/apps/com.example.myapp
  2. Напишіть свій manifest.json і код
  3. Зберіть бінарний файл:
    go build -o ~/Library/Application\ Support/Nebo/apps/com.example.myapp/binary .
  4. Nebo автоматично виявляє новий каталог (або перезапустіть Nebo)
  5. Після змін у коді перезберіть виконуваний файл — спостерігач за файлами перезапустить застосунок

Перегляд журналів

stdout/stderr застосунку записуються в окремі журнали для кожного застосунку:

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

Постійні дані

Використовуйте каталог data/ (також доступний через змінну середовища NEBO_APP_DATA) для будь-яких файлів, які ваш застосунок має зберігати. Цей каталог зберігається під час оновлень застосунку й карантину.

Поради з налагодження

  • Якщо ваш застосунок не запускається, перевірте logs/stderr.log на помилки
  • Переконайтеся, що файл виконуваний (chmod +x binary)
  • Переконайтеся, що ви слухаєте шлях Unix-сокета з NEBO_APP_SOCK
  • Сокет має бути готовий протягом 10 секунд після запуску
  • Використовуйте NEBO_APP_DATA для зберігання, а не жорстко задані шляхи
  • Виводьте налагоджувальні журнали в stderr (вони записуються в logs/stderr.log)

Перевірка

# 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

Видалення

nebo apps uninstall com.example.myapp

Навички

Що таке навички

Навички — це набори інструкцій, що визначають, як Nebo поводиться під час розмови. Коли навичка активна, її вміст вставляється безпосередньо в системний промпт — і визначає тон ШІ-співробітника, його методологію, експертизу в предметній галузі та використання інструментів у цій сесії.

Навички — це не код. Це документи Markdown з метаданими YAML. Без компіляції, без виконуваного файлу, без gRPC. Навичка — це файл SKILL.md у каталозі. От і все.

Навички контекстні й тимчасові. Вони активуються, коли доречні (за збігом тригера або ручним завантаженням), діють кілька ходів і завершуються, коли більше не потрібні. Так контекст ШІ-співробітника залишається компактним — у промпті лише ті вказівки, що важливі саме зараз.

Навички доповнюють застосунки. Застосунки дають виконувані можливості (інструменти, канали, шлюзи). Навички дають вказівки з оркестрації — як ефективно користуватися цими інструментами. Застосунок календаря дає Nebo змогу читати й записувати події. Навичка «підготовка до зустрічі» підказує Nebo, як готуватися до зустрічей, використовуючи разом цей застосунок календаря, пошту й вебпошук.

Навички й застосунки

НавичкиЗастосунки
ФорматMarkdown (SKILL.md)Скомпільований виконуваний файл (.napp)
Середовище виконанняВставляється в системний промптІзольований процес через gRPC
НадаєПоведінкові вказівки, методологіюІнструменти, канали, панелі інтерфейсу
ТривалістьУ межах сесії, завершення за TTLПрацює постійно
СтворенняНаписати файл MarkdownНаписати, скомпілювати, підписати, запакувати
БезпекаДозволи не потрібніПісочниця, де все заборонено за замовчуванням

Швидкий старт

Створіть каталог у папці навичок Nebo з файлом SKILL.md:

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

Напишіть 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 стежить за каталогом навичок через fsnotify. Ваша навичка доступна одразу — перезапуск не потрібен. Скажіть щось, що збігається з тригером, і вона активується автоматично.

Або попросіть Nebo напряму: «Створи навичку для написання дописів у блог» — Nebo напише файл SKILL.md за вас.

Формат SKILL.md

Кожна навичка — це один файл SKILL.md із двох частин: YAML-фронтматер між маркерами --- і тіло Markdown (власне інструкції, що вставляються в системний промпт).

ПолеОбов’язковеЗа замовчуваннямОпис
nameТак—Унікальний ідентифікатор (стає slug)
descriptionТак—Однорядковий опис, що показується в каталозі навичок
versionНі"1.0.0"Semver для відстеження оновлень
authorНі—Автор навички
priorityНі0Вище = перевіряється першим (100+ для критичних перевизначень)
max_turnsНі4Кількість ходів без активності до автоматичного завершення
triggersНі[]Фрази, що автоматично активують цю навичку (пошук підрядка без урахування регістру)
toolsНі[]Інструменти, якими ця навичка збирається користуватися (для довідки)
dependenciesНі[]Інші навички, які мають бути встановлені
tagsНі[]Для категоризації й пошуку
platformНі[]Підтримувані платформи: macos, linux, windows (порожньо = усі)

Як активуються навички

Навички активуються у дві фази: підказка, потім виклик.

Фаза 1: збіг тригерів — щоразу, коли користувач надсилає повідомлення, Nebo перевіряє всі зареєстровані навички на збіг тригерів. Навички, що збіглися, з’являються як підказки в системному промпті. ШІ-співробітник бачить підказку й вирішує, чи викликати навичку.

Фаза 2: виклик — ШІ-співробітник викликає навичку так:

skill(name: "code-review")

Це повертає повний шаблон SKILL.md як результат інструменту, фіксує виклик і знову вставляє шаблон у системний промпт у наступних ходах.

TTL і завершення:

  • Навички, активовані автоматично: 4 ходи без активності (налаштовується через max_turns)
  • Навички, завантажені вручну: 6 ходів без активності
  • Повторний виклик скидає таймер
  • Жорстке обмеження: максимум 4 активні навички на сесію
  • Бюджет токенів: сукупний вміст активних навичок обмежено 16,000 символами

Керування навичками

ШІ-співробітник може керувати навичками через інструмент skill:

ДіяОписПриклад
catalogПоказати всі доступні навичкиskill(action: "catalog")
loadАктивувати для цієї сесіїskill(name: "code-review", action: "load")
unloadДеактивувати навичкуskill(name: "code-review", action: "unload")
createСтворити нову навичку на дискуskill(action: "create", content: "...")
updateОновити наявну навичкуskill(name: "my-skill", action: "update", content: "...")
deleteВидалити навичку з дискаskill(name: "my-skill", action: "delete")

Як писати хороші навички

Хороший шаблон навички має:

  1. Чіткий заголовок — повідомляє ШІ-співробітникові, в якому він режимі
  2. Основні принципи — непорушні правила поведінки
  3. Методологію — покроковий підхід для типових сценаріїв
  4. Приклади — конкретні зразки «повідомлення користувача — відповідь»
  5. Антипатерни — чого НЕ робити (моделі добре вчаться на негативних прикладах)

Порада: кожна навичка має робити одну річ добре. Не створюйте навичку «програмування загалом» — створіть code-review, debugging, api-design як окремі навички. У ШІ-співробітника може бути кілька активних одночасно.

Вбудовані навички

Nebo постачається з вбудованими навичками для типових сценаріїв:

НавичкаПріоритетОпис
onboarding100Привітання нового користувача й збір профілю
best-friend50Навичка особистості — невимушено, віддано, по-справжньому
debugging25Систематична методологія налагодження
api-design15Найкращі практики проєктування RESTful API
code-review10Структурований код-рев’ю з рівнями серйозності
database-expert10Проєктування баз даних, запити, оптимізація
git-workflow10Гілки Git, коміти, робота з PR
security-audit10Аналіз безпеки й виявлення вразливостей

Вони слугують і корисними стандартними навичками, і еталонними реалізаціями для створення власних.

Довідник

Proto-файли

Proto-файли розміщено в proto/apps/v0/. SDK постачаються з уже згенерованим кодом, тож для звичайної розробки protoc не потрібен.

ФайлСервісОсновні RPC
v0/common.proto(лише повідомлення)HealthCheckRequest/Response, SettingsMap, UserContext, Empty
v0/tool.protoToolServiceName, Description, Schema, Execute, RequiresApproval, Configure
v0/channel.protoChannelServiceID, Connect, Disconnect, Send, Receive (stream), Configure
v0/comm.protoCommServiceName, Version, Connect, Disconnect, Send, Subscribe, Register, Receive (stream), Configure
v0/gateway.protoGatewayServiceHealthCheck, Stream (stream), Poll, Cancel, Configure
v0/ui.protoUIServiceHealthCheck, HandleRequest, Configure
v0/schedule.protoScheduleServiceHealthCheck, Create, Get, List, Update, Delete, Enable, Disable, Trigger, History, Triggers (stream), Configure

Кожен сервіс містить RPC HealthCheck і Configure. SDK обробляє обидва автоматично.

Proto-типи каналів

Тип повідомленняОпис
ChannelSendRequestКонверт вихідного повідомлення з message_id, channelId, sender, text, attachments, reply_to, actions, platform_data
ChannelSendResponseID повідомлення платформи для гілок
InboundMessageКонверт вхідного повідомлення з усіма спільними полями + timestamp
MessageSenderІдентичність бота (name, role, botId) — доповнюється брокером
AttachmentВкладення файлу, зображення чи аудіо (type, url, filename, size)
MessageActionДія інтерактивної кнопки чи клавіатури (label, callback_id)

Ідентичність і ролі бота

Боти Nebo мають модель ідентичності за трьома осями:

  • creature — ким є бот (архетип): «Кмітливий стратег», «Ретельний дослідник»
  • role — як він пов’язаний з користувачем (стосунки): «Друг», «COO», «Наставник»
  • vibe — його енергія (стиль спілкування): «Спокійний, але з власною думкою», «Теплий і підбадьорливий»

Коли ваш плагін каналу отримує вихідне повідомлення, поле sender містить name і role бота. Використовуйте їх, щоб сформувати ім’я для відображення на вашій платформі. Роль — це не посада, а опис стосунків. «Друг», «Син» і «Наставник» — такі самі допустимі ролі, як «COO» і «DevLead».