外掛能新增什麼
外掛是一個有名稱和 setup 函式的物件。
setup 回傳這個外掛要新增的部分。
回傳值裡每個 key 就是一個部分;契約裡沒有的 key 會讓啟動停下來,並指出最接近的那一個。
這一頁把這些部分分成五組,你可以找到需要的那一個,再點連結往下看。
範例檔放在 examples/。
每個範例旁邊都有一個不需要 Discord 就能跑的測試,指南也把每個範例嵌進去。
表格裡的連結都指向外掛完整指南(英文)的章節。
外掛物件與 context
Section titled “外掛物件與 context”| 項目 | 用途 | 範例 | 指南 |
|---|---|---|---|
| 外掛物件 | 放 name(小寫單字用連字號連起來,各外掛之間不能重複)和 setup。選填的欄位放在外掛本身,不放在 setup 的回傳值裡:migrations、providers、provides、replaces、requires 和 preflight。外掛必須新增某樣東西,否則啟動會停下來。 |
tools.ts |
外掛物件 |
| context | setup 收到的東西:一個會在每一行加上外掛名稱的 logger、主機環境(locale、時區)、資料庫、服務等等。有些欄位要等所有外掛都 setup 完才能用。 |
shared-services.ts |
context |
agent 會用到的部分
Section titled “agent 會用到的部分”| 部分 | 適用時機 | 範例 | 指南 |
|---|---|---|---|
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 |
bot 自己做的事
Section titled “bot 自己做的事”| 部分 | 適用時機 | 範例 | 指南 |
|---|---|---|---|
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 |
Discord 和 HTTP 周邊
Section titled “Discord 和 HTTP 周邊”| 部分 | 適用時機 | 範例 | 指南 |
|---|---|---|---|
斜線指令(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 |
換掉核心的部分
Section titled “換掉核心的部分”| 部分 | 適用時機 | 範例 | 指南 |
|---|---|---|---|
providers |
你想換掉核心運作所依靠的某個部分。共有三個槽位:judge、images 和 runtime,每個槽位只能由一個外掛填入。 |
providers.ts |
providers |
runtime 槽位 |
你想用 Pi 以外的 runtime 來跑每一場對話。 | echo-runtime.ts |
runtime 槽位 |
provides 和 replaces |
你想接手一個內建服務,例如排程的儲存。 | shared-services.ts |
取代內建服務 |
上面的範例一次聚焦一個外掛能力。 下列套件展示相關 API 的完整實作:
- 需要 owner 核准的
repo_push和獨立 Pi worker:coding 指南及原始碼。 - 在沒有網路的 container 執行工具型 guest agent,由 host broker 提供 credential:sandbox 指南及原始碼。
- 必須通過驗證的
httpconsole:web 指南及原始碼。 - 繪製圖片並附在回覆裡的工具:drawing 指南及原始碼。
- 由 owner 登入提供的
images實作:codex-images複製式外掛及範本原始碼。 - MCP connector 和 remote MCP endpoint:MCP 指南及原始碼。
dice 和 release-notice 的複製式來源見官方外掛指南。
provides、requires 和 replaces 見服務與 addon,所有範例檔見範例。