跳到內容

外掛能新增什麼

外掛是一個有名稱和 setup 函式的物件。 setup 回傳這個外掛要新增的部分。 回傳值裡每個 key 就是一個部分;契約裡沒有的 key 會讓啟動停下來,並指出最接近的那一個。 這一頁把這些部分分成五組,你可以找到需要的那一個,再點連結往下看。

範例檔放在 examples/。 每個範例旁邊都有一個不需要 Discord 就能跑的測試,指南也把每個範例嵌進去。 表格裡的連結都指向外掛完整指南(英文)的章節。

項目 用途 範例 指南
外掛物件 放 name(小寫單字用連字號連起來,各外掛之間不能重複)和 setup。選填的欄位放在外掛本身,不放在 setup 的回傳值裡:migrations、providers、provides、replaces、requires 和 preflight。外掛必須新增某樣東西,否則啟動會停下來。 tools.ts 外掛物件
context setup 收到的東西:一個會在每一行加上外掛名稱的 logger、主機環境(locale、時區)、資料庫、服務等等。有些欄位要等所有外掛都 setup 完才能用。 shared-services.ts context
部分 適用時機 範例 指南
tools 你想讓 agent 能呼叫某個東西。每個工具都標明能呼叫它的 speaker 最低要達到哪個層級。 tools.ts tools
holdRules 和工具的 hold 某個呼叫要等 owner 在 Discord 核准才執行。 holds.ts holdRules
prompt 你想在每一輪 agent 的核心提示詞後面再加一段文字。 prompt.ts prompt
seeds 你想在第一次啟動時建立 agent。已經存在資料庫裡的 agent 不會被覆蓋。 seeds.ts seeds
agentSelection 每個 agent 除了自己的工具,還要帶一些共同的工具。 selection.ts agentSelection
piPackages 每個 session 都要載入你安裝的某個 npm 套件裡的 Pi 擴充。它的工具也要列進 agentSelection;roundtable add package 會兩個一起寫好。 packages.ts piPackages
sessionTools tools 表達不了你要的,例如工具組合會在行程執行期間改變。這是 Pi 擴充的原始形式。 session-tools.ts sessionTools
toolTiers 你用了 sessionTools,需要指定每個原始工具要哪個層級才能用。 無 toolTiers
部分 適用時機 範例 指南
events 你想知道核心做了什麼:服務啟動完成、一輪開始或結束、團隊有變動、開始關機。 events.ts events
services 你需要有生命週期的東西,例如計時器、佇列或連線。服務在 setup 之後啟動,以相反的順序停止。 services.ts services
migrations 外掛需要自己的資料表。它們在所有 setup 之前執行。 migrations.ts migrations
preflight 設定有誤時,要在 Discord 連線之前就讓啟動停下來。 preflight.ts preflight
backgroundTargets 排程或委派的任務要以你定義的那種一輪回來,並有自己的限制。 support-desk.ts backgroundTargets
channels 你的外掛要自己負責某些頻道裡的對話,而不是交給 agent server。多數外掛用不到。 channels.ts channels
context.observe 你想聽到其他 claim 所擁有頻道裡的訊息,但不接手、也不回應。除非你要求,私訊不會被聽到;承載代理人房間的介面,除非你的篩選明確指定該介面,否則其房間也不會被聽到。 無 observe
personas 和 context.turns 你擁有某一種對話,替它寫 system prompt,並執行它的每一輪,不必自己寫輸入中、停止和回覆的流程。 study-room.ts personas
部分 適用時機 範例 指南
斜線指令(commands.add) 你想在根指令(預設是 /roundtable)底下加一個子指令。從 setup 透過 DISCORD 服務加入。 interactions.ts 斜線指令
http 你想在 bot 的 listener 上加一條路由,例如健康檢查或 WebSocket 端點。放在上面的東西,網際網路上都能連到,所以要在 handler 裡檢查一個祕密值,或在 WebSocket 開啟前的 accept 裡檢查一張只能用一次的票證。 http.ts http
dashboard 你想在 agent server 釘在 Discord 的 dashboard 訊息上多加幾行。 dashboard.ts dashboard
surfaces 你想接上 Discord 以外的聊天網路。surface 負責回報人們寫了什麼,並貼出對話的回答。 fake-surface.ts surfaces
部分 適用時機 範例 指南
providers 你想換掉核心運作所依靠的某個部分。共有三個槽位:judge、images 和 runtime,每個槽位只能由一個外掛填入。 providers.ts providers
runtime 槽位 你想用 Pi 以外的 runtime 來跑每一場對話。 echo-runtime.ts runtime 槽位
provides 和 replaces 你想接手一個內建服務,例如排程的儲存。 shared-services.ts 取代內建服務

上面的範例一次聚焦一個外掛能力。 下列套件展示相關 API 的完整實作:

dice 和 release-notice 的複製式來源見官方外掛指南。 provides、requires 和 replaces 見服務與 addon,所有範例檔見範例。