Ikhtisar
Apa Itu Nebo
Nebo adalah asisten AI desktop pribadi — karyawan AI yang selalu berjalan dan mengelola kehidupan digital Anda. Anggap Nebo seperti Anda memandang smartphone: platform andal yang menjadi transformatif berkat aplikasinya.
Dengan sendirinya, Nebo adalah karyawan AI yang cakap dengan memori, penjadwalan, penjelajahan web, pengelolaan file, dan akses shell. Namun kunci sebenarnya adalah Aplikasi. Seperti kekuatan smartphone berasal dari ekosistem aplikasinya, kekuatan Nebo berasal dari aplikasi yang memperluas apa yang bisa dilakukannya.
Apa Itu Aplikasi
Aplikasi Nebo adalah unit fungsionalitas luar biasa yang berdiri sendiri dan sudah dikompilasi. Setiap aplikasi memberi Nebo kekuatan super baru — pengelolaan kalender, pemilahan email, pelacakan proyek, otomatisasi rumah, analisis keuangan — apa pun yang bisa dibayangkan developer.
Aplikasi memberikan kekuatan luar biasa dengan cara yang sangat aman. Setiap aplikasi berjalan di sandbox dengan izin yang ditolak secara default. Aplikasi hanya dapat mengakses apa yang dideklarasikan manifesnya dan disetujui pengguna.
Antarmukanya 100% berbasis percakapan. Pengguna tidak berinteraksi dengan aplikasi melalui layar atau dasbor terpisah. Mereka berbicara dengan Nebo, dan Nebo menggunakan alat aplikasi untuk menyelesaikan pekerjaan. "Apa jadwal saya besok?" — Nebo memanggil aplikasi kalender. "Buat rapat dengan Sarah pukul 3 sore" — Nebo memanggil aplikasi kalender. Pengguna tidak pernah meninggalkan percakapan.
Aplikasi secara opsional dapat menyediakan UI pengaturan — panel konfigurasi yang terbuka di jendela browser bawaan Nebo. Di sinilah pengguna memasukkan kunci API, mengaktifkan fitur, dan mengonfigurasi aplikasi. UI pengaturan dikendalikan oleh array settings di manifes (Nebo merender formulirnya secara otomatis), atau aplikasi dapat menyediakan UI kustomnya sendiri sepenuhnya melalui kapabilitas ui.
Aplikasi menggantikan dan memperluas kemampuan bawaan Nebo. Nebo dilengkapi alat platform dasar (akses kalender lokal, tangkapan layar, dll.). Saat Anda memasang aplikasi kalender, aplikasi itu menggantikan alat kalender bawaan dan menjadi superset-nya — lokal + cloud + agregasi + pengecekan ketersediaan.
Kebijakan Hanya Kompilasi
Nebo menerapkan kebijakan ketat yang hanya menerima biner terkompilasi. Semua aplikasi harus berupa executable native yang dikompilasi.
| Status | Bahasa |
|---|---|
| Didukung | Go (direkomendasikan), Rust, C/C++, Zig |
| Ditolak | Python, Node.js, Ruby, Java, .NET, skrip shell |
Alasan:
- Mencegah AI memodifikasi dirinya sendiri — Karyawan AI dengan akses shell dapat mengubah perilaku skrip yang diinterpretasikan saat runtime. Biner terkompilasi tidak dapat diubah setelah ditandatangani.
- Integritas tanda tangan — Tanda tangan Ed25519 mencakup byte biner mentah. Biner yang ditandatangani tidak dapat dimodifikasi tanpa membatalkan tanda tangannya.
- Penegakan sandbox — Validasi format biner (magic bytes ELF/Mach-O/PE) adalah gerbang yang cepat dan andal.
Mulai Cepat
Pasang SDK
SDK resmi menangani semua penyiapan server gRPC, penanganan sinyal, dan penjembatanan protokol. Anda cukup mengimplementasikan antarmuka handler.
Go (direkomendasikan):
go get github.com/neboloop/nebo-sdk-go Rust (segera hadir):
# Coming soon
[dependencies]
nebo-sdk = "0.1" C/C++ (segera hadir):
# Coming soon — Add as a CMake subdirectory or copy headers from sdk/c/include/ Struktur Direktori Aplikasi
Aplikasi berada di subdirektori apps/ dari 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) Daftar Periksa Aplikasi Minimal
- Buat
manifest.jsondenganid,name,version,provides - Tulis
TOOL.mdyang menjelaskan cara karyawan AI menggunakan alat Anda - Pasang SDK (
go get github.com/neboloop/nebo-sdk-go) - Implementasikan antarmuka handler untuk kapabilitas Anda (
ToolHandler,ChannelHandler, dll.) - Daftarkan handler dan panggil
app.Run() - Build biner native (
go build -o binary .) - Letakkan biner + manifest.json + TOOL.md di direktori
apps/<your-app-id>/ - Nebo menemukan dan meluncurkannya secara otomatis
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
}
]
} Field wajib:
| Field | Deskripsi |
|---|---|
id | Pengenal domain terbalik (misalnya, com.mycompany.myapp) |
name | Nama yang mudah dibaca |
version | String semver |
provides | Setidaknya satu kapabilitas (lihat di bawah) |
Field opsional:
| Field | Default | Deskripsi |
|---|---|---|
runtime | "local" | "local" atau "remote" |
protocol | "grpc" | Hanya "grpc" yang didukung |
permissions | [] | Apa yang perlu diakses aplikasi |
description | "" | Ditampilkan di UI |
settings | [] | Pengaturan yang dapat dikonfigurasi (dirender di UI Pengaturan) |
oauth | [] | Persyaratan penyedia OAuth (lihat bagian OAuth di bawah) |
Kapabilitas
Deklarasikan apa yang disediakan aplikasi Anda:
| Kapabilitas | Layanan gRPC | Deskripsi |
|---|---|---|
gateway | GatewayService | Perutean model LLM |
tool:<name> | ToolService | Alat bernama untuk karyawan AI |
channel:<name> | ChannelService | Kanal perpesanan |
comm | CommService | Komunikasi antar-karyawan AI |
ui | UIService | UI kustom dengan proxy HTTP |
schedule | ScheduleService | Penjadwalan kustom |
vision | ToolService | Pemrosesan visual |
browser | ToolService | Otomatisasi browser |
Satu aplikasi dapat menyediakan beberapa kapabilitas. Misalnya, sebuah aplikasi dapat menyediakan alat sekaligus panel UI.
Izin
Izin mengatur apa yang dapat diakses aplikasi. Ditolak secara default — jika tidak dideklarasikan, aplikasi tidak dapat menggunakannya.
| Prefiks | Contoh | Deskripsi |
|---|---|---|
network: | network:outbound, network:* | Akses jaringan |
filesystem: | filesystem:read, filesystem:write | Akses sistem file |
memory: | memory:read, memory:write | Akses memori karyawan AI |
session: | session:read | Sesi percakapan |
tool: | tool:shell, tool:file | Menggunakan alat lain |
shell: | shell:exec | Eksekusi perintah shell |
channel: | channel:send, channel:* | Operasi kanal |
comm: | comm:send, comm:* | Komunikasi antar-karyawan AI |
model: | model:chat | Akses model AI |
user: | user:token | Menerima JWT pengguna dalam permintaan |
schedule: | schedule:create | Pengelolaan cron job |
database: | database:query | Akses database |
storage: | storage:read, storage:write | Penyimpanan persisten |
context: | context:read | Akses konteks karyawan AI |
subagent: | subagent:spawn | Operasi sub-agent |
lane: | lane:enqueue | Operasi lane |
notification: | notification:send | Notifikasi push |
embedding: | embedding:search | Akses embedding vektor |
skill: | skill:invoke | Pemanggilan skill |
advisor: | advisor:consult | Akses sistem penasihat |
mcp: | mcp:connect | Akses server MCP |
voice: | voice:record | Akses suara/audio |
browser: | browser:navigate | Otomatisasi browser |
oauth: | oauth:google, oauth:* | Akses token OAuth |
settings: | settings:read | Akses pengaturan |
capability: | capability:register | Pendaftaran kapabilitas |
Izin wildcard didukung: network:* cocok dengan pemeriksaan izin network: apa pun.
Pengaturan
Pengaturan muncul di UI Nebo pada panel pengaturan aplikasi. Nebo menyimpannya di database dan mengirimkannya ke aplikasi Anda melalui RPC Configure saat berubah.
Skema pengaturan Anda disertakan dalam listing toko aplikasi NeboAI. Aplikasi dengan pengaturan wajib yang belum dikonfigurasi menampilkan lencana "Perlu Penyiapan" di UI.
| Tipe | Deskripsi |
|---|---|
text | Input teks satu baris |
password | Input teks tersamar |
toggle | Sakelar boolean aktif/nonaktif |
select | Dropdown dengan opsi yang telah ditentukan |
number | Input numerik |
url | Input URL dengan validasi |
{
"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"}
]
} Persyaratan OAuth
Aplikasi dapat mendeklarasikan persyaratan penyedia OAuth. Broker OAuth Nebo menangani seluruh alurnya — aplikasi menerima token secara otomatis melalui RPC Configure.
{
"oauth": [
{
"provider": "google",
"scopes": ["https://www.googleapis.com/auth/calendar"]
}
]
} | Field | Deskripsi |
|---|---|
provider | Penyedia OAuth: "google", "microsoft", "github" |
scopes | Array cakupan OAuth yang dibutuhkan aplikasi |
Saat pengguna memasang aplikasi, Nebo meminta mereka mengotorisasi cakupan OAuth yang diperlukan. Aplikasi menerima token yang diperbarui melalui RPC Configure tanpa menangani alur OAuth sendiri.
Variabel Lingkungan
Proses aplikasi Anda menerima lingkungan yang telah disanitasi. Semua rahasia dihapus. Anda mendapatkan:
| Variabel | Nilai |
|---|---|
NEBO_APP_DIR | Direktori instalasi aplikasi |
NEBO_APP_SOCK | Path ke socket Unix yang harus dibuat |
NEBO_APP_ID | ID aplikasi dari manifes |
NEBO_APP_NAME | Nama aplikasi dari manifes |
NEBO_APP_VERSION | Versi aplikasi dari manifes |
NEBO_APP_DATA | Path ke direktori data/ aplikasi |
PATH | PATH sistem (diteruskan) |
HOME | Direktori home pengguna (diteruskan) |
TMPDIR | Direktori sementara (diteruskan) |
Penting: Biner Anda harus membuat server gRPC yang mendengarkan socket Unix di NEBO_APP_SOCK. Nebo menunggu hingga 10 detik sampai socket ini muncul.
Urutan Peluncuran Aplikasi
- Nebo membaca
manifest.jsondan memvalidasinya - Menemukan executable
binaryatauappdi direktori aplikasi - Memeriksa penanda
.quarantined(menolak meluncurkan aplikasi yang dikarantina) - Pemeriksaan pencabutan (hanya aplikasi yang didistribusikan NeboAI)
- Verifikasi tanda tangan (hanya aplikasi yang didistribusikan NeboAI, dilewati dalam mode dev)
- Validasi biner (menolak symlink, skrip, file non-executable, file berukuran terlalu besar)
- Membersihkan socket usang dari proses sebelumnya
- Membuat direktori
data/untuk penyimpanan dalam sandbox - Menyiapkan file log per aplikasi (
logs/stdout.log,logs/stderr.log) - Memulai biner dengan lingkungan yang disanitasi dan isolasi grup proses
- Menunggu socket Unix muncul (exponential backoff, maksimal 10 detik)
- Terhubung melalui gRPC lewat socket Unix
- Membuat klien gRPC khusus kapabilitas berdasarkan
provides - Menjalankan pemeriksaan kesehatan
- Mendaftarkan kapabilitas ke karyawan AI (alat, gateway, comm, dll.)
Aplikasi Alat
Deklarasikan "provides": ["tool:my_tool_name"] di manifes Anda.
Pola STRAP
Semua aplikasi alat Nebo wajib menggunakan STRAP (Single Tool Resource Action Pattern) untuk skema dan perutean eksekusinya. Ini adalah pola yang sama yang digunakan Nebo secara internal untuk menggabungkan 35+ alat individual menjadi 4 alat domain — mengurangi beban konteks LLM sekitar 80%.
Gagasan inti: Alih-alih mendaftarkan banyak alat (get_events, check_availability, suggest_slots), daftarkan SATU alat dengan field action (dan opsional resource) yang merutekan ke handler yang tepat.
Contoh satu resource (kalender):
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 multi-resource (manajer proyek):
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") Aturan skema:
- Selalu sertakan field
actionsebagai enum string wajib - Tambahkan field
resource(enum string wajib) hanya jika alat Anda mengelola beberapa tipe resource yang berbeda - Semua field lainnya adalah parameter khusus action
- Deskripsi enum
actionharus mencantumkan semua action yang tersedia
Mengapa STRAP penting:
- LLM mempelajari pola perutean
actionsekali dan menerapkannya ke semua operasi - Definisi alat memakan ~6% konteks — STRAP memangkasnya hingga 80%
- Operasi baru cukup berupa penambahan enum, bukan pendaftaran alat baru
- Bekerja secara identik di model yang di-host maupun model lokal
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": []
} Build 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 Kanal
Deklarasikan "provides": ["channel:my_channel"] dan "permissions": ["channel:send"].
Aplikasi kanal menjembatani platform perpesanan eksternal (Telegram, Discord, Slack, dll.) ke karyawan AI Nebo. Saat pengguna mengirim pesan di platform eksternal, aplikasi Anda mengalirkannya ke Nebo melalui Receive. Saat karyawan AI ingin membalas, Nebo memanggil Send milik aplikasi Anda.
Cara kerjanya
- Nebo memanggil
ID()untuk mendapatkan pengenal unik kanal Anda - Nebo memanggil
Connect()dengan konfigurasi dari pengaturan aplikasi Anda - Nebo membuka stream
Receive()— aplikasi Anda mengirim pesan masuk setiap kali pengguna mengirim pesan ke bot - Pesan masuk dirutekan ke lane percakapan utama karyawan AI
- Saat karyawan AI ingin mengirim pesan, Nebo memanggil
Send()dengan amplop pesan v1 - Saat dimatikan, Nebo memanggil
Disconnect()
Amplop Pesan v1
Semua pesan kanal — masuk maupun keluar — menggunakan amplop pesan bersama:
{
"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"
} | Field | Tipe | Deskripsi |
|---|---|---|
message_id | UUID v7 | ID unik berurutan waktu |
channel_id | {type}:{platform_id} | Pengenal kanal yang dapat dirutekan |
sender | object | Identitas bot — name, role, botId |
text | string | Isi pesan |
attachments | array | File, gambar, audio |
reply_to | UUID v7 | ID pesan induk untuk utas |
actions | array | Tombol/keyboard interaktif |
platform_data | bytes | Data passthrough buram untuk fitur khusus platform |
timestamp | ISO 8601 | Diisi oleh penerbit |
Desain dua lapis: Field umum (text, attachments, reply_to, actions) mencakup 90% pesan yang dimulai oleh karyawan. Fitur khusus platform masuk ke platform_data — plugin Anda memetakannya ke dan dari format native platform.
Stream Percakapan
Pesan kanal dirutekan melalui stream percakapan per kanal untuk isolasi:
neboai/bot/{botID}/channels/{channelType}/inbound # messages from users → agent
neboai/bot/{botID}/channels/{channelType}/outbound # messages from agent → channel Contoh Go — Kanal 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
}
]
} Kapabilitas Lainnya
Aplikasi Comm
Deklarasikan "provides": ["comm"] dan "permissions": ["comm:*"]. Aplikasi comm memungkinkan komunikasi antar-karyawan AI.
| Field | Deskripsi |
|---|---|
from | ID karyawan pengirim |
to | ID karyawan penerima |
topic | Topik/kanal pesan |
type | "message", "mention", "proposal", "command", "info", "task" |
content | Isi pesan |
Perilaku utama:
Registermengumumkan karyawan AI ini di jaringan beserta kapabilitasnyaSubscribe/Unsubscribemengelola langganan topikReceivemengalirkan pesan masuk (server-streaming, sama seperti kanal)- Hanya satu aplikasi comm yang dapat aktif pada satu waktu
Aplikasi Gateway
Aplikasi gateway merutekan permintaan LLM ke model. Deklarasikan "provides": ["gateway"] dan "permissions": ["network:outbound", "user:token"].
GatewayRequest berisi pesan, alat, system prompt, max tokens, temperature, dan UserContext (token JWT jika izin user:token diberikan).
Tipe GatewayEvent:
| Tipe | Konten | Deskripsi |
|---|---|---|
"text" | Potongan teks | Token teks streaming |
"tool_call" | JSON | Model ingin memanggil alat |
"thinking" | Potongan teks | Extended thinking/penalaran |
"error" | Pesan error | Terjadi kesalahan |
"done" | Kosong | Stream selesai |
Aplikasi UI
Aplikasi UI menyediakan antarmuka konfigurasi kustom yang terbuka di jendela browser bawaan Nebo. Deklarasikan "provides": ["ui"]. Berbeda dengan formulir pengaturan otomatis (yang dirender Nebo dari manifes settings Anda), aplikasi UI menyajikan frontend HTML/CSS/JS lengkapnya sendiri.
Aplikasi Anda menyertakan direktori ui/ yang berisi aset web statis (HTML, CSS, JS — biasanya SPA dengan index.html). Nebo menyajikan file-file ini secara langsung dan mem-proxy panggilan API ke aplikasi Anda melalui gRPC.
| Path | Mekanisme | Tujuan |
|---|---|---|
GET /api/v1/apps/{id}/ui/* | Server file statis | Menyajikan file dari direktori ui/ Anda (fallback SPA ke index.html) |
ANY /api/v1/apps/{id}/api/* | Proxy gRPC | Mem-proxy permintaan HTTP ke UIService.HandleRequest() milik aplikasi Anda |
SDK membungkus net/http.ServeMux standar sehingga Anda menulis handler HTTP Go biasa — SDK menangani penjembatanan gRPC secara otomatis.
Contoh Go — UI Dasbor:
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 melakukan panggilan fetch ke /api/v1/apps/com.example.dashboard/api/status, yang di-proxy ke handler mux Anda.
Aplikasi Jadwal
Aplikasi jadwal menggantikan penjadwal cron bawaan Nebo. Deklarasikan "provides": ["schedule"] dan "permissions": ["schedule:create"].
Saat aplikasi jadwal Anda diluncurkan, Nebo merutekan semua penjadwalan melalui aplikasi Anda, bukan mesin cron default. Jika aplikasi Anda crash, Nebo otomatis kembali ke mesin bawaan.
- Aplikasi Anda memegang status jadwal — Nebo tidak menyimpan jadwal di DB-nya sendiri saat aplikasi jadwal aktif
- CRUD standar:
Create,Get,List,Update,Delete,Enable,Disable Triggersadalah RPC server-streaming — aplikasi Anda mengirim pesan pemicu setiap kali jadwal berjalan- Hanya satu aplikasi jadwal yang dapat aktif pada satu waktu
Aplikasi Multi-Kapabilitas
Satu aplikasi dapat menyediakan beberapa kapabilitas. Misalnya, aplikasi dasbor dengan alat sekaligus 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()) Pengemasan
Format .napp
Untuk distribusi melalui NeboAI, kemas aplikasi Anda sebagai file .napp (arsip tar.gz):
cd com.example.myapp/
tar -czf myapp-1.0.0.napp manifest.json binary signatures.json TOOL.md File wajib:
| File | Ukuran Maks | Deskripsi |
|---|---|---|
manifest.json | 1 MB | Metadata aplikasi |
binary atau app | 500 MB | Executable |
signatures.json | 1 MB | Tanda tangan Ed25519 |
TOOL.md | 1 MB | Instruksi alat untuk karyawan AI |
Aturan keamanan saat ekstraksi:
- Tanpa path traversal (
../ditolak) - Tanpa symlink (ditolak)
- Tanpa path absolut (ditolak)
- Hanya nama file dalam daftar yang diizinkan yang diterima
Tanda Tangan
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 mode dev (tanpa URL NeboAI yang dikonfigurasi), verifikasi tanda tangan dilewati sepenuhnya. Anda tidak memerlukan signatures.json untuk pengembangan lokal.
Publikasi
Setelah aplikasi Anda berfungsi secara lokal, publikasikan melalui NeboAI untuk didistribusikan ke semua pengguna Nebo.
Penyiapan Akun Developer
- Daftarkan akun NeboAI di
POST /api/v1/owners/register - Masuk untuk mendapatkan token JWT:
POST /api/v1/owners/login - Buat akun developer:
POST /api/v1/developer/accounts
Alur Pengiriman
draft → pending_review → [approved] → published
→ [rejected] → draft (fix and resubmit) Langkah 1: Buat 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: Unggah biner 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" Unggah satu biner per platform: darwin-arm64, darwin-amd64, linux-amd64, linux-arm64.
Langkah 3: Kirim untuk ditinjau
curl -X POST https://neboai.com/api/v1/developer/apps/{id}/submit \
-H "Authorization: Bearer $TOKEN" Proses Peninjauan
- Pemindaian otomatis — biner dipindai melalui VirusTotal
- Peninjauan admin — tim NeboAI meninjau metadata, manifes, dan hasil pemindaian
- Jika disetujui — NeboAI menandatangani aplikasi dengan Ed25519 dan memublikasikannya
- Jika ditolak — Anda menerima alasannya dan dapat memperbaiki lalu mengirim ulang
Target waktu peninjauan: <24 jam.
Mengirim Pembaruan
- Perbarui versi aplikasi:
PUT /api/v1/developer/apps/{id}dengan versi baru - Unggah biner baru untuk setiap platform
- Kirim untuk ditinjau lagi
Setiap pembaruan melalui proses peninjauan yang sama. Versi sebelumnya tetap tersedia hingga versi baru disetujui.
Metadata Toko
| Field | Deskripsi |
|---|---|
category | misalnya, productivity, communication, developer-tools |
icon | URL ikon aplikasi |
visibility | public atau private |
description | Bisa lebih panjang/lebih kaya daripada deskripsi manifes |
Workflow Dev
Pengembangan Lokal
Tidak perlu pengemasan untuk pengembangan lokal:
- Buat direktori aplikasi Anda:
mkdir -p ~/Library/Application\ Support/Nebo/apps/com.example.myapp - Tulis
manifest.jsondan kode Anda - Build binary Anda:
go build -o ~/Library/Application\ Support/Nebo/apps/com.example.myapp/binary . - Nebo mendeteksi direktori baru secara otomatis (atau mulai ulang Nebo)
- Setelah kode diubah, build ulang binernya — file watcher akan memulai ulang aplikasi
Melihat Log
stdout/stderr aplikasi direkam dalam file log per 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 Persisten
Gunakan direktori data/ (juga tersedia sebagai variabel lingkungan NEBO_APP_DATA) untuk file apa pun yang perlu disimpan aplikasi Anda secara persisten. Direktori ini tetap ada setelah pembaruan aplikasi dan karantina.
Tips Debugging
- Jika aplikasi Anda tidak mau mulai, periksa
logs/stderr.loguntuk melihat error - Pastikan binernya dapat dieksekusi (
chmod +x binary) - Pastikan Anda mendengarkan path socket Unix dari
NEBO_APP_SOCK - Socket harus siap dalam 10 detik setelah peluncuran
- Gunakan
NEBO_APP_DATAuntuk penyimpanan, bukan path yang di-hardcode - Cetak ke stderr untuk log debug (direkam di
logs/stderr.log)
Memverifikasi
# 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 Mencopot pemasangan
nebo apps uninstall com.example.myapp Skill
Apa Itu Skill
Skill adalah kumpulan instruksi yang membentuk cara Nebo berperilaku selama percakapan. Saat skill aktif, isinya disuntikkan langsung ke system prompt — memandu nada, metodologi, keahlian domain, dan penggunaan alat karyawan AI untuk sesi tersebut.
Skill bukan kode. Skill adalah dokumen markdown dengan metadata YAML. Tanpa kompilasi, tanpa biner, tanpa gRPC. Skill adalah file SKILL.md di sebuah direktori. Itu saja.
Skill bersifat kontekstual dan sementara. Skill aktif saat relevan (melalui pencocokan pemicu atau dimuat manual), bertahan selama beberapa giliran, dan kedaluwarsa saat tidak lagi dibutuhkan. Ini menjaga konteks karyawan AI tetap ramping — hanya panduan yang penting saat ini yang ada di prompt.
Skill melengkapi aplikasi. Aplikasi menyediakan kapabilitas yang dapat dieksekusi (alat, kanal, gateway). Skill menyediakan panduan orkestrasi — cara menggunakan alat-alat itu secara efektif. Aplikasi kalender memberi Nebo kemampuan membaca dan menulis event. Skill "persiapan rapat" memberi tahu Nebo cara mempersiapkan rapat dengan menggunakan aplikasi kalender, email, dan pencarian web bersama-sama.
Skill vs Aplikasi
| Skill | Aplikasi | |
|---|---|---|
| Format | Markdown (SKILL.md) | Biner terkompilasi (.napp) |
| Runtime | Disuntikkan ke system prompt | Proses dalam sandbox melalui gRPC |
| Menyediakan | Panduan perilaku, metodologi | Alat, kanal, panel UI |
| Masa aktif | Terbatas pada sesi, kedaluwarsa berbasis TTL | Selalu berjalan |
| Pembuatan | Tulis file markdown | Tulis, kompilasi, tanda tangani, kemas |
| Keamanan | Tidak perlu izin | Sandbox yang menolak secara default |
Mulai Cepat
Buat direktori di folder skill Nebo Anda dengan file 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 memantau direktori skill dengan fsnotify. Skill Anda langsung tersedia — tidak perlu memulai ulang. Ucapkan sesuatu yang cocok dengan pemicu, dan skill aktif secara otomatis.
Atau minta langsung kepada Nebo: "Buat skill untuk menulis postingan blog" — Nebo akan menulis file SKILL.md untuk Anda.
Format SKILL.md
Setiap skill adalah satu file SKILL.md dengan dua bagian: frontmatter YAML di antara penanda ---, dan isi markdown (instruksi sebenarnya yang disuntikkan ke system prompt).
| Field | Wajib | Default | Deskripsi |
|---|---|---|---|
name | Ya | — | Pengenal unik (menjadi slug) |
description | Ya | — | Deskripsi satu baris yang ditampilkan di katalog skill |
version | Tidak | "1.0.0" | Semver untuk melacak pembaruan |
author | Tidak | — | Penulis skill |
priority | Tidak | 0 | Lebih tinggi = dicocokkan lebih dulu (100+ untuk penimpaan kritis) |
max_turns | Tidak | 4 | Jumlah giliran tanpa aktivitas sebelum kedaluwarsa otomatis |
triggers | Tidak | [] | Frasa yang mengaktifkan skill ini secara otomatis (pencocokan substring, tidak peka huruf besar/kecil) |
tools | Tidak | [] | Alat yang akan digunakan skill ini (informatif) |
dependencies | Tidak | [] | Skill lain yang harus dipasang |
tags | Tidak | [] | Untuk kategorisasi dan penemuan |
platform | Tidak | [] | Platform yang didukung: macos, linux, windows (kosong = semua) |
Cara Skill Aktif
Skill mengikuti model aktivasi dua fase: petunjuk lalu pemanggilan.
Fase 1: Pencocokan Pemicu — Setiap kali pengguna mengirim pesan, Nebo memindai semua skill terdaftar untuk mencari kecocokan pemicu. Skill yang cocok muncul sebagai petunjuk di system prompt. Karyawan AI melihat petunjuk itu dan memutuskan apakah akan memanggil skill tersebut.
Fase 2: Pemanggilan — Karyawan AI memanggil skill dengan memanggil:
skill(name: "code-review") Ini mengembalikan templat SKILL.md lengkap sebagai hasil alat, mencatat pemanggilan, dan menyuntikkan kembali templat ke system prompt pada giliran berikutnya.
TTL dan Kedaluwarsa:
- Skill yang dicocokkan otomatis: 4 giliran tanpa aktivitas (dapat dikonfigurasi melalui
max_turns) - Skill yang dimuat manual: 6 giliran tanpa aktivitas
- Pemanggilan ulang mengatur ulang timer
- Batas keras: maksimal 4 skill aktif per sesi
- Anggaran token: total konten skill aktif dibatasi 16,000 karakter
Mengelola Skill
Karyawan AI dapat mengelola skill melalui alat skill:
| Action | Deskripsi | Contoh |
|---|---|---|
catalog | Daftar semua skill yang tersedia | skill(action: "catalog") |
load | Aktifkan untuk sesi ini | skill(name: "code-review", action: "load") |
unload | Nonaktifkan skill | skill(name: "code-review", action: "unload") |
create | Buat skill baru di disk | skill(action: "create", content: "...") |
update | Perbarui skill yang sudah ada | skill(name: "my-skill", action: "update", content: "...") |
delete | Hapus skill dari disk | skill(name: "my-skill", action: "delete") |
Menulis Skill yang Baik
Templat skill yang baik memiliki:
- Judul yang jelas — memberi tahu karyawan AI mode apa yang sedang dijalankannya
- Prinsip inti — aturan perilaku yang tidak bisa ditawar
- Metodologi — pendekatan langkah demi langkah untuk skenario umum
- Contoh — pola konkret dari pesan pengguna ke respons
- Anti-pola — apa yang TIDAK boleh dilakukan (model belajar dengan baik dari contoh negatif)
Tips: Setiap skill sebaiknya melakukan satu hal dengan baik. Jangan membuat skill "pemrograman umum" — buat code-review, debugging, api-design sebagai skill terpisah. Karyawan AI dapat mengaktifkan beberapa skill sekaligus.
Skill Bawaan
Nebo dilengkapi skill bawaan yang mencakup kasus penggunaan umum:
| Skill | Prioritas | Deskripsi |
|---|---|---|
onboarding | 100 | Sapaan pengguna baru dan pengumpulan profil |
best-friend | 50 | Skill kepribadian — santai, setia, bicara apa adanya |
debugging | 25 | Metodologi debugging yang sistematis |
api-design | 15 | Praktik terbaik desain API RESTful |
code-review | 10 | Code review terstruktur dengan tingkat keparahan |
database-expert | 10 | Desain database, kueri, optimasi |
git-workflow | 10 | Branching Git, commit, workflow PR |
security-audit | 10 | Analisis keamanan dan deteksi kerentanan |
Skill ini berfungsi sebagai default yang berguna sekaligus implementasi referensi untuk membuat skill Anda sendiri.
Referensi
File Proto
File proto berada di proto/apps/v0/. SDK sudah menyertakan kode yang dihasilkan sebelumnya, jadi Anda tidak memerlukan protoc untuk pengembangan normal.
| File | Layanan | RPC Utama |
|---|---|---|
v0/common.proto | (hanya pesan) | 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 |
Setiap layanan menyertakan RPC HealthCheck dan Configure. SDK menangani keduanya secara otomatis.
Tipe Proto Kanal
| Tipe Pesan | Deskripsi |
|---|---|
ChannelSendRequest | Amplop pesan keluar dengan message_id, channelId, sender, text, attachments, reply_to, actions, platform_data |
ChannelSendResponse | ID pesan platform untuk utas |
InboundMessage | Amplop pesan masuk dengan semua field umum + timestamp |
MessageSender | Identitas bot (name, role, botId) — dilengkapi oleh broker |
Attachment | Lampiran file/gambar/audio (type, url, filename, size) |
MessageAction | Aksi tombol/keyboard interaktif (label, callback_id) |
Identitas dan Peran Bot
Bot Nebo memiliki model identitas tiga sumbu:
- creature — Apa bot itu (arketipe): "Ahli strategi yang cerdas", "Peneliti yang teliti"
- role — Bagaimana hubungannya dengan pengguna (relasi): "Teman", "COO", "Mentor"
- vibe — Energinya (gaya komunikasi): "Santai tapi punya pendapat", "Hangat dan menyemangati"
Saat plugin kanal Anda menerima pesan keluar, field sender berisi name dan role bot. Gunakan ini untuk memformat nama tampilan di platform Anda. Role bukanlah jabatan — melainkan penanda hubungan. "Teman", "Anak", dan "Mentor" adalah role yang valid di samping "COO" dan "DevLead".