NeboAI
NeboAI
開始使用

為 Nebo 打造應用程式

賦予你的 AI 全新超能力。工具、頻道、閘道、UI 面板 — 任何你想像得到的功能,都能編譯成原生二進位檔。

概覽

Nebo 是什麼

Nebo 是一款個人桌面 AI 助理 — 一位全天候運作、替你打理數位生活的 AI 員工。你可以把 Nebo 想成智慧型手機:一個強大的平台,透過它的應用程式帶來徹底的改變。

單靠本身,Nebo 就是一位能幹的 AI 員工,具備記憶、排程、網頁瀏覽、檔案管理與 shell 存取能力。但真正的關鍵在於應用程式。就像智慧型手機的威力來自它的應用程式生態系,Nebo 的威力也來自擴充其能力的應用程式。

應用程式是什麼

Nebo 應用程式是獨立、預先編譯、功能強大的單元。每個應用程式都賦予 Nebo 一項新的超能力 — 行事曆管理、電子郵件分類、專案追蹤、居家自動化、財務分析 — 任何開發者想像得到的功能。

應用程式以非常安全的方式提供強大的能力。每個應用程式都在沙箱中執行,權限預設為拒絕。它只能存取其 manifest 所宣告且經使用者核准的項目。

介面百分之百是對話式的。使用者不會透過另外的畫面或儀表板與應用程式互動。他們跟 Nebo 對話,Nebo 再使用應用程式的工具把事情辦好。「我明天的行事曆有什麼?」— Nebo 呼叫行事曆應用程式。「幫我跟 Sarah 約下午 3 點開會」— Nebo 呼叫行事曆應用程式。使用者從不需要離開對話。

應用程式可以選擇提供設定 UI — 一個在 Nebo 內建瀏覽器視窗中開啟的設定面板。使用者在這裡輸入 API 金鑰、切換功能並設定應用程式。設定 UI 由 manifest 中的 settings 陣列驅動(Nebo 會自動產生表單),應用程式也可以透過 ui 能力提供完整的自訂 UI。

應用程式會取代並擴充 Nebo 的內建能力。Nebo 內建基本的平台工具(本機行事曆存取、螢幕截圖等)。當你安裝行事曆應用程式時,它會取代內建的行事曆工具,成為功能更完整的超集合 — 本機 + 雲端 + 彙整 + 空檔查詢。

僅限編譯政策

Nebo 嚴格執行僅限編譯的二進位檔政策。所有應用程式都必須是原生編譯的可執行檔。

狀態語言
支援Go(建議)、Rust、C/C++、Zig
不接受Python、Node.js、Ruby、Java、.NET、shell 指令碼

理由:

  • 防止 AI 自我修改 — 具備 shell 存取權的 AI 員工可能在執行時修改直譯式指令碼的行為。編譯後的二進位檔在簽署後就無法變更。
  • 簽章完整性 — Ed25519 簽章涵蓋原始二進位位元組。已簽署的二進位檔一經修改,簽章就會失效。
  • 沙箱強制執行 — 二進位格式驗證(ELF/Mach-O/PE 魔術位元組)是一道快速又可靠的關卡。

快速入門

安裝 SDK

官方 SDK 會處理所有 gRPC 伺服器設定、訊號處理與協定橋接。你只需要實作處理常式介面。

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/

應用程式目錄結構

應用程式位於 Nebo 資料目錄中的 apps/ 子目錄:

~/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. 為你的能力實作處理常式介面(ToolHandler、ChannelHandler 等)
  5. 註冊處理常式並呼叫 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易於閱讀的名稱
versionSemver 字串
provides至少一項能力(見下方)

選填欄位:

欄位預設值說明
runtime"local""local" 或 "remote"
protocol"grpc"僅支援 "grpc"
permissions[]應用程式需要存取的項目
description""顯示於 UI 中
settings[]可設定的選項(顯示於設定 UI 中)
oauth[]OAuth 供應商需求(見下方 OAuth 章節)

能力

宣告你的應用程式提供哪些功能:

能力gRPC 服務說明
gatewayGatewayServiceLLM 模型路由
tool:<name>ToolService供 AI 員工使用的具名工具
channel:<name>ChannelService訊息頻道
commCommServiceAI 員工之間的通訊
uiUIService搭配 HTTP 代理的自訂 UI
scheduleScheduleService自訂排程
visionToolService影像處理
browserToolService瀏覽器自動化

一個應用程式可以提供多項能力。例如,一個應用程式可以同時提供工具和 UI 面板。

權限

權限控制應用程式可以存取的內容。預設為拒絕 — 若未宣告,應用程式就無法使用。

前綴範例說明
network:network:outbound、network:*網路存取
filesystem:filesystem:read、filesystem:write檔案系統存取
memory:memory:read、memory:writeAI 員工記憶存取
session:session:read對話工作階段
tool:tool:shell、tool:file使用其他工具
shell:shell:exec執行 shell 指令
channel:channel:send、channel:*頻道操作
comm:comm:send、comm:*AI 員工之間的通訊
model:model:chatAI 模型存取
user:user:token在請求中接收使用者 JWT
schedule:schedule:createCron 排程工作管理
database:database:query資料庫存取
storage:storage:read、storage:write永久儲存空間
context:context:readAI 員工情境存取
subagent:subagent:spawn子代理操作
lane:lane:enqueueLane 操作
notification:notification:send推播通知
embedding:embedding:search向量嵌入存取
skill:skill:invoke技能呼叫
advisor:advisor:consult顧問系統存取
mcp:mcp:connectMCP 伺服器存取
voice:voice:record語音/音訊存取
browser:browser:navigate瀏覽器自動化
oauth:oauth:google、oauth:*OAuth 權杖存取
settings:settings:read設定存取
capability:capability:register能力註冊

支援萬用字元權限:network:* 符合任何 network: 權限檢查。

設定

設定會顯示在 Nebo UI 中該應用程式的設定面板。Nebo 會將設定儲存在資料庫中,並在設定變更時透過 Configure RPC 傳送給你的應用程式。

你的設定結構描述會包含在 NeboAI 應用程式商店的上架資訊中。有必填設定尚未完成的應用程式,會在 UI 中顯示「需要設定」標章。

類型說明
text單行文字輸入
password遮罩文字輸入
toggle布林開關
select含預設選項的下拉選單
number數字輸入
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 供應商需求。Nebo 的 OAuth 代理會處理整個流程 — 應用程式透過 Configure RPC 自動收到權杖。

{
    "oauth": [
        {
            "provider": "google",
            "scopes": ["https://www.googleapis.com/auth/calendar"]
        }
    ]
}
欄位說明
providerOAuth 供應商:"google"、"microsoft"、"github"
scopes應用程式需要的 OAuth 範圍陣列

使用者安裝應用程式時,Nebo 會提示他們授權所需的 OAuth 範圍。應用程式透過 Configure RPC 收到更新後的權杖,不必自行處理 OAuth 流程。

環境變數

你的應用程式程序會收到經過清理的環境。所有機密資訊都會被移除。你會得到:

變數值
NEBO_APP_DIR應用程式的安裝目錄
NEBO_APP_SOCK要建立的 Unix socket 路徑
NEBO_APP_IDmanifest 中的應用程式 ID
NEBO_APP_NAMEmanifest 中的應用程式名稱
NEBO_APP_VERSIONmanifest 中的應用程式版本
NEBO_APP_DATA應用程式 data/ 目錄的路徑
PATH系統 PATH(直接傳遞)
HOME使用者主目錄(直接傳遞)
TMPDIR暫存目錄(直接傳遞)

重要:你的二進位檔必須建立一個 gRPC 伺服器,監聽位於 NEBO_APP_SOCK 的 Unix socket。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. 透過 Unix socket 以 gRPC 連線
  13. 依據 provides 建立對應能力的 gRPC 用戶端
  14. 執行健康檢查
  15. 向 AI 員工註冊能力(工具、閘道、通訊等)

工具應用程式

在你的 manifest 中宣告 "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)欄位路由到正確的處理常式。

單一資源範例(行事曆):

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 欄位,作為必填的字串列舉
  2. 只有當你的工具管理多種不同的資源類型時,才加上 resource 欄位(必填的字串列舉)
  3. 其他所有欄位都是特定動作的參數
  4. action 列舉的說明應列出所有可用的動作

STRAP 為什麼重要:

  • LLM 只需學一次 action 路由模式,就能套用到所有操作
  • 工具定義會占用約 6% 的情境 — STRAP 可將其減少 80%
  • 新增操作只需加入列舉值,不必註冊新工具
  • 在雲端託管模型與本機模型上運作方式完全相同

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 等)橋接到 Nebo 的 AI 員工。當使用者在外部平台傳送訊息時,你的應用程式會透過 Receive 將訊息串流給 Nebo。當 AI 員工要回覆時,Nebo 會呼叫你應用程式的 Send。

運作方式

  1. Nebo 呼叫 ID() 取得你頻道的唯一識別碼
  2. Nebo 使用你應用程式設定中的組態呼叫 Connect()
  3. Nebo 開啟一個 Receive() 串流 — 每當使用者傳訊息給機器人,你的應用程式就傳送傳入訊息
  4. 傳入訊息會被路由到 AI 員工的主要對話 lane
  5. 當 AI 員工要傳送訊息時,Nebo 會以 v1 訊息信封呼叫 Send()
  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依時間排序的唯一 ID
channel_id{type}:{platform_id}可路由的頻道識別碼
senderobject機器人身分 — 名稱、角色、botId
textstring訊息內文
attachmentsarray檔案、圖片、音訊
reply_toUUID v7用於討論串的上層訊息 ID
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傳送者員工 ID
to接收者員工 ID
topic訊息主題/頻道
type"message"、"mention"、"proposal"、"command"、"info"、"task"
content訊息內文

主要行為:

  • Register 會在網路上宣告這位 AI 員工及其能力
  • Subscribe/Unsubscribe 管理主題訂閱
  • Receive 串流傳入訊息(伺服器串流,與頻道相同)
  • 同一時間只能有一個通訊應用程式處於啟用狀態

閘道應用程式

閘道應用程式負責將 LLM 請求路由到模型。宣告 "provides": ["gateway"] 與 "permissions": ["network:outbound", "user:token"]。

GatewayRequest 包含訊息、工具、系統提示、最大權杖數、溫度,以及 UserContext(若已授予 user:token 權限,則包含 JWT 權杖)。

GatewayEvent 類型:

類型內容說明
"text"文字片段串流文字權杖
"tool_call"JSON模型要呼叫工具
"thinking"文字片段延伸思考/推理
"error"錯誤訊息發生錯誤
"done"空白串流已結束

UI 應用程式

UI 應用程式提供自訂的設定介面,在 Nebo 的內建瀏覽器視窗中開啟。宣告 "provides": ["ui"]。不同於自動產生的設定表單(Nebo 依據你 manifest 中的 settings 產生),UI 應用程式會提供自己完整的 HTML/CSS/JS 前端。

你的應用程式隨附一個 ui/ 目錄,內含靜態網頁資源(HTML、CSS、JS — 通常是含有 index.html 的 SPA)。Nebo 會直接提供這些檔案,並透過 gRPC 將 API 呼叫代理到你的應用程式。

路徑機制用途
GET /api/v1/apps/{id}/ui/*靜態檔案伺服器提供你 ui/ 目錄中的檔案(SPA 退回至 index.html)
ANY /api/v1/apps/{id}/api/*gRPC 代理將 HTTP 請求代理到你應用程式的 UIService.HandleRequest()

SDK 包裝了標準的 net/http.ServeMux,讓你撰寫一般的 Go HTTP 處理常式 — SDK 會自動處理 gRPC 橋接。

Go 範例 — 儀表板 UI:

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 會對 /api/v1/apps/com.example.dashboard/api/status 發出 fetch 呼叫,這些呼叫會被代理到你的 mux 處理常式。

排程應用程式

排程應用程式會取代 Nebo 內建的 cron 排程器。宣告 "provides": ["schedule"] 與 "permissions": ["schedule:create"]。

排程應用程式啟動後,Nebo 會將所有排程交由你的應用程式處理,而非預設的 cron 引擎。如果你的應用程式當機,Nebo 會自動退回使用內建引擎。

  • 你的應用程式擁有排程狀態 — 排程應用程式啟用時,Nebo 不會將排程存在自己的資料庫中
  • 標準 CRUD:Create、Get、List、Update、Delete、Enable、Disable
  • Triggers 是伺服器串流 RPC — 每當排程觸發時,你的應用程式就會傳送一則觸發訊息
  • 同一時間只能有一個排程應用程式處於啟用狀態

多能力應用程式

一個應用程式可以提供多項能力。例如,一個同時具備工具與 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())

封裝

.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 MBEd25519 簽章
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. 在 POST /api/v1/owners/register 註冊 NeboAI 帳戶
  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 團隊會審核中繼資料、manifest 與掃描結果
  3. 核准後 — NeboAI 會以 Ed25519 簽署應用程式並將其發布
  4. 遭拒時 — 你會收到原因,修正後可重新提交

目標審核時間:<24 小時。

推送更新

  1. 更新 app 的版本:以新版本呼叫 PUT /api/v1/developer/apps/{id}
  2. 為每個平台上傳新的二進位檔
  3. 再次提交審核

每次更新都會經過相同的審核流程。在新版本核准之前,先前的版本仍可使用。

商店中繼資料

欄位說明
category例如 productivity、communication、developer-tools
icon應用程式圖示網址
visibilitypublic 或 private
description可以比 manifest 中的說明更長、更豐富

開發工作流程

本機開發

本機開發不需要封裝:

  1. 建立你的 app 目錄:
    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)
  • 確認你正在監聽 NEBO_APP_SOCK 所指定的 Unix socket 路徑
  • 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 員工在該工作階段中的語氣、方法、領域專業與工具使用方式。

技能不是程式碼。它們是帶有 YAML 中繼資料的 markdown 文件。不需要編譯、不需要二進位檔、不需要 gRPC。一個技能就是目錄中的一個 SKILL.md 檔案,就這樣。

技能是情境式且暫時的。它們在相關時啟用(透過觸發詞比對或手動載入),持續幾個回合,不再需要時就會過期。這讓 AI 員工的情境保持精簡 — 提示中只會有當下真正重要的指引。

技能與應用程式相輔相成。應用程式提供可執行的能力(工具、頻道、閘道)。技能則提供協調指引 — 說明如何有效運用這些工具。行事曆應用程式讓 Nebo 能讀寫行程;「會議準備」技能則告訴 Nebo 如何同時運用該行事曆應用程式、電子郵件和網頁搜尋來準備會議。

技能與應用程式比較

技能應用程式
格式Markdown(SKILL.md)編譯後的二進位檔(.napp)
執行環境注入系統提示透過 gRPC 執行的沙箱程序
提供行為指引、方法工具、頻道、UI 面板
生命週期以工作階段為範圍,依 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 檔案,分成兩部分:位於 --- 標記之間的 YAML frontmatter,以及 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-design15RESTful API 設計最佳實務
code-review10依嚴重程度分級的結構化程式碼審查
database-expert10資料庫設計、查詢與最佳化
git-workflow10Git 分支、提交與 PR 工作流程
security-audit10安全性分析與漏洞偵測

這些既是實用的預設值,也是你建立自己技能時的參考範例。

參考資料

Proto 檔案

Proto 檔案位於 proto/apps/v0/。SDK 已隨附預先產生的程式碼,所以一般開發不需要 protoc。

檔案服務主要 RPC
v0/common.proto(僅含訊息)HealthCheckRequest/Response、SettingsMap、UserContext、Empty
v0/tool.protoToolServiceName、Description、Schema、Execute、RequiresApproval、Configure
v0/channel.protoChannelServiceID、Connect、Disconnect、Send、Receive(串流)、Configure
v0/comm.protoCommServiceName、Version、Connect、Disconnect、Send、Subscribe、Register、Receive(串流)、Configure
v0/gateway.protoGatewayServiceHealthCheck、Stream(串流)、Poll、Cancel、Configure
v0/ui.protoUIServiceHealthCheck、HandleRequest、Configure
v0/schedule.protoScheduleServiceHealthCheck、Create、Get、List、Update、Delete、Enable、Disable、Trigger、History、Triggers(串流)、Configure

每個服務都包含 HealthCheck 與 Configure RPC。SDK 會自動處理這兩者。

頻道 Proto 類型

訊息類型說明
ChannelSendRequest傳出訊息信封,包含 message_id、channelId、sender、text、attachments、reply_to、actions、platform_data
ChannelSendResponse用於討論串的平台訊息 ID
InboundMessage傳入訊息信封,包含所有共通欄位 + 時間戳記
MessageSender機器人身分(name、role、botId)— 由代理伺服器補充
Attachment檔案/圖片/音訊附件(type、url、filename、size)
MessageAction互動式按鈕/鍵盤動作(label、callback_id)

機器人身分與角色

Nebo 機器人採用三軸身分模型:

  • creature — 機器人是什麼(原型):「機智的策略家」、「一絲不苟的研究員」
  • role — 它與使用者的關係(關係):「朋友」、「營運長」、「導師」
  • vibe — 它的氣質(溝通風格):「隨和但有主見」、「溫暖又鼓舞人心」

當你的頻道外掛收到傳出訊息時,sender 欄位會包含機器人的 name 與 role。用它來設定在你的平台上顯示的名稱。role 不是職稱 — 而是描述關係的詞。「朋友」、「兒子」和「導師」,跟「營運長」和「開發主管」一樣都是有效的角色。