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, shell-скрипты

Обоснование:

  • Защита от самоизменения ИИ — ИИ-сотрудник с доступом к командной оболочке мог бы изменить поведение интерпретируемого скрипта во время работы. Скомпилированные бинарные файлы после подписания неизменяемы.
  • Целостность подписи — подписи 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"]
        }
    ]
}
ПолеОписание
providerOAuth-провайдер: "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. Регистрирует возможности у ИИ-сотрудника (инструменты, шлюз, связь и т. д.)

Приложения-инструменты

Объявите "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 как обязательное строковое перечисление
  2. Добавляйте поле resource (обязательное строковое перечисление), только если ваш инструмент управляет несколькими разными типами ресурсов
  3. Все остальные поля — параметры конкретного действия
  4. В описании перечисления action должны быть перечислены все доступные действия

Почему STRAP важен:

  • LLM один раз усваивают паттерн маршрутизации по action и обобщают его на все операции
  • Определения инструментов занимают ~6% контекста — STRAP сокращает это на 80%
  • Новые операции — это просто новые значения перечисления, а не регистрация новых инструментов
  • Работает одинаково с облачными и локальными моделями

Пример на 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Идентичность бота — имя, роль, 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
        }
    ]
}

Другие возможности

Приложение связи

Объявите "provides": ["comm"] и "permissions": ["comm:*"]. Приложения связи обеспечивают общение между ИИ-сотрудниками.

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

Ключевые особенности:

  • Register объявляет этого ИИ-сотрудника в сети вместе с его возможностями
  • Subscribe/Unsubscribe управляют подписками на темы
  • Receive передаёт входящие сообщения потоком (серверный поток, как у каналов)
  • Одновременно может быть активно только одно приложение связи

Приложение-шлюз

Приложение-шлюз направляет запросы LLM к моделям. Объявите "provides": ["gateway"] и "permissions": ["network:outbound", "user:token"].

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

Типы GatewayEvent:

ТипСодержимоеОписание
"text"Фрагмент текстаПотоковый токен текста
"tool_call"JSONМодель хочет вызвать инструмент
"thinking"Фрагмент текстаРасширенное размышление и рассуждение
"error"Сообщение об ошибкеЧто-то пошло не так
"done"ПустоПоток завершён

Приложение интерфейса

Приложение интерфейса предоставляет собственный интерфейс конфигурации, который открывается во встроенном окне браузера Nebo. Объявите "provides": ["ui"]. В отличие от автоматической формы настроек (которую Nebo строит из settings в вашем манифесте), приложение интерфейса отдаёт собственный полноценный фронтенд на 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Да—Уникальный идентификатор (становится слагом)
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 — кем он приходится пользователю (отношения): «Друг», «Операционный директор», «Наставник»
  • vibe — его энергия (стиль общения): «Спокойный, но со своим мнением», «Тёплый и ободряющий»

Когда ваш плагин канала получает исходящее сообщение, поле sender содержит name и role бота. Используйте их, чтобы сформировать отображаемое имя для вашей платформы. Роль — это не должность, а описание отношений. «Друг», «Сын» и «Наставник» — такие же допустимые роли, как «COO» и «DevLead».