NeboAI
NeboAI
開始使用

外掛

外掛讓員工有可以操作的對象:線上服務、商務系統,或電腦上的程式。你把它建置成命令列二進位檔,並用 plugin.json 資訊清單描述它。員工呼叫它的指令,而 Nebo 負責安裝、每位員工各自的帳戶與更新。

外掛的運作方式

外掛由一個執行檔加上一份資訊清單組成。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。
timeoutinteger等待秒數。預設為 120,上限為資訊清單中的 permissions.maxTimeoutSeconds。
displaystring呼叫需要核准時,擁有者看到的說明句子。

建置你的第一個外掛

用任何語言撰寫一個二進位檔,從引數讀取指令並輸出結果。然後把它和一份 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 }
  ]
}
  1. auth.env 指名憑證。capabilities.configSchema 為它們加上標籤,並設定它們在連線表單中的順序。
  2. auth.profileDirEnv 指名你的外掛讀取憑證資料夾時使用的變數。Nebo 會為每位員工與每個帳戶建立一個資料夾,並在每次呼叫時設定該變數。
  3. 當擁有者連接帳戶時,Nebo 會以擁有者輸入的值並設定好帳戶資料夾來執行你的 login 指令。你的外掛會把需要的內容存到該資料夾。Nebo 不會保留這些值。
  4. 你的 status 指令會輸出像 {"authenticated": true} 這樣的 JSON。權杖過期時,若你有宣告 refresh,Nebo 就會執行它。

若要使用瀏覽器登入,請將 type 設為 oauth_cli,並讓 login 輸出或開啟供應商的登入網址。員工絕不會自行登入:當呼叫需要登入時,擁有者會看到一張連線卡片。擁有多個帳戶的員工,可以在指令中加上 --account <label> 來選擇其中一個。Nebo 會在你的二進位檔看到之前移除這個旗標。

寫出服務名稱,而不是形式。外掛的名稱要說明它連接的對象,例如「Example Notes」。外掛名稱中絕不要放「CLI」;對員工和擁有者來說,它是一個連線,而不是命令列。

下一步

  • plugin.json 參考:每個欄位,包括事件、掛鉤與型別化操作。
  • 發布外掛:平台、二進位檔、簽署與更新。
  • 發布:所有項目的市集發布流程。