NeboAI
NeboAI
开始使用

为 Nebo 构建应用

赋予你的 AI 全新的超能力。工具、频道、网关、UI 面板——任何你能想到的东西,都能编译成原生二进制文件。

概述

Nebo 是什么

Nebo 是一款个人桌面 AI 助手——一位始终在线、帮你打理数字生活的 AI 员工。你可以像看待智能手机那样看待 Nebo:一个强大的平台,因为有了应用而焕然一新。

Nebo 本身就是一位能干的 AI 员工,具备记忆、日程安排、网页浏览、文件管理和 shell 访问能力。但真正的突破在于应用。正如智能手机的强大来自其应用生态,Nebo 的强大也来自那些扩展其能力的应用。

应用是什么

Nebo 应用是自成一体、预先编译的功能单元,能力惊人。每个应用都为 Nebo 带来一项新的超能力——日历管理、邮件分拣、项目跟踪、家居自动化、财务分析——开发者能想到的任何东西。

应用以非常安全的方式提供强大的能力。每个应用都在沙箱中运行,权限默认全部拒绝。它只能访问其清单中声明且经用户批准的内容。

界面 100% 基于对话。用户不需要通过单独的界面或仪表板来使用应用。他们只需与 Nebo 对话,Nebo 会调用应用的工具把事情办好。“我明天有什么安排?”——Nebo 调用日历应用。“帮我和 Sarah 约一个下午 3 点的会议”——Nebo 调用日历应用。用户始终不必离开对话。

应用还可以选择提供设置界面——一个在 Nebo 内置浏览器窗口中打开的配置面板。用户在这里输入 API 密钥、开关功能并配置应用。设置界面由清单中的 settings 数组驱动(Nebo 会自动渲染表单),应用也可以通过 ui 能力提供自己的完整自定义界面。

应用可以替代并扩展 Nebo 的内置能力。Nebo 自带一些基础平台工具(本地日历访问、截图等)。当你安装日历应用后,它会替代内置的日历工具,并成为其超集——本地 + 云端 + 聚合 + 空闲时间检查。

仅限编译型政策

Nebo 严格执行仅限编译型二进制文件的政策。所有应用都必须是原生编译的可执行文件。

状态语言
支持Go(推荐)、Rust、C/C++、Zig
不支持Python、Node.js、Ruby、Java、.NET、shell 脚本

理由:

  • 防止 AI 自我修改——拥有 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""显示在界面中
settings[]可配置的设置(在设置界面中渲染)
oauth[]OAuth 提供方要求(见下文 OAuth 部分)

能力

声明你的应用提供什么:

能力gRPC 服务说明
gatewayGatewayServiceLLM 模型路由
tool:<name>ToolService供 AI 员工使用的具名工具
channel:<name>ChannelService一个消息频道
commCommServiceAI 员工之间的通信
uiUIService带 HTTP 代理的自定义界面
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:create定时任务管理
database:database:query数据库访问
storage:storage:read、storage:write持久化存储
context:context:readAI 员工上下文访问
subagent:subagent:spawn子智能体操作
lane:lane:enqueue通道(lane)操作
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 界面中该应用的设置面板里。Nebo 将它们保存在数据库中,并在设置变更时通过 Configure RPC 发送给你的应用。

你的设置结构会包含在 NeboAI 应用商店的列表信息中。必填设置尚未配置的应用,会在界面中显示“需要设置”标记。

类型说明
text单行文本输入
password掩码文本输入
toggle布尔开关
select带预设选项的下拉菜单
number数字输入
url带校验的 URL 输入
{
    "key": "region",
    "title": "Region",
    "type": "select",
    "required": true,
    "default": "us-east-1",
    "options": [
        {"label": "US East", "value": "us-east-1"},
        {"label": "EU West", "value": "eu-west-1"}
    ]
}

OAuth 要求

应用可以声明 OAuth 提供方要求。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 套接字路径
NEBO_APP_ID清单中的应用 ID
NEBO_APP_NAME清单中的应用名称
NEBO_APP_VERSION清单中的应用版本
NEBO_APP_DATA应用 data/ 目录的路径
PATH系统 PATH(直接透传)
HOME用户主目录(直接透传)
TMPDIR临时目录(直接透传)

关键:你的二进制文件必须创建一个 gRPC 服务器,监听位于 NEBO_APP_SOCK 的 Unix 套接字。Nebo 最多等待 10 秒让该套接字出现。

应用启动顺序

  1. Nebo 读取 manifest.json 并进行校验
  2. 在应用目录中查找 binary 或 app 可执行文件
  3. 检查 .quarantined 标记(拒绝启动已隔离的应用)
  4. 吊销检查(仅限 NeboAI 分发的应用)
  5. 签名验证(仅限 NeboAI 分发的应用,开发模式下跳过)
  6. 二进制校验(拒绝符号链接、脚本、不可执行文件和超大文件)
  7. 清理上次运行遗留的套接字
  8. 创建 data/ 目录用于沙箱存储
  9. 为每个应用设置日志文件(logs/stdout.log、logs/stderr.log)
  10. 以净化后的环境和进程组隔离方式启动二进制文件
  11. 等待 Unix 套接字出现(指数退避,最长 10 秒)
  12. 通过 Unix 套接字上的 gRPC 建立连接
  13. 根据 provides 创建各能力对应的 gRPC 客户端
  14. 运行健康检查
  15. 向 AI 员工注册能力(工具、网关、通信等)

工具应用

在清单中声明 "provides": ["tool:my_tool_name"]。

STRAP 模式

所有 Nebo 工具应用的结构定义和执行路由都必须使用 STRAP(Single Tool Resource Action Pattern,单工具资源动作模式)。Nebo 内部也用同样的模式,把 35 个以上的独立工具整合为 4 个领域工具——将 LLM 上下文开销降低约 80%。

核心思路:不要注册多个工具(get_events、check_availability、suggest_slots),而是只注册一个工具,用 action(以及可选的 resource)字段路由到正确的处理器。

单资源示例(日历):

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() 流——每当用户给 bot 发消息,你的应用就发送入站消息
  4. 入站消息被路由到 AI 员工的主对话通道
  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}可路由的频道标识符
senderobjectbot 身份——名称、角色、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 包含消息、工具、系统提示词、最大 token 数、温度,以及一个 UserContext(若授予了 user:token 权限,则包含 JWT 令牌)。

GatewayEvent 类型:

类型内容说明
"text"文本块流式文本 token
"tool_call"JSON模型要调用工具
"thinking"文本块扩展思考/推理
"error"错误信息出了问题
"done"空流已结束

UI 应用

UI 应用提供一个在 Nebo 内置浏览器窗口中打开的自定义配置界面。声明 "provides": ["ui"]。与自动生成的设置表单(Nebo 根据你清单中的 settings 渲染)不同,UI 应用提供自己完整的 HTML/CSS/JS 前端。

你的应用附带一个 ui/ 目录,其中包含静态网页资源(HTML、CSS、JS——通常是带有 index.html 的单页应用)。Nebo 直接提供这些文件,并通过 gRPC 将 API 调用代理到你的应用。

路径机制用途
GET /api/v1/apps/{id}/ui/*静态文件服务器提供你 ui/ 目录中的文件(单页应用回退到 index.html)
ANY /api/v1/apps/{id}/api/*gRPC 代理将 HTTP 请求代理到你应用的 UIService.HandleRequest()

SDK 封装了一个标准的 net/http.ServeMux,因此你可以编写普通的 Go HTTP 处理器——SDK 会自动处理 gRPC 桥接。

Go 示例——仪表板界面:

package main

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

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

type Dashboard struct {
    mux *http.ServeMux
}

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

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

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

    return d
}

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

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

你的 ui/index.html 会向 /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——每当日程触发时,你的应用就发送一条触发消息
  • 同一时间只能有一个日程应用处于启用状态

多能力应用

一个应用可以提供多项能力。例如,一个同时带有工具和界面的仪表板应用:

{
    "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 URL),会完全跳过签名验证。本地开发不需要 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 团队审核元数据、清单和扫描结果
  3. 审核通过——NeboAI 使用 Ed25519 为应用签名并发布
  4. 审核未通过——你会收到原因,修改后可以重新提交

目标审核时间:<24 小时。

推送更新

  1. 更新应用的版本:使用新版本调用 PUT /api/v1/developer/apps/{id}
  2. 为每个平台上传新的二进制文件
  3. 再次提交审核

每次更新都要经过同样的审核流程。在新版本获批之前,旧版本仍然可用。

商店元数据

字段说明
category例如:productivity、communication、developer-tools
icon应用图标 URL
visibilitypublic 或 private
description可以比清单中的描述更长、更丰富

开发工作流

本地开发

本地开发无需打包:

  1. 创建你的应用目录:
    mkdir -p ~/Library/Application\ Support/Nebo/apps/com.example.myapp
  2. 编写你的 manifest.json 和代码
  3. 构建你的二进制文件:
    go build -o ~/Library/Application\ Support/Nebo/apps/com.example.myapp/binary .
  4. Nebo 会自动检测到新目录(或重启 Nebo)
  5. 修改代码后,重新构建二进制文件——文件监视器会重启应用

查看日志

应用的 stdout/stderr 会记录在每个应用各自的日志文件中:

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

持久化数据

使用 data/ 目录(也可通过环境变量 NEBO_APP_DATA 获取)存放应用需要持久保存的任何文件。该目录在应用更新和隔离后依然保留。

调试技巧

  • 如果你的应用无法启动,请检查 logs/stderr.log 中的错误
  • 确保二进制文件可执行(chmod +x binary)
  • 确保你正在监听 NEBO_APP_SOCK 给出的 Unix 套接字路径
  • 套接字必须在启动后 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 员工的上下文保持精简——提示词里只保留当下真正有用的指引。

技能与应用相辅相成。应用提供可执行的能力(工具、频道、网关)。技能提供编排指引——告诉 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 前置元数据,以及 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 个技能
  • token 预算:所有已启用技能的内容合计上限为 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 不是职位头衔,而是对关系的描述。“朋友”“儿子”“导师”和“COO”“DevLead”一样,都是有效的角色。