NeboAI
NeboAI
开始使用

插件

插件给员工提供可以操作的对象:在线服务、业务系统,或电脑上的程序。你把它构建成一个命令行二进制文件,并用 plugin.json 清单来描述它。员工调用它的命令,Nebo 负责安装、每位员工的账户和更新。

插件的工作方式

插件就是一个可执行文件加一个清单。两次调用之间,Nebo 不会让任何插件进程保持运行。每当员工使用插件时,Nebo 会带上命令和参数启动二进制文件,等待它退出,然后把输出交还给员工。

  • 命令就是参数。员工选择一个命令(例如 notes search)以及命名参数。Nebo 以 --name value 的形式传递每个参数。这里没有 shell,所以管道和重定向都不适用。
  • 输出就是 stdout。把结果写到 stdout。JSON 格式很合适。
  • 普通调用时,标准输入是关闭的。钩子、路由和聊天提供商会使用 stdin;参见 plugin.json 参考。

每个已安装并启用的插件,在员工看来都是一个名为 plugin__<slug> 的工具。员工这样调用它:

{
  "command": "notes search",
  "args": { "query": "quarterly plan", "limit": "5" },
  "display": "Search notes for the quarterly plan"
}

Nebo 会运行:

notes-sync notes search --query "quarterly plan" --limit 5
参数类型含义
command字符串,必填插件命令以及任何位置参数。
args字符串对象命名参数。每个都会变成 --key value。
timeoutinteger等待的秒数。默认 120,上限为清单中的 permissions.maxTimeoutSeconds。
displaystring调用需要审批时所有者看到的那句话。

构建你的第一个插件

用任意语言编写一个二进制程序,从参数中读取命令并输出结果。然后把它和一个 plugin.json 一起放进机器人的用户插件目录。

<data>/user/plugins/notes-sync/
├── plugin.json      # runtime manifest
├── notes-sync       # your binary, named after the slug
└── skills/          # optional: skills that teach employees to use it
    └── notes-sync/
        └── SKILL.md
{
  "id": "notes-sync",
  "slug": "notes-sync",
  "name": "Notes Sync",
  "version": "0.1.0",
  "description": "Search, read and create notes in Example Notes.",
  "platforms": {}
}

id、slug、name、version 和 platforms 是必填的。在用户插件目录中,platforms 映射可以为空:Nebo 会先在 plugin.json 旁边查找以 slug 命名的二进制文件,然后在 target/release/ 和 target/debug/ 中查找。发布时,市场会为你上传的每个二进制文件填写 platforms。

<data> 在 macOS 上是 ~/Library/Application Support/Nebo,在 Windows 上是 %APPDATA%\Nebo,在 Linux 上是 ~/.local/share/nebo,或者是 NEBO_HOME 的值。用户目录中的插件会覆盖市场上同一 slug 的插件,因此这里正适合测试新构建。

教员工使用它

在 plugin.json 旁边放一个 skills/ 文件夹。插件安装期间,其中的每个技能都对所有员工可用,并会自动把该插件列为依赖。在技能里说明有哪些命令、它们返回什么,以及各自何时使用。把最有用的技能写进 entrySkills,这样插件的工具描述会最先指向它们。

市场页面是另一个文件 PLUGIN.md。Nebo 在运行时不会读取它;它是人们安装前看到的页面。参见发布插件。

环境

每次调用都会继承机器人的环境,并移除加载器和 shell 注入相关的变量,然后添加以下值。排在后面的条目优先。

变量值
auth.env 键来自清单的默认值。
<SLUG>_BIN此插件的二进制文件路径,以及它所依赖的每个插件的路径。slug 会转成大写,连字符换成下划线。
NEBO_DATA_DIR插件自己的数据文件夹 <data>/appdata/plugins/<slug>/。它也是工作目录,卸载后仍会保留。
PATH先是插件文件夹,然后是继承的路径。
设置所有者为 configSchema 字段保存的值。
NEBO_AGENT_ID发起调用的员工。
profileDirEnv插件支持账户时,此员工和此账户对应的账户文件夹。

permissions.envAllow 和 permissions.envDeny 用于收窄插件从机器人继承的内容。它们永远不会移除插件自己的认证变量。

账户与凭据

登录某项服务的插件,应该为每位员工保存一个账户。记账员用财务账号登录,助理用它自己的账号登录,两者都看不到对方的令牌。你在清单中声明这一点,其余的交给 Nebo。

"auth": {
  "type": "env",
  "label": "Example Notes account",
  "env": { "EXAMPLE_NOTES_TOKEN": "" },
  "commands": { "login": "auth login", "status": "auth status", "logout": "auth logout" },
  "profileDirEnv": "EXAMPLE_NOTES_CONFIG_DIR"
},
"capabilities": {
  "configSchema": [
    { "key": "EXAMPLE_NOTES_TOKEN", "label": "API token", "fieldType": "password", "secret": true, "required": true }
  ]
}
  1. auth.env 指定凭据的名称。capabilities.configSchema 为它们提供标签,并设置它们在连接表单中的顺序。
  2. auth.profileDirEnv 指定你的插件用来读取凭据文件夹的变量。Nebo 会为每位员工和每个账户创建一个文件夹,并在每次调用时设置该变量。
  3. 当所有者连接一个账户时,Nebo 会运行你的 login 命令,传入所有者输入的值,并设置好账户文件夹。你的插件把需要的内容保存在该文件夹中。Nebo 不会保留这些值。
  4. 你的 status 命令会输出 JSON,例如 {"authenticated": true}。令牌过期时,如果你声明了 refresh,Nebo 会运行它。

对于浏览器登录,把 type 设为 oauth_cli,并让 login 输出或打开提供商的登录 URL。员工永远不会自行登录:当某次调用需要登录时,所有者会看到一张连接卡片。拥有多个账户的员工,可以在命令中加上 --account <label> 来选择其中一个。Nebo 会在你的二进制文件看到之前移除这个标志。

用服务命名,而不是用形式命名。插件的名称说明它连接的是什么,例如“Example Notes”。永远不要在插件名称中写“CLI”;对员工和所有者来说,它是一个连接,而不是命令行。

下一步

  • plugin.json 参考:所有字段,包括事件、钩子和类型化操作。
  • 发布插件:平台、二进制文件、签名和更新。
  • 发布:每种作品的市场发布流程。