跳到內容

寫一個外掛

  1. 建立外掛。 這會寫出 plugins/<name>.ts 和它的測試,並把外掛列進 roundtable.config.ts。

    終端機視窗
    bunx roundtable add plugin hello
  2. 編輯它。 外掛是一個有名稱和 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}!`,
    }),
    ],
    }),
    });
  3. 測試它。 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
  4. 重新啟動 bot。 每個 agent 現在都能呼叫 hello_greet。

    終端機視窗
    bunx roundtable start

請 agent 用它,它會呼叫這個工具:

在 guide 頻道,使用者請 Guide 向一個團隊問好。Guide 呼叫 hello_greet 工具,並回覆 Hello, Ada's team!

工具仍要回傳模型會讀到的文字,也可以呼叫 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)發佈,並列在變更記錄(英文)中。