寫一個外掛
-
建立外掛。 這會寫出
plugins/<name>.ts和它的測試,並把外掛列進roundtable.config.ts。終端機視窗 bunx roundtable add plugin hello -
編輯它。 外掛是一個有名稱和
setup函式的物件,setup回傳它要新增的東西。 下面這個外掛給每個 agent 一個工具:import { definePlugin, defineTool } from "pi-roundtable";import { Type } from "typebox";export const hello = definePlugin({name: "hello",setup: () => ({tools: [defineTool({name: "hello_greet",description: "Greet someone by name. Call it when asked to say hello.",parameters: Type.Object({ who: Type.String() }),minTier: "member",run: ({ who }) => `Hello, ${who}!`,}),],}),}); -
測試它。
testPlugin執行外掛時不需要 Discord 或 PostgreSQL。import { expect, test } from "bun:test";import { testPlugin } from "pi-roundtable/testing";import { hello } from "./hello.ts";test("hello greets", async () => {const harness = await testPlugin(hello);expect(await harness.runTool("hello_greet", { who: "Ada" })).toBe("Hello, Ada!");await harness.stop();});終端機視窗 bun test -
重新啟動 bot。 每個 agent 現在都能呼叫
hello_greet。終端機視窗 bunx roundtable start
請 agent 用它,它會呼叫這個工具:
把檔案附在 agent 回覆裡
Section titled “把檔案附在 agent 回覆裡”工具仍要回傳模型會讀到的文字,也可以呼叫 turn.attachFile({ name, data }),把圖片或其他檔案附在 agent 最後的回覆。
data 是非空的 Uint8Array 原始位元組,不是檔案路徑或 base64。
核心會立即複製資料。
turn.attachFile({ name: "drawing.png", data: pngBytes });return "圖片會附在這輪回覆裡。";不要在工具裡呼叫 context.surfaces.sendReply 來送檔案,否則檔案會先於 agent 回覆送出,而且可能使用 bot 身分。
成功完成的一輪會一起送出文字和附件。
Discord 會用相同的 agent webhook 名稱和頭像,在文字後逐個送出檔案。
成功但沒有文字時仍可送檔。
停止、逾時或失敗的一輪會丟棄附件。
工具失敗後若模型成功完成該輪,先前接受的附件仍會保留。
pi-roundtable 主入口匯出 ReplyFile、attachReplyFile(file)、ReplyFileError 和凍結的 REPLY_FILE_LIMITS。
Raw session tool 和 Pi package tool 可在工具執行期間(await 完成前)呼叫 attachReplyFile。
Pi package 應使用 host 的 pi-roundtable peer dependency,不能另外包一份。
對話輪次以外、輪次結束後,或 transient runTask 內呼叫都會失敗。
獨立 worker 可用主入口的 withReplyFiles(supported, run) 包住整個 await 輪次;run 回傳 Promise<TurnResult>,呼叫者負責送出回傳的附件。
/kit 的 prepareImageBytes 處理圖片位元組,不重新開啟 guest 可改寫的路徑。
它會在 native decode 前檢查 25 MiB 編碼大小與 64 MP 解碼像素上限(包含所有影格合計),超過上限時會拋出 ImagePreparationError。
一般 48 MP 圖片仍可使用,9000×1 長條圖片仍會縮至長邊 2,000 px。
此 collector 使用相同驗證,失敗或拋出錯誤時會丟棄附件;不能為每個工具另開 collector 來繞過每輪上限。
每輪最多 10 個檔案、每個最多 10 MiB(10,485,760 bytes),所有工具合計最多 50 MiB(52,428,800 bytes)。
空資料、非 Uint8Array 資料、空檔名、. 或 ..、含路徑或控制字元的檔名、超過 255 字元的檔名,以及超過上限的附件都會以 ReplyFileError 拒絕,不會靜默丟棄。
自訂 ChatSurface 必須設 supportsFiles: true,並用回覆者身分送出每個 OutboundReply.files,或以錯誤拒絕送出。
未設定或設為 false 時,附件呼叫會失敗。
傳輸端仍可能設更嚴格的限制。
surface 拒絕送出時,reply path 會寫入 log。
訊息群組可能只送出一部分,而且不會重試。
自訂 ConversationTurnInput.reply 會收到成功結果中的 TurnResult.files,並由該 callback 負責送出。
測試附件工具時,注入 supportsFiles: true 的 surface,再檢查 testPlugin 的 harness.files。
範例見 reply-files example,測試方法見測試外掛。
完整附件契約見外掛指南(英文)。
要看一個完整的本機繪圖工具如何附上產出,見drawing 套件指南和套件原始碼。
外掛指南(英文)說明外掛能新增的每個部分(工具、提示詞區段、agent、事件、服務、migration、provider、斜線指令、HTTP 路由等等)、啟動與停止的順序,以及每一種啟動錯誤和它的修正方式。
指南裡的範例放在 examples/,測試套件會執行每一個範例。
pi-roundtable/kit 提供頻道認領(claim)、工具與呈現用的輔助函式。
pi-roundtable/discord 提供斜線指令註冊器、擁有者指令與面板的輔助函式,以及 agent 面板。
這兩個入口的版本規則與主入口相同:1.0 之前,不相容的變更會放在次版本(minor)發佈,並列在變更記錄(英文)中。