NeboAI
NeboAI
Bắt đầu

Xây dựng ứng dụng cho Nebo

Trao cho AI của bạn những siêu năng lực mới. Công cụ, kênh, cổng, bảng giao diện — bất cứ thứ gì bạn có thể nghĩ ra, được biên dịch thành tệp nhị phân gốc.

Tổng quan

Nebo là gì

Nebo là một trợ lý AI cá nhân trên máy tính — một nhân viên AI luôn hoạt động, quản lý cuộc sống số của bạn. Hãy nghĩ về Nebo như cách bạn nghĩ về điện thoại thông minh: một nền tảng mạnh mẽ trở nên đột phá nhờ các ứng dụng của nó.

Tự thân Nebo đã là một nhân viên AI có năng lực, với bộ nhớ, lập lịch, duyệt web, quản lý tệp và quyền truy cập shell. Nhưng điều mở khóa thực sự là Ứng dụng. Giống như sức mạnh của điện thoại thông minh đến từ hệ sinh thái ứng dụng, sức mạnh của Nebo đến từ những ứng dụng mở rộng những gì nó làm được.

Ứng dụng là gì

Ứng dụng Nebo là những đơn vị chức năng mạnh mẽ, độc lập và được biên dịch sẵn. Mỗi ứng dụng mang đến cho Nebo một siêu năng lực mới — quản lý lịch, phân loại email, theo dõi dự án, tự động hóa nhà ở, phân tích tài chính — bất cứ thứ gì nhà phát triển có thể nghĩ ra.

Ứng dụng mang lại sức mạnh to lớn một cách rất an toàn. Mỗi ứng dụng chạy trong sandbox với quyền mặc định là từ chối. Ứng dụng chỉ truy cập được những gì manifest của nó khai báo và người dùng chấp thuận.

Giao diện hoàn toàn bằng hội thoại. Người dùng không tương tác với ứng dụng qua các màn hình hay bảng điều khiển riêng. Họ trò chuyện với Nebo, và Nebo dùng các công cụ của ứng dụng để hoàn thành công việc. "Ngày mai lịch của tôi có gì?" — Nebo gọi ứng dụng lịch. "Tạo cuộc họp với Sarah lúc 3 giờ chiều" — Nebo gọi ứng dụng lịch. Người dùng không bao giờ phải rời khỏi cuộc trò chuyện.

Ứng dụng có thể tùy chọn cung cấp một giao diện cài đặt — bảng cấu hình mở trong cửa sổ trình duyệt tích hợp của Nebo. Đây là nơi người dùng nhập khóa API, bật tắt tính năng và cấu hình ứng dụng. Giao diện cài đặt được điều khiển bởi mảng settings trong manifest (Nebo tự động hiển thị biểu mẫu), hoặc ứng dụng có thể cung cấp giao diện tùy chỉnh hoàn chỉnh của riêng mình qua khả năng ui.

Ứng dụng thay thế và mở rộng các khả năng tích hợp sẵn của Nebo. Nebo đi kèm các công cụ nền tảng cơ bản (truy cập lịch cục bộ, chụp màn hình, v.v.). Khi bạn cài một ứng dụng lịch, nó thay thế công cụ lịch tích hợp sẵn và trở thành một tập bao trùm — cục bộ + đám mây + tổng hợp + kiểm tra lịch trống.

Chính sách chỉ dùng mã biên dịch

Nebo áp dụng nghiêm ngặt chính sách chỉ chấp nhận tệp nhị phân đã biên dịch. Mọi ứng dụng phải là tệp thực thi gốc đã biên dịch.

Trạng tháiNgôn ngữ
Được hỗ trợGo (khuyến nghị), Rust, C/C++, Zig
Bị từ chốiPython, Node.js, Ruby, Java, .NET, shell script

Lý do:

  • Ngăn AI tự sửa đổi — Một nhân viên AI có quyền truy cập shell có thể sửa đổi hành vi của một script thông dịch ngay lúc chạy. Tệp nhị phân đã biên dịch không thể thay đổi sau khi ký số.
  • Tính toàn vẹn của chữ ký — Chữ ký Ed25519 bao phủ các byte nhị phân thô. Một tệp nhị phân đã ký không thể bị sửa đổi mà không làm mất hiệu lực chữ ký.
  • Thực thi sandbox — Kiểm tra định dạng nhị phân (magic byte của ELF/Mach-O/PE) là một chốt chặn nhanh và đáng tin cậy.

Bắt đầu nhanh

Cài đặt SDK

Các SDK chính thức lo toàn bộ việc thiết lập máy chủ gRPC, xử lý tín hiệu và cầu nối giao thức. Bạn chỉ cần triển khai các interface xử lý.

Go (khuyến nghị):

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

Rust (sắp ra mắt):

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

C/C++ (sắp ra mắt):

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

Cấu trúc thư mục ứng dụng

Ứng dụng nằm trong thư mục con apps/ của thư mục dữ liệu 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)

Danh sách kiểm tra ứng dụng tối thiểu

  1. Tạo manifest.json với id, name, version, provides
  2. Viết TOOL.md mô tả cách nhân viên AI nên dùng công cụ của bạn
  3. Cài đặt SDK (go get github.com/neboloop/nebo-sdk-go)
  4. Triển khai interface xử lý cho khả năng của bạn (ToolHandler, ChannelHandler, v.v.)
  5. Đăng ký trình xử lý và gọi app.Run()
  6. Biên dịch tệp nhị phân gốc (go build -o binary .)
  7. Đặt tệp nhị phân + manifest.json + TOOL.md vào thư mục apps/<your-app-id>/
  8. Nebo tự động phát hiện và khởi chạy ứng dụng

Cấu hình

manifest.json

Mỗi ứng dụng đều cần một 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
        }
    ]
}

Các trường bắt buộc:

TrườngMô tả
idĐịnh danh theo tên miền đảo ngược (ví dụ: com.mycompany.myapp)
nameTên dễ đọc
versionChuỗi semver
providesÍt nhất một khả năng (xem bên dưới)

Các trường tùy chọn:

TrườngMặc địnhMô tả
runtime"local""local" hoặc "remote"
protocol"grpc"Chỉ hỗ trợ "grpc"
permissions[]Những gì ứng dụng cần truy cập
description""Hiển thị trong giao diện
settings[]Các cài đặt có thể cấu hình (hiển thị trong giao diện Cài đặt)
oauth[]Yêu cầu nhà cung cấp OAuth (xem phần OAuth bên dưới)

Khả năng

Khai báo những gì ứng dụng của bạn cung cấp:

Khả năngDịch vụ gRPCMô tả
gatewayGatewayServiceĐịnh tuyến mô hình LLM
tool:<name>ToolServiceMột công cụ có tên dành cho nhân viên AI
channel:<name>ChannelServiceMột kênh nhắn tin
commCommServiceGiao tiếp giữa các nhân viên AI
uiUIServiceGiao diện tùy chỉnh với proxy HTTP
scheduleScheduleServiceLập lịch tùy chỉnh
visionToolServiceXử lý hình ảnh
browserToolServiceTự động hóa trình duyệt

Một ứng dụng có thể cung cấp nhiều khả năng. Ví dụ, một ứng dụng có thể cung cấp cả công cụ lẫn bảng giao diện.

Quyền

Quyền kiểm soát những gì ứng dụng có thể truy cập. Mặc định là từ chối — nếu không khai báo, ứng dụng không thể dùng.

Tiền tốVí dụMô tả
network:network:outbound, network:*Truy cập mạng
filesystem:filesystem:read, filesystem:writeTruy cập hệ thống tệp
memory:memory:read, memory:writeTruy cập bộ nhớ của nhân viên AI
session:session:readPhiên hội thoại
tool:tool:shell, tool:fileDùng các công cụ khác
shell:shell:execThực thi lệnh shell
channel:channel:send, channel:*Thao tác trên kênh
comm:comm:send, comm:*Giao tiếp giữa các nhân viên AI
model:model:chatTruy cập mô hình AI
user:user:tokenNhận JWT của người dùng trong các yêu cầu
schedule:schedule:createQuản lý tác vụ cron
database:database:queryTruy cập cơ sở dữ liệu
storage:storage:read, storage:writeLưu trữ bền vững
context:context:readTruy cập ngữ cảnh của nhân viên AI
subagent:subagent:spawnThao tác với agent con
lane:lane:enqueueThao tác với lane
notification:notification:sendThông báo đẩy
embedding:embedding:searchTruy cập vector embedding
skill:skill:invokeGọi kỹ năng
advisor:advisor:consultTruy cập hệ thống cố vấn
mcp:mcp:connectTruy cập máy chủ MCP
voice:voice:recordTruy cập giọng nói/âm thanh
browser:browser:navigateTự động hóa trình duyệt
oauth:oauth:google, oauth:*Truy cập token OAuth
settings:settings:readTruy cập cài đặt
capability:capability:registerĐăng ký khả năng

Hỗ trợ quyền ký tự đại diện: network:* khớp với mọi lần kiểm tra quyền network:.

Cài đặt

Cài đặt xuất hiện trong giao diện Nebo, tại bảng cài đặt của ứng dụng. Nebo lưu chúng trong cơ sở dữ liệu và gửi tới ứng dụng của bạn qua RPC Configure mỗi khi chúng thay đổi.

Lược đồ cài đặt của bạn được đưa vào trang niêm yết trên cửa hàng ứng dụng NeboAI. Ứng dụng có cài đặt bắt buộc chưa được cấu hình sẽ hiện huy hiệu "Cần thiết lập" trong giao diện.

LoạiMô tả
textÔ nhập văn bản một dòng
passwordÔ nhập văn bản được che
toggleCông tắc bật/tắt kiểu boolean
selectDanh sách thả xuống với các tùy chọn định sẵn
numberÔ nhập số
urlÔ nhập URL có kiểm tra hợp lệ
{
    "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"}
    ]
}

Yêu cầu OAuth

Ứng dụng có thể khai báo yêu cầu nhà cung cấp OAuth. Trình môi giới OAuth của Nebo xử lý toàn bộ luồng — ứng dụng tự động nhận token qua RPC Configure.

{
    "oauth": [
        {
            "provider": "google",
            "scopes": ["https://www.googleapis.com/auth/calendar"]
        }
    ]
}
TrườngMô tả
providerNhà cung cấp OAuth: "google", "microsoft", "github"
scopesMảng các phạm vi OAuth mà ứng dụng cần

Khi người dùng cài ứng dụng, Nebo nhắc họ cấp quyền cho các phạm vi OAuth cần thiết. Ứng dụng nhận token đã làm mới qua RPC Configure mà không cần tự xử lý luồng OAuth.

Biến môi trường

Tiến trình ứng dụng của bạn nhận một môi trường đã được làm sạch. Mọi bí mật đều bị loại bỏ. Bạn nhận được:

BiếnGiá trị
NEBO_APP_DIRThư mục cài đặt của ứng dụng
NEBO_APP_SOCKĐường dẫn tới Unix socket cần tạo
NEBO_APP_IDID ứng dụng từ manifest
NEBO_APP_NAMETên ứng dụng từ manifest
NEBO_APP_VERSIONPhiên bản ứng dụng từ manifest
NEBO_APP_DATAĐường dẫn tới thư mục data/ của ứng dụng
PATHPATH của hệ thống (truyền nguyên)
HOMEThư mục home của người dùng (truyền nguyên)
TMPDIRThư mục tạm (truyền nguyên)

Quan trọng: Tệp nhị phân của bạn phải tạo một máy chủ gRPC lắng nghe trên Unix socket tại NEBO_APP_SOCK. Nebo chờ tối đa 10 giây để socket này xuất hiện.

Trình tự khởi chạy ứng dụng

  1. Nebo đọc manifest.json và kiểm tra tính hợp lệ
  2. Tìm tệp thực thi binary hoặc app trong thư mục ứng dụng
  3. Kiểm tra dấu hiệu .quarantined (từ chối khởi chạy ứng dụng bị cách ly)
  4. Kiểm tra thu hồi (chỉ với ứng dụng do NeboAI phân phối)
  5. Xác minh chữ ký (chỉ với ứng dụng do NeboAI phân phối, bỏ qua trong môi trường phát triển)
  6. Kiểm tra tệp nhị phân (từ chối symlink, script, tệp không thực thi được, tệp quá lớn)
  7. Dọn dẹp socket cũ từ lần chạy trước
  8. Tạo thư mục data/ để lưu trữ trong sandbox
  9. Thiết lập tệp nhật ký riêng cho từng ứng dụng (logs/stdout.log, logs/stderr.log)
  10. Khởi động tệp nhị phân với môi trường đã làm sạch và cô lập nhóm tiến trình
  11. Chờ Unix socket xuất hiện (backoff theo cấp số nhân, tối đa 10 giây)
  12. Kết nối qua gRPC trên Unix socket
  13. Tạo các client gRPC theo từng khả năng dựa trên provides
  14. Chạy kiểm tra sức khỏe
  15. Đăng ký các khả năng với nhân viên AI (công cụ, cổng, comm, v.v.)

Ứng dụng công cụ

Khai báo "provides": ["tool:my_tool_name"] trong manifest của bạn.

Mẫu STRAP

Mọi ứng dụng công cụ của Nebo bắt buộc dùng STRAP (Single Tool Resource Action Pattern) cho lược đồ và định tuyến thực thi. Đây cũng là mẫu Nebo dùng nội bộ để gộp hơn 35 công cụ riêng lẻ thành 4 công cụ theo miền — giảm khoảng 80% chi phí ngữ cảnh của LLM.

Ý tưởng cốt lõi: Thay vì đăng ký nhiều công cụ (get_events, check_availability, suggest_slots), hãy đăng ký MỘT công cụ với các trường action (và tùy chọn resource) để định tuyến tới đúng trình xử lý.

Ví dụ một tài nguyên (lịch):

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

Ví dụ nhiều tài nguyên (quản lý dự án):

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

Quy tắc lược đồ:

  1. Luôn có trường action là một enum chuỗi bắt buộc
  2. Chỉ thêm trường resource (enum chuỗi bắt buộc) nếu công cụ của bạn quản lý nhiều loại tài nguyên khác nhau
  3. Mọi trường khác là tham số riêng của từng hành động
  4. Mô tả của enum action nên liệt kê mọi hành động có sẵn

Vì sao STRAP quan trọng:

  • LLM học mẫu định tuyến action một lần và áp dụng chung cho mọi thao tác
  • Định nghĩa công cụ chiếm khoảng 6% ngữ cảnh — STRAP cắt giảm 80% phần đó
  • Thao tác mới chỉ là thêm giá trị enum, không phải đăng ký công cụ mới
  • Hoạt động giống hệt nhau trên cả mô hình được lưu trữ lẫn mô hình cục bộ

Ví dụ Go — Công cụ máy tính bỏ túi

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

Biên dịch và cài đặt:

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/

Ví dụ 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(())
}

Ví dụ 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;
}

Ứng dụng kênh

Khai báo "provides": ["channel:my_channel"] và "permissions": ["channel:send"].

Ứng dụng kênh là cầu nối giữa các nền tảng nhắn tin bên ngoài (Telegram, Discord, Slack, v.v.) và nhân viên AI của Nebo. Khi người dùng gửi tin nhắn trên nền tảng bên ngoài, ứng dụng của bạn truyền nó tới Nebo qua Receive. Khi nhân viên AI muốn trả lời, Nebo gọi Send của ứng dụng.

Cách hoạt động

  1. Nebo gọi ID() để lấy định danh duy nhất của kênh
  2. Nebo gọi Connect() với cấu hình từ cài đặt của ứng dụng
  3. Nebo mở một luồng Receive() — ứng dụng của bạn gửi tin nhắn đến mỗi khi người dùng nhắn cho bot
  4. Tin nhắn đến được định tuyến tới lane hội thoại chính của nhân viên AI
  5. Khi nhân viên AI muốn gửi tin nhắn, Nebo gọi Send() với phong bì tin nhắn v1
  6. Khi tắt, Nebo gọi Disconnect()

Phong bì tin nhắn v1

Mọi tin nhắn kênh — đến và đi — đều dùng phong bì tin nhắn chung:

{
  "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"
}
TrườngLoạiMô tả
message_idUUID v7ID duy nhất sắp xếp theo thời gian
channel_id{type}:{platform_id}Định danh kênh có thể định tuyến
senderobjectDanh tính bot — name, role, botId
textstringNội dung tin nhắn
attachmentsarrayTệp, hình ảnh, âm thanh
reply_toUUID v7ID tin nhắn cha để tạo luồng
actionsarrayNút/bàn phím tương tác
platform_databytesDữ liệu truyền nguyên không minh bạch cho các tính năng riêng của nền tảng
timestampISO 8601Nhà xuất bản đặt giá trị này

Thiết kế hai lớp: Các trường chung (text, attachments, reply_to, actions) đáp ứng 90% tin nhắn do nhân viên khởi tạo. Các tính năng riêng của nền tảng đặt trong platform_data — plugin của bạn ánh xạ chúng sang/từ định dạng gốc của nền tảng.

Luồng hội thoại

Tin nhắn kênh được định tuyến qua các luồng hội thoại riêng cho từng kênh để đảm bảo cô lập:

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

Ví dụ Go — Kênh 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
        }
    ]
}

Thêm khả năng

Ứng dụng Comm

Khai báo "provides": ["comm"] và "permissions": ["comm:*"]. Ứng dụng comm cho phép các nhân viên AI giao tiếp với nhau.

TrườngMô tả
fromID nhân viên gửi
toID nhân viên nhận
topicChủ đề/kênh của tin nhắn
type"message", "mention", "proposal", "command", "info", "task"
contentNội dung tin nhắn

Hành vi chính:

  • Register thông báo nhân viên AI này lên mạng cùng các khả năng của nó
  • Subscribe/Unsubscribe quản lý việc đăng ký theo dõi chủ đề
  • Receive truyền tin nhắn đến (server-streaming, giống như kênh)
  • Mỗi lúc chỉ có một ứng dụng comm được hoạt động

Ứng dụng cổng

Ứng dụng cổng định tuyến các yêu cầu LLM tới mô hình. Khai báo "provides": ["gateway"] và "permissions": ["network:outbound", "user:token"].

GatewayRequest chứa tin nhắn, công cụ, system prompt, số token tối đa, temperature và một UserContext (token JWT nếu quyền user:token được cấp).

Các loại GatewayEvent:

LoạiNội dungMô tả
"text"Đoạn văn bảnToken văn bản dạng streaming
"tool_call"JSONMô hình muốn gọi một công cụ
"thinking"Đoạn văn bảnSuy nghĩ/lập luận mở rộng
"error"Thông báo lỗiĐã xảy ra lỗi
"done"TrốngLuồng đã hoàn tất

Ứng dụng giao diện

Ứng dụng giao diện cung cấp một giao diện cấu hình tùy chỉnh mở trong cửa sổ trình duyệt tích hợp của Nebo. Khai báo "provides": ["ui"]. Khác với biểu mẫu cài đặt tự động (mà Nebo hiển thị từ settings trong manifest), ứng dụng giao diện phục vụ frontend HTML/CSS/JS hoàn chỉnh của riêng nó.

Ứng dụng của bạn đi kèm một thư mục ui/ chứa các tài nguyên web tĩnh (HTML, CSS, JS — thường là một SPA với index.html). Nebo phục vụ trực tiếp các tệp này và chuyển tiếp các lệnh gọi API tới ứng dụng của bạn qua gRPC.

Đường dẫnCơ chếMục đích
GET /api/v1/apps/{id}/ui/*Máy chủ tệp tĩnhPhục vụ các tệp từ thư mục ui/ của bạn (SPA dự phòng về index.html)
ANY /api/v1/apps/{id}/api/*Proxy gRPCChuyển tiếp các yêu cầu HTTP tới UIService.HandleRequest() của ứng dụng

SDK bọc một net/http.ServeMux tiêu chuẩn nên bạn viết các trình xử lý HTTP Go bình thường — SDK tự động lo phần cầu nối gRPC.

Ví dụ Go — Giao diện bảng điều khiển:

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 của bạn sẽ gọi fetch tới /api/v1/apps/com.example.dashboard/api/status, và các lệnh gọi này được chuyển tiếp tới trình xử lý mux của bạn.

Ứng dụng lập lịch

Ứng dụng lập lịch thay thế bộ lập lịch cron tích hợp sẵn của Nebo. Khai báo "provides": ["schedule"] và "permissions": ["schedule:create"].

Khi ứng dụng lập lịch của bạn khởi chạy, Nebo định tuyến mọi việc lập lịch qua ứng dụng của bạn thay vì engine cron mặc định. Nếu ứng dụng gặp sự cố, Nebo tự động quay về engine tích hợp sẵn.

  • Ứng dụng của bạn sở hữu trạng thái lịch — Nebo không lưu lịch vào cơ sở dữ liệu của mình khi có ứng dụng lập lịch đang hoạt động
  • CRUD tiêu chuẩn: Create, Get, List, Update, Delete, Enable, Disable
  • Triggers là một RPC server-streaming — ứng dụng của bạn gửi một tin nhắn kích hoạt mỗi khi một lịch được kích hoạt
  • Mỗi lúc chỉ có một ứng dụng lập lịch được hoạt động

Ứng dụng nhiều khả năng

Một ứng dụng có thể cung cấp nhiều khả năng. Ví dụ, một ứng dụng bảng điều khiển có cả công cụ lẫn giao diện:

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

Đóng gói

Định dạng .napp

Để phân phối qua NeboAI, hãy đóng gói ứng dụng thành tệp .napp (một kho lưu trữ tar.gz):

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

Các tệp bắt buộc:

TệpKích thước tối đaMô tả
manifest.json1 MBSiêu dữ liệu của ứng dụng
binary hoặc app500 MBTệp thực thi
signatures.json1 MBChữ ký Ed25519
TOOL.md1 MBHướng dẫn dùng công cụ cho nhân viên AI

Quy tắc bảo mật khi giải nén:

  • Không có path traversal (../ bị từ chối)
  • Không có symlink (bị từ chối)
  • Không có đường dẫn tuyệt đối (bị từ chối)
  • Chỉ chấp nhận các tên tệp trong danh sách cho phép

Chữ ký

NeboAI ký ứng dụng bằng Ed25519. Định dạng 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>"
}

Ở chế độ phát triển (chưa cấu hình URL của NeboAI), việc xác minh chữ ký được bỏ qua hoàn toàn. Bạn không cần signatures.json khi phát triển cục bộ.

Xuất bản

Khi ứng dụng đã chạy tốt ở máy cục bộ, hãy xuất bản qua NeboAI để phân phối tới mọi người dùng Nebo.

Thiết lập tài khoản nhà phát triển

  1. Đăng ký tài khoản NeboAI tại POST /api/v1/owners/register
  2. Đăng nhập để lấy token JWT: POST /api/v1/owners/login
  3. Tạo tài khoản nhà phát triển: POST /api/v1/developer/accounts

Quy trình gửi

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

Bước 1: Tạo ứng dụng

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

Bước 2: Tải lên tệp nhị phân cho từng nền tảng

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"

Tải lên một tệp nhị phân cho mỗi nền tảng: darwin-arm64, darwin-amd64, linux-amd64, linux-arm64.

Bước 3: Gửi để kiểm duyệt

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

Quy trình kiểm duyệt

  1. Quét tự động — tệp nhị phân được quét qua VirusTotal
  2. Quản trị viên kiểm duyệt — đội ngũ NeboAI xem xét siêu dữ liệu, manifest và kết quả quét
  3. Khi được duyệt — NeboAI ký ứng dụng bằng Ed25519 và xuất bản
  4. Khi bị từ chối — bạn nhận được lý do và có thể sửa rồi gửi lại

Thời gian kiểm duyệt mục tiêu: <24 giờ.

Phát hành bản cập nhật

  1. Cập nhật phiên bản của ứng dụng: PUT /api/v1/developer/apps/{id} với phiên bản mới
  2. Tải lên tệp nhị phân mới cho từng nền tảng
  3. Gửi lại để kiểm duyệt

Mỗi bản cập nhật đều qua cùng quy trình kiểm duyệt. Các phiên bản trước vẫn khả dụng cho đến khi phiên bản mới được duyệt.

Siêu dữ liệu cửa hàng

TrườngMô tả
categoryví dụ: productivity, communication, developer-tools
iconURL biểu tượng ứng dụng
visibilitypublic hoặc private
descriptionCó thể dài hơn/phong phú hơn mô tả trong manifest

Quy trình phát triển

Phát triển cục bộ

Không cần đóng gói khi phát triển cục bộ:

  1. Tạo thư mục ứng dụng của bạn:
    mkdir -p ~/Library/Application\ Support/Nebo/apps/com.example.myapp
  2. Viết manifest.json và mã nguồn
  3. Build tệp nhị phân của bạn:
    go build -o ~/Library/Application\ Support/Nebo/apps/com.example.myapp/binary .
  4. Nebo tự động phát hiện thư mục mới (hoặc khởi động lại Nebo)
  5. Sau khi thay đổi mã, hãy biên dịch lại tệp nhị phân — trình theo dõi tệp sẽ khởi động lại ứng dụng

Xem nhật ký

stdout/stderr của ứng dụng được ghi vào các tệp nhật ký riêng cho từng ứng dụng:

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

Dữ liệu bền vững

Dùng thư mục data/ (cũng có sẵn dưới dạng biến môi trường NEBO_APP_DATA) cho mọi tệp mà ứng dụng cần lưu lâu dài. Thư mục này vẫn còn qua các bản cập nhật ứng dụng và khi bị cách ly.

Mẹo gỡ lỗi

  • Nếu ứng dụng không khởi động, hãy kiểm tra lỗi trong logs/stderr.log
  • Đảm bảo tệp nhị phân có quyền thực thi (chmod +x binary)
  • Đảm bảo bạn đang lắng nghe trên đường dẫn Unix socket từ NEBO_APP_SOCK
  • Socket phải sẵn sàng trong vòng 10 giây sau khi khởi chạy
  • Dùng NEBO_APP_DATA để lưu trữ, không dùng đường dẫn viết cứng
  • In ra stderr để ghi nhật ký gỡ lỗi (được ghi vào logs/stderr.log)

Xác minh

# 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

Gỡ cài đặt

nebo apps uninstall com.example.myapp

Kỹ năng

Kỹ năng là gì

Kỹ năng là những bộ chỉ dẫn định hình cách Nebo hành xử trong cuộc trò chuyện. Khi một kỹ năng được kích hoạt, nội dung của nó được chèn trực tiếp vào system prompt — định hướng giọng điệu, phương pháp, chuyên môn và cách dùng công cụ của nhân viên AI trong phiên đó.

Kỹ năng không phải là mã. Chúng là các tài liệu markdown có siêu dữ liệu YAML. Không biên dịch, không tệp nhị phân, không gRPC. Một kỹ năng là một tệp SKILL.md trong một thư mục. Chỉ vậy thôi.

Kỹ năng mang tính ngữ cảnh và tạm thời. Chúng kích hoạt khi liên quan (qua khớp trình kích hoạt hoặc tải thủ công), duy trì trong vài lượt và hết hạn khi không còn cần. Điều này giúp ngữ cảnh của nhân viên AI luôn gọn nhẹ — chỉ những chỉ dẫn cần thiết lúc này mới có trong prompt.

Kỹ năng bổ trợ cho ứng dụng. Ứng dụng cung cấp các khả năng thực thi được (công cụ, kênh, cổng). Kỹ năng cung cấp chỉ dẫn điều phối — cách dùng các công cụ đó hiệu quả. Một ứng dụng lịch cho Nebo khả năng đọc và ghi sự kiện. Một kỹ năng "chuẩn bị họp" cho Nebo biết cách chuẩn bị cho cuộc họp bằng cách kết hợp ứng dụng lịch đó, email và tìm kiếm web.

Kỹ năng và ứng dụng

Kỹ năngỨng dụng
Định dạngMarkdown (SKILL.md)Tệp nhị phân đã biên dịch (.napp)
Môi trường chạyĐược chèn vào system promptTiến trình trong sandbox qua gRPC
Cung cấpChỉ dẫn hành vi, phương phápCông cụ, kênh, bảng giao diện
Vòng đờiTheo phạm vi phiên, hết hạn dựa trên TTLLuôn chạy
Cách tạoViết một tệp markdownViết, biên dịch, ký số, đóng gói
Bảo mậtKhông cần quyềnSandbox mặc định từ chối

Bắt đầu nhanh

Tạo một thư mục trong thư mục kỹ năng của Nebo với một tệp SKILL.md:

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

Viết một 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 theo dõi thư mục kỹ năng bằng fsnotify. Kỹ năng của bạn có sẵn ngay — không cần khởi động lại. Nói điều gì đó khớp với một trình kích hoạt, và kỹ năng sẽ tự động kích hoạt.

Hoặc hỏi thẳng Nebo: "Tạo một kỹ năng để viết bài blog" — Nebo sẽ viết tệp SKILL.md cho bạn.

Định dạng SKILL.md

Mỗi kỹ năng là một tệp SKILL.md duy nhất gồm hai phần: frontmatter YAML nằm giữa các dấu ---, và phần thân markdown (các chỉ dẫn thực tế được chèn vào system prompt).

TrườngBắt buộcMặc địnhMô tả
nameCó—Định danh duy nhất (trở thành slug)
descriptionCó—Mô tả một dòng hiển thị trong danh mục kỹ năng
versionKhông"1.0.0"Semver để theo dõi các bản cập nhật
authorKhông—Tác giả kỹ năng
priorityKhông0Cao hơn = được khớp trước (100+ cho các ghi đè quan trọng)
max_turnsKhông4Số lượt không hoạt động trước khi tự động hết hạn
triggersKhông[]Các cụm từ tự động kích hoạt kỹ năng này (khớp chuỗi con, không phân biệt hoa thường)
toolsKhông[]Các công cụ kỹ năng này dự kiến dùng (mang tính thông tin)
dependenciesKhông[]Các kỹ năng khác phải được cài đặt
tagsKhông[]Để phân loại và khám phá
platformKhông[]Nền tảng được hỗ trợ: macos, linux, windows (để trống = tất cả)

Cách kỹ năng kích hoạt

Kỹ năng tuân theo mô hình kích hoạt hai giai đoạn: gợi ý rồi gọi.

Giai đoạn 1: Khớp trình kích hoạt — Mỗi khi người dùng gửi tin nhắn, Nebo quét mọi kỹ năng đã đăng ký để tìm trình kích hoạt khớp. Các kỹ năng khớp xuất hiện dưới dạng gợi ý trong system prompt. Nhân viên AI thấy gợi ý và quyết định có gọi kỹ năng hay không.

Giai đoạn 2: Gọi — Nhân viên AI gọi một kỹ năng bằng cách gọi:

skill(name: "code-review")

Lệnh này trả về toàn bộ mẫu SKILL.md làm kết quả công cụ, ghi nhận lần gọi và chèn lại mẫu vào system prompt ở các lượt sau.

TTL và hết hạn:

  • Kỹ năng tự động khớp: 4 lượt không hoạt động (cấu hình qua max_turns)
  • Kỹ năng tải thủ công: 6 lượt không hoạt động
  • Gọi lại sẽ đặt lại bộ đếm
  • Giới hạn cứng: tối đa 4 kỹ năng hoạt động mỗi phiên
  • Ngân sách token: tổng nội dung các kỹ năng đang hoạt động tối đa 16,000 ký tự

Quản lý kỹ năng

Nhân viên AI có thể quản lý kỹ năng qua công cụ skill:

Hành độngMô tảVí dụ
catalogLiệt kê mọi kỹ năng có sẵnskill(action: "catalog")
loadKích hoạt cho phiên nàyskill(name: "code-review", action: "load")
unloadTắt một kỹ năngskill(name: "code-review", action: "unload")
createTạo kỹ năng mới trên ổ đĩaskill(action: "create", content: "...")
updateCập nhật một kỹ năng hiện cóskill(name: "my-skill", action: "update", content: "...")
deleteXóa một kỹ năng khỏi ổ đĩaskill(name: "my-skill", action: "delete")

Viết kỹ năng tốt

Một mẫu kỹ năng tốt có:

  1. Tiêu đề rõ ràng — cho nhân viên AI biết nó đang ở chế độ nào
  2. Nguyên tắc cốt lõi — các quy tắc hành vi không thể thương lượng
  3. Phương pháp — cách tiếp cận từng bước cho các tình huống phổ biến
  4. Ví dụ — các mẫu cụ thể từ tin nhắn người dùng đến câu trả lời
  5. Phản mẫu — những điều KHÔNG nên làm (mô hình học tốt từ ví dụ phản diện)

Mẹo: Mỗi kỹ năng nên làm tốt một việc. Đừng tạo kỹ năng "lập trình chung" — hãy tạo code-review, debugging, api-design thành các kỹ năng riêng. Nhân viên AI có thể có nhiều kỹ năng hoạt động cùng lúc.

Kỹ năng đi kèm

Nebo đi kèm các kỹ năng dựng sẵn cho các trường hợp sử dụng phổ biến:

Kỹ năngĐộ ưu tiênMô tả
onboarding100Chào người dùng mới và thu thập hồ sơ
best-friend50Kỹ năng tính cách — thoải mái, trung thành, nói thật lòng
debugging25Phương pháp gỡ lỗi có hệ thống
api-design15Thực hành tốt nhất về thiết kế API RESTful
code-review10Đánh giá mã có cấu trúc với các mức độ nghiêm trọng
database-expert10Thiết kế cơ sở dữ liệu, truy vấn, tối ưu hóa
git-workflow10Phân nhánh Git, commit, quy trình PR
security-audit10Phân tích bảo mật và phát hiện lỗ hổng

Đây vừa là các mặc định hữu ích, vừa là bản triển khai tham khảo để bạn tạo kỹ năng của riêng mình.

Tham chiếu

Tệp proto

Các tệp proto nằm trong proto/apps/v0/. Các SDK đi kèm mã đã được sinh sẵn, nên bạn không cần protoc cho việc phát triển thông thường.

TệpDịch vụRPC chính
v0/common.proto(chỉ có message)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

Mọi dịch vụ đều có các RPC HealthCheck và Configure. SDK tự động xử lý cả hai.

Các kiểu proto của kênh

Kiểu messageMô tả
ChannelSendRequestPhong bì tin nhắn đi với message_id, channelId, sender, text, attachments, reply_to, actions, platform_data
ChannelSendResponseID tin nhắn của nền tảng để tạo luồng
InboundMessagePhong bì tin nhắn đến với mọi trường chung + timestamp
MessageSenderDanh tính bot (name, role, botId) — được broker bổ sung
AttachmentTệp/hình ảnh/âm thanh đính kèm (type, url, filename, size)
MessageActionHành động nút/bàn phím tương tác (label, callback_id)

Danh tính và vai trò của bot

Bot của Nebo có mô hình danh tính ba trục:

  • creature — Bot là gì (nguyên mẫu): "Nhà chiến lược nhanh trí", "Nhà nghiên cứu tỉ mỉ"
  • role — Bot liên hệ với người dùng thế nào (mối quan hệ): "Bạn bè", "COO", "Người cố vấn"
  • vibe — Năng lượng của bot (phong cách giao tiếp): "Thư thái nhưng có chính kiến", "Ấm áp và khích lệ"

Khi plugin kênh của bạn nhận một tin nhắn đi, trường sender chứa name và role của bot. Dùng thông tin này để định dạng tên hiển thị trên nền tảng của bạn. Vai trò không phải là chức danh — mà là mô tả mối quan hệ. "Bạn bè", "Con trai" và "Người cố vấn" đều là vai trò hợp lệ, bên cạnh "COO" và "DevLead".