跳到內容

官方外掛與套件

pi-roundtable 附了三個外掛,用複製的方式放進你的專案,不用安裝。 複製出來的就是你自己的一般外掛檔案,可以讀、可以改,也可以刪。

外掛 作用
codex-images 用提示詞和參考圖,透過你的 ChatGPT 訂閱登入,畫出 agent 的頭像。
dice 給 agent 一個 roll_dice 工具。
release-notice 部署後公告新版本包含的 commit,以及上次關機時被中斷工作的頻道。

在你的專案裡,用外掛的名稱執行 add plugin:

終端機視窗
bunx roundtable add plugin dice
bunx roundtable add plugin codex-images
bunx roundtable add plugin release-notice

每個指令都會寫出 plugins/<name>.ts 和 plugins/<name>.test.ts,在 roundtable.config.ts 裡 import 這個外掛,並把它列進 plugins。 這三個名稱是保留的:用它們時,add plugin 複製的是官方外掛;其他名稱則維持使用 hello 範本。 任何一個檔案已經存在時,它會拒絕,而且什麼都不寫。 add plugin 檢查的所有項目,見 CLI。

然後在你的專案裡跑測試:

終端機視窗
bun test

dice 新增一個工具 roll_dice,member 以上的人都能呼叫。 它接受一個算式,用純文字回答:

2d6+3: [3, 5] + 3 = 11

你可以在傳給 agent 的訊息裡要它擲骰,例如「擲 4d6,去掉最小的。」 agent 會呼叫這個工具,再把結果回報給你。

寫法 意思
2d6、d20 擲指定顆數、指定面數的骰子。
+3、-1 加或減一個數字。
2d6+1d4-1 一個算式裡有好幾組。
4d6k3、4d6kh3 保留最大的 3 顆。
4d6kl1 保留最小的 1 顆。
4d6d1、4d6dl1 去掉最小的 1 顆。
4d6dh1 去掉最大的 1 顆。
dF、3dF Fate 骰,每顆是 -1、0 或 +1。沒寫顆數時擲 4 顆。

被去掉的骰子顯示在括號裡,例如 4d6k3: [5, (1), 6, 3] = 14。 超出上限或讀不懂的算式會被拒絕,訊息會說明要修正什麼,agent 可以再試一次。 上限是:全部 100 顆骰子、一顆骰子 1000 面、算式 200 個字元,單一數字 1000000。

dice 不需要登入,也不需要任何設定。 它的複製式來源範本實作了這個工具。

codex-images 填入 images 槽位,也就是核心用來畫圖的那個部分。 它供 generate_image 使用;0.23 起 agent 自己的頭像是組合出來的角色,不再經過它。 roundtable doctor 會回報有沒有外掛填入這個槽位。 它的複製式來源範本是一個很短的檔案:用 pi-roundtable/kit 的 createCodexImages 建出外掛,畫圖則由 kit 的 drawCodexImage 負責。 通訊協定的修正會隨套件升級而來,不必重新複製。

它需要登入 openai-codex provider,登入機制和 agent 登入模型時用的相同。 host 沒有登入時,外掛會拒絕啟動,訊息會說要登入 openai-codex。 外掛每次畫圖都會重新讀取登入資料,所以更新過的 token 會被用到。 傳入 createCodexImages({ onMissingLogin: "warn" }),沒有登入的 host 也能啟動:setup 只記一則警告,之後畫圖時才用同樣的錯誤失敗。

Codex 拒絕的請求(通常是提示詞的問題)會以 ImageNotGeneratedError 失敗,同一個提示詞再問一次還是一樣。 畫圖會隨提出要求的那個 turn 一起中止。 一個請求有五分鐘的時間限制,超過 32 MiB 的回應會被拒絕。 模型名稱只用來導向請求,影像模型由後端自己挑;它是 kit 的 CODEX_IMAGE_MODEL,用 createCodexImages({ model }) 可以更改。 0.19.0 之前複製的檔案帶著完整的客戶端,照原樣繼續運作,但沒有中止和大小限制,要重新複製範本才會有。

release-notice 會在部署後公告版本資訊。 它的複製式來源範本實作公告和關機追蹤。 agent server 的頻道都啟動後,它最多公告一次,訊息會發在 coordinator 頻道:

  • 執行中的版本和上次公告的版本不同時,它會列出新的 sha 和這次 release 包含的 commit。
  • 上次關機若中斷了工作,訊息也會列出受影響的頻道。 關機預設最多等三分鐘(drainSeconds)讓工作完成,之後才放棄。
  • 同一個版本重新啟動、沒有中斷工作時不會公告。 沒有 release.json 時也不會公告。

啟動 bot 前,deploy 必須先在 bot 執行目錄寫入 release.json。 檔案記錄 release 的 commit,以及從上次公告版本到這次新增的 commit subject,依新到舊排列。 這樣即使上次公告失敗或根本沒執行,也不會跳過未公告的版本:

{ "sha": "abc1234", "commits": ["fix: handle an empty reply", "feat: add a notes tool"] }

外掛會把上次公告的 sha 存在 data/announced-release,同一台 host 上的 deploy script 可用它作為比較起點。 下列 script 遇到 git log 或 jq 失敗時會停止 deploy。 第一次部署還沒有公告紀錄,commits 會是空陣列:

終端機視窗
set -euo pipefail
previous=$(cat data/announced-release 2>/dev/null || true)
commits='[]'
if [ -n "$previous" ]; then
commits=$(git log --format=%s "$previous..HEAD" | jq -R . | jq -s .)
fi
printf '{"sha":"%s","commits":%s}\n' "$(git rev-parse --short HEAD)" "$commits" > release.json

外掛會在 ./data 記錄已公告的版本(announced-release),以及上次關機時中斷工作的頻道(aborted-on-shutdown.json)。 只有成功發出公告後才會記錄版本。 發送失敗時,下次啟動會再試一次。 如果 release.json 格式錯誤,例如 sha 是空值,log 會指出檔案路徑,但不會發公告。

複製出來的檔案在你的專案裡,所以和任何外掛一樣直接改。

  • plugins/dice.ts 的上限是檔案開頭的常數,工具的描述也把這些上限告訴模型,所以兩處要一起改。
  • plugins/codex-images.ts 裡,負責轉送請求的模型是一個常數。
  • plugins/release-notice.ts 匯出 createReleaseNotice({ releaseFile, dataDir, announce })。 設定中的 dataDir 不是 ./data 時,傳入 dataDir;deploy 把檔案寫到其他位置時,傳入 releaseFile;要公告到 coordinator 頻道以外的位置,傳入 announce。 設定檔要列出這個函式的回傳值,取代 releaseNotice。 公告文字由 noticeText 函式產生。
  • 每個檔案都匯出建立函式(createDice、createCodexImages、createReleaseNotice),以及設定檔直接使用的現成外掛(dice、codexImages、releaseNotice)。 建立函式可注入測試替換的亂數來源、fetch,或 release-notice 讀取與發送通知的位置。
  • 測試都能離線執行:dice 使用假的亂數來源,codex-images 使用假的 fetch,release-notice 使用暫存目錄和自己的 announce。 修改外掛後,讓這些測試繼續通過。

要移除,就刪掉它的兩個檔案,以及 roundtable.config.ts 裡的項目。

官方套件都可用 bun add 安裝,並與 core 使用相同的 lockstep 版本。 每個套件都需要相同 minor 版本的 pi-roundtable。

套件 功能
pi-roundtable-drawing 在本機繪製人物關係圖、符號、幾何圖形和牌陣。
pi-roundtable-coding 透過獨立的 Pi coding worker 提供 repository 工具。
pi-roundtable-web owner app:跟 agent 團隊對話的房間、核准卡、yolo 與長時間執行模式、可安裝並推播的 PWA,以及查看對話、團隊狀態和 memory note 的 console。
pi-roundtable-sandbox 在 Linux Docker 隔離環境中執行 guest-only Discord 頻道。
pi-roundtable-mcp 管理 MCP connector,並提供 remote MCP 存取。
pi-roundtable-browser 給 agent 的瀏覽器 worker:browser_task 在連不到 host 私有網路的 Docker container 裡操作 agent-browser。
pi-roundtable-webchat 讓經 OpenID Connect 供應商登入的人用網頁聊天,有私人對話、即時進度和核准卡。
pi-roundtable-line LINE Messaging API 傳輸層:簽章驗證的 webhook、聊天室允許清單、唯一的消費者,以及帶寄件人名稱、重試金鑰和額度檢查的推播。

外掛在這之外還能新增什麼,見外掛能新增什麼;想寫這樣的測試,見測試外掛。