插件的工作方式
插件就是一个可执行文件加一个清单。两次调用之间,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。 |
timeout | integer | 等待的秒数。默认 120,上限为清单中的 permissions.maxTimeoutSeconds。 |
display | string | 调用需要审批时所有者看到的那句话。 |
构建你的第一个插件
用任意语言编写一个二进制程序,从参数中读取命令并输出结果。然后把它和一个 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 }
]
} auth.env指定凭据的名称。capabilities.configSchema为它们提供标签,并设置它们在连接表单中的顺序。auth.profileDirEnv指定你的插件用来读取凭据文件夹的变量。Nebo 会为每位员工和每个账户创建一个文件夹,并在每次调用时设置该变量。- 当所有者连接一个账户时,Nebo 会运行你的
login命令,传入所有者输入的值,并设置好账户文件夹。你的插件把需要的内容保存在该文件夹中。Nebo 不会保留这些值。 - 你的
status命令会输出 JSON,例如{"authenticated": true}。令牌过期时,如果你声明了refresh,Nebo 会运行它。
对于浏览器登录,把 type 设为 oauth_cli,并让 login 输出或打开提供商的登录 URL。员工永远不会自行登录:当某次调用需要登录时,所有者会看到一张连接卡片。拥有多个账户的员工,可以在命令中加上 --account <label> 来选择其中一个。Nebo 会在你的二进制文件看到之前移除这个标志。
用服务命名,而不是用形式命名。插件的名称说明它连接的是什么,例如“Example Notes”。永远不要在插件名称中写“CLI”;对员工和所有者来说,它是一个连接,而不是命令行。
下一步
- plugin.json 参考:所有字段,包括事件、钩子和类型化操作。
- 发布插件:平台、二进制文件、签名和更新。
- 发布:每种作品的市场发布流程。