NeboAI
NeboAI
להתחלה

בנה אפליקציות ל-Nebo

תן ל-AI שלך כוחות-על חדשים. כלים, ערוצים, שערים, חלוניות ממשק — כל מה שאתה יכול לדמיין, מהודר לקובץ בינארי מקורי.

סקירה כללית

מה זה Nebo

Nebo הוא עוזר AI אישי למחשב — עובד AI שפועל כל הזמן ומנהל את החיים הדיגיטליים שלך. חשוב על Nebo כמו שאתה חושב על סמארטפון: פלטפורמה עוצמתית שהופכת למהפכנית בזכות האפליקציות שלה.

בפני עצמו, Nebo הוא עובד AI מוכשר עם זיכרון, תזמון, גלישה באינטרנט, ניהול קבצים וגישה ל-shell. אבל מה שפותח את הפוטנציאל האמיתי הוא האפליקציות. בדיוק כמו שהכוח של סמארטפון מגיע ממערכת האפליקציות שלו, הכוח של Nebo מגיע מהאפליקציות שמרחיבות את מה שהוא יכול לעשות.

מה הן אפליקציות

אפליקציות Nebo הן יחידות עצמאיות ומהודרות מראש של פונקציונליות מדהימה. כל אפליקציה נותנת ל-Nebo כוח-על חדש — ניהול יומן, מיון אימיילים, מעקב אחר פרויקטים, אוטומציה ביתית, ניתוח פיננסי — כל מה שמפתח יכול לדמיין.

אפליקציות מספקות כוח עצום בצורה בטוחה מאוד. כל אפליקציה רצה בארגז חול עם הרשאות שחסומות כברירת מחדל. היא יכולה לגשת רק למה שהמניפסט שלה מצהיר עליו ושהמשתמש מאשר.

הממשק הוא שיחתי ב-100%. משתמשים לא עובדים עם אפליקציות דרך מסכים או לוחות בקרה נפרדים. הם מדברים עם Nebo, ו-Nebo משתמש בכלים של האפליקציה כדי לבצע את העבודה. „מה יש לי ביומן מחר?” — Nebo קורא לאפליקציית היומן. „קבע פגישה עם Sarah ב-3 אחר הצהריים” — Nebo קורא לאפליקציית היומן. המשתמש אף פעם לא יוצא מהשיחה.

אפליקציות יכולות לספק, אם רוצים, ממשק הגדרות — חלונית תצורה שנפתחת בחלון הדפדפן המובנה של Nebo. כאן משתמשים מזינים מפתחות API, מפעילים ומכבים תכונות ומגדירים את האפליקציה. ממשק ההגדרות נבנה מהמערך settings שבמניפסט (Nebo מציג את הטופס אוטומטית), או שהאפליקציה יכולה לספק ממשק מותאם מלא משלה באמצעות היכולת ui.

אפליקציות מחליפות ומרחיבות את היכולות המובנות של Nebo. Nebo מגיע עם כלי פלטפורמה בסיסיים (גישה ליומן מקומי, צילומי מסך וכו׳). כשאתה מתקין אפליקציית יומן, היא מחליפה את כלי היומן המובנה והופכת לקבוצת-על שלו — מקומי + ענן + איחוד + בדיקת זמינות.

מדיניות קוד מהודר בלבד

Nebo אוכף מדיניות קפדנית של קבצים בינאריים מהודרים בלבד. כל האפליקציות חייבות להיות קובצי הפעלה מקוריים מהודרים.

סטטוסשפות
נתמכותGo (מומלץ), Rust, ‏C/C++‎, Zig
נדחותPython, ‏Node.js, ‏Ruby, ‏Java, ‏.NET, סקריפטים של shell

הנימוק:

  • מניעת שינוי עצמי על ידי ה-AI — עובד AI עם גישה ל-shell עלול לשנות את ההתנהגות של סקריפט מפורש בזמן ריצה. קבצים בינאריים מהודרים אינם ניתנים לשינוי אחרי החתימה.
  • שלמות החתימה — חתימות Ed25519 מכסות את הבייטים הגולמיים של הקובץ הבינארי. אי אפשר לשנות קובץ בינארי חתום בלי לפסול את החתימה.
  • אכיפת ארגז החול — אימות פורמט הקובץ הבינארי (magic bytes של ELF/Mach-O/PE) הוא שער מהיר ואמין.

התחלה מהירה

התקנת ה-SDK

ערכות ה-SDK הרשמיות מטפלות בכל הגדרת שרת ה-gRPC, בטיפול באותות ובגישור הפרוטוקול. אתה רק מממש ממשקי handler.

Go (מומלץ):

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

Rust (בקרוב):

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

C/C++ (בקרוב):

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

מבנה התיקיות של אפליקציה

אפליקציות נמצאות בתת-התיקייה apps/ של תיקיית הנתונים של Nebo:

~/Library/Application Support/Nebo/apps/   # macOS
~/.config/nebo/apps/                        # Linux
%AppData%\Nebo\apps\                        # Windows

apps/
  com.example.myapp/
    manifest.json       # Required: app metadata
    binary              # Required: executable (or named "app")
    signatures.json     # Required for NeboAI distribution, optional in dev
    TOOL.md             # Required: tool instructions for the agent
    data/               # Auto-created: app's sandboxed storage
    logs/               # Auto-created: stdout.log, stderr.log
    ui/                 # Optional: static UI assets (HTML/CSS/JS)

רשימת בדיקה לאפליקציה מינימלית

  1. צור manifest.json עם id, name, version, provides
  2. כתוב TOOL.md שמתאר איך עובד ה-AI צריך להשתמש בכלי שלך
  3. התקן את ה-SDK (go get github.com/neboloop/nebo-sdk-go)
  4. ממש את ממשק ה-handler עבור היכולת שלך (ToolHandler, ChannelHandler וכו׳)
  5. רשום את ה-handler וקרא ל-app.Run()
  6. בנה קובץ בינארי מקורי (go build -o binary .)
  7. הנח את הקובץ הבינארי + manifest.json + TOOL.md בתיקייה apps/<your-app-id>/
  8. Nebo מגלה ומפעיל אותה אוטומטית

תצורה

manifest.json

כל אפליקציה דורשת manifest.json:

{
    "id": "com.example.myapp",
    "name": "My App",
    "version": "1.0.0",
    "description": "What this app does",
    "runtime": "local",
    "protocol": "grpc",
    "provides": ["tool:my_tool"],
    "permissions": ["network:outbound"],
    "settings": [
        {
            "key": "api_key",
            "title": "API Key",
            "type": "password",
            "required": true,
            "description": "Your API key for the service",
            "secret": true
        }
    ]
}

שדות חובה:

שדהתיאור
idמזהה בתבנית דומיין הפוך (לדוגמה, com.mycompany.myapp)
nameשם קריא לבני אדם
versionמחרוזת Semver
providesיכולת אחת לפחות (ראה למטה)

שדות אופציונליים:

שדהברירת מחדלתיאור
runtime"local""local" או "remote"
protocol"grpc"רק "grpc" נתמך
permissions[]למה האפליקציה צריכה גישה
description""מוצג בממשק
settings[]הגדרות ניתנות לשינוי (מוצגות בממשק ההגדרות)
oauth[]דרישות ספק OAuth (ראה את סעיף OAuth למטה)

יכולות

הצהר על מה שהאפליקציה שלך מספקת:

יכולתשירות gRPCתיאור
gatewayGatewayServiceניתוב מודלי LLM
tool:<name>ToolServiceכלי בעל שם עבור עובד ה-AI
channel:<name>ChannelServiceערוץ הודעות
commCommServiceתקשורת בין עובדי AI
uiUIServiceממשק מותאם עם HTTP proxy
scheduleScheduleServiceתזמון מותאם
visionToolServiceעיבוד ראייה
browserToolServiceאוטומציה של דפדפן

אפליקציה יכולה לספק כמה יכולות. לדוגמה, אפליקציה יכולה לספק גם כלי וגם חלונית ממשק.

הרשאות

ההרשאות קובעות למה האפליקציה יכולה לגשת. חסום כברירת מחדל — אם לא הוצהר, האפליקציה לא יכולה להשתמש בזה.

קידומתדוגמאותתיאור
network:network:outbound, network:*גישה לרשת
filesystem:filesystem:read, filesystem:writeגישה למערכת הקבצים
memory:memory:read, memory:writeגישה לזיכרון של עובד ה-AI
session:session:readסשנים של שיחה
tool:tool:shell, tool:fileשימוש בכלים אחרים
shell:shell:execהרצת פקודות shell
channel:channel:send, channel:*פעולות ערוץ
comm:comm:send, comm:*תקשורת בין עובדי AI
model:model:chatגישה למודלי AI
user:user:tokenקבלת ה-JWT של המשתמש בבקשות
schedule:schedule:createניהול משימות cron
database:database:queryגישה למסד נתונים
storage:storage:read, storage:writeאחסון קבוע
context:context:readגישה להקשר של עובד ה-AI
subagent:subagent:spawnפעולות תת-סוכן
lane:lane:enqueueפעולות מסלול (lane)
notification:notification:sendהתראות Push
embedding:embedding:searchגישה להטמעות וקטוריות
skill:skill:invokeהפעלת כישורים
advisor:advisor:consultגישה למערכת היועצים
mcp:mcp:connectגישה לשרת MCP
voice:voice:recordגישה לקול/אודיו
browser:browser:navigateאוטומציה של דפדפן
oauth:oauth:google, oauth:*גישה לאסימוני OAuth
settings:settings:readגישה להגדרות
capability:capability:registerרישום יכולות

הרשאות עם תו כללי נתמכות: network:* תואם לכל בדיקת הרשאה מסוג network:.

הגדרות

ההגדרות מופיעות בממשק של Nebo, בחלונית ההגדרות של האפליקציה. Nebo שומר אותן במסד הנתונים ושולח אותן לאפליקציה שלך דרך ה-RPC‏ Configure כשהן משתנות.

סכמת ההגדרות שלך נכללת בדף האפליקציה בחנות של NeboAI. אפליקציות עם הגדרות חובה שלא הוגדרו מציגות בממשק תג „דורש הגדרה”.

סוגתיאור
textשדה טקסט בשורה אחת
passwordשדה טקסט מוסתר
toggleמתג בוליאני מופעל/כבוי
selectתפריט נפתח עם אפשרויות מוגדרות מראש
numberשדה מספרי
urlשדה URL עם אימות
{
    "key": "region",
    "title": "Region",
    "type": "select",
    "required": true,
    "default": "us-east-1",
    "options": [
        {"label": "US East", "value": "us-east-1"},
        {"label": "EU West", "value": "eu-west-1"}
    ]
}

דרישות OAuth

אפליקציות יכולות להצהיר על דרישות ספק OAuth. מתווך ה-OAuth של Nebo מטפל בכל התהליך — האפליקציות מקבלות אסימונים אוטומטית דרך ה-RPC‏ Configure.

{
    "oauth": [
        {
            "provider": "google",
            "scopes": ["https://www.googleapis.com/auth/calendar"]
        }
    ]
}
שדהתיאור
providerספק OAuth: "google", "microsoft", "github"
scopesמערך של היקפי OAuth שהאפליקציה צריכה

כשהמשתמש מתקין את האפליקציה, Nebo מבקש ממנו לאשר את היקפי ה-OAuth הנדרשים. האפליקציה מקבלת אסימונים מרועננים דרך ה-RPC‏ Configure בלי לטפל בתהליך ה-OAuth בעצמה.

משתני סביבה

תהליך האפליקציה שלך מקבל סביבה מנוקה. כל הסודות מוסרים. אתה מקבל:

משתנהערך
NEBO_APP_DIRתיקיית ההתקנה של האפליקציה
NEBO_APP_SOCKהנתיב ל-Unix socket שיש ליצור
NEBO_APP_IDמזהה האפליקציה מהמניפסט
NEBO_APP_NAMEשם האפליקציה מהמניפסט
NEBO_APP_VERSIONגרסת האפליקציה מהמניפסט
NEBO_APP_DATAהנתיב לתיקייה data/ של האפליקציה
PATHPATH של המערכת (מועבר כמו שהוא)
HOMEתיקיית הבית של המשתמש (מועברת כמו שהיא)
TMPDIRתיקייה זמנית (מועברת כמו שהיא)

קריטי: הקובץ הבינארי שלך חייב ליצור שרת gRPC שמאזין ב-Unix socket שבנתיב NEBO_APP_SOCK. Nebo ממתין עד 10 שניות עד שה-socket הזה יופיע.

רצף ההפעלה של אפליקציה

  1. Nebo קורא את manifest.json ומאמת אותו
  2. מאתר את קובץ ההפעלה binary או app בתיקיית האפליקציה
  3. בודק אם קיים הסמן .quarantined (מסרב להפעיל אפליקציות בהסגר)
  4. בדיקת ביטול (רק לאפליקציות שמופצות על ידי NeboAI)
  5. אימות חתימה (רק לאפליקציות שמופצות על ידי NeboAI, מדולג בפיתוח)
  6. אימות הקובץ הבינארי (דוחה קישורים סימבוליים, סקריפטים, קבצים שאינם ניתנים להפעלה וקבצים גדולים מדי)
  7. מנקה socket ישן מהריצה הקודמת
  8. יוצר תיקייה data/ לאחסון בארגז חול
  9. מגדיר קובצי לוג לכל אפליקציה (logs/stdout.log, logs/stderr.log)
  10. מפעיל את הקובץ הבינארי עם סביבה מנוקה ובידוד של קבוצת תהליכים
  11. ממתין שה-Unix socket יופיע (השהיה מעריכית, עד 10 שניות)
  12. מתחבר דרך gRPC על גבי ה-Unix socket
  13. יוצר לקוחות gRPC ייעודיים לכל יכולת לפי provides
  14. מריץ בדיקת תקינות
  15. רושם את היכולות אצל עובד ה-AI (כלים, שער, תקשורת וכו׳)

אפליקציות כלים

הצהר על "provides": ["tool:my_tool_name"] במניפסט שלך.

תבנית STRAP

כל אפליקציות הכלים של Nebo חייבות להשתמש ב-STRAP (Single Tool Resource Action Pattern) עבור הסכמה וניתוב הביצוע שלהן. זו אותה תבנית ש-Nebo משתמש בה באופן פנימי כדי לאחד יותר מ-35 כלים נפרדים ל-4 כלי תחום — וכך להקטין את עומס ההקשר של ה-LLM בכ-80%.

הרעיון המרכזי: במקום לרשום כמה כלים (get_events, check_availability, suggest_slots), רושמים כלי אחד בלבד עם השדות action (ואופציונלית resource) שמנתבים ל-handler הנכון.

דוגמה למשאב יחיד (יומן):

calendar(action: "get_events", start: "2025-01-15T09:00:00Z", end: "2025-01-16T00:00:00Z")
calendar(action: "next_event")
calendar(action: "check_availability", start: "...", end: "...")
calendar(action: "suggest_slots", duration_minutes: 30, preferred_time: "morning")

דוגמה לכמה משאבים (מנהל פרויקטים):

project(resource: "task", action: "create", title: "Ship v2", assignee: "alice")
project(resource: "task", action: "list", status: "open")
project(resource: "milestone", action: "create", name: "Beta", deadline: "2025-03-01")
project(resource: "milestone", action: "list")

כללי סכמה:

  1. תמיד כלול שדה action כ-enum מחרוזת חובה
  2. הוסף שדה resource (enum מחרוזת חובה) רק אם הכלי שלך מנהל כמה סוגי משאבים נפרדים
  3. כל שאר השדות הם פרמטרים ייעודיים לפעולה
  4. התיאור של ה-enum ‏action צריך לפרט את כל הפעולות הזמינות

למה STRAP חשוב:

  • מודלי LLM לומדים את תבנית הניתוב של action פעם אחת ומכלילים אותה לכל הפעולות
  • הגדרות כלים צורכות כ-6% מההקשר — STRAP מקצץ את זה ב-80%
  • פעולות חדשות הן רק תוספות ל-enum, לא רישומי כלים חדשים
  • עובד באופן זהה במודלים מתארחים ובמודלים מקומיים

דוגמת Go — כלי מחשבון

package main

import (
    "context"
    "encoding/json"
    "fmt"
    "log"

    nebo "github.com/neboloop/nebo-sdk-go"
)

type Calculator struct{}

func (c *Calculator) Name() string        { return "calculator" }
func (c *Calculator) Description() string { return "Performs arithmetic calculations." }

func (c *Calculator) Schema() json.RawMessage {
    return nebo.NewSchema("add", "subtract", "multiply", "divide").
        Number("a", "First operand", true).
        Number("b", "Second operand", true).
        Build()
}

func (c *Calculator) Execute(_ context.Context, input json.RawMessage) (string, error) {
    var in struct {
        Action string  `json:"action"`
        A      float64 `json:"a"`
        B      float64 `json:"b"`
    }
    if err := json.Unmarshal(input, &in); err != nil {
        return "", fmt.Errorf("invalid input: %w", err)
    }

    var result float64
    switch in.Action {
    case "add":
        result = in.A + in.B
    case "subtract":
        result = in.A - in.B
    case "multiply":
        result = in.A * in.B
    case "divide":
        if in.B == 0 {
            return "", fmt.Errorf("division by zero")
        }
        result = in.A / in.B
    default:
        return "", fmt.Errorf("unknown action: %s", in.Action)
    }

    return fmt.Sprintf("%g %s %g = %g", in.A, in.Action, in.B, result), nil
}

func main() {
    app, err := nebo.New()
    if err != nil {
        log.Fatal(err)
    }
    app.RegisterTool(&Calculator{})
    log.Fatal(app.Run())
}

manifest.json:

{
    "id": "com.example.calculator",
    "name": "Calculator",
    "version": "1.0.0",
    "description": "Arithmetic calculator tool for the agent",
    "runtime": "local",
    "protocol": "grpc",
    "provides": ["tool:calculator"],
    "permissions": []
}

בנייה והתקנה:

go build -o binary .
mkdir -p ~/Library/Application\ Support/Nebo/apps/com.example.calculator
cp binary manifest.json ~/Library/Application\ Support/Nebo/apps/com.example.calculator/

דוגמת Rust

use async_trait::async_trait;
use nebo_sdk::{NeboApp, NeboError, SchemaBuilder};
use nebo_sdk::tool::ToolHandler;
use serde::Deserialize;
use serde_json::Value;

struct Calculator;

#[derive(Deserialize)]
struct Input { action: String, a: f64, b: f64 }

#[async_trait]
impl ToolHandler for Calculator {
    fn name(&self) -> &str { "calculator" }
    fn description(&self) -> &str { "Performs arithmetic calculations." }
    fn schema(&self) -> Value {
        SchemaBuilder::new(&["add", "subtract", "multiply", "divide"])
            .number("a", "First operand", true)
            .number("b", "Second operand", true)
            .build()
    }
    async fn execute(&self, input: Value) -> Result<String, NeboError> {
        let i: Input = serde_json::from_value(input)
            .map_err(|e| NeboError::Execution(e.to_string()))?;
        let r = match i.action.as_str() {
            "add" => i.a + i.b,
            "subtract" => i.a - i.b,
            "multiply" => i.a * i.b,
            "divide" => {
                if i.b == 0.0 {
                    return Err(NeboError::Execution("division by zero".into()));
                }
                i.a / i.b
            }
            other => return Err(NeboError::Execution(format!("unknown action: {other}"))),
        };
        Ok(format!("{} {} {} = {}", i.a, i.action, i.b, r))
    }
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    NeboApp::new()?.register_tool(Calculator).run().await?;
    Ok(())
}

דוגמת C

#include <nebo/nebo.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>

static int calculator_execute(const char *input_json, char **output, int *is_error) {
    /* Parse JSON, compute result, set *output */
    *output = strdup("2 add 3 = 5");
    *is_error = 0;
    return 0;
}

int main(void) {
    const char *actions[] = {"add", "subtract", "multiply", "divide", NULL};
    nebo_schema_builder_t *sb = nebo_schema_new(actions);
    nebo_schema_number(sb, "a", "First operand", 1);
    nebo_schema_number(sb, "b", "Second operand", 1);
    char *schema = nebo_schema_build(sb);
    nebo_schema_free(sb);

    nebo_tool_handler_t calculator = {
        .name = "calculator",
        .description = "Performs arithmetic calculations.",
        .schema = schema,
        .execute = calculator_execute,
    };

    nebo_app_t *app = nebo_app_new();
    nebo_app_register_tool(app, &calculator);
    int ret = nebo_app_run(app);
    free(schema);
    return ret;
}

אפליקציות ערוצים

הצהר על "provides": ["channel:my_channel"] ועל "permissions": ["channel:send"].

אפליקציות ערוצים מגשרות בין פלטפורמות הודעות חיצוניות (Telegram, ‏Discord, ‏Slack וכו׳) לבין עובד ה-AI של Nebo. כשמשתמש שולח הודעה בפלטפורמה החיצונית, האפליקציה שלך מזרימה אותה ל-Nebo דרך Receive. כשעובד ה-AI רוצה להשיב, Nebo קורא ל-Send של האפליקציה שלך.

איך זה עובד

  1. Nebo קורא ל-ID() כדי לקבל את המזהה הייחודי של הערוץ שלך
  2. Nebo קורא ל-Connect() עם התצורה מההגדרות של האפליקציה שלך
  3. Nebo פותח זרם Receive() — האפליקציה שלך שולחת הודעות נכנסות בכל פעם שמשתמש שולח הודעה לבוט
  4. הודעות נכנסות מנותבות למסלול השיחה הראשי של עובד ה-AI
  5. כשעובד ה-AI רוצה לשלוח הודעה, Nebo קורא ל-Send() עם מעטפת ההודעה v1
  6. בכיבוי, Nebo קורא ל-Disconnect()

מעטפת הודעה v1

כל הודעות הערוץ — נכנסות ויוצאות — משתמשות במעטפת ההודעה המשותפת:

{
  "message_id": "01953f8a-...",
  "channel_id": "telegram:12345",
  "sender": { "name": "Alex", "role": "COO", "bot_id": "uuid" },
  "text": "Q3 numbers look good...",
  "attachments": [{ "type": "image", "url": "https://...", "filename": "chart.png", "size": 45000 }],
  "reply_to": "01953f89-...",
  "actions": [{ "label": "Approve", "callback_id": "approve_q3" }],
  "platform_data": null,
  "timestamp": "2026-02-12T15:10:00Z"
}
שדהסוגתיאור
message_idUUID v7מזהה ייחודי מסודר לפי זמן
channel_id{type}:{platform_id}מזהה ערוץ שניתן לנתב אליו
senderobjectזהות הבוט — שם, תפקיד, botId
textstringגוף ההודעה
attachmentsarrayקבצים, תמונות, אודיו
reply_toUUID v7מזהה הודעת האב לשרשור
actionsarrayכפתורים/מקלדות אינטראקטיביים
platform_databytesהעברה אטומה של תכונות ייעודיות לפלטפורמה
timestampISO 8601המפרסם קובע את זה

תכנון בשתי שכבות: השדות המשותפים (text, ‏attachments, ‏reply_to, ‏actions) מכסים 90% מההודעות שעובדים יוזמים. תכונות ייעודיות לפלטפורמה נכנסות ל-platform_data — התוסף שלך ממפה אותן מהפורמט המקורי של הפלטפורמה ואליו.

זרמי שיחה

הודעות ערוץ מנותבות בזרמי שיחה נפרדים לכל ערוץ, לשם בידוד:

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

דוגמת Go — ערוץ Telegram

package main

import (
    "context"
    "encoding/json"
    "fmt"
    "log"
    "time"

    "github.com/google/uuid"
    tgbot "github.com/go-telegram/bot"
    nebo "github.com/neboloop/nebo-sdk-go"
)

type Telegram struct {
    bot      *tgbot.Bot
    messages chan nebo.ChannelEnvelope
    cancel   context.CancelFunc
}

func (t *Telegram) ID() string { return "telegram" }

func (t *Telegram) Connect(_ context.Context, config map[string]string) error {
    token := config["bot_token"]
    if token == "" {
        return fmt.Errorf("bot_token is required")
    }

    botCtx, cancel := context.WithCancel(context.Background())
    t.cancel = cancel

    bot, err := tgbot.New(token, tgbot.WithDefaultHandler(
        func(bCtx context.Context, b *tgbot.Bot, update *tgbot.Update) {
            if update.Message == nil {
                return
            }
            env := nebo.ChannelEnvelope{
                MessageID: uuid.Must(uuid.NewV7()).String(),
                ChannelID: fmt.Sprintf("telegram:%d", update.Message.Chat.ID),
                Text:      update.Message.Text,
                Timestamp: time.Unix(int64(update.Message.Date), 0).UTC(),
            }
            t.messages <- env
        },
    ))
    if err != nil {
        return err
    }

    t.bot = bot
    go bot.Start(botCtx)
    return nil
}

func (t *Telegram) Send(ctx context.Context, env nebo.ChannelEnvelope) (string, error) {
    if t.bot == nil {
        return "", fmt.Errorf("not connected")
    }
    chatID := env.ChannelID[len("telegram:"):]
    params := &tgbot.SendMessageParams{
        ChatID: chatID,
        Text:   env.Text,
    }
    msg, err := t.bot.SendMessage(ctx, params)
    if err != nil {
        return "", err
    }
    return fmt.Sprintf("%d", msg.MessageID), nil
}

func (t *Telegram) Receive(_ context.Context) (<-chan nebo.ChannelEnvelope, error) {
    return t.messages, nil
}

func (t *Telegram) Disconnect(_ context.Context) error {
    if t.cancel != nil {
        t.cancel()
    }
    return nil
}

func main() {
    app, err := nebo.New()
    if err != nil {
        log.Fatal(err)
    }
    app.RegisterChannel(&Telegram{
        messages: make(chan nebo.ChannelEnvelope, 100),
    })
    log.Fatal(app.Run())
}

manifest.json:

{
    "id": "com.example.telegram",
    "name": "Telegram",
    "version": "1.0.0",
    "description": "Telegram messaging channel for Nebo",
    "runtime": "local",
    "protocol": "grpc",
    "provides": ["channel:telegram"],
    "permissions": ["channel:send", "network:outbound"],
    "settings": [
        {
            "key": "bot_token",
            "title": "Bot Token",
            "type": "password",
            "required": true,
            "description": "Telegram bot token from @BotFather",
            "secret": true
        }
    ]
}

יכולות נוספות

אפליקציית תקשורת

הצהר על "provides": ["comm"] ועל "permissions": ["comm:*"]. אפליקציות תקשורת מאפשרות תקשורת בין עובדי AI.

שדהתיאור
fromמזהה העובד השולח
toמזהה העובד הנמען
topicנושא/ערוץ ההודעה
type"message", "mention", "proposal", "command", "info", "task"
contentגוף ההודעה

התנהגויות עיקריות:

  • Register מכריז על עובד ה-AI הזה ברשת יחד עם היכולות שלו
  • Subscribe/Unsubscribe מנהלים מינויים לנושאים
  • Receive מזרים הודעות נכנסות (server-streaming, כמו בערוצים)
  • רק אפליקציית תקשורת אחת יכולה להיות פעילה בכל רגע

אפליקציית שער

אפליקציית שער מנתבת בקשות LLM למודלים. הצהר על "provides": ["gateway"] ועל "permissions": ["network:outbound", "user:token"].

GatewayRequest מכיל הודעות, כלים, הנחיית מערכת, מספר טוקנים מרבי, temperature ו-UserContext (אסימון JWT אם ההרשאה user:token ניתנה).

סוגי GatewayEvent:

סוגתוכןתיאור
"text"מקטע טקסטטוקן טקסט בזרימה
"tool_call"JSONהמודל רוצה לקרוא לכלי
"thinking"מקטע טקסטחשיבה/הסקה מורחבת
"error"הודעת שגיאהמשהו השתבש
"done"ריקהזרם הסתיים

אפליקציית ממשק

אפליקציית ממשק מספקת ממשק תצורה מותאם שנפתח בחלון הדפדפן המובנה של Nebo. הצהר על "provides": ["ui"]. בניגוד לטופס ההגדרות האוטומטי (ש-Nebo מציג מתוך המניפסט settings שלך), אפליקציית ממשק מגישה ממשק HTML/CSS/JS מלא משלה.

האפליקציה שלך כוללת תיקייה ui/ עם נכסי אינטרנט סטטיים (HTML, ‏CSS, ‏JS — בדרך כלל SPA עם index.html). Nebo מגיש את הקבצים האלה ישירות ומעביר קריאות API לאפליקציה שלך דרך gRPC.

נתיבמנגנוןמטרה
GET /api/v1/apps/{id}/ui/*שרת קבצים סטטייםמגיש קבצים מהתיקייה ui/ שלך (נפילה של SPA אל index.html)
ANY /api/v1/apps/{id}/api/*gRPC proxyמעביר בקשות HTTP אל UIService.HandleRequest() של האפליקציה שלך

ה-SDK עוטף net/http.ServeMux סטנדרטי, כך שאתה כותב handlers רגילים של HTTP ב-Go — ה-SDK מטפל בגישור ה-gRPC אוטומטית.

דוגמת Go — ממשק לוח בקרה:

package main

import (
    "encoding/json"
    "log"
    "net/http"

    nebo "github.com/neboloop/nebo-sdk-go"
)

type Dashboard struct {
    mux *http.ServeMux
}

func NewDashboard() *Dashboard {
    d := &Dashboard{mux: http.NewServeMux()}

    d.mux.HandleFunc("GET /status", func(w http.ResponseWriter, r *http.Request) {
        json.NewEncoder(w).Encode(map[string]string{"status": "ok"})
    })

    d.mux.HandleFunc("POST /action", func(w http.ResponseWriter, r *http.Request) {
        var req map[string]string
        json.NewDecoder(r.Body).Decode(&req)
        json.NewEncoder(w).Encode(map[string]string{"result": "done"})
    })

    return d
}

func (d *Dashboard) Handler() *http.ServeMux { return d.mux }

func main() {
    app, err := nebo.New()
    if err != nil {
        log.Fatal(err)
    }
    app.RegisterUI(NewDashboard())
    log.Fatal(app.Run())
}

הקובץ ui/index.html שלך יבצע קריאות fetch אל /api/v1/apps/com.example.dashboard/api/status, שמועברות אל ה-handler ‏mux שלך.

אפליקציית תזמון

אפליקציית תזמון מחליפה את מתזמן ה-cron המובנה של Nebo. הצהר על "provides": ["schedule"] ועל "permissions": ["schedule:create"].

כשאפליקציית התזמון שלך מופעלת, Nebo מנתב את כל התזמון דרך האפליקציה שלך במקום דרך מנוע ה-cron המוגדר כברירת מחדל. אם האפליקציה שלך קורסת, Nebo חוזר אוטומטית למנוע המובנה.

  • האפליקציה שלך אחראית למצב התזמונים — Nebo לא שומר תזמונים במסד הנתונים שלו כשאפליקציית תזמון פעילה
  • CRUD סטנדרטי: Create, Get, List, Update, Delete, Enable, Disable
  • Triggers הוא RPC מסוג server-streaming — האפליקציה שלך שולחת הודעת טריגר בכל פעם שתזמון מופעל
  • רק אפליקציית תזמון אחת יכולה להיות פעילה בכל רגע

אפליקציות מרובות יכולות

אפליקציה יכולה לספק כמה יכולות. לדוגמה, אפליקציית לוח בקרה עם כלי וגם ממשק:

{
    "id": "com.example.dashboard",
    "name": "Dashboard",
    "version": "1.0.0",
    "provides": ["tool:dashboard_query", "ui"],
    "permissions": ["network:outbound"]
}
app, _ := nebo.New()
app.RegisterTool(&dashboardTool{})
app.RegisterUI(&dashboardUI{})
log.Fatal(app.Run())

אריזה

פורמט ‎.napp

להפצה דרך NeboAI, ארוז את האפליקציה שלך כקובץ .napp (ארכיון tar.gz):

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

קבצים נדרשים:

קובץגודל מרביתיאור
manifest.json1 MBמטא-נתונים של האפליקציה
binary או app500 MBקובץ הפעלה
signatures.json1 MBחתימות Ed25519
TOOL.md1 MBהוראות הכלי עבור עובד ה-AI

כללי אבטחה בזמן החילוץ:

  • אין מעבר בין נתיבים (../ נדחה)
  • אין קישורים סימבוליים (נדחים)
  • אין נתיבים מוחלטים (נדחים)
  • רק שמות קבצים מרשימת ההיתר מתקבלים

חתימות

NeboAI חותם על אפליקציות עם Ed25519. הפורמט של signatures.json:

{
    "key_id": "a1b2c3d4",
    "algorithm": "ed25519",
    "manifest_signature": "<base64 signature of raw manifest.json bytes>",
    "binary_sha256": "<hex SHA256 of binary>",
    "binary_signature": "<base64 signature of raw binary bytes>"
}

במצב פיתוח (בלי כתובת NeboAI מוגדרת), אימות החתימה מדולג לחלוטין. אין צורך ב-signatures.json לפיתוח מקומי.

פרסום

ברגע שהאפליקציה שלך עובדת מקומית, פרסם אותה דרך NeboAI כדי להפיץ אותה לכל משתמשי Nebo.

הגדרת חשבון מפתח

  1. רשום חשבון NeboAI בכתובת POST /api/v1/owners/register
  2. התחבר כדי לקבל אסימון JWT: POST /api/v1/owners/login
  3. צור חשבון מפתח: POST /api/v1/developer/accounts

תהליך ההגשה

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

שלב 1: יצירת האפליקציה

curl -X POST https://neboai.com/api/v1/developer/apps \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My App",
    "version": "1.0.0",
    "description": "What it does",
    "category": "productivity",
    "visibility": "public"
  }'

שלב 2: העלאת קבצים בינאריים לפלטפורמות

curl -X POST https://neboai.com/api/v1/developer/apps/{id}/binaries \
  -H "Authorization: Bearer $TOKEN" \
  -F "binary=@myapp-darwin-arm64" \
  -F "platform=darwin-arm64"

העלה קובץ בינארי אחד לכל פלטפורמה: darwin-arm64, darwin-amd64, linux-amd64, linux-arm64.

שלב 3: שליחה לבדיקה

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

תהליך הבדיקה

  1. סריקה אוטומטית — הקבצים הבינאריים נסרקים באמצעות VirusTotal
  2. בדיקת מנהל — צוות NeboAI בודק את המטא-נתונים, את המניפסט ואת תוצאות הסריקה
  3. באישור — NeboAI חותם על האפליקציה עם Ed25519 ומפרסם אותה
  4. בדחייה — אתה מקבל סיבה ויכול לתקן ולהגיש מחדש

זמן בדיקה יעד: פחות מ-24 שעות.

פרסום עדכונים

  1. עדכן את הגרסה של האפליקציה: PUT /api/v1/developer/apps/{id} עם הגרסה החדשה
  2. העלה קבצים בינאריים חדשים לכל פלטפורמה
  3. שלח שוב לבדיקה

כל עדכון עובר את אותו תהליך בדיקה. גרסאות קודמות נשארות זמינות עד שהגרסה החדשה מאושרת.

מטא-נתונים לחנות

שדהתיאור
categoryלדוגמה: productivity, ‏communication, ‏developer-tools
iconכתובת ה-URL של סמל האפליקציה
visibilitypublic או private
descriptionיכול להיות ארוך ועשיר יותר מהתיאור שבמניפסט

תהליך הפיתוח

פיתוח מקומי

לפיתוח מקומי אין צורך באריזה:

  1. צור את תיקיית האפליקציה שלך:
    mkdir -p ~/Library/Application\ Support/Nebo/apps/com.example.myapp
  2. כתוב את manifest.json ואת הקוד שלך
  3. בנה את הקובץ הבינארי שלך:
    go build -o ~/Library/Application\ Support/Nebo/apps/com.example.myapp/binary .
  4. Nebo מזהה את התיקייה החדשה אוטומטית (או הפעל מחדש את Nebo)
  5. אחרי שינויים בקוד, בנה מחדש את הקובץ הבינארי — מנגנון מעקב הקבצים יפעיל את האפליקציה מחדש

צפייה בלוגים

ה-stdout/stderr של האפליקציה נלכדים בקובצי לוג נפרדים לכל אפליקציה:

tail -f ~/Library/Application\ Support/Nebo/apps/com.example.myapp/logs/stdout.log
tail -f ~/Library/Application\ Support/Nebo/apps/com.example.myapp/logs/stderr.log

נתונים קבועים

השתמש בתיקייה data/ (זמינה גם כמשתנה הסביבה NEBO_APP_DATA) לכל קובץ שהאפליקציה שלך צריכה לשמור. התיקייה הזו שורדת עדכוני אפליקציה והסגר.

טיפים לניפוי באגים

  • אם האפליקציה שלך לא עולה, בדוק את logs/stderr.log לאיתור שגיאות
  • ודא שהקובץ הבינארי ניתן להפעלה (chmod +x binary)
  • ודא שאתה מאזין בנתיב ה-Unix socket שמגיע מ-NEBO_APP_SOCK
  • ה-socket חייב להיות מוכן תוך 10 שניות מההפעלה
  • השתמש ב-NEBO_APP_DATA לאחסון, לא בנתיבים קבועים בקוד
  • הדפס ל-stderr לצורכי לוג ניפוי באגים (נלכד ב-logs/stderr.log)

אימות

# List installed apps
nebo apps list

# Check running apps via the web UI Settings > Apps
# Or check the apps directory for running sockets
ls ~/Library/Application\ Support/Nebo/apps/*/app.sock

הסרת התקנה

nebo apps uninstall com.example.myapp

כישורים

מה הם כישורים

כישורים הם ערכות הוראות שמעצבות את ההתנהגות של Nebo במהלך שיחה. כשכישור פעיל, התוכן שלו מוזרק ישירות להנחיית המערכת — ומכוון את הטון, המתודולוגיה, המומחיות בתחום והשימוש בכלים של עובד ה-AI באותו סשן.

כישורים אינם קוד. הם מסמכי markdown עם מטא-נתונים ב-YAML. בלי הידור, בלי קובץ בינארי, בלי gRPC. כישור הוא קובץ SKILL.md בתיקייה. זה הכול.

כישורים הם הקשריים וזמניים. הם מופעלים כשהם רלוונטיים (דרך התאמת טריגרים או טעינה ידנית), נשארים לכמה תורות ופגים כשאין בהם עוד צורך. כך ההקשר של עובד ה-AI נשאר רזה — רק ההכוונה שחשובה עכשיו נמצאת בהנחיה.

כישורים משלימים אפליקציות. אפליקציות מספקות יכולות הרצה (כלים, ערוצים, שערים). כישורים מספקים הכוונה לתזמור — איך להשתמש בכלים האלה ביעילות. אפליקציית יומן נותנת ל-Nebo את היכולת לקרוא ולכתוב אירועים. כישור „הכנה לפגישה” מסביר ל-Nebo איך להתכונן לפגישות בעזרת אפליקציית היומן, האימייל וחיפוש באינטרנט יחד.

כישורים לעומת אפליקציות

כישוריםאפליקציות
פורמטMarkdown ‏(SKILL.md)קובץ בינארי מהודר (‎.napp)
זמן ריצהמוזרק להנחיית המערכתתהליך בארגז חול על גבי gRPC
מספקהכוונה התנהגותית, מתודולוגיהכלים, ערוצים, חלוניות ממשק
משך חייםמוגבל לסשן, פג לפי TTLרץ תמיד
יצירהכתיבת קובץ markdownכתיבה, הידור, חתימה, אריזה
אבטחהלא נדרשות הרשאותארגז חול חסום כברירת מחדל

התחלה מהירה

צור תיקייה בתיקיית הכישורים של Nebo עם קובץ SKILL.md:

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

כתוב SKILL.md:

---
name: my-skill
description: One-line description of what this skill does
version: "1.0.0"
triggers:
  - keyword that activates this skill
  - another trigger phrase
---

# My Skill

Instructions for Nebo when this skill is active.

Tell the agent what to do, how to approach problems,
what tools to use, and what tone to take.

Nebo עוקב אחר תיקיית הכישורים באמצעות fsnotify. הכישור שלך זמין מיד — בלי צורך בהפעלה מחדש. אמור משהו שתואם לטריגר, והוא יופעל אוטומטית.

או בקש מ-Nebo ישירות: „צור כישור לכתיבת פוסטים לבלוג” — Nebo יכתוב עבורך את קובץ ה-SKILL.md.

פורמט SKILL.md

כל כישור הוא קובץ SKILL.md אחד עם שני חלקים: frontmatter של YAML בין סימני ---, וגוף markdown (ההוראות עצמן שמוזרקות להנחיית המערכת).

שדהחובהברירת מחדלתיאור
nameכן—מזהה ייחודי (הופך ל-slug)
descriptionכן—תיאור בשורה אחת שמוצג בקטלוג הכישורים
versionלא"1.0.0"Semver למעקב אחר עדכונים
authorלא—מחבר הכישור
priorityלא0גבוה יותר = מותאם ראשון (100+ לעקיפות קריטיות)
max_turnsלא4מספר תורות ללא פעילות לפני פקיעה אוטומטית
triggersלא[]ביטויים שמפעילים את הכישור הזה אוטומטית (התאמת תת-מחרוזת שאינה תלויה ברישיות)
toolsלא[]כלים שהכישור הזה מצפה להשתמש בהם (לידיעה בלבד)
dependenciesלא[]כישורים אחרים שחייבים להיות מותקנים
tagsלא[]לסיווג ולגילוי
platformלא[]פלטפורמות נתמכות: macos, linux, windows (ריק = כולן)

איך כישורים מופעלים

כישורים פועלים לפי מודל הפעלה בשני שלבים: רמז ואז הפעלה.

שלב 1: התאמת טריגרים — בכל פעם שמשתמש שולח הודעה, Nebo סורק את כל הכישורים הרשומים ומחפש התאמות לטריגרים. כישורים תואמים מופיעים כרמזים בהנחיית המערכת. עובד ה-AI רואה את הרמז ומחליט אם להפעיל את הכישור.

שלב 2: הפעלה — עובד ה-AI מפעיל כישור באמצעות הקריאה:

skill(name: "code-review")

הקריאה מחזירה את תבנית ה-SKILL.md המלאה כתוצאת הכלי, רושמת את ההפעלה ומזריקה מחדש את התבנית להנחיית המערכת בתורות הבאים.

TTL ופקיעה:

  • כישורים שהותאמו אוטומטית: 4 תורות ללא פעילות (ניתן להגדרה דרך max_turns)
  • כישורים שנטענו ידנית: 6 תורות ללא פעילות
  • הפעלה חוזרת מאפסת את הטיימר
  • תקרה קשיחה: לכל היותר 4 כישורים פעילים בכל סשן
  • תקציב טוקנים: התוכן המשולב של הכישורים הפעילים מוגבל ל-16,000 תווים

ניהול כישורים

עובד ה-AI יכול לנהל כישורים באמצעות הכלי skill:

פעולהתיאורדוגמה
catalogהצגת כל הכישורים הזמיניםskill(action: "catalog")
loadהפעלה לסשן הזהskill(name: "code-review", action: "load")
unloadהשבתת כישורskill(name: "code-review", action: "unload")
createיצירת כישור חדש בדיסקskill(action: "create", content: "...")
updateעדכון כישור קייםskill(name: "my-skill", action: "update", content: "...")
deleteמחיקת כישור מהדיסקskill(name: "my-skill", action: "delete")

כתיבת כישורים טובים

לתבנית כישור טובה יש:

  1. כותרת ברורה — אומרת לעובד ה-AI באיזה מצב הוא נמצא
  2. עקרונות ליבה — כללי ההתנהגות שאינם נתונים למשא ומתן
  3. מתודולוגיה — גישה צעד אחר צעד לתרחישים נפוצים
  4. דוגמאות — תבניות קונקרטיות של הודעת משתמש ותשובה
  5. אנטי-תבניות — מה לא לעשות (מודלים לומדים היטב מדוגמאות שליליות)

טיפ: כל כישור צריך לעשות דבר אחד היטב. אל תיצור כישור „תכנות כללי” — צור code-review, debugging, api-design ככישורים נפרדים. לעובד ה-AI יכולים להיות כמה כישורים פעילים בו-זמנית.

כישורים מצורפים

Nebo מגיע עם כישורים מצורפים שמכסים תרחישי שימוש נפוצים:

כישורעדיפותתיאור
onboarding100ברכת משתמש חדש ואיסוף פרופיל
best-friend50כישור אישיות — קליל, נאמן, דיבור אמיתי
debugging25מתודולוגיה שיטתית לניפוי באגים
api-design15שיטות עבודה מומלצות לתכנון RESTful API
code-review10סקירת קוד מובנית עם רמות חומרה
database-expert10תכנון מסדי נתונים, שאילתות, אופטימיזציה
git-workflow10ענפים ב-Git, קומיטים, תהליכי PR
security-audit10ניתוח אבטחה וזיהוי חולשות

אלה משמשים גם כברירות מחדל שימושיות וגם כמימושי ייחוס ליצירת כישורים משלך.

מדריך עיון

קובצי Proto

קובצי Proto נמצאים ב-proto/apps/v0/. ערכות ה-SDK מגיעות עם קוד שנוצר מראש, כך שאין צורך ב-protoc לפיתוח רגיל.

קובץשירותRPCs עיקריים
v0/common.proto(הודעות בלבד)HealthCheckRequest/Response, SettingsMap, UserContext, Empty
v0/tool.protoToolServiceName, Description, Schema, Execute, RequiresApproval, Configure
v0/channel.protoChannelServiceID, Connect, Disconnect, Send, Receive (stream), Configure
v0/comm.protoCommServiceName, Version, Connect, Disconnect, Send, Subscribe, Register, Receive (stream), Configure
v0/gateway.protoGatewayServiceHealthCheck, Stream (stream), Poll, Cancel, Configure
v0/ui.protoUIServiceHealthCheck, HandleRequest, Configure
v0/schedule.protoScheduleServiceHealthCheck, Create, Get, List, Update, Delete, Enable, Disable, Trigger, History, Triggers (stream), Configure

כל שירות כולל את ה-RPCs ‏HealthCheck ו-Configure. ה-SDK מטפל בשניהם אוטומטית.

סוגי Proto של ערוצים

סוג הודעהתיאור
ChannelSendRequestמעטפת הודעה יוצאת עם message_id, ‏channelId, ‏sender, ‏text, ‏attachments, ‏reply_to, ‏actions, ‏platform_data
ChannelSendResponseמזהה הודעה בפלטפורמה לשרשור
InboundMessageמעטפת הודעה נכנסת עם כל השדות המשותפים + timestamp
MessageSenderזהות הבוט (name, ‏role, ‏botId) — מועשרת על ידי המתווך
Attachmentקובץ מצורף מסוג קובץ/תמונה/אודיו (type, ‏url, ‏filename, ‏size)
MessageActionפעולת כפתור/מקלדת אינטראקטיבית (label, ‏callback_id)

זהות ותפקידים של בוטים

לבוטים של Nebo יש מודל זהות בשלושה צירים:

  • creature — מה הבוט הוא (ארכיטיפ): „אסטרטג שנון”, „חוקר קפדן”
  • role — איך הוא קשור למשתמש (מערכת יחסים): „חבר”, „סמנכ״ל תפעול”, „מנטור”
  • vibe — האנרגיה שלו (סגנון תקשורת): „רגוע אבל דעתן”, „חם ומעודד”

כשתוסף הערוץ שלך מקבל הודעה יוצאת, השדה sender מכיל את ה-name וה-role של הבוט. השתמש בהם כדי לעצב את שם התצוגה בפלטפורמה שלך. התפקיד אינו תואר משרה — הוא מתאר מערכת יחסים. „חבר”, „בן” ו„מנטור” הם תפקידים תקפים לצד „COO” ו-„DevLead”.