NeboAI
NeboAI
开始使用

plugin.json 参考

plugin.json 是 Nebo 用来安装和运行插件的清单文件。键名使用 camelCase。本页列出 Nebo 目前读取的每个字段及其作用。

顶层字段

字段类型必填含义
idstring是插件在市场中的标识符。开发期间使用 slug。
slugstring是稳定标识符。[a-z0-9-],最多 64 个字符,不能以连字符开头或结尾,也不能有连续两个连字符。用于命名 plugin__<slug> 工具和 <SLUG>_BIN 变量。
namestring是显示名称。写出它所连接的服务名。
versionstring是语义化版本号,例如 0.1.0。
platformsmap是平台键到二进制文件的映射。参见“平台”。
descriptionstring否一句话说明,供人和员工阅读。
authorstring否发布者名称。
categorystring否帮助员工找到该插件。
triggers字符串列表否描述插件适用场景的词语。用于搜索提示。
entrySkills字符串列表否在插件的工具描述中最先列出的打包技能。
dependencies{name, version, optional} 列表否此插件会运行的其他插件。version 默认为 "*";optional 默认为 false。每次调用时都会设置它们的 <SLUG>_BIN 路径。
authobject否登录和账户。参见“认证”。
capabilitiesobject否configSchema, hooks, commands, routes, providers.
permissionsobject否环境变量过滤和超时上限。
eventslist否为员工工作流提供数据的监听器。
interfaceBindingsmap否插件提供的类型化操作。
channelobject否与消息服务之间的持久桥接。
setupobject否分步设置向导。

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大小(字节)。
downloadUrlNebo 下载软件包的地址。

认证

字段含义
typeoauth_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 会为每位员工的连接表单中的字段提供标签。

字段类型默认值含义
keystring必填环境变量名。
labelstring必填字段标签。
descriptionstring""帮助文字。
fieldTypestring"string"输入类型,例如 string、number、boolean、select 或 password。
defaultstring无预填值。
requiredbooleanfalse设置该值之前,插件不可用。
secretbooleanfalse读回时该值会被遮盖。
options字符串列表无select 的可选项。

permissions

字段默认值含义
envAllow[]插件可以看到的继承变量。留空则全部允许。
envDeny[]始终移除的继承变量。
maxTimeoutSeconds300任何调用超时时间的上限。
networkfalse声明网络使用。仅供参考,不强制执行。

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必填传给你的二进制文件的参数。
priority100数值小的先运行。
timeoutMs500时间限制(毫秒)。

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""显示在设置中。
restartDelaySecs5崩溃后重启前的等待时间。
sharedfalse所有员工共用一个桥接;消息按员工名称路由,回复带有各员工自己的身份。
needsLocalApifalse向桥接程序提供机器人的本地 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" }
  ]
}
步骤类型字段
formtitle, description, fields
generatetitle、description、command、args、outputFormat(yaml、json、toml、text)、buttonLabel。显示命令的输出供复制。
externaltitle, description, url, urlLabel, instructions
credentialstitle、description、fields、verifyCommand。verifyCommand 成功时该步骤完成。

字段包含 key、label、default、placeholder、maxLength、help、inputType(text、textarea、password)和 required。