NeboAI
NeboAI
Başlayın

Nebo için Uygulama Geliştirin

Yapay zekânıza yeni süper güçler kazandırın. Araçlar, kanallar, ağ geçitleri, arayüz panelleri — hayal edebileceğiniz her şey, yerel bir ikili dosyaya derlenmiş hâlde.

Genel Bakış

Nebo Nedir

Nebo, kişisel bir masaüstü yapay zekâ asistanıdır — dijital hayatınızı yöneten, sürekli çalışan bir yapay zekâ çalışanı. Nebo'yu bir akıllı telefon gibi düşünün: uygulamalarıyla dönüştürücü hâle gelen güçlü bir platform.

Nebo tek başına da bellek, zamanlama, web'de gezinme, dosya yönetimi ve kabuk erişimi olan yetenekli bir yapay zekâ çalışanıdır. Ama asıl kilidi açan Uygulamalardır. Bir akıllı telefonun gücü uygulama ekosisteminden geldiği gibi, Nebo'nun gücü de yapabileceklerini genişleten uygulamalardan gelir.

Uygulamalar Nedir

Nebo Uygulamaları, olağanüstü işlevsellik sunan, kendi içinde bütün, önceden derlenmiş birimlerdir. Her uygulama Nebo'ya yeni bir süper güç kazandırır — takvim yönetimi, e-posta ayıklama, proje takibi, ev otomasyonu, finansal analiz — bir geliştiricinin hayal edebileceği her şey.

Uygulamalar olağanüstü gücü çok güvenli bir şekilde sunar. Her uygulama, varsayılan olarak her şeyin reddedildiği izinlerle bir korumalı alanda çalışır. Yalnızca manifestosunun bildirdiği ve kullanıcının onayladığı şeylere erişebilir.

Arayüz %100 sohbet tabanlıdır. Kullanıcılar uygulamalarla ayrı ekranlar veya panolar üzerinden etkileşime girmez. Nebo ile konuşurlar, Nebo da işleri halletmek için uygulamanın araçlarını kullanır. "Yarın takvimimde ne var?" — Nebo takvim uygulamasını çağırır. "Sarah ile saat 15:00'te bir toplantı oluştur" — Nebo takvim uygulamasını çağırır. Kullanıcı sohbetten hiç ayrılmaz.

Uygulamalar isteğe bağlı olarak bir ayarlar arayüzü sunabilir — Nebo'nun yerleşik tarayıcı penceresinde açılan bir yapılandırma paneli. Kullanıcılar API anahtarlarını burada girer, özellikleri açıp kapatır ve uygulamayı yapılandırır. Ayarlar arayüzü manifestodaki settings dizisiyle yönetilir (Nebo formu otomatik olarak oluşturur) ya da uygulama ui yeteneğiyle tamamen kendine özgü bir arayüz sunabilir.

Uygulamalar Nebo'nun yerleşik yeteneklerinin yerini alır ve onları genişletir. Nebo temel platform araçlarıyla gelir (yerel takvim erişimi, ekran görüntüleri vb.). Bir takvim uygulaması yüklediğinizde, yerleşik takvim aracının yerini alır ve onun bir üst kümesi olur — yerel + bulut + birleştirme + müsaitlik kontrolü.

Yalnızca Derlenmiş Politikası

Nebo, yalnızca derlenmiş ikili dosyalara izin veren katı bir politika uygular. Tüm uygulamalar yerel olarak derlenmiş yürütülebilir dosyalar olmalıdır.

DurumDiller
DestekleniyorGo (önerilen), Rust, C/C++, Zig
ReddedildiPython, Node.js, Ruby, Java, .NET, kabuk betikleri

Gerekçe:

  • Yapay zekânın kendini değiştirmesinin önlenmesi — Kabuk erişimi olan bir yapay zekâ çalışanı, yorumlanan bir betiğin davranışını çalışma anında değiştirebilir. Derlenmiş ikili dosyalar imzalandıktan sonra değiştirilemez.
  • İmza bütünlüğü — Ed25519 imzaları ham ikili baytları kapsar. İmzalı bir ikili dosya, imzayı geçersiz kılmadan değiştirilemez.
  • Korumalı alan denetimi — İkili biçim doğrulaması (ELF/Mach-O/PE sihirli baytları) hızlı ve güvenilir bir kapıdır.

Hızlı Başlangıç

SDK'yı yükleyin

Resmi SDK'lar tüm gRPC sunucu kurulumunu, sinyal işlemeyi ve protokol köprülemeyi üstlenir. Siz yalnızca işleyici arayüzlerini uygularsınız.

Go (önerilen):

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

Rust (yakında):

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

C/C++ (yakında):

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

Uygulama Dizin Yapısı

Uygulamalar, Nebo veri dizininizin apps/ alt dizininde bulunur:

~/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)

Minimal Uygulama Kontrol Listesi

  1. id, name, version, provides alanlarıyla manifest.json oluşturun
  2. Yapay zekâ çalışanının aracınızı nasıl kullanması gerektiğini anlatan TOOL.md dosyasını yazın
  3. SDK'yı yükleyin (go get github.com/neboloop/nebo-sdk-go)
  4. Yeteneğiniz için işleyici arayüzünü uygulayın (ToolHandler, ChannelHandler vb.)
  5. İşleyiciyi kaydedin ve app.Run() çağırın
  6. Yerel bir ikili dosya derleyin (go build -o binary .)
  7. İkili dosyayı + manifest.json + TOOL.md dosyalarını apps/<your-app-id>/ dizinine koyun
  8. Nebo onu otomatik olarak bulur ve başlatır

Yapılandırma

manifest.json

Her uygulamanın bir manifest.json dosyasına ihtiyacı vardır:

{
    "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
        }
    ]
}

Zorunlu alanlar:

AlanAçıklama
idTers alan adı biçiminde tanımlayıcı (ör. com.mycompany.myapp)
nameOkunabilir ad
versionSemver dizesi
providesEn az bir yetenek (aşağıya bakın)

İsteğe bağlı alanlar:

AlanVarsayılanAçıklama
runtime"local""local" veya "remote"
protocol"grpc"Yalnızca "grpc" desteklenir
permissions[]Uygulamanın neye erişmesi gerektiği
description""Arayüzde gösterilir
settings[]Yapılandırılabilir ayarlar (Ayarlar arayüzünde gösterilir)
oauth[]OAuth sağlayıcı gereksinimleri (aşağıdaki OAuth bölümüne bakın)

Yetenekler

Uygulamanızın ne sağladığını bildirin:

YetenekgRPC HizmetiAçıklama
gatewayGatewayServiceLLM model yönlendirme
tool:<name>ToolServiceYapay zekâ çalışanı için adlandırılmış bir araç
channel:<name>ChannelServiceBir mesajlaşma kanalı
commCommServiceYapay zekâ çalışanları arasında iletişim
uiUIServiceHTTP proxy'li özel arayüz
scheduleScheduleServiceÖzel zamanlama
visionToolServiceGörüntü işleme
browserToolServiceTarayıcı otomasyonu

Bir uygulama birden fazla yetenek sağlayabilir. Örneğin bir uygulama hem bir araç hem de bir arayüz paneli sağlayabilir.

İzinler

İzinler, uygulamanın neye erişebileceğini denetler. Varsayılan olarak her şey reddedilir — bildirilmemişse uygulama onu kullanamaz.

ÖnekÖrneklerAçıklama
network:network:outbound, network:*Ağ erişimi
filesystem:filesystem:read, filesystem:writeDosya sistemi erişimi
memory:memory:read, memory:writeYapay zekâ çalışanı bellek erişimi
session:session:readSohbet oturumları
tool:tool:shell, tool:fileDiğer araçları kullanma
shell:shell:execKabuk komutu çalıştırma
channel:channel:send, channel:*Kanal işlemleri
comm:comm:send, comm:*Yapay zekâ çalışanları arasında iletişim
model:model:chatYapay zekâ modeli erişimi
user:user:tokenİsteklerde kullanıcı JWT'sini alma
schedule:schedule:createCron işi yönetimi
database:database:queryVeritabanı erişimi
storage:storage:read, storage:writeKalıcı depolama
context:context:readYapay zekâ çalışanı bağlam erişimi
subagent:subagent:spawnAlt ajan işlemleri
lane:lane:enqueueŞerit işlemleri
notification:notification:sendAnlık bildirimler
embedding:embedding:searchVektör gömme erişimi
skill:skill:invokeBeceri çağırma
advisor:advisor:consultDanışman sistemi erişimi
mcp:mcp:connectMCP sunucusu erişimi
voice:voice:recordSes erişimi
browser:browser:navigateTarayıcı otomasyonu
oauth:oauth:google, oauth:*OAuth belirteci erişimi
settings:settings:readAyarlara erişim
capability:capability:registerYetenek kaydı

Joker karakterli izinler desteklenir: network:*, herhangi bir network: izin denetimiyle eşleşir.

Ayarlar

Ayarlar, Nebo arayüzünde uygulamanın ayarlar panelinde görünür. Nebo bunları veritabanında saklar ve değiştiklerinde Configure RPC'si ile uygulamanıza gönderir.

Ayar şemanız NeboAI uygulama mağazası listesine dahil edilir. Zorunlu ayarları yapılandırılmamış uygulamalar arayüzde "Kurulum Gerekli" rozetiyle gösterilir.

TürAçıklama
textTek satırlık metin girişi
passwordMaskelenmiş metin girişi
toggleAçık/kapalı anahtarı
selectÖnceden tanımlı seçenekli açılır liste
numberSayısal giriş
urlDoğrulamalı URL girişi
{
    "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 Gereksinimleri

Uygulamalar OAuth sağlayıcı gereksinimlerini bildirebilir. Nebo'nun OAuth aracısı tüm akışı yönetir — uygulamalar belirteçleri Configure RPC'si ile otomatik olarak alır.

{
    "oauth": [
        {
            "provider": "google",
            "scopes": ["https://www.googleapis.com/auth/calendar"]
        }
    ]
}
AlanAçıklama
providerOAuth sağlayıcısı: "google", "microsoft", "github"
scopesUygulamanın ihtiyaç duyduğu OAuth kapsamlarının dizisi

Kullanıcı uygulamayı yüklediğinde Nebo, gerekli OAuth kapsamlarını yetkilendirmesini ister. Uygulama, OAuth akışını kendisi yönetmeden yenilenmiş belirteçleri Configure RPC'si ile alır.

Ortam Değişkenleri

Uygulama süreciniz temizlenmiş bir ortam alır. Tüm gizli bilgiler çıkarılır. Size verilenler:

DeğişkenDeğer
NEBO_APP_DIRUygulamanın kurulum dizini
NEBO_APP_SOCKOluşturulacak Unix soketinin yolu
NEBO_APP_IDManifestodaki uygulama kimliği
NEBO_APP_NAMEManifestodaki uygulama adı
NEBO_APP_VERSIONManifestodaki uygulama sürümü
NEBO_APP_DATAUygulamanın data/ dizininin yolu
PATHSistem PATH değeri (olduğu gibi aktarılır)
HOMEKullanıcının ana dizini (olduğu gibi aktarılır)
TMPDIRGeçici dizin (olduğu gibi aktarılır)

Önemli: İkili dosyanız, NEBO_APP_SOCK konumundaki Unix soketini dinleyen bir gRPC sunucusu oluşturmalıdır. Nebo bu soketin görünmesi için en fazla 10 saniye bekler.

Uygulama Başlatma Sırası

  1. Nebo manifest.json dosyasını okur ve doğrular
  2. Uygulama dizininde binary veya app yürütülebilir dosyasını bulur
  3. .quarantined işaretini denetler (karantinaya alınmış uygulamaları başlatmayı reddeder)
  4. İptal denetimi (yalnızca NeboAI üzerinden dağıtılan uygulamalar)
  5. İmza doğrulama (yalnızca NeboAI üzerinden dağıtılan uygulamalar, geliştirme modunda atlanır)
  6. İkili dosya doğrulama (sembolik bağlantıları, betikleri, yürütülebilir olmayan ve aşırı büyük dosyaları reddeder)
  7. Önceki çalıştırmadan kalan eski soketi temizler
  8. Korumalı depolama için data/ dizinini oluşturur
  9. Uygulamaya özel günlük dosyalarını ayarlar (logs/stdout.log, logs/stderr.log)
  10. İkili dosyayı temizlenmiş ortam ve süreç grubu yalıtımıyla başlatır
  11. Unix soketinin görünmesini bekler (üstel geri çekilme, en fazla 10 saniye)
  12. Unix soketi üzerinden gRPC ile bağlanır
  13. provides alanına göre yeteneğe özel gRPC istemcileri oluşturur
  14. Sağlık denetimi çalıştırır
  15. Yetenekleri yapay zekâ çalışanına kaydeder (araçlar, ağ geçidi, iletişim vb.)

Araç Uygulamaları

Manifestonuzda "provides": ["tool:my_tool_name"] bildirin.

STRAP Kalıbı

Tüm Nebo araç uygulamaları, şemaları ve yürütme yönlendirmeleri için STRAP (Single Tool Resource Action Pattern) kalıbını kullanmak zorundadır. Bu, Nebo'nun 35'ten fazla ayrı aracı 4 alan aracında birleştirmek için kendi içinde kullandığı kalıbın aynısıdır — LLM bağlam yükünü yaklaşık %80 azaltır.

Temel fikir: Birden fazla araç (get_events, check_availability, suggest_slots) kaydetmek yerine, doğru işleyiciye yönlendiren action (ve isteğe bağlı olarak resource) alanlarına sahip TEK bir araç kaydedin.

Tek kaynaklı örnek (takvim):

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

Çok kaynaklı örnek (proje yöneticisi):

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

Şema kuralları:

  1. Her zaman zorunlu bir dize enum'u olarak action alanını ekleyin
  2. resource alanını (zorunlu dize enum'u) yalnızca aracınız birden fazla farklı kaynak türünü yönetiyorsa ekleyin
  3. Diğer tüm alanlar eyleme özel parametrelerdir
  4. action enum açıklaması kullanılabilir tüm eylemleri listelemelidir

STRAP neden önemlidir:

  • LLM'ler action yönlendirme kalıbını bir kez öğrenir ve tüm işlemlere genelleştirir
  • Araç tanımları bağlamın yaklaşık %6'sını tüketir — STRAP bunu %80 azaltır
  • Yeni işlemler yeni araç kayıtları değil, yalnızca enum eklemeleridir
  • Barındırılan ve yerel modellerde aynı şekilde çalışır

Go Örneği — Hesap Makinesi Aracı

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

Derleme ve kurulum:

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 Örneği

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 Örneği

#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;
}

Kanal Uygulamaları

"provides": ["channel:my_channel"] ve "permissions": ["channel:send"] bildirin.

Kanal uygulamaları, harici mesajlaşma platformlarını (Telegram, Discord, Slack vb.) Nebo'nun yapay zekâ çalışanına bağlar. Bir kullanıcı harici platformda mesaj gönderdiğinde, uygulamanız bunu Receive ile Nebo'ya akıtır. Yapay zekâ çalışanı yanıt vermek istediğinde Nebo, uygulamanızın Send yöntemini çağırır.

Nasıl çalışır

  1. Nebo, kanalınızın benzersiz tanımlayıcısını almak için ID() çağırır
  2. Nebo, uygulamanızın ayarlarındaki yapılandırmayla Connect() çağırır
  3. Nebo bir Receive() akışı açar — bir kullanıcı bota her mesaj gönderdiğinde uygulamanız gelen mesajları iletir
  4. Gelen mesajlar yapay zekâ çalışanının ana sohbet şeridine yönlendirilir
  5. Yapay zekâ çalışanı mesaj göndermek istediğinde Nebo, v1 mesaj zarfıyla Send() çağırır
  6. Kapanışta Nebo Disconnect() çağırır

v1 Mesaj Zarfı

Gelen ve giden tüm kanal mesajları ortak mesaj zarfını kullanır:

{
  "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"
}
AlanTürAçıklama
message_idUUID v7Zamana göre sıralı benzersiz kimlik
channel_id{type}:{platform_id}Yönlendirilebilir kanal tanımlayıcısı
senderobjectBot kimliği — name, role, botId
textstringMesaj gövdesi
attachmentsarrayDosyalar, görseller, ses
reply_toUUID v7İleti dizisi için üst mesaj kimliği
actionsarrayEtkileşimli düğmeler/klavyeler
platform_databytesPlatforma özel özellikler için opak aktarım
timestampISO 8601Bunu yayıncı ayarlar

İki katmanlı tasarım: Ortak alanlar (text, attachments, reply_to, actions), çalışanın başlattığı mesajlaşmanın %90'ını karşılar. Platforma özel özellikler platform_data içine girer — eklentiniz bunları yerel platform biçimine ve bu biçimden dönüştürür.

Sohbet Akışları

Kanal mesajları, yalıtım için kanal başına ayrı sohbet akışları üzerinden yönlendirilir:

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

Go Örneği — Telegram Kanalı

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
        }
    ]
}

Diğer Yetenekler

İletişim Uygulaması

"provides": ["comm"] ve "permissions": ["comm:*"] bildirin. İletişim uygulamaları, yapay zekâ çalışanları arasında iletişimi sağlar.

AlanAçıklama
fromGönderen çalışan kimliği
toAlıcı çalışan kimliği
topicMesaj konusu/kanalı
type"message", "mention", "proposal", "command", "info", "task"
contentMesaj gövdesi

Temel davranışlar:

  • Register, bu yapay zekâ çalışanını yetenekleriyle birlikte ağda duyurur
  • Subscribe/Unsubscribe konu aboneliklerini yönetir
  • Receive gelen mesajları akıtır (sunucu akışı, kanallarla aynı)
  • Aynı anda yalnızca bir iletişim uygulaması etkin olabilir

Ağ Geçidi Uygulaması

Bir ağ geçidi uygulaması LLM isteklerini modellere yönlendirir. "provides": ["gateway"] ve "permissions": ["network:outbound", "user:token"] bildirin.

GatewayRequest; mesajları, araçları, sistem istemini, en fazla belirteç sayısını, sıcaklığı ve bir UserContext (user:token izni verilmişse JWT belirteci) içerir.

GatewayEvent türleri:

TürİçerikAçıklama
"text"Metin parçasıAkış hâlinde metin belirteci
"tool_call"JSONModel bir araç çağırmak istiyor
"thinking"Metin parçasıGenişletilmiş düşünme/akıl yürütme
"error"Hata mesajıBir şeyler ters gitti
"done"BoşAkış tamamlandı

Arayüz Uygulaması

Bir arayüz uygulaması, Nebo'nun yerleşik tarayıcı penceresinde açılan özel bir yapılandırma arayüzü sağlar. "provides": ["ui"] bildirin. Otomatik ayarlar formundan (Nebo'nun settings manifestonuzdan oluşturduğu) farklı olarak, bir arayüz uygulaması kendi eksiksiz HTML/CSS/JS ön yüzünü sunar.

Uygulamanız statik web varlıkları (HTML, CSS, JS — genellikle index.html içeren bir SPA) barındıran bir ui/ dizini ile gelir. Nebo bu dosyaları doğrudan sunar ve API çağrılarını gRPC üzerinden uygulamanıza iletir.

YolMekanizmaAmaç
GET /api/v1/apps/{id}/ui/*Statik dosya sunucusuDosyaları ui/ dizininizden sunar (SPA yedeği olarak index.html)
ANY /api/v1/apps/{id}/api/*gRPC proxyHTTP isteklerini uygulamanızın UIService.HandleRequest() yöntemine iletir

SDK standart bir net/http.ServeMux sarmalar, böylece normal Go HTTP işleyicileri yazarsınız — gRPC köprülemesini SDK otomatik olarak halleder.

Go Örneği — Pano Arayüzü:

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 dosyanız /api/v1/apps/com.example.dashboard/api/status adresine fetch çağrıları yapar ve bunlar mux işleyicinize iletilir.

Zamanlama Uygulaması

Bir zamanlama uygulaması, Nebo'nun yerleşik cron zamanlayıcısının yerini alır. "provides": ["schedule"] ve "permissions": ["schedule:create"] bildirin.

Zamanlama uygulamanız başladığında Nebo, tüm zamanlamayı varsayılan cron motoru yerine uygulamanız üzerinden yönlendirir. Uygulamanız çökerse Nebo otomatik olarak yerleşik motora geri döner.

  • Uygulamanız zamanlama durumunun sahibidir — bir zamanlama uygulaması etkinken Nebo zamanlamaları kendi veritabanında saklamaz
  • Standart CRUD: Create, Get, List, Update, Delete, Enable, Disable
  • Triggers sunucu akışlı bir RPC'dir — bir zamanlama her tetiklendiğinde uygulamanız bir tetikleme mesajı gönderir
  • Aynı anda yalnızca bir zamanlama uygulaması etkin olabilir

Çok Yetenekli Uygulamalar

Bir uygulama birden fazla yetenek sağlayabilir. Örneğin hem araç hem de arayüz içeren bir pano uygulaması:

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

Paketleme

.napp Biçimi

NeboAI üzerinden dağıtım için uygulamanızı bir .napp dosyası (tar.gz arşivi) olarak paketleyin:

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

Zorunlu dosyalar:

DosyaEn Büyük BoyutAçıklama
manifest.json1 MBUygulama meta verileri
binary veya app500 MBYürütülebilir dosya
signatures.json1 MBEd25519 imzaları
TOOL.md1 MBYapay zekâ çalışanı için araç talimatları

Çıkarma sırasındaki güvenlik kuralları:

  • Yol geçişi yok (../ reddedilir)
  • Sembolik bağlantı yok (reddedilir)
  • Mutlak yol yok (reddedilir)
  • Yalnızca izin listesindeki dosya adları kabul edilir

İmzalar

NeboAI uygulamaları Ed25519 ile imzalar. signatures.json biçimi:

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

Geliştirme modunda (NeboAI URL'si yapılandırılmamışken) imza doğrulaması tamamen atlanır. Yerel geliştirme için signatures.json dosyasına ihtiyacınız yoktur.

Yayımlama

Uygulamanız yerel olarak çalıştığında, tüm Nebo kullanıcılarına dağıtılması için NeboAI üzerinden yayımlayın.

Geliştirici Hesabı Kurulumu

  1. POST /api/v1/owners/register adresinden bir NeboAI hesabı oluşturun
  2. JWT belirteci almak için giriş yapın: POST /api/v1/owners/login
  3. Bir geliştirici hesabı oluşturun: POST /api/v1/developer/accounts

Gönderim Akışı

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

Adım 1: Uygulamayı oluşturun

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

Adım 2: Platform ikili dosyalarını yükleyin

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"

Her platform için bir ikili dosya yükleyin: darwin-arm64, darwin-amd64, linux-amd64, linux-arm64.

Adım 3: İncelemeye gönderin

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

İnceleme Süreci

  1. Otomatik tarama — ikili dosyalar VirusTotal ile taranır
  2. Yönetici incelemesi — NeboAI ekibi meta verileri, manifestoyu ve tarama sonuçlarını inceler
  3. Onaylandığında — NeboAI uygulamayı Ed25519 ile imzalar ve yayımlar
  4. Reddedildiğinde — size bir gerekçe iletilir; düzeltip yeniden gönderebilirsiniz

Hedef inceleme süresi: <24 saat.

Güncelleme Gönderme

  1. Uygulamanın sürümünü güncelleyin: yeni sürümle PUT /api/v1/developer/apps/{id}
  2. Her platform için yeni ikili dosyaları yükleyin
  3. Yeniden incelemeye gönderin

Her güncelleme aynı inceleme sürecinden geçer. Yeni sürüm onaylanana kadar önceki sürümler kullanılabilir kalır.

Mağaza Meta Verileri

AlanAçıklama
categoryör. productivity, communication, developer-tools
iconUygulama simgesi URL'si
visibilitypublic veya private
descriptionManifestodaki açıklamadan daha uzun/zengin olabilir

Geliştirme İş Akışı

Yerel Geliştirme

Yerel geliştirme için paketleme gerekmez:

  1. Uygulama dizininizi oluşturun:
    mkdir -p ~/Library/Application\ Support/Nebo/apps/com.example.myapp
  2. manifest.json dosyanızı ve kodunuzu yazın
  3. İkili dosyanızı derleyin:
    go build -o ~/Library/Application\ Support/Nebo/apps/com.example.myapp/binary .
  4. Nebo yeni dizini otomatik olarak algılar (veya Nebo'yu yeniden başlatın)
  5. Kod değişikliklerinden sonra ikili dosyayı yeniden derleyin — dosya izleyici uygulamayı yeniden başlatır

Günlükleri Görüntüleme

Uygulamanın stdout/stderr çıktıları uygulamaya özel günlük dosyalarında toplanır:

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

Kalıcı Veriler

Uygulamanızın kalıcı olarak saklaması gereken dosyalar için data/ dizinini (NEBO_APP_DATA ortam değişkeni olarak da kullanılabilir) kullanın. Bu dizin uygulama güncellemelerinden ve karantinadan etkilenmez.

Hata Ayıklama İpuçları

  • Uygulamanız başlamıyorsa hatalar için logs/stderr.log dosyasını kontrol edin
  • İkili dosyanın yürütülebilir olduğundan emin olun (chmod +x binary)
  • NEBO_APP_SOCK içindeki Unix soketi yolunu dinlediğinizden emin olun
  • Soket, başlatmadan sonraki 10 saniye içinde hazır olmalıdır
  • Depolama için sabit kodlanmış yollar değil, NEBO_APP_DATA kullanın
  • Hata ayıklama günlükleri için stderr'e yazdırın (logs/stderr.log içinde toplanır)

Doğrulama

# 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

Kaldırma

nebo apps uninstall com.example.myapp

Beceriler

Beceriler Nedir

Beceriler, Nebo'nun bir sohbet sırasında nasıl davranacağını şekillendiren talimat kümeleridir. Bir beceri etkin olduğunda içeriği doğrudan sistem istemine eklenir — o oturum boyunca yapay zekâ çalışanının üslubunu, yöntemini, alan uzmanlığını ve araç kullanımını yönlendirir.

Beceriler kod değildir. YAML meta verileri olan markdown belgeleridir. Derleme yok, ikili dosya yok, gRPC yok. Bir beceri, bir dizindeki SKILL.md dosyasıdır. Hepsi bu.

Beceriler bağlama özgü ve geçicidir. İlgili olduklarında etkinleşir (tetikleyici eşleşmesiyle veya elle yüklenerek), birkaç tur boyunca kalır ve artık gerekmediğinde sona erer. Bu, yapay zekâ çalışanının bağlamını yalın tutar — istemde yalnızca şu an önemli olan yönlendirme bulunur.

Beceriler uygulamaları tamamlar. Uygulamalar çalıştırılabilir yetenekler sağlar (araçlar, kanallar, ağ geçitleri). Beceriler ise yönetim rehberliği sağlar — bu araçların etkili şekilde nasıl kullanılacağını. Bir takvim uygulaması Nebo'ya etkinlikleri okuma ve yazma yeteneği verir. Bir "toplantı hazırlığı" becerisi ise Nebo'ya o takvim uygulamasını, e-postayı ve web aramasını birlikte kullanarak toplantılara nasıl hazırlanacağını anlatır.

Beceriler ve Uygulamalar

BecerilerUygulamalar
BiçimMarkdown (SKILL.md)Derlenmiş ikili dosya (.napp)
Çalışma zamanıSistem istemine eklenirgRPC üzerinden korumalı alanda çalışan süreç
SağladıklarıDavranışsal rehberlik, yöntemAraçlar, kanallar, arayüz panelleri
ÖmürOturumla sınırlı, TTL'ye dayalı sona ermeHer zaman çalışır
OluşturmaBir markdown dosyası yazınYazın, derleyin, imzalayın, paketleyin
Güvenlikİzin gerekmezVarsayılan olarak reddeden korumalı alan

Hızlı Başlangıç

Nebo beceriler klasörünüzde SKILL.md dosyası içeren bir dizin oluşturun:

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

Bir SKILL.md yazın:

---
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, beceriler dizinini fsnotify ile izler. Beceriniz hemen kullanılabilir — yeniden başlatma gerekmez. Bir tetikleyiciyle eşleşen bir şey söyleyin, otomatik olarak etkinleşsin.

Ya da doğrudan Nebo'dan isteyin: "Blog yazıları yazmak için bir beceri oluştur" — Nebo SKILL.md dosyasını sizin için yazar.

SKILL.md Biçimi

Her beceri iki bölümden oluşan tek bir SKILL.md dosyasıdır: --- işaretleri arasındaki YAML ön bilgisi ve bir markdown gövdesi (sistem istemine eklenen asıl talimatlar).

AlanZorunluVarsayılanAçıklama
nameEvet—Benzersiz tanımlayıcı (kısa ad olur)
descriptionEvet—Beceri kataloğunda gösterilen tek satırlık açıklama
versionHayır"1.0.0"Güncellemeleri izlemek için semver
authorHayır—Beceri yazarı
priorityHayır0Yüksek değer = önce eşleşir (kritik geçersiz kılmalar için 100+)
max_turnsHayır4Otomatik sona ermeden önceki etkinlik dışı tur sayısı
triggersHayır[]Bu beceriyi otomatik etkinleştiren ifadeler (büyük/küçük harfe duyarsız alt dize eşleşmesi)
toolsHayır[]Bu becerinin kullanmayı beklediği araçlar (bilgi amaçlı)
dependenciesHayır[]Yüklü olması gereken diğer beceriler
tagsHayır[]Sınıflandırma ve keşif için
platformHayır[]Desteklenen platformlar: macos, linux, windows (boş = tümü)

Beceriler Nasıl Etkinleşir

Beceriler iki aşamalı bir etkinleştirme modeli izler: önce ipucu, sonra çağırma.

Aşama 1: Tetikleyici Eşleşmesi — Kullanıcı her mesaj gönderdiğinde Nebo, kayıtlı tüm becerileri tetikleyici eşleşmeleri için tarar. Eşleşen beceriler sistem isteminde ipucu olarak görünür. Yapay zekâ çalışanı ipucunu görür ve beceriyi çağırıp çağırmayacağına karar verir.

Aşama 2: Çağırma — Yapay zekâ çalışanı bir beceriyi şu çağrıyla çağırır:

skill(name: "code-review")

Bu, SKILL.md şablonunun tamamını araç sonucu olarak döndürür, çağrıyı kaydeder ve sonraki turlarda şablonu sistem istemine yeniden ekler.

TTL ve Sona Erme:

  • Otomatik eşleşen beceriler: 4 tur etkinlik dışılık (max_turns ile yapılandırılabilir)
  • Elle yüklenen beceriler: 6 tur etkinlik dışılık
  • Yeniden çağırma zamanlayıcıyı sıfırlar
  • Kesin sınır: oturum başına en fazla 4 etkin beceri
  • Belirteç bütçesi: etkin becerilerin toplam içeriği 16.000 karakterle sınırlıdır

Becerileri Yönetme

Yapay zekâ çalışanı becerileri skill aracıyla yönetebilir:

EylemAçıklamaÖrnek
catalogKullanılabilir tüm becerileri listeleskill(action: "catalog")
loadBu oturum için etkinleştirskill(name: "code-review", action: "load")
unloadBir beceriyi devre dışı bırakskill(name: "code-review", action: "unload")
createDiskte yeni bir beceri oluşturskill(action: "create", content: "...")
updateMevcut bir beceriyi güncelleskill(name: "my-skill", action: "update", content: "...")
deleteBir beceriyi diskten silskill(name: "my-skill", action: "delete")

İyi Beceriler Yazmak

İyi bir beceri şablonunda şunlar bulunur:

  1. Net bir başlık — yapay zekâ çalışanına hangi modda olduğunu söyler
  2. Temel ilkeler — pazarlığa açık olmayan davranış kuralları
  3. Yöntem — yaygın senaryolar için adım adım yaklaşım
  4. Örnekler — somut kullanıcı mesajı ve yanıt kalıpları
  5. Kaçınılacak kalıplar — YAPILMAMASI gerekenler (modeller olumsuz örneklerden iyi öğrenir)

İpucu: Her beceri tek bir işi iyi yapmalıdır. "Genel programlama" becerisi oluşturmayın — code-review, debugging, api-design becerilerini ayrı ayrı oluşturun. Yapay zekâ çalışanında aynı anda birden fazlası etkin olabilir.

Hazır Beceriler

Nebo, yaygın kullanım durumlarını kapsayan hazır becerilerle gelir:

BeceriÖncelikAçıklama
onboarding100Yeni kullanıcıyı karşılama ve profil bilgilerini toplama
best-friend50Kişilik becerisi — samimi, sadık, açık sözlü
debugging25Sistematik hata ayıklama yöntemi
api-design15RESTful API tasarımında en iyi uygulamalar
code-review10Önem düzeyli yapılandırılmış kod incelemesi
database-expert10Veritabanı tasarımı, sorgular, optimizasyon
git-workflow10Git dallanma, commit'ler, PR iş akışları
security-audit10Güvenlik analizi ve güvenlik açığı tespiti

Bunlar hem kullanışlı varsayılanlar hem de kendi becerilerinizi oluşturmak için başvuru örnekleridir.

Başvuru

Proto Dosyaları

Proto dosyaları proto/apps/v0/ içinde bulunur. SDK'lar önceden üretilmiş kodla gelir, bu yüzden normal geliştirme için protoc gerekmez.

DosyaHizmetTemel RPC'ler
v0/common.proto(yalnızca mesajlar)HealthCheckRequest/Response, SettingsMap, UserContext, Empty
v0/tool.protoToolServiceName, Description, Schema, Execute, RequiresApproval, Configure
v0/channel.protoChannelServiceID, Connect, Disconnect, Send, Receive (akış), Configure
v0/comm.protoCommServiceName, Version, Connect, Disconnect, Send, Subscribe, Register, Receive (akış), Configure
v0/gateway.protoGatewayServiceHealthCheck, Stream (akış), Poll, Cancel, Configure
v0/ui.protoUIServiceHealthCheck, HandleRequest, Configure
v0/schedule.protoScheduleServiceHealthCheck, Create, Get, List, Update, Delete, Enable, Disable, Trigger, History, Triggers (akış), Configure

Her hizmet HealthCheck ve Configure RPC'lerini içerir. SDK ikisini de otomatik olarak yönetir.

Kanal Proto Türleri

Mesaj TürüAçıklama
ChannelSendRequestmessage_id, channelId, sender, text, attachments, reply_to, actions, platform_data içeren giden mesaj zarfı
ChannelSendResponseİleti dizisi için platform mesaj kimliği
InboundMessageTüm ortak alanları + zaman damgasını içeren gelen mesaj zarfı
MessageSenderBot kimliği (name, role, botId) — aracı tarafından zenginleştirilir
AttachmentDosya/görsel/ses eki (type, url, filename, size)
MessageActionEtkileşimli düğme/klavye eylemi (label, callback_id)

Bot Kimliği ve Rolleri

Nebo botlarının üç eksenli bir kimlik modeli vardır:

  • creature — Botun ne olduğu (arketip): "Hazırcevap stratejist", "Titiz araştırmacı"
  • role — Kullanıcıyla nasıl bir ilişkisi olduğu (ilişki): "Arkadaş", "COO", "Mentor"
  • vibe — Enerjisi (iletişim tarzı): "Rahat ama fikir sahibi", "Sıcak ve cesaretlendirici"

Kanal eklentiniz giden bir mesaj aldığında sender alanı botun name ve role değerlerini içerir. Bunu platformunuzdaki görünen adı biçimlendirmek için kullanın. Rol bir iş unvanı değildir — bir ilişki tanımıdır. "COO" ve "DevLead" yanında "Arkadaş", "Oğul" ve "Mentor" da geçerli rollerdir.