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。每個項目都包含下列五個欄位。發布時,市集會寫入實際的雜湊值、大小、簽章與下載網址,因此在你上傳的檔案中請將它們留空。

"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 中的憑證鍵,這份結構描述會為每位員工的連線表單欄位加上標籤。

欄位類型預設值意義
keystring必填環境變數名稱。
labelstring必填欄位標籤。
descriptionstring""說明文字。
fieldTypestring"string"輸入類型,例如 string、number、boolean、select 或 password。
defaultstring無預先填入的值。
requiredbooleanfalse在設定此值之前,外掛無法就緒。
secretbooleanfalse讀回時會遮蔽此值。
options字串清單無select 的選項。

permissions

欄位預設值意義
envAllow[]外掛可以看到的繼承變數。留空表示全部允許。
envDeny[]一律移除的繼承變數。
maxTimeoutSeconds300任何呼叫逾時時間的上限。
networkfalse宣告網路使用情形。僅供參考,不會強制執行。

events

事件是長時間執行的監看程式。當員工的工作流程監看它時,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

hook 會在員工回合中的某個時間點執行你的指令。Nebo 會把 JSON 酬載寫入 stdin。action hook 的輸出會被忽略。filter hook 會回傳 {"payload": ..., "handled": false};"handled": true 會讓後續的 hook 不再執行。錯誤與逾時會保留先前的酬載,絕不會卡住回合。hook 連續失敗三次後會暫停五分鐘。

欄位預設值意義
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。