頂層欄位
| 欄位 | 類型 | 必填 | 意義 |
|---|---|---|---|
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。每個項目都包含下列五個欄位。發布時,市集會寫入實際的雜湊值、大小、簽章與下載網址,因此在你上傳的檔案中請將它們留空。
"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 中的憑證鍵,這份結構描述會為每位員工的連線表單欄位加上標籤。
| 欄位 | 類型 | 預設值 | 意義 |
|---|---|---|---|
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 會啟動它,並在它結束時重新啟動。監看程式寫到 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 | 必填 | 傳給你的二進位檔的引數。 |
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。