NeboAI
NeboAI
Mulakan

Bina Aplikasi untuk Nebo

Berikan AI anda kuasa luar biasa baharu. Alat, saluran, get laluan, panel UI — apa sahaja yang boleh anda bayangkan, dikompil kepada binari natif.

Gambaran Keseluruhan

Apa Itu Nebo

Nebo ialah pembantu AI desktop peribadi — pekerja AI yang sentiasa berjalan dan menguruskan kehidupan digital anda. Fikirkan Nebo seperti anda memikirkan telefon pintar: platform berkuasa yang menjadi transformatif melalui aplikasinya.

Dengan sendirinya, Nebo ialah pekerja AI yang berkebolehan dengan memori, penjadualan, pelayaran web, pengurusan fail dan akses shell. Tetapi kunci sebenarnya ialah Aplikasi. Sama seperti kuasa telefon pintar datang daripada ekosistem aplikasinya, kuasa Nebo datang daripada aplikasi yang meluaskan apa yang boleh dilakukannya.

Apa Itu Aplikasi

Aplikasi Nebo ialah unit fungsi luar biasa yang lengkap dengan sendirinya dan siap dikompil. Setiap aplikasi memberi Nebo kuasa luar biasa baharu — pengurusan kalendar, penyaringan e-mel, penjejakan projek, automasi rumah, analisis kewangan — apa sahaja yang boleh dibayangkan oleh pembangun.

Aplikasi memberikan kuasa luar biasa dengan cara yang sangat selamat. Setiap aplikasi berjalan dalam kotak pasir dengan kebenaran yang ditolak secara lalai. Ia hanya boleh mengakses apa yang diisytiharkan dalam manifesnya dan diluluskan oleh pengguna.

Antara mukanya 100% berasaskan perbualan. Pengguna tidak berinteraksi dengan aplikasi melalui skrin atau papan pemuka berasingan. Mereka bercakap dengan Nebo, dan Nebo menggunakan alat aplikasi itu untuk menyiapkan kerja. "Apa dalam kalendar saya esok?" — Nebo memanggil aplikasi kalendar. "Cipta mesyuarat dengan Sarah pada pukul 3 petang" — Nebo memanggil aplikasi kalendar. Pengguna tidak pernah meninggalkan perbualan.

Aplikasi boleh menyediakan UI tetapan secara pilihan — panel konfigurasi yang dibuka dalam tetingkap pelayar terbina dalam Nebo. Di sinilah pengguna memasukkan kunci API, menghidupkan atau mematikan ciri dan mengkonfigurasi aplikasi. UI tetapan dipacu oleh tatasusunan settings dalam manifes (Nebo memaparkan borang secara automatik), atau aplikasi boleh menyediakan UI tersuai penuhnya sendiri melalui keupayaan ui.

Aplikasi menggantikan dan meluaskan keupayaan terbina dalam Nebo. Nebo disertakan dengan alat platform asas (akses kalendar setempat, tangkapan skrin dan sebagainya). Apabila anda memasang aplikasi kalendar, ia menggantikan alat kalendar terbina dalam dan menjadi superset — setempat + awan + pengagregatan + semakan ketersediaan.

Dasar Kompil Sahaja

Nebo menguatkuasakan dasar binari kompil sahaja yang ketat. Semua aplikasi mestilah fail boleh laku natif yang dikompil.

StatusBahasa
DisokongGo (disyorkan), Rust, C/C++, Zig
DitolakPython, Node.js, Ruby, Java, .NET, skrip shell

Rasional:

  • Pencegahan pengubahsuaian diri oleh AI — Pekerja AI dengan akses shell boleh mengubah tingkah laku skrip yang ditafsir semasa masa jalan. Binari yang dikompil tidak boleh diubah selepas ditandatangani.
  • Integriti tandatangan — Tandatangan Ed25519 meliputi bait binari mentah. Binari yang ditandatangani tidak boleh diubah tanpa membatalkan tandatangan.
  • Penguatkuasaan kotak pasir — Pengesahan format binari (bait ajaib ELF/Mach-O/PE) ialah pintu kawalan yang pantas dan boleh dipercayai.

Mula Pantas

Pasang SDK

SDK rasmi mengendalikan semua persediaan pelayan gRPC, pengendalian isyarat dan penghubungan protokol. Anda hanya perlu melaksanakan antara muka pengendali.

Go (disyorkan):

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

Rust (akan datang):

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

C/C++ (akan datang):

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

Struktur Direktori Aplikasi

Aplikasi berada dalam subdirektori apps/ dalam direktori data Nebo anda:

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

Senarai Semak Aplikasi Minimum

  1. Cipta manifest.json dengan id, name, version, provides
  2. Tulis TOOL.md yang menerangkan cara pekerja AI patut menggunakan alat anda
  3. Pasang SDK (go get github.com/neboloop/nebo-sdk-go)
  4. Laksanakan antara muka pengendali untuk keupayaan anda (ToolHandler, ChannelHandler, dan sebagainya)
  5. Daftarkan pengendali dan panggil app.Run()
  6. Bina binari natif (go build -o binary .)
  7. Letakkan binari + manifest.json + TOOL.md dalam direktori apps/<your-app-id>/
  8. Nebo menemui dan melancarkannya secara automatik

Konfigurasi

manifest.json

Setiap aplikasi memerlukan 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
        }
    ]
}

Medan wajib:

MedanPenerangan
idPengecam domain terbalik (cth., com.mycompany.myapp)
nameNama yang boleh dibaca manusia
versionRentetan semver
providesSekurang-kurangnya satu keupayaan (lihat di bawah)

Medan pilihan:

MedanLalaiPenerangan
runtime"local""local" atau "remote"
protocol"grpc"Hanya "grpc" yang disokong
permissions[]Apa yang perlu diakses oleh aplikasi
description""Dipaparkan dalam UI
settings[]Tetapan boleh dikonfigurasi (dipaparkan dalam UI Tetapan)
oauth[]Keperluan penyedia OAuth (lihat bahagian OAuth di bawah)

Keupayaan

Isytiharkan apa yang disediakan oleh aplikasi anda:

KeupayaanPerkhidmatan gRPCPenerangan
gatewayGatewayServicePenghalaan model LLM
tool:<name>ToolServiceAlat bernama untuk pekerja AI
channel:<name>ChannelServiceSaluran pemesejan
commCommServiceKomunikasi antara pekerja AI
uiUIServiceUI tersuai dengan proksi HTTP
scheduleScheduleServicePenjadualan tersuai
visionToolServicePemprosesan penglihatan
browserToolServiceAutomasi pelayar

Satu aplikasi boleh menyediakan beberapa keupayaan. Contohnya, aplikasi boleh menyediakan kedua-dua alat dan panel UI.

Kebenaran

Kebenaran mengawal apa yang boleh diakses oleh aplikasi. Ditolak secara lalai — jika tidak diisytiharkan, aplikasi tidak boleh menggunakannya.

AwalanContohPenerangan
network:network:outbound, network:*Akses rangkaian
filesystem:filesystem:read, filesystem:writeAkses sistem fail
memory:memory:read, memory:writeAkses memori pekerja AI
session:session:readSesi perbualan
tool:tool:shell, tool:fileGunakan alat lain
shell:shell:execPelaksanaan arahan shell
channel:channel:send, channel:*Operasi saluran
comm:comm:send, comm:*Komunikasi antara pekerja AI
model:model:chatAkses model AI
user:user:tokenTerima JWT pengguna dalam permintaan
schedule:schedule:createPengurusan kerja cron
database:database:queryAkses pangkalan data
storage:storage:read, storage:writeStoran kekal
context:context:readAkses konteks pekerja AI
subagent:subagent:spawnOperasi sub-ejen
lane:lane:enqueueOperasi lorong
notification:notification:sendPemberitahuan tolak
embedding:embedding:searchAkses benaman vektor
skill:skill:invokePemanggilan kemahiran
advisor:advisor:consultAkses sistem penasihat
mcp:mcp:connectAkses pelayan MCP
voice:voice:recordAkses suara/audio
browser:browser:navigateAutomasi pelayar
oauth:oauth:google, oauth:*Akses token OAuth
settings:settings:readAkses tetapan
capability:capability:registerPendaftaran keupayaan

Kebenaran kad bebas disokong: network:* sepadan dengan mana-mana semakan kebenaran network:.

Tetapan

Tetapan dipaparkan dalam UI Nebo di bawah panel tetapan aplikasi. Nebo menyimpannya dalam pangkalan data dan menghantarnya kepada aplikasi anda melalui RPC Configure apabila ia berubah.

Skema tetapan anda disertakan dalam senarai gedung aplikasi NeboAI. Aplikasi dengan tetapan wajib yang belum dikonfigurasi menunjukkan lencana "Perlu Persediaan" dalam UI.

JenisPenerangan
textInput teks satu baris
passwordInput teks bertopeng
toggleSuis hidup/mati Boolean
selectSenarai juntai bawah dengan pilihan yang ditetapkan
numberInput angka
urlInput URL dengan pengesahan
{
    "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"}
    ]
}

Keperluan OAuth

Aplikasi boleh mengisytiharkan keperluan penyedia OAuth. Broker OAuth Nebo mengendalikan keseluruhan aliran — aplikasi menerima token secara automatik melalui RPC Configure.

{
    "oauth": [
        {
            "provider": "google",
            "scopes": ["https://www.googleapis.com/auth/calendar"]
        }
    ]
}
MedanPenerangan
providerPenyedia OAuth: "google", "microsoft", "github"
scopesTatasusunan skop OAuth yang diperlukan oleh aplikasi

Apabila pengguna memasang aplikasi, Nebo meminta mereka membenarkan skop OAuth yang diperlukan. Aplikasi menerima token yang disegarkan melalui RPC Configure tanpa perlu mengendalikan aliran OAuth sendiri.

Pemboleh Ubah Persekitaran

Proses aplikasi anda menerima persekitaran yang telah dibersihkan. Semua rahsia dibuang. Anda mendapat:

Pemboleh ubahNilai
NEBO_APP_DIRDirektori pemasangan aplikasi
NEBO_APP_SOCKLaluan ke soket Unix yang perlu dicipta
NEBO_APP_IDID aplikasi daripada manifes
NEBO_APP_NAMENama aplikasi daripada manifes
NEBO_APP_VERSIONVersi aplikasi daripada manifes
NEBO_APP_DATALaluan ke direktori data/ aplikasi
PATHPATH sistem (diteruskan)
HOMEDirektori rumah pengguna (diteruskan)
TMPDIRDirektori sementara (diteruskan)

Penting: Binari anda mesti mencipta pelayan gRPC yang mendengar pada soket Unix di NEBO_APP_SOCK. Nebo menunggu sehingga 10 saat untuk soket ini muncul.

Urutan Pelancaran Aplikasi

  1. Nebo membaca manifest.json dan mengesahkannya
  2. Mencari fail boleh laku binary atau app dalam direktori aplikasi
  3. Menyemak penanda .quarantined (enggan melancarkan aplikasi yang dikuarantin)
  4. Semakan pembatalan (aplikasi yang diedarkan oleh NeboAI sahaja)
  5. Pengesahan tandatangan (aplikasi yang diedarkan oleh NeboAI sahaja, dilangkau dalam mod pembangunan)
  6. Pengesahan binari (menolak pautan simbolik, skrip, fail bukan boleh laku, fail bersaiz terlalu besar)
  7. Membersihkan soket lapuk daripada larian sebelumnya
  8. Mencipta direktori data/ untuk storan berkotak pasir
  9. Menyediakan fail log bagi setiap aplikasi (logs/stdout.log, logs/stderr.log)
  10. Memulakan binari dengan persekitaran yang dibersihkan dan pengasingan kumpulan proses
  11. Menunggu soket Unix muncul (pengunduran eksponen, maksimum 10 saat)
  12. Menyambung melalui gRPC menerusi soket Unix
  13. Mencipta klien gRPC khusus keupayaan berdasarkan provides
  14. Menjalankan semakan kesihatan
  15. Mendaftarkan keupayaan dengan pekerja AI (alat, get laluan, komunikasi, dan sebagainya)

Aplikasi Alat

Isytiharkan "provides": ["tool:my_tool_name"] dalam manifes anda.

Corak STRAP

Semua aplikasi alat Nebo mesti menggunakan STRAP (Single Tool Resource Action Pattern) untuk skema dan penghalaan pelaksanaannya. Inilah corak yang sama digunakan Nebo secara dalaman untuk menyatukan 35+ alat individu kepada 4 alat domain — mengurangkan beban konteks LLM sebanyak ~80%.

Idea teras: Daripada mendaftarkan beberapa alat (get_events, check_availability, suggest_slots), daftarkan SATU alat dengan medan action (dan secara pilihan resource) yang menghalakan kepada pengendali yang betul.

Contoh satu sumber (kalendar):

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

Contoh berbilang sumber (pengurus projek):

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

Peraturan skema:

  1. Sentiasa sertakan medan action sebagai enum rentetan wajib
  2. Tambah medan resource (enum rentetan wajib) hanya jika alat anda menguruskan beberapa jenis sumber yang berbeza
  3. Semua medan lain ialah parameter khusus tindakan
  4. Penerangan enum action patut menyenaraikan semua tindakan yang tersedia

Mengapa STRAP penting:

  • LLM mempelajari corak penghalaan action sekali dan menggeneralisasikannya merentas semua operasi
  • Definisi alat menggunakan ~6% konteks — STRAP mengurangkannya sebanyak 80%
  • Operasi baharu hanyalah tambahan enum, bukan pendaftaran alat baharu
  • Berfungsi secara sama merentas model yang dihoskan dan model setempat

Contoh Go — Alat Kalkulator

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

Bina dan pasang:

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/

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

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

Aplikasi Saluran

Isytiharkan "provides": ["channel:my_channel"] dan "permissions": ["channel:send"].

Aplikasi saluran menghubungkan platform pemesejan luaran (Telegram, Discord, Slack, dan sebagainya) dengan pekerja AI Nebo. Apabila pengguna menghantar mesej pada platform luaran, aplikasi anda menstrimnya kepada Nebo melalui Receive. Apabila pekerja AI mahu membalas, Nebo memanggil Send aplikasi anda.

Cara ia berfungsi

  1. Nebo memanggil ID() untuk mendapatkan pengecam unik saluran anda
  2. Nebo memanggil Connect() dengan konfigurasi daripada tetapan aplikasi anda
  3. Nebo membuka strim Receive() — aplikasi anda menghantar mesej masuk setiap kali pengguna menghantar mesej kepada bot
  4. Mesej masuk dihalakan ke lorong perbualan utama pekerja AI
  5. Apabila pekerja AI mahu menghantar mesej, Nebo memanggil Send() dengan sampul mesej v1
  6. Semasa penutupan, Nebo memanggil Disconnect()

Sampul Mesej v1

Semua mesej saluran — masuk dan keluar — menggunakan sampul mesej yang sama:

{
  "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"
}
MedanJenisPenerangan
message_idUUID v7ID unik tersusun mengikut masa
channel_id{type}:{platform_id}Pengecam saluran yang boleh dihalakan
senderobjectIdentiti bot — nama, peranan, botId
textstringKandungan mesej
attachmentsarrayFail, imej, audio
reply_toUUID v7ID mesej induk untuk bebenang
actionsarrayButang/papan kekunci interaktif
platform_databytesData lalu legap untuk ciri khusus platform
timestampISO 8601Penerbit menetapkan ini

Reka bentuk dua lapisan: Medan biasa (text, attachments, reply_to, actions) meliputi 90% pemesejan yang dimulakan oleh pekerja. Ciri khusus platform diletakkan dalam platform_data — plugin anda memetakannya ke/dari format platform natif.

Strim Perbualan

Mesej saluran dihalakan melalui strim perbualan bagi setiap saluran untuk pengasingan:

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

Contoh Go — Saluran 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
        }
    ]
}

Lebih Banyak Keupayaan

Aplikasi Komunikasi

Isytiharkan "provides": ["comm"] dan "permissions": ["comm:*"]. Aplikasi komunikasi membolehkan komunikasi antara pekerja AI.

MedanPenerangan
fromID pekerja penghantar
toID pekerja penerima
topicTopik/saluran mesej
type"message", "mention", "proposal", "command", "info", "task"
contentKandungan mesej

Tingkah laku utama:

  • Register mengumumkan pekerja AI ini pada rangkaian bersama keupayaannya
  • Subscribe/Unsubscribe menguruskan langganan topik
  • Receive menstrim mesej masuk (penstriman pelayan, sama seperti saluran)
  • Hanya satu aplikasi komunikasi boleh aktif pada satu masa

Aplikasi Get Laluan

Aplikasi get laluan menghalakan permintaan LLM kepada model. Isytiharkan "provides": ["gateway"] dan "permissions": ["network:outbound", "user:token"].

GatewayRequest mengandungi mesej, alat, gesaan sistem, token maksimum, suhu dan UserContext (token JWT jika kebenaran user:token diberikan).

Jenis GatewayEvent:

JenisKandunganPenerangan
"text"Cebisan teksToken teks penstriman
"tool_call"JSONModel mahu memanggil alat
"thinking"Cebisan teksPemikiran/penaakulan lanjutan
"error"Mesej ralatSesuatu telah tidak kena
"done"KosongStrim telah selesai

Aplikasi UI

Aplikasi UI menyediakan antara muka konfigurasi tersuai yang dibuka dalam tetingkap pelayar terbina dalam Nebo. Isytiharkan "provides": ["ui"]. Tidak seperti borang tetapan automatik (yang dipaparkan Nebo daripada manifes settings anda), aplikasi UI menyajikan bahagian hadapan HTML/CSS/JS penuhnya sendiri.

Aplikasi anda disertakan dengan direktori ui/ yang mengandungi aset web statik (HTML, CSS, JS — biasanya SPA dengan index.html). Nebo menyajikan fail ini secara terus dan memproksikan panggilan API kepada aplikasi anda melalui gRPC.

LaluanMekanismeTujuan
GET /api/v1/apps/{id}/ui/*Pelayan fail statikMenyajikan fail daripada direktori ui/ anda (sandaran SPA kepada index.html)
ANY /api/v1/apps/{id}/api/*Proksi gRPCMemproksikan permintaan HTTP kepada UIService.HandleRequest() aplikasi anda

SDK membalut net/http.ServeMux standard supaya anda menulis pengendali HTTP Go biasa — SDK mengendalikan penghubungan gRPC secara automatik.

Contoh Go — UI Papan Pemuka:

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 anda akan membuat panggilan fetch ke /api/v1/apps/com.example.dashboard/api/status, yang diproksikan terus kepada pengendali mux anda.

Aplikasi Jadual

Aplikasi jadual menggantikan penjadual cron terbina dalam Nebo. Isytiharkan "provides": ["schedule"] dan "permissions": ["schedule:create"].

Apabila aplikasi jadual anda dilancarkan, Nebo menghalakan semua penjadualan melalui aplikasi anda dan bukannya enjin cron lalai. Jika aplikasi anda ranap, Nebo kembali kepada enjin terbina dalam secara automatik.

  • Aplikasi anda memiliki keadaan jadual — Nebo tidak menyimpan jadual dalam DB sendiri apabila aplikasi jadual aktif
  • CRUD standard: Create, Get, List, Update, Delete, Enable, Disable
  • Triggers ialah RPC penstriman pelayan — aplikasi anda menghantar mesej pencetus setiap kali sesuatu jadual tercetus
  • Hanya satu aplikasi jadual boleh aktif pada satu masa

Aplikasi Berbilang Keupayaan

Satu aplikasi boleh menyediakan beberapa keupayaan. Contohnya, aplikasi papan pemuka dengan kedua-dua alat dan UI:

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

Pembungkusan

Format .napp

Untuk pengedaran melalui NeboAI, bungkus aplikasi anda sebagai fail .napp (arkib tar.gz):

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

Fail wajib:

FailSaiz MaksPenerangan
manifest.json1 MBMetadata aplikasi
binary atau app500 MBFail boleh laku
signatures.json1 MBTandatangan Ed25519
TOOL.md1 MBArahan alat untuk pekerja AI

Peraturan keselamatan semasa pengekstrakan:

  • Tiada penyusuran laluan (../ ditolak)
  • Tiada pautan simbolik (ditolak)
  • Tiada laluan mutlak (ditolak)
  • Hanya nama fail dalam senarai dibenarkan diterima

Tandatangan

NeboAI menandatangani aplikasi dengan Ed25519. Format 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>"
}

Dalam mod pembangunan (tiada URL NeboAI dikonfigurasi), pengesahan tandatangan dilangkau sepenuhnya. Anda tidak memerlukan signatures.json untuk pembangunan setempat.

Penerbitan

Setelah aplikasi anda berfungsi secara setempat, terbitkannya melalui NeboAI untuk diedarkan kepada semua pengguna Nebo.

Persediaan Akaun Pembangun

  1. Daftar akaun NeboAI di POST /api/v1/owners/register
  2. Log masuk untuk mendapatkan token JWT: POST /api/v1/owners/login
  3. Cipta akaun pembangun: POST /api/v1/developer/accounts

Aliran Penghantaran

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

Langkah 1: Cipta aplikasi

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

Langkah 2: Muat naik binari platform

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"

Muat naik satu binari bagi setiap platform: darwin-arm64, darwin-amd64, linux-amd64, linux-arm64.

Langkah 3: Hantar untuk semakan

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

Proses Semakan

  1. Imbasan automatik — binari diimbas melalui VirusTotal
  2. Semakan pentadbir — pasukan NeboAI menyemak metadata, manifes dan hasil imbasan
  3. Apabila diluluskan — NeboAI menandatangani aplikasi dengan Ed25519 dan menerbitkannya
  4. Apabila ditolak — anda menerima sebab penolakan dan boleh membetulkan serta menghantarnya semula

Sasaran masa semakan: <24 jam.

Menghantar Kemas Kini

  1. Kemas kini versi aplikasi: PUT /api/v1/developer/apps/{id} dengan versi baharu
  2. Muat naik binari baharu untuk setiap platform
  3. Hantar untuk semakan sekali lagi

Setiap kemas kini melalui proses semakan yang sama. Versi sebelumnya kekal tersedia sehingga versi baharu diluluskan.

Metadata Gedung

MedanPenerangan
categorycth., productivity, communication, developer-tools
iconURL ikon aplikasi
visibilitypublic atau private
descriptionBoleh lebih panjang/lebih terperinci daripada penerangan manifes

Aliran Kerja Pembangunan

Pembangunan Setempat

Tiada pembungkusan diperlukan untuk pembangunan setempat:

  1. Cipta direktori aplikasi anda:
    mkdir -p ~/Library/Application\ Support/Nebo/apps/com.example.myapp
  2. Tulis manifest.json dan kod anda
  3. Bina binari anda:
    go build -o ~/Library/Application\ Support/Nebo/apps/com.example.myapp/binary .
  4. Nebo mengesan direktori baharu secara automatik (atau mulakan semula Nebo)
  5. Selepas perubahan kod, bina semula binari — pemerhati fail akan memulakan semula aplikasi

Melihat Log

stdout/stderr aplikasi ditangkap dalam fail log bagi setiap aplikasi:

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 Kekal

Gunakan direktori data/ (juga tersedia sebagai pemboleh ubah persekitaran NEBO_APP_DATA) untuk sebarang fail yang perlu disimpan secara kekal oleh aplikasi anda. Direktori ini kekal selepas kemas kini aplikasi dan kuarantin.

Petua Penyahpepijatan

  • Jika aplikasi anda tidak bermula, semak logs/stderr.log untuk ralat
  • Pastikan binari boleh dilaksanakan (chmod +x binary)
  • Pastikan anda mendengar pada laluan soket Unix daripada NEBO_APP_SOCK
  • Soket mesti sedia dalam masa 10 saat selepas pelancaran
  • Gunakan NEBO_APP_DATA untuk storan, bukan laluan yang dikod keras
  • Cetak ke stderr untuk log penyahpepijatan (ditangkap dalam logs/stderr.log)

Mengesahkan

# 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

Menyahpasang

nebo apps uninstall com.example.myapp

Kemahiran

Apa Itu Kemahiran

Kemahiran ialah set arahan yang membentuk tingkah laku Nebo semasa perbualan. Apabila kemahiran aktif, kandungannya disuntik terus ke dalam gesaan sistem — membimbing nada, metodologi, kepakaran domain dan penggunaan alat pekerja AI untuk sesi itu.

Kemahiran bukan kod. Ia ialah dokumen markdown dengan metadata YAML. Tiada pengkompilan, tiada binari, tiada gRPC. Kemahiran ialah fail SKILL.md dalam sebuah direktori. Itu sahaja.

Kemahiran bersifat kontekstual dan sementara. Ia diaktifkan apabila relevan (melalui padanan pencetus atau pemuatan manual), kekal untuk beberapa giliran, dan tamat tempoh apabila tidak lagi diperlukan. Ini memastikan konteks pekerja AI kekal ramping — hanya panduan yang penting pada masa itu berada dalam gesaan.

Kemahiran melengkapi aplikasi. Aplikasi menyediakan keupayaan boleh laksana (alat, saluran, get laluan). Kemahiran menyediakan panduan orkestrasi — cara menggunakan alat tersebut dengan berkesan. Aplikasi kalendar memberi Nebo keupayaan membaca dan menulis acara. Kemahiran "persediaan mesyuarat" memberitahu Nebo cara bersedia untuk mesyuarat menggunakan aplikasi kalendar itu, e-mel dan carian web bersama-sama.

Kemahiran berbanding Aplikasi

KemahiranAplikasi
FormatMarkdown (SKILL.md)Binari yang dikompil (.napp)
Masa jalanDisuntik ke dalam gesaan sistemProses berkotak pasir melalui gRPC
MenyediakanPanduan tingkah laku, metodologiAlat, saluran, panel UI
Jangka hayatBerskop sesi, tamat tempoh berdasarkan TTLSentiasa berjalan
PenciptaanTulis fail markdownTulis, kompil, tandatangan, bungkus
KeselamatanTiada kebenaran diperlukanKotak pasir yang menolak secara lalai

Mula Pantas

Cipta direktori dalam folder kemahiran Nebo anda dengan fail SKILL.md:

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

Tulis 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 memerhati direktori kemahiran dengan fsnotify. Kemahiran anda tersedia serta-merta — tidak perlu dimulakan semula. Katakan sesuatu yang sepadan dengan pencetus, dan ia diaktifkan secara automatik.

Atau minta Nebo secara terus: "Cipta kemahiran untuk menulis catatan blog" — Nebo akan menulis fail SKILL.md untuk anda.

Format SKILL.md

Setiap kemahiran ialah satu fail SKILL.md dengan dua bahagian: frontmatter YAML di antara penanda ---, dan badan markdown (arahan sebenar yang disuntik ke dalam gesaan sistem).

MedanWajibLalaiPenerangan
nameYa—Pengecam unik (menjadi slug)
descriptionYa—Penerangan satu baris yang dipaparkan dalam katalog kemahiran
versionTidak"1.0.0"Semver untuk menjejak kemas kini
authorTidak—Pengarang kemahiran
priorityTidak0Lebih tinggi = dipadankan dahulu (100+ untuk penggantian kritikal)
max_turnsTidak4Giliran tanpa aktiviti sebelum tamat tempoh automatik
triggersTidak[]Frasa yang mengaktifkan kemahiran ini secara automatik (padanan subrentetan tanpa mengira huruf besar/kecil)
toolsTidak[]Alat yang dijangka digunakan oleh kemahiran ini (untuk makluman)
dependenciesTidak[]Kemahiran lain yang mesti dipasang
tagsTidak[]Untuk pengkategorian dan penemuan
platformTidak[]Platform yang disokong: macos, linux, windows (kosong = semua)

Cara Kemahiran Diaktifkan

Kemahiran mengikut model pengaktifan dua fasa: petunjuk, kemudian panggil.

Fasa 1: Padanan Pencetus — Setiap kali pengguna menghantar mesej, Nebo mengimbas semua kemahiran berdaftar untuk padanan pencetus. Kemahiran yang sepadan muncul sebagai petunjuk dalam gesaan sistem. Pekerja AI melihat petunjuk itu dan memutuskan sama ada untuk memanggil kemahiran tersebut.

Fasa 2: Pemanggilan — Pekerja AI memanggil kemahiran dengan memanggil:

skill(name: "code-review")

Ini mengembalikan templat SKILL.md penuh sebagai hasil alat, merekodkan pemanggilan, dan menyuntik semula templat ke dalam gesaan sistem pada giliran seterusnya.

TTL dan Tamat Tempoh:

  • Kemahiran yang dipadankan secara automatik: 4 giliran tanpa aktiviti (boleh dikonfigurasi melalui max_turns)
  • Kemahiran yang dimuatkan secara manual: 6 giliran tanpa aktiviti
  • Pemanggilan semula menetapkan semula pemasa
  • Had mutlak: maksimum 4 kemahiran aktif bagi setiap sesi
  • Bajet token: gabungan kandungan kemahiran aktif dihadkan kepada 16,000 aksara

Menguruskan Kemahiran

Pekerja AI boleh menguruskan kemahiran melalui alat skill:

TindakanPeneranganContoh
catalogSenaraikan semua kemahiran yang tersediaskill(action: "catalog")
loadAktifkan untuk sesi iniskill(name: "code-review", action: "load")
unloadNyahaktifkan kemahiranskill(name: "code-review", action: "unload")
createCipta kemahiran baharu pada cakeraskill(action: "create", content: "...")
updateKemas kini kemahiran sedia adaskill(name: "my-skill", action: "update", content: "...")
deletePadam kemahiran daripada cakeraskill(name: "my-skill", action: "delete")

Menulis Kemahiran yang Baik

Templat kemahiran yang baik mempunyai:

  1. Tajuk yang jelas — memberitahu pekerja AI mod apa yang sedang digunakannya
  2. Prinsip teras — peraturan tingkah laku yang tidak boleh dikompromi
  3. Metodologi — pendekatan langkah demi langkah untuk senario biasa
  4. Contoh — corak konkrit mesej pengguna kepada balasan
  5. Anti-corak — apa yang TIDAK patut dilakukan (model belajar dengan baik daripada contoh negatif)

Petua: Setiap kemahiran patut melakukan satu perkara dengan baik. Jangan cipta kemahiran "pengaturcaraan umum" — cipta code-review, debugging, api-design sebagai kemahiran berasingan. Pekerja AI boleh mempunyai beberapa kemahiran aktif serentak.

Kemahiran Terbina

Nebo disertakan dengan kemahiran terbina yang meliputi kes penggunaan biasa:

KemahiranKeutamaanPenerangan
onboarding100Ucapan alu-aluan pengguna baharu dan pengumpulan profil
best-friend50Kemahiran personaliti — santai, setia, bercakap terus terang
debugging25Metodologi penyahpepijatan yang sistematik
api-design15Amalan terbaik reka bentuk API RESTful
code-review10Semakan kod berstruktur dengan tahap keterukan
database-expert10Reka bentuk pangkalan data, pertanyaan, pengoptimuman
git-workflow10Pencabangan Git, commit, aliran kerja PR
security-audit10Analisis keselamatan dan pengesanan kerentanan

Ini berfungsi sebagai lalai yang berguna dan juga pelaksanaan rujukan untuk mencipta kemahiran anda sendiri.

Rujukan

Fail Proto

Fail proto berada dalam proto/apps/v0/. SDK disertakan dengan kod yang telah dijana, jadi anda tidak memerlukan protoc untuk pembangunan biasa.

FailPerkhidmatanRPC Utama
v0/common.proto(mesej sahaja)HealthCheckRequest/Response, SettingsMap, UserContext, Empty
v0/tool.protoToolServiceName, Description, Schema, Execute, RequiresApproval, Configure
v0/channel.protoChannelServiceID, Connect, Disconnect, Send, Receive (strim), Configure
v0/comm.protoCommServiceName, Version, Connect, Disconnect, Send, Subscribe, Register, Receive (strim), Configure
v0/gateway.protoGatewayServiceHealthCheck, Stream (strim), Poll, Cancel, Configure
v0/ui.protoUIServiceHealthCheck, HandleRequest, Configure
v0/schedule.protoScheduleServiceHealthCheck, Create, Get, List, Update, Delete, Enable, Disable, Trigger, History, Triggers (strim), Configure

Setiap perkhidmatan menyertakan RPC HealthCheck dan Configure. SDK mengendalikan kedua-duanya secara automatik.

Jenis Proto Saluran

Jenis MesejPenerangan
ChannelSendRequestSampul mesej keluar dengan message_id, channelId, sender, text, attachments, reply_to, actions, platform_data
ChannelSendResponseID mesej platform untuk bebenang
InboundMessageSampul mesej masuk dengan semua medan biasa + cap masa
MessageSenderIdentiti bot (name, role, botId) — diperkaya oleh broker
AttachmentLampiran fail/imej/audio (type, url, filename, size)
MessageActionTindakan butang/papan kekunci interaktif (label, callback_id)

Identiti dan Peranan Bot

Bot Nebo mempunyai model identiti tiga paksi:

  • creature — Apa bot itu (arketaip): "Ahli strategi yang cepat berfikir", "Penyelidik yang teliti"
  • role — Hubungannya dengan pengguna (perhubungan): "Kawan", "COO", "Mentor"
  • vibe — Tenaganya (gaya komunikasi): "Tenang tetapi berpendirian", "Mesra dan memberi galakan"

Apabila plugin saluran anda menerima mesej keluar, medan sender mengandungi name dan role bot. Gunakan ini untuk memformat nama paparan bagi platform anda. Peranan itu bukan jawatan — ia ialah penerangan perhubungan. "Kawan", "Anak" dan "Mentor" ialah peranan yang sah selain "COO" dan "DevLead".