官方外掛與套件
pi-roundtable 附了三個外掛,用複製的方式放進你的專案,不用安裝。 複製出來的就是你自己的一般外掛檔案,可以讀、可以改,也可以刪。
| 外掛 | 作用 |
|---|---|
codex-images |
用提示詞和參考圖,透過你的 ChatGPT 訂閱登入,畫出 agent 的頭像。 |
dice |
給 agent 一個 roll_dice 工具。 |
release-notice |
部署後公告新版本包含的 commit,以及上次關機時被中斷工作的頻道。 |
在你的專案裡,用外掛的名稱執行 add plugin:
bunx roundtable add plugin dicebunx roundtable add plugin codex-imagesbunx roundtable add plugin release-notice每個指令都會寫出 plugins/<name>.ts 和 plugins/<name>.test.ts,在 roundtable.config.ts 裡 import 這個外掛,並把它列進 plugins。
這三個名稱是保留的:用它們時,add plugin 複製的是官方外掛;其他名稱則維持使用 hello 範本。
任何一個檔案已經存在時,它會拒絕,而且什麼都不寫。
add plugin 檢查的所有項目,見 CLI。
然後在你的專案裡跑測試:
bun testdice 新增一個工具 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
Section titled “codex-images”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
Section titled “release-notice”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 pipefailprevious=$(cat data/announced-release 2>/dev/null || true)commits='[]'if [ -n "$previous" ]; then commits=$(git log --format=%s "$previous..HEAD" | jq -R . | jq -s .)fiprintf '{"sha":"%s","commits":%s}\n' "$(git rev-parse --short HEAD)" "$commits" > release.json外掛會在 ./data 記錄已公告的版本(announced-release),以及上次關機時中斷工作的頻道(aborted-on-shutdown.json)。
只有成功發出公告後才會記錄版本。
發送失敗時,下次啟動會再試一次。
如果 release.json 格式錯誤,例如 sha 是空值,log 會指出檔案路徑,但不會發公告。
修改複製出來的檔案
Section titled “修改複製出來的檔案”複製出來的檔案在你的專案裡,所以和任何外掛一樣直接改。
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、聊天室允許清單、唯一的消費者,以及帶寄件人名稱、重試金鑰和額度檢查的推播。 |