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.
| Status | Bahasa |
|---|---|
| Disokong | Go (disyorkan), Rust, C/C++, Zig |
| Ditolak | Python, 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
- Cipta
manifest.jsondenganid,name,version,provides - Tulis
TOOL.mdyang menerangkan cara pekerja AI patut menggunakan alat anda - Pasang SDK (
go get github.com/neboloop/nebo-sdk-go) - Laksanakan antara muka pengendali untuk keupayaan anda (
ToolHandler,ChannelHandler, dan sebagainya) - Daftarkan pengendali dan panggil
app.Run() - Bina binari natif (
go build -o binary .) - Letakkan binari + manifest.json + TOOL.md dalam direktori
apps/<your-app-id>/ - 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:
| Medan | Penerangan |
|---|---|
id | Pengecam domain terbalik (cth., com.mycompany.myapp) |
name | Nama yang boleh dibaca manusia |
version | Rentetan semver |
provides | Sekurang-kurangnya satu keupayaan (lihat di bawah) |
Medan pilihan:
| Medan | Lalai | Penerangan |
|---|---|---|
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:
| Keupayaan | Perkhidmatan gRPC | Penerangan |
|---|---|---|
gateway | GatewayService | Penghalaan model LLM |
tool:<name> | ToolService | Alat bernama untuk pekerja AI |
channel:<name> | ChannelService | Saluran pemesejan |
comm | CommService | Komunikasi antara pekerja AI |
ui | UIService | UI tersuai dengan proksi HTTP |
schedule | ScheduleService | Penjadualan tersuai |
vision | ToolService | Pemprosesan penglihatan |
browser | ToolService | Automasi 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.
| Awalan | Contoh | Penerangan |
|---|---|---|
network: | network:outbound, network:* | Akses rangkaian |
filesystem: | filesystem:read, filesystem:write | Akses sistem fail |
memory: | memory:read, memory:write | Akses memori pekerja AI |
session: | session:read | Sesi perbualan |
tool: | tool:shell, tool:file | Gunakan alat lain |
shell: | shell:exec | Pelaksanaan arahan shell |
channel: | channel:send, channel:* | Operasi saluran |
comm: | comm:send, comm:* | Komunikasi antara pekerja AI |
model: | model:chat | Akses model AI |
user: | user:token | Terima JWT pengguna dalam permintaan |
schedule: | schedule:create | Pengurusan kerja cron |
database: | database:query | Akses pangkalan data |
storage: | storage:read, storage:write | Storan kekal |
context: | context:read | Akses konteks pekerja AI |
subagent: | subagent:spawn | Operasi sub-ejen |
lane: | lane:enqueue | Operasi lorong |
notification: | notification:send | Pemberitahuan tolak |
embedding: | embedding:search | Akses benaman vektor |
skill: | skill:invoke | Pemanggilan kemahiran |
advisor: | advisor:consult | Akses sistem penasihat |
mcp: | mcp:connect | Akses pelayan MCP |
voice: | voice:record | Akses suara/audio |
browser: | browser:navigate | Automasi pelayar |
oauth: | oauth:google, oauth:* | Akses token OAuth |
settings: | settings:read | Akses tetapan |
capability: | capability:register | Pendaftaran 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.
| Jenis | Penerangan |
|---|---|
text | Input teks satu baris |
password | Input teks bertopeng |
toggle | Suis hidup/mati Boolean |
select | Senarai juntai bawah dengan pilihan yang ditetapkan |
number | Input angka |
url | Input 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"]
}
]
} | Medan | Penerangan |
|---|---|
provider | Penyedia OAuth: "google", "microsoft", "github" |
scopes | Tatasusunan 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 ubah | Nilai |
|---|---|
NEBO_APP_DIR | Direktori pemasangan aplikasi |
NEBO_APP_SOCK | Laluan ke soket Unix yang perlu dicipta |
NEBO_APP_ID | ID aplikasi daripada manifes |
NEBO_APP_NAME | Nama aplikasi daripada manifes |
NEBO_APP_VERSION | Versi aplikasi daripada manifes |
NEBO_APP_DATA | Laluan ke direktori data/ aplikasi |
PATH | PATH sistem (diteruskan) |
HOME | Direktori rumah pengguna (diteruskan) |
TMPDIR | Direktori 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
- Nebo membaca
manifest.jsondan mengesahkannya - Mencari fail boleh laku
binaryatauappdalam direktori aplikasi - Menyemak penanda
.quarantined(enggan melancarkan aplikasi yang dikuarantin) - Semakan pembatalan (aplikasi yang diedarkan oleh NeboAI sahaja)
- Pengesahan tandatangan (aplikasi yang diedarkan oleh NeboAI sahaja, dilangkau dalam mod pembangunan)
- Pengesahan binari (menolak pautan simbolik, skrip, fail bukan boleh laku, fail bersaiz terlalu besar)
- Membersihkan soket lapuk daripada larian sebelumnya
- Mencipta direktori
data/untuk storan berkotak pasir - Menyediakan fail log bagi setiap aplikasi (
logs/stdout.log,logs/stderr.log) - Memulakan binari dengan persekitaran yang dibersihkan dan pengasingan kumpulan proses
- Menunggu soket Unix muncul (pengunduran eksponen, maksimum 10 saat)
- Menyambung melalui gRPC menerusi soket Unix
- Mencipta klien gRPC khusus keupayaan berdasarkan
provides - Menjalankan semakan kesihatan
- 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:
- Sentiasa sertakan medan
actionsebagai enum rentetan wajib - Tambah medan
resource(enum rentetan wajib) hanya jika alat anda menguruskan beberapa jenis sumber yang berbeza - Semua medan lain ialah parameter khusus tindakan
- Penerangan enum
actionpatut menyenaraikan semua tindakan yang tersedia
Mengapa STRAP penting:
- LLM mempelajari corak penghalaan
actionsekali 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
- Nebo memanggil
ID()untuk mendapatkan pengecam unik saluran anda - Nebo memanggil
Connect()dengan konfigurasi daripada tetapan aplikasi anda - Nebo membuka strim
Receive()— aplikasi anda menghantar mesej masuk setiap kali pengguna menghantar mesej kepada bot - Mesej masuk dihalakan ke lorong perbualan utama pekerja AI
- Apabila pekerja AI mahu menghantar mesej, Nebo memanggil
Send()dengan sampul mesej v1 - 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"
} | Medan | Jenis | Penerangan |
|---|---|---|
message_id | UUID v7 | ID unik tersusun mengikut masa |
channel_id | {type}:{platform_id} | Pengecam saluran yang boleh dihalakan |
sender | object | Identiti bot — nama, peranan, botId |
text | string | Kandungan mesej |
attachments | array | Fail, imej, audio |
reply_to | UUID v7 | ID mesej induk untuk bebenang |
actions | array | Butang/papan kekunci interaktif |
platform_data | bytes | Data lalu legap untuk ciri khusus platform |
timestamp | ISO 8601 | Penerbit 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.
| Medan | Penerangan |
|---|---|
from | ID pekerja penghantar |
to | ID pekerja penerima |
topic | Topik/saluran mesej |
type | "message", "mention", "proposal", "command", "info", "task" |
content | Kandungan mesej |
Tingkah laku utama:
Registermengumumkan pekerja AI ini pada rangkaian bersama keupayaannyaSubscribe/Unsubscribemenguruskan langganan topikReceivemenstrim 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:
| Jenis | Kandungan | Penerangan |
|---|---|---|
"text" | Cebisan teks | Token teks penstriman |
"tool_call" | JSON | Model mahu memanggil alat |
"thinking" | Cebisan teks | Pemikiran/penaakulan lanjutan |
"error" | Mesej ralat | Sesuatu telah tidak kena |
"done" | Kosong | Strim 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.
| Laluan | Mekanisme | Tujuan |
|---|---|---|
GET /api/v1/apps/{id}/ui/* | Pelayan fail statik | Menyajikan fail daripada direktori ui/ anda (sandaran SPA kepada index.html) |
ANY /api/v1/apps/{id}/api/* | Proksi gRPC | Memproksikan 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 Triggersialah 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:
| Fail | Saiz Maks | Penerangan |
|---|---|---|
manifest.json | 1 MB | Metadata aplikasi |
binary atau app | 500 MB | Fail boleh laku |
signatures.json | 1 MB | Tandatangan Ed25519 |
TOOL.md | 1 MB | Arahan 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
- Daftar akaun NeboAI di
POST /api/v1/owners/register - Log masuk untuk mendapatkan token JWT:
POST /api/v1/owners/login - 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
- Imbasan automatik — binari diimbas melalui VirusTotal
- Semakan pentadbir — pasukan NeboAI menyemak metadata, manifes dan hasil imbasan
- Apabila diluluskan — NeboAI menandatangani aplikasi dengan Ed25519 dan menerbitkannya
- Apabila ditolak — anda menerima sebab penolakan dan boleh membetulkan serta menghantarnya semula
Sasaran masa semakan: <24 jam.
Menghantar Kemas Kini
- Kemas kini versi aplikasi:
PUT /api/v1/developer/apps/{id}dengan versi baharu - Muat naik binari baharu untuk setiap platform
- Hantar untuk semakan sekali lagi
Setiap kemas kini melalui proses semakan yang sama. Versi sebelumnya kekal tersedia sehingga versi baharu diluluskan.
Metadata Gedung
| Medan | Penerangan |
|---|---|
category | cth., productivity, communication, developer-tools |
icon | URL ikon aplikasi |
visibility | public atau private |
description | Boleh lebih panjang/lebih terperinci daripada penerangan manifes |
Aliran Kerja Pembangunan
Pembangunan Setempat
Tiada pembungkusan diperlukan untuk pembangunan setempat:
- Cipta direktori aplikasi anda:
mkdir -p ~/Library/Application\ Support/Nebo/apps/com.example.myapp - Tulis
manifest.jsondan kod anda - Bina binari anda:
go build -o ~/Library/Application\ Support/Nebo/apps/com.example.myapp/binary . - Nebo mengesan direktori baharu secara automatik (atau mulakan semula Nebo)
- 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.loguntuk 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_DATAuntuk 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
| Kemahiran | Aplikasi | |
|---|---|---|
| Format | Markdown (SKILL.md) | Binari yang dikompil (.napp) |
| Masa jalan | Disuntik ke dalam gesaan sistem | Proses berkotak pasir melalui gRPC |
| Menyediakan | Panduan tingkah laku, metodologi | Alat, saluran, panel UI |
| Jangka hayat | Berskop sesi, tamat tempoh berdasarkan TTL | Sentiasa berjalan |
| Penciptaan | Tulis fail markdown | Tulis, kompil, tandatangan, bungkus |
| Keselamatan | Tiada kebenaran diperlukan | Kotak 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).
| Medan | Wajib | Lalai | Penerangan |
|---|---|---|---|
name | Ya | — | Pengecam unik (menjadi slug) |
description | Ya | — | Penerangan satu baris yang dipaparkan dalam katalog kemahiran |
version | Tidak | "1.0.0" | Semver untuk menjejak kemas kini |
author | Tidak | — | Pengarang kemahiran |
priority | Tidak | 0 | Lebih tinggi = dipadankan dahulu (100+ untuk penggantian kritikal) |
max_turns | Tidak | 4 | Giliran tanpa aktiviti sebelum tamat tempoh automatik |
triggers | Tidak | [] | Frasa yang mengaktifkan kemahiran ini secara automatik (padanan subrentetan tanpa mengira huruf besar/kecil) |
tools | Tidak | [] | Alat yang dijangka digunakan oleh kemahiran ini (untuk makluman) |
dependencies | Tidak | [] | Kemahiran lain yang mesti dipasang |
tags | Tidak | [] | Untuk pengkategorian dan penemuan |
platform | Tidak | [] | 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:
| Tindakan | Penerangan | Contoh |
|---|---|---|
catalog | Senaraikan semua kemahiran yang tersedia | skill(action: "catalog") |
load | Aktifkan untuk sesi ini | skill(name: "code-review", action: "load") |
unload | Nyahaktifkan kemahiran | skill(name: "code-review", action: "unload") |
create | Cipta kemahiran baharu pada cakera | skill(action: "create", content: "...") |
update | Kemas kini kemahiran sedia ada | skill(name: "my-skill", action: "update", content: "...") |
delete | Padam kemahiran daripada cakera | skill(name: "my-skill", action: "delete") |
Menulis Kemahiran yang Baik
Templat kemahiran yang baik mempunyai:
- Tajuk yang jelas — memberitahu pekerja AI mod apa yang sedang digunakannya
- Prinsip teras — peraturan tingkah laku yang tidak boleh dikompromi
- Metodologi — pendekatan langkah demi langkah untuk senario biasa
- Contoh — corak konkrit mesej pengguna kepada balasan
- 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:
| Kemahiran | Keutamaan | Penerangan |
|---|---|---|
onboarding | 100 | Ucapan alu-aluan pengguna baharu dan pengumpulan profil |
best-friend | 50 | Kemahiran personaliti — santai, setia, bercakap terus terang |
debugging | 25 | Metodologi penyahpepijatan yang sistematik |
api-design | 15 | Amalan terbaik reka bentuk API RESTful |
code-review | 10 | Semakan kod berstruktur dengan tahap keterukan |
database-expert | 10 | Reka bentuk pangkalan data, pertanyaan, pengoptimuman |
git-workflow | 10 | Pencabangan Git, commit, aliran kerja PR |
security-audit | 10 | Analisis 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.
| Fail | Perkhidmatan | RPC Utama |
|---|---|---|
v0/common.proto | (mesej sahaja) | HealthCheckRequest/Response, SettingsMap, UserContext, Empty |
v0/tool.proto | ToolService | Name, Description, Schema, Execute, RequiresApproval, Configure |
v0/channel.proto | ChannelService | ID, Connect, Disconnect, Send, Receive (strim), Configure |
v0/comm.proto | CommService | Name, Version, Connect, Disconnect, Send, Subscribe, Register, Receive (strim), Configure |
v0/gateway.proto | GatewayService | HealthCheck, Stream (strim), 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 (strim), Configure |
Setiap perkhidmatan menyertakan RPC HealthCheck dan Configure. SDK mengendalikan kedua-duanya secara automatik.
Jenis Proto Saluran
| Jenis Mesej | Penerangan |
|---|---|
ChannelSendRequest | Sampul mesej keluar dengan message_id, channelId, sender, text, attachments, reply_to, actions, platform_data |
ChannelSendResponse | ID mesej platform untuk bebenang |
InboundMessage | Sampul mesej masuk dengan semua medan biasa + cap masa |
MessageSender | Identiti bot (name, role, botId) — diperkaya oleh broker |
Attachment | Lampiran fail/imej/audio (type, url, filename, size) |
MessageAction | Tindakan 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".