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ái | Ngôn ngữ |
|---|---|
| Được hỗ trợ | Go (khuyến nghị), Rust, C/C++, Zig |
| Bị từ chối | Python, 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
- Tạo
manifest.jsonvớiid,name,version,provides - Viết
TOOL.mdmô tả cách nhân viên AI nên dùng công cụ của bạn - Cài đặt SDK (
go get github.com/neboloop/nebo-sdk-go) - Triển khai interface xử lý cho khả năng của bạn (
ToolHandler,ChannelHandler, v.v.) - Đăng ký trình xử lý và gọi
app.Run() - Biên dịch tệp nhị phân gốc (
go build -o binary .) - Đặt tệp nhị phân + manifest.json + TOOL.md vào thư mục
apps/<your-app-id>/ - 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ường | Mô tả |
|---|---|
id | Định danh theo tên miền đảo ngược (ví dụ: com.mycompany.myapp) |
name | Tên dễ đọc |
version | Chuỗ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ường | Mặc định | Mô 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ăng | Dịch vụ gRPC | Mô tả |
|---|---|---|
gateway | GatewayService | Định tuyến mô hình LLM |
tool:<name> | ToolService | Một công cụ có tên dành cho nhân viên AI |
channel:<name> | ChannelService | Một kênh nhắn tin |
comm | CommService | Giao tiếp giữa các nhân viên AI |
ui | UIService | Giao diện tùy chỉnh với proxy HTTP |
schedule | ScheduleService | Lập lịch tùy chỉnh |
vision | ToolService | Xử lý hình ảnh |
browser | ToolService | Tự độ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:write | Truy cập hệ thống tệp |
memory: | memory:read, memory:write | Truy cập bộ nhớ của nhân viên AI |
session: | session:read | Phiên hội thoại |
tool: | tool:shell, tool:file | Dùng các công cụ khác |
shell: | shell:exec | Thự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:chat | Truy cập mô hình AI |
user: | user:token | Nhận JWT của người dùng trong các yêu cầu |
schedule: | schedule:create | Quản lý tác vụ cron |
database: | database:query | Truy cập cơ sở dữ liệu |
storage: | storage:read, storage:write | Lưu trữ bền vững |
context: | context:read | Truy cập ngữ cảnh của nhân viên AI |
subagent: | subagent:spawn | Thao tác với agent con |
lane: | lane:enqueue | Thao tác với lane |
notification: | notification:send | Thông báo đẩy |
embedding: | embedding:search | Truy cập vector embedding |
skill: | skill:invoke | Gọi kỹ năng |
advisor: | advisor:consult | Truy cập hệ thống cố vấn |
mcp: | mcp:connect | Truy cập máy chủ MCP |
voice: | voice:record | Truy cập giọng nói/âm thanh |
browser: | browser:navigate | Tự động hóa trình duyệt |
oauth: | oauth:google, oauth:* | Truy cập token OAuth |
settings: | settings:read | Truy 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ại | Mô tả |
|---|---|
text | Ô nhập văn bản một dòng |
password | Ô nhập văn bản được che |
toggle | Công tắc bật/tắt kiểu boolean |
select | Danh 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ường | Mô tả |
|---|---|
provider | Nhà cung cấp OAuth: "google", "microsoft", "github" |
scopes | Mả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ến | Giá trị |
|---|---|
NEBO_APP_DIR | Thư 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_ID | ID ứng dụng từ manifest |
NEBO_APP_NAME | Tên ứng dụng từ manifest |
NEBO_APP_VERSION | Phiê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 |
PATH | PATH của hệ thống (truyền nguyên) |
HOME | Thư mục home của người dùng (truyền nguyên) |
TMPDIR | Thư 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
- Nebo đọc
manifest.jsonvà kiểm tra tính hợp lệ - Tìm tệp thực thi
binaryhoặcapptrong thư mục ứng dụng - Kiểm tra dấu hiệu
.quarantined(từ chối khởi chạy ứng dụng bị cách ly) - Kiểm tra thu hồi (chỉ với ứng dụng do NeboAI phân phối)
- 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)
- 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)
- Dọn dẹp socket cũ từ lần chạy trước
- Tạo thư mục
data/để lưu trữ trong sandbox - Thiết lập tệp nhật ký riêng cho từng ứng dụng (
logs/stdout.log,logs/stderr.log) - 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
- Chờ Unix socket xuất hiện (backoff theo cấp số nhân, tối đa 10 giây)
- Kết nối qua gRPC trên Unix socket
- Tạo các client gRPC theo từng khả năng dựa trên
provides - Chạy kiểm tra sức khỏe
- Đă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 đồ:
- Luôn có trường
actionlà một enum chuỗi bắt buộc - 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 - Mọi trường khác là tham số riêng của từng hành động
- Mô tả của enum
actionnê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
actionmộ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
- Nebo gọi
ID()để lấy định danh duy nhất của kênh - Nebo gọi
Connect()với cấu hình từ cài đặt của ứng dụng - 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 - Tin nhắn đến được định tuyến tới lane hội thoại chính của nhân viên AI
- 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 - 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ường | Loại | Mô tả |
|---|---|---|
message_id | UUID v7 | ID 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 |
sender | object | Danh tính bot — name, role, botId |
text | string | Nội dung tin nhắn |
attachments | array | Tệp, hình ảnh, âm thanh |
reply_to | UUID v7 | ID tin nhắn cha để tạo luồng |
actions | array | Nút/bàn phím tương tác |
platform_data | bytes | Dữ 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 |
timestamp | ISO 8601 | Nhà 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ường | Mô tả |
|---|---|
from | ID nhân viên gửi |
to | ID nhân viên nhận |
topic | Chủ đề/kênh của tin nhắn |
type | "message", "mention", "proposal", "command", "info", "task" |
content | Nội dung tin nhắn |
Hành vi chính:
Registerthô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/Unsubscribequản lý việc đăng ký theo dõi chủ đềReceivetruyề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ại | Nội dung | Mô tả |
|---|---|---|
"text" | Đoạn văn bản | Token văn bản dạng streaming |
"tool_call" | JSON | Mô hình muốn gọi một công cụ |
"thinking" | Đoạn văn bản | Suy nghĩ/lập luận mở rộng |
"error" | Thông báo lỗi | Đã xảy ra lỗi |
"done" | Trống | Luồ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ẫn | Cơ chế | Mục đích |
|---|---|---|
GET /api/v1/apps/{id}/ui/* | Máy chủ tệp tĩnh | Phụ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 gRPC | Chuyể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 Triggerslà 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ệp | Kích thước tối đa | Mô tả |
|---|---|---|
manifest.json | 1 MB | Siêu dữ liệu của ứng dụng |
binary hoặc app | 500 MB | Tệp thực thi |
signatures.json | 1 MB | Chữ ký Ed25519 |
TOOL.md | 1 MB | Hướ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
- Đăng ký tài khoản NeboAI tại
POST /api/v1/owners/register - Đăng nhập để lấy token JWT:
POST /api/v1/owners/login - 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
- Quét tự động — tệp nhị phân được quét qua VirusTotal
- 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
- Khi được duyệt — NeboAI ký ứng dụng bằng Ed25519 và xuất bản
- 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
- 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 - Tải lên tệp nhị phân mới cho từng nền tảng
- 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ường | Mô tả |
|---|---|
category | ví dụ: productivity, communication, developer-tools |
icon | URL biểu tượng ứng dụng |
visibility | public hoặc private |
description | Có 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ộ:
- Tạo thư mục ứng dụng của bạn:
mkdir -p ~/Library/Application\ Support/Nebo/apps/com.example.myapp - Viết
manifest.jsonvà mã nguồn - Build tệp nhị phân của bạn:
go build -o ~/Library/Application\ Support/Nebo/apps/com.example.myapp/binary . - Nebo tự động phát hiện thư mục mới (hoặc khởi động lại Nebo)
- 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ạng | Markdown (SKILL.md) | Tệp nhị phân đã biên dịch (.napp) |
| Môi trường chạy | Được chèn vào system prompt | Tiến trình trong sandbox qua gRPC |
| Cung cấp | Chỉ dẫn hành vi, phương pháp | Công cụ, kênh, bảng giao diện |
| Vòng đời | Theo phạm vi phiên, hết hạn dựa trên TTL | Luôn chạy |
| Cách tạo | Viết một tệp markdown | Viết, biên dịch, ký số, đóng gói |
| Bảo mật | Không cần quyền | Sandbox 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ường | Bắt buộc | Mặc định | Mô tả |
|---|---|---|---|
name | Có | — | Định danh duy nhất (trở thành slug) |
description | Có | — | Mô tả một dòng hiển thị trong danh mục kỹ năng |
version | Không | "1.0.0" | Semver để theo dõi các bản cập nhật |
author | Không | — | Tác giả kỹ năng |
priority | Không | 0 | Cao hơn = được khớp trước (100+ cho các ghi đè quan trọng) |
max_turns | Không | 4 | Số lượt không hoạt động trước khi tự động hết hạn |
triggers | Khô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) |
tools | Không | [] | Các công cụ kỹ năng này dự kiến dùng (mang tính thông tin) |
dependencies | Không | [] | Các kỹ năng khác phải được cài đặt |
tags | Không | [] | Để phân loại và khám phá |
platform | Khô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 động | Mô tả | Ví dụ |
|---|---|---|
catalog | Liệt kê mọi kỹ năng có sẵn | skill(action: "catalog") |
load | Kích hoạt cho phiên này | skill(name: "code-review", action: "load") |
unload | Tắt một kỹ năng | skill(name: "code-review", action: "unload") |
create | Tạo kỹ năng mới trên ổ đĩa | skill(action: "create", content: "...") |
update | Cập nhật một kỹ năng hiện có | skill(name: "my-skill", action: "update", content: "...") |
delete | Xóa một kỹ năng khỏi ổ đĩa | skill(name: "my-skill", action: "delete") |
Viết kỹ năng tốt
Một mẫu kỹ năng tốt có:
- Tiêu đề rõ ràng — cho nhân viên AI biết nó đang ở chế độ nào
- Nguyên tắc cốt lõi — các quy tắc hành vi không thể thương lượng
- Phương pháp — cách tiếp cận từng bước cho các tình huống phổ biến
- Ví dụ — các mẫu cụ thể từ tin nhắn người dùng đến câu trả lời
- 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ên | Mô tả |
|---|---|---|
onboarding | 100 | Chào người dùng mới và thu thập hồ sơ |
best-friend | 50 | Kỹ năng tính cách — thoải mái, trung thành, nói thật lòng |
debugging | 25 | Phương pháp gỡ lỗi có hệ thống |
api-design | 15 | Thực hành tốt nhất về thiết kế API RESTful |
code-review | 10 | Đánh giá mã có cấu trúc với các mức độ nghiêm trọng |
database-expert | 10 | Thiết kế cơ sở dữ liệu, truy vấn, tối ưu hóa |
git-workflow | 10 | Phân nhánh Git, commit, quy trình PR |
security-audit | 10 | Phâ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ệp | Dịch vụ | RPC chính |
|---|---|---|
v0/common.proto | (chỉ có message) | HealthCheckRequest/Response, SettingsMap, UserContext, Empty |
v0/tool.proto | ToolService | Name, Description, Schema, Execute, RequiresApproval, Configure |
v0/channel.proto | ChannelService | ID, Connect, Disconnect, Send, Receive (stream), Configure |
v0/comm.proto | CommService | Name, Version, Connect, Disconnect, Send, Subscribe, Register, Receive (stream), Configure |
v0/gateway.proto | GatewayService | HealthCheck, Stream (stream), Poll, Cancel, Configure |
v0/ui.proto | UIService | HealthCheck, HandleRequest, Configure |
v0/schedule.proto | ScheduleService | HealthCheck, Create, Get, List, Update, Delete, Enable, Disable, Trigger, History, Triggers (stream), Configure |
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 message | Mô tả |
|---|---|
ChannelSendRequest | Phong bì tin nhắn đi với message_id, channelId, sender, text, attachments, reply_to, actions, platform_data |
ChannelSendResponse | ID tin nhắn của nền tảng để tạo luồng |
InboundMessage | Phong bì tin nhắn đến với mọi trường chung + timestamp |
MessageSender | Danh tính bot (name, role, botId) — được broker bổ sung |
Attachment | Tệp/hình ảnh/âm thanh đính kèm (type, url, filename, size) |
MessageAction | Hà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".