外掛的運作方式
外掛由一個執行檔加上一份資訊清單組成。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指令會輸出像{"authenticated": true}這樣的 JSON。權杖過期時,若你有宣告refresh,Nebo 就會執行它。
若要使用瀏覽器登入,請將 type 設為 oauth_cli,並讓 login 輸出或開啟供應商的登入網址。員工絕不會自行登入:當呼叫需要登入時,擁有者會看到一張連線卡片。擁有多個帳戶的員工,可以在指令中加上 --account <label> 來選擇其中一個。Nebo 會在你的二進位檔看到之前移除這個旗標。
寫出服務名稱,而不是形式。外掛的名稱要說明它連接的對象,例如「Example Notes」。外掛名稱中絕不要放「CLI」;對員工和擁有者來說,它是一個連線,而不是命令列。
下一步
- plugin.json 參考:每個欄位,包括事件、掛鉤與型別化操作。
- 發布外掛:平台、二進位檔、簽署與更新。
- 發布:所有項目的市集發布流程。