Обзор
Что такое 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) Чек-лист минимального приложения
- Создайте
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 - Выполняет проверку работоспособности
- Регистрирует возможности у ИИ-сотрудника (инструменты, шлюз, связь и т. д.)
Приложения-инструменты
Объявите "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как обязательное строковое перечисление - Добавляйте поле
resource(обязательное строковое перечисление), только если ваш инструмент управляет несколькими разными типами ресурсов - Все остальные поля — параметры конкретного действия
- В описании перечисления
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 вашего приложения.
Как это работает
- 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 | Идентичность бота — имя, роль, 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
}
]
} Другие возможности
Приложение связи
Объявите "provides": ["comm"] и "permissions": ["comm:*"]. Приложения связи обеспечивают общение между ИИ-сотрудниками.
| Поле | Описание |
|---|---|
from | ID сотрудника-отправителя |
to | ID сотрудника-получателя |
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.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 | Да | — | Уникальный идентификатор (становится слагом) |
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 — кем он приходится пользователю (отношения): «Друг», «Операционный директор», «Наставник»
- vibe — его энергия (стиль общения): «Спокойный, но со своим мнением», «Тёплый и ободряющий»
Когда ваш плагин канала получает исходящее сообщение, поле sender содержит name и role бота. Используйте их, чтобы сформировать отображаемое имя для вашей платформы. Роль — это не должность, а описание отношений. «Друг», «Сын» и «Наставник» — такие же допустимые роли, как «COO» и «DevLead».