顶层字段
| 字段 | 类型 | 必填 | 含义 |
|---|---|---|---|
id | string | 是 | 插件在市场中的标识符。开发期间使用 slug。 |
slug | string | 是 | 稳定标识符。[a-z0-9-],最多 64 个字符,不能以连字符开头或结尾,也不能有连续两个连字符。用于命名 plugin__<slug> 工具和 <SLUG>_BIN 变量。 |
name | string | 是 | 显示名称。写出它所连接的服务名。 |
version | string | 是 | 语义化版本号,例如 0.1.0。 |
platforms | map | 是 | 平台键到二进制文件的映射。参见“平台”。 |
description | string | 否 | 一句话说明,供人和员工阅读。 |
author | string | 否 | 发布者名称。 |
category | string | 否 | 帮助员工找到该插件。 |
triggers | 字符串列表 | 否 | 描述插件适用场景的词语。用于搜索提示。 |
entrySkills | 字符串列表 | 否 | 在插件的工具描述中最先列出的打包技能。 |
dependencies | {name, version, optional} 列表 | 否 | 此插件会运行的其他插件。version 默认为 "*";optional 默认为 false。每次调用时都会设置它们的 <SLUG>_BIN 路径。 |
auth | object | 否 | 登录和账户。参见“认证”。 |
capabilities | object | 否 | configSchema, hooks, commands, routes, providers. |
permissions | object | 否 | 环境变量过滤和超时上限。 |
events | list | 否 | 为员工工作流提供数据的监听器。 |
interfaceBindings | map | 否 | 插件提供的类型化操作。 |
channel | object | 否 | 与消息服务之间的持久桥接。 |
setup | object | 否 | 分步设置向导。 |
Nebo 会校验从市场安装的插件:slug 规则、语义化版本号、至少一个平台、不含路径分隔符或 .. 的 binaryName、除非 auth.type 为 env 否则必须有 login 命令、非空的事件名称和命令,以及可以解析的绑定模板。用户插件目录中的插件不做校验。
平台
键为 darwin-arm64、darwin-amd64、linux-arm64、linux-amd64、windows-arm64 和 windows-amd64。每个条目都包含下面全部五个字段。发布时,市场会写入真实的哈希值、大小、签名和下载 URL,所以在你上传的文件中把它们留空。
"platforms": {
"darwin-arm64": { "binaryName": "notes-sync", "sha256": "", "signature": "", "size": 0, "downloadUrl": "" },
"linux-amd64": { "binaryName": "notes-sync", "sha256": "", "signature": "", "size": 0, "downloadUrl": "" },
"windows-amd64": { "binaryName": "notes-sync.exe", "sha256": "", "signature": "", "size": 0, "downloadUrl": "" }
} | 字段 | 含义 |
|---|---|
binaryName | 可执行文件的文件名。Windows 上要加 .exe。 |
sha256 | 二进制文件的哈希值。在安装时校验。 |
signature | 二进制文件的签名。有签名密钥时会在安装时校验。 |
size | 大小(字节)。 |
downloadUrl | Nebo 下载软件包的地址。 |
认证
| 字段 | 含义 |
|---|---|
type | oauth_cli 表示由插件运行的浏览器登录;env 表示以值的形式输入的凭据;neboai 表示在每个以 _TOKEN 结尾的 auth.env 键中接收所有者的 NeboAI 令牌。 |
env | 变量名到默认值的映射。这也是 Nebo 传给 login 的全部凭据名称。 |
commands.login | 登录。除非 type 为 env,否则必填。运行时会设置好账户文件夹。 |
commands.status | 输出 JSON,说明该账户是否已登录。 |
commands.refresh | 无需交互即可续期令牌。 |
commands.logout | 退出登录。只有所有者可以运行。 |
profileDirEnv | 一个变量,为每位员工和每个账户分别提供独立的凭据文件夹。没有它,插件只持有一个共享账户。 |
label, description | 连接卡片上的文字。 |
help | 连接过程中显示的 {url, urlLabel, text}。 |
publicRedirect | 当提供商拒绝 http://localhost 重定向时设为 true;此时登录会经由 NeboAI 的公共重定向地址。 |
Nebo 读取状态输出中 authenticated、isAuthenticated、logged_in、loggedIn 或 token_valid 里最先出现的那个。非空的 token_error,或 credential_source、auth_method、storage、status 中的值为 none,都表示已退出登录。状态命令有 45 秒的执行时间。
{"authenticated": true, "account": "finance@example.com"} configSchema
capabilities.configSchema 描述所有者为插件设置的值。每个值都会作为以 key 命名的环境变量传给二进制文件。对于同时列在 auth.env 中的凭据键,该 schema 会为每位员工的连接表单中的字段提供标签。
| 字段 | 类型 | 默认值 | 含义 |
|---|---|---|---|
key | string | 必填 | 环境变量名。 |
label | string | 必填 | 字段标签。 |
description | string | "" | 帮助文字。 |
fieldType | string | "string" | 输入类型,例如 string、number、boolean、select 或 password。 |
default | string | 无 | 预填值。 |
required | boolean | false | 设置该值之前,插件不可用。 |
secret | boolean | false | 读回时该值会被遮盖。 |
options | 字符串列表 | 无 | select 的可选项。 |
permissions
| 字段 | 默认值 | 含义 |
|---|---|---|
envAllow | [] | 插件可以看到的继承变量。留空则全部允许。 |
envDeny | [] | 始终移除的继承变量。 |
maxTimeoutSeconds | 300 | 任何调用超时时间的上限。 |
network | false | 声明网络使用。仅供参考,不强制执行。 |
events
事件是一个长期运行的监听器。当员工的工作流监听它时,Nebo 会启动它;如果它退出,Nebo 会重新启动它。监听器写到 stdout 的每一行就是一个事件。运行时事件名会加上 slug 前缀,因此 note.created 会变成 notes-sync.note.created。
"events": [
{
"name": "note.created",
"description": "A note was created in the watched notebook.",
"command": "watch --notebook {{notebook}} --format ndjson"
}
] | 字段 | 含义 |
|---|---|
name | 事件名称,不含 slug。必填。 |
command | 启动监听器的参数。必填。{{key}} 会被替换为员工的输入值。 |
description | 触发该事件的原因。 |
multiplexed | 设为 true 时,一个监听器会发出多种类型的事件,每一行都带有 "event" 字段。 |
工作流通过 watch 触发器订阅事件。参见触发器。
interfaceBindings
绑定把一个接口操作映射到你的某个命令。每个绑定都会成为员工可用的类型化工具,名称取自操作名的小写形式,并把点和连字符换成下划线:notes.search 变成 notes_search。插件正是通过绑定来满足员工所需的能力;参见能力。
"interfaceBindings": {
"notes.search": "notes search --query {query} {tag[]:--tag} {limit?:--limit}",
"invoice.create": "invoices create --amount {amount_cents:cents->dollars}"
} | 占位符 | 展开为 |
|---|---|
{field} | 字段的值,作为一个词传入。该字段不会再作为标志传入。 |
{field[]:--flag} | 列表字段中的每一项对应一对 --flag <item>。 |
{field?:--flag} | 字段存在时为 --flag <value>;不存在时为空。 |
{field:cents->dollars} | 以分为单位的整数金额,写成美元形式。 |
模板中没有提到的输入字段会以 --field value 的形式追加。列表占位符和可选占位符必须是完整的词。需要审批的操作,无法通过 plugin__<slug> 调用同一命令来执行。
钩子、斜杠命令和路由
"capabilities": {
"hooks": [
{ "hook": "tool.post_execute", "hookType": "filter", "command": "hook redact", "priority": 50, "timeoutMs": 500 }
],
"commands": [
{ "name": "notes", "description": "Show today's notes", "command": "notes today", "slash": true }
],
"routes": [
{ "path": "/callback", "method": "GET", "command": "http callback" }
]
} hooks
钩子会在员工回合中的某个时间点运行你的命令。Nebo 会把 JSON 负载写入 stdin。action 钩子的输出会被忽略。filter 钩子返回 {"payload": ..., "handled": false};"handled": true 会阻止后续钩子运行。出错和超时时会保留之前的负载,绝不会阻塞回合。钩子连续失败三次后会暂停五分钟。
| 字段 | 默认值 | 含义 |
|---|---|---|
hook | 必填 | 取值为 tool.pre_execute、tool.post_execute、message.post_receive、session.message_append、steering.generate、agent.turn、agent.should_continue 之一。 |
hookType | "action" | action 或 filter。 |
command | 必填 | 传给你的二进制文件的参数。 |
priority | 100 | 数值小的先运行。 |
timeoutMs | 500 | 时间限制(毫秒)。 |
commands
设置 "slash": true 后,在聊天中输入 /name args 会直接运行 command args,不经过员工。输出就是回复内容。时间限制为 30 秒。
routes
路由在机器人上的 /api/v1/plugins/<slug>/api/<path> 处响应 HTTP 请求,按 path 和 method 匹配。请求正文传给 stdin,你的 stdout 就是响应。时间限制为 30 秒。
providers
提供商用于添加一个聊天模型来源。需要声明 id、displayName、providerType、modelsCommand 和 chatCommand。Nebo 会把聊天请求以 JSON 形式通过 stdin 发给 chatCommand,并从 stdout 读取以换行分隔的 JSON 流式事件,最长 300 秒。目前只使用聊天流式传输。
channel
频道用于桥接一个消息服务。Nebo 会让 command 持续运行,从它的 stdout 读取收到的消息,并把回复写入它的 stdin,两者都是以换行分隔的 JSON。
| 字段 | 默认值 | 含义 |
|---|---|---|
command | 必填 | 启动桥接程序的参数。 |
name, description | "" | 显示在设置中。 |
restartDelaySecs | 5 | 崩溃后重启前的等待时间。 |
shared | false | 所有员工共用一个桥接;消息按员工名称路由,回复带有各员工自己的身份。 |
needsLocalApi | false | 向桥接程序提供机器人的本地 API 地址、一个令牌和员工 ID。除非你需要,否则保持关闭。 |
setup
设置向导会引导所有者完成单个表单无法涵盖的步骤。form 步骤中的值会填入后续 generate 参数中的 {{key}}。credentials 步骤中的值会保存为插件的环境变量。
"setup": {
"title": "Connect Example Chat",
"steps": [
{ "kind": "form", "title": "Bot name", "fields": [ { "key": "bot_name", "label": "Name", "required": true } ] },
{ "kind": "generate", "title": "App manifest", "command": "manifest", "args": ["--name", "{{bot_name}}"], "outputFormat": "yaml" },
{ "kind": "external", "title": "Create the app", "url": "https://example.com/apps", "urlLabel": "Open admin" },
{ "kind": "credentials", "title": "Paste the token", "fields": [ { "key": "EXAMPLE_CHAT_TOKEN", "label": "Token", "inputType": "password", "required": true } ], "verifyCommand": "auth status" }
]
} | 步骤类型 | 字段 |
|---|---|
form | title, description, fields |
generate | title、description、command、args、outputFormat(yaml、json、toml、text)、buttonLabel。显示命令的输出供复制。 |
external | title, description, url, urlLabel, instructions |
credentials | title、description、fields、verifyCommand。verifyCommand 成功时该步骤完成。 |
字段包含 key、label、default、placeholder、maxLength、help、inputType(text、textarea、password)和 required。