Огляд
Що таке 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) Контрольний список мінімального застосунку
- Створіть
manifest.jsonзid,name,version,provides - Напишіть
TOOL.mdз описом того, як ШІ-співробітник має використовувати ваш інструмент - Встановіть SDK (
go get github.com/neboloop/nebo-sdk-go) - Реалізуйте інтерфейс обробника для своєї можливості (
ToolHandler,ChannelHandlerтощо) - Зареєструйте обробник і викличте
app.Run() - Зберіть нативний виконуваний файл (
go build -o binary .) - Покладіть виконуваний файл + manifest.json + TOOL.md у каталог
apps/<your-app-id>/ - 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-сервіс | Опис |
|---|---|---|
gateway | GatewayService | Маршрутизація моделей LLM |
tool:<name> | ToolService | Іменований інструмент для ШІ-співробітника |
channel:<name> | ChannelService | Канал обміну повідомленнями |
comm | CommService | Зв’язок між ШІ-співробітниками |
ui | UIService | Кастомний інтерфейс з HTTP-проксі |
schedule | ScheduleService | Кастомне планування |
vision | ToolService | Обробка зображень |
browser | ToolService | Автоматизація браузера |
Застосунок може надавати кілька можливостей. Наприклад, застосунок може надавати і інструмент, і панель інтерфейсу.
Дозволи
Дозволи визначають, до чого застосунок має доступ. За замовчуванням усе заборонено — якщо дозвіл не оголошено, застосунок не може ним скористатися.
| Префікс | Приклади | Опис |
|---|---|---|
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:send | Push-сповіщення |
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_ID | ID застосунку з маніфесту |
NEBO_APP_NAME | Назва застосунку з маніфесту |
NEBO_APP_VERSION | Версія застосунку з маніфесту |
NEBO_APP_DATA | Шлях до каталогу data/ застосунку |
PATH | Системний PATH (передається без змін) |
HOME | Домашній каталог користувача (передається без змін) |
TMPDIR | Тимчасовий каталог (передається без змін) |
Важливо: ваш виконуваний файл має створити gRPC-сервер, що слухає Unix-сокет за адресою NEBO_APP_SOCK. Nebo чекає на появу цього сокета до 10 секунд.
Послідовність запуску застосунку
- Nebo читає
manifest.jsonі перевіряє його - Знаходить виконуваний файл
binaryабоappу каталозі застосунку - Перевіряє наявність маркера
.quarantined(відмовляється запускати застосунки в карантині) - Перевірка відкликання (лише для застосунків, поширюваних через NeboAI)
- Перевірка підпису (лише для застосунків, поширюваних через NeboAI; пропускається в режимі розробки)
- Перевірка виконуваного файлу (відхиляє символьні посилання, скрипти, невиконувані та завеликі файли)
- Прибирає застарілий сокет від попереднього запуску
- Створює каталог
data/для ізольованого сховища - Налаштовує журнали для кожного застосунку (
logs/stdout.log,logs/stderr.log) - Запускає виконуваний файл з очищеним середовищем та ізоляцією групи процесів
- Чекає на появу Unix-сокета (експоненційна затримка, максимум 10 секунд)
- Підключається через gRPC по Unix-сокету
- Створює gRPC-клієнти для конкретних можливостей на основі
provides - Виконує перевірку стану
- Реєструє можливості в ШІ-співробітника (інструменти, шлюз, 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") Правила схеми:
- Завжди додавайте поле
actionяк обов’язковий рядковий enum - Додавайте поле
resource(обов’язковий рядковий enum), лише якщо ваш інструмент керує кількома різними типами ресурсів - Усі інші поля — параметри конкретної дії
- В описі 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 вашого застосунку.
Як це працює
- Nebo викликає
ID(), щоб отримати унікальний ідентифікатор вашого каналу - Nebo викликає
Connect()з конфігурацією з налаштувань вашого застосунку - Nebo відкриває потік
Receive()— ваш застосунок надсилає вхідні повідомлення щоразу, коли користувач пише боту - Вхідні повідомлення спрямовуються в основну лінію розмови ШІ-співробітника
- Коли ШІ-співробітник хоче надіслати повідомлення, Nebo викликає
Send()з конвертом повідомлення v1 - Під час завершення роботи 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_id | UUID v7 | Унікальний ID, упорядкований за часом |
channel_id | {type}:{platform_id} | Ідентифікатор каналу для маршрутизації |
sender | object | Ідентичність бота — name, role, botId |
text | string | Тіло повідомлення |
attachments | array | Файли, зображення, аудіо |
reply_to | UUID v7 | ID батьківського повідомлення для гілок |
actions | array | Інтерактивні кнопки й клавіатури |
platform_data | bytes | Непрозора передача даних для функцій конкретної платформи |
timestamp | ISO 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 забезпечують зв’язок між ШІ-співробітниками.
| Поле | Опис |
|---|---|
from | ID співробітника-відправника |
to | ID співробітника-отримувача |
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.json | 1 MB | Метадані застосунку |
binary або app | 500 MB | Виконуваний файл |
signatures.json | 1 MB | Підписи Ed25519 |
TOOL.md | 1 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.
Налаштування акаунта розробника
- Зареєструйте акаунт NeboAI через
POST /api/v1/owners/register - Увійдіть, щоб отримати токен JWT:
POST /api/v1/owners/login - Створіть акаунт розробника:
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" Процес перевірки
- Автоматичне сканування — виконувані файли скануються через VirusTotal
- Перевірка адміністратором — команда NeboAI перевіряє метадані, маніфест і результати сканування
- У разі схвалення — NeboAI підписує застосунок за допомогою Ed25519 і публікує його
- У разі відхилення — ви отримуєте причину й можете виправити та надіслати повторно
Цільовий час перевірки: <24 годин.
Випуск оновлень
- Оновіть версію застосунку:
PUT /api/v1/developer/apps/{id}з новою версією - Завантажте нові виконувані файли для кожної платформи
- Знову надішліть на перевірку
Кожне оновлення проходить той самий процес перевірки. Попередні версії залишаються доступними, доки нову версію не схвалять.
Метадані магазину
| Поле | Опис |
|---|---|
category | наприклад, productivity, communication, developer-tools |
icon | URL значка застосунку |
visibility | public або private |
description | Може бути довшим і детальнішим, ніж опис у маніфесті |
Робочий процес розробки
Локальна розробка
Для локальної розробки пакування не потрібне:
- Створіть каталог застосунку:
mkdir -p ~/Library/Application\ Support/Nebo/apps/com.example.myapp - Напишіть свій
manifest.jsonі код - Зберіть бінарний файл:
go build -o ~/Library/Application\ Support/Nebo/apps/com.example.myapp/binary . - Nebo автоматично виявляє новий каталог (або перезапустіть Nebo)
- Після змін у коді перезберіть виконуваний файл — спостерігач за файлами перезапустить застосунок
Перегляд журналів
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") |
Як писати хороші навички
Хороший шаблон навички має:
- Чіткий заголовок — повідомляє ШІ-співробітникові, в якому він режимі
- Основні принципи — непорушні правила поведінки
- Методологію — покроковий підхід для типових сценаріїв
- Приклади — конкретні зразки «повідомлення користувача — відповідь»
- Антипатерни — чого НЕ робити (моделі добре вчаться на негативних прикладах)
Порада: кожна навичка має робити одну річ добре. Не створюйте навичку «програмування загалом» — створіть code-review, debugging, api-design як окремі навички. У ШІ-співробітника може бути кілька активних одночасно.
Вбудовані навички
Nebo постачається з вбудованими навичками для типових сценаріїв:
| Навичка | Пріоритет | Опис |
|---|---|---|
onboarding | 100 | Привітання нового користувача й збір профілю |
best-friend | 50 | Навичка особистості — невимушено, віддано, по-справжньому |
debugging | 25 | Систематична методологія налагодження |
api-design | 15 | Найкращі практики проєктування RESTful API |
code-review | 10 | Структурований код-рев’ю з рівнями серйозності |
database-expert | 10 | Проєктування баз даних, запити, оптимізація |
git-workflow | 10 | Гілки Git, коміти, робота з PR |
security-audit | 10 | Аналіз безпеки й виявлення вразливостей |
Вони слугують і корисними стандартними навичками, і еталонними реалізаціями для створення власних.
Довідник
Proto-файли
Proto-файли розміщено в proto/apps/v0/. SDK постачаються з уже згенерованим кодом, тож для звичайної розробки protoc не потрібен.
| Файл | Сервіс | Основні RPC |
|---|---|---|
v0/common.proto | (лише повідомлення) | 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 |
Кожен сервіс містить RPC HealthCheck і Configure. SDK обробляє обидва автоматично.
Proto-типи каналів
| Тип повідомлення | Опис |
|---|---|
ChannelSendRequest | Конверт вихідного повідомлення з message_id, channelId, sender, text, attachments, reply_to, actions, platform_data |
ChannelSendResponse | ID повідомлення платформи для гілок |
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».