CLI
這個套件安裝一個指令:roundtable。
它在 Bun 上執行,沒有 Bun 的時候,會告訴你去哪裡取得。
在專案裡,用 bunx roundtable <command> 執行。
| 指令 | 作用 |
|---|---|
roundtable init [dir] [--adapter discord|web] |
在 dir 建立專案(預設是目前的目錄),透過 Discord(預設)或網頁聊天對話。 |
roundtable doctor [--reachable] |
檢查設定,並說明有問題的地方該怎麼修。 |
roundtable start |
先跑不需要網路的檢查,再啟動 bot。 |
roundtable add plugin <name> |
加入 plugins/<name>.ts 和它的測試,並把外掛列進設定。codex-images、dice 和 release-notice 保留給官方外掛。 |
roundtable add package <spec> |
用 bun add 安裝 Pi package,並加入一個載入它、把它的工具交給每一輪 agent 的外掛。 |
roundtable upgrade [--write [--unchecked]] |
以 diff 顯示改寫成 0.9 寫法的 roundtable.config.ts(owner 與 speakers 改成 access,discord 改成 adapter);--write 在確認改寫後服務的人不變之後才寫入。 |
roundtable principal list|show|create|link|unlink|grant|revoke|disable|enable |
列出並修改資料庫裡的 principal、它們的身分與角色。 |
roundtable help 和 roundtable --help 會印出這份清單。
roundtable --version 會印出套件版本。
npx pi-roundtable init my-bot # or: bunx pi-roundtable init my-botinit 寫出一個能運作的專案,不會要你提供任何祕密資訊。
它在 dir 裡建立這些檔案:package.json、.gitignore、roundtable.config.ts、biome.json、README.md、agents.ts、docker-compose.yml、persona/shared.md、.env.example、tsconfig.json、plugins/hello.ts、plugins/hello.test.ts 和 plugins/self-compact.ts。
plugins/self-compact.ts 載入 Pi 套件 pi-self-compact,package.json 釘住它的版本:每個 session 都需要它的 compact_session 工具,沒有它 start 會停下來。
package.json 會固定在執行 init 的那個 pi-roundtable 的精確版本。
接著印出三個下一步:安裝並填寫 .env、執行 doctor、執行 start。
所有的拒絕都發生在第一次寫入之前,所以被拒絕之後,目錄維持原樣:
- 沒有 Bun,或 Bun 比套件需要的範圍還舊。
init要建立的某個檔案已經存在。訊息會列出這些檔案,並以Remove them or run init in an empty directory; nothing was written.結尾。
init 最多接受一個目錄;多給一個引數會是用法錯誤。
--adapter web
Section titled “--adapter web”npx pi-roundtable init my-desk --adapter web--adapter web 會以 pi-roundtable-webchat 為中心,寫出一個沒有 Discord 的專案。
它不寫 agents.ts 和 persona/shared.md,改寫 persona/assistant.md。
它的 roundtable.config.ts 沒有 discord,監聽 127.0.0.1:3000,並列出 webChat({ ... }):一個 OpenID Connect verifier、一份頂層的 access(由 token 角色決定 member 與 admin),以及一個在 selection 寫明工具的 persona。
它的 package.json 另外把 pi-roundtable-webchat 固定在與 core 相同的版本,.env.example 要求的是 OWNER_NAME、DATABASE_URL、MODEL、OIDC_ISSUER、OIDC_AUDIENCE、OIDC_JWKS_URL、CHAT_MEMBER_ROLES 和 CHAT_ORIGINS。
預設是 --adapter discord;其他值都是用法錯誤,錯誤訊息會列出 discord, web,而且什麼都不寫。
doctor
Section titled “doctor”doctor 依下表的順序執行每一項檢查,每一項印出一行。
它不會更動它檢查過的任何東西,只要有任何一項失敗,就以非零狀態結束。
✓ Bun: Bun 1.4.4✗ environment: no value for DISCORD_TOKEN, ... Copy .env.example to .env and fill them in; .env.example says where each one comes from.- plugins: skipped, the configuration is not valid yet通過的檢查以 ✓ 開頭,可能會附上細節。
失敗的檢查以 ✗ 開頭,寫出問題,修正方式則放在它底下縮排的幾行。
因為前面某一項失敗而無法執行的檢查,以 - 開頭並被跳過。
被跳過的檢查不會讓整次執行失敗。
| # | 檢查 | 看什麼 |
|---|---|---|
| 1 | Bun | 執行中的 Bun 版本,是否符合套件的 engines.bun 範圍。 |
| 2 | environment | .env.example 裡每個沒有註解掉的變數,在 .env 都有值。 |
| 3 | configuration | roundtable.config.ts 能載入、通過 schema,也能組裝。失敗時會指出是哪個 key。 |
| 4 | plugins | 每個外掛都能載入,沒有兩個外掛同名(包括內建的外掛),而且註冊內容有效。 |
| 5 | access | access 服務哪些人:列出 owner;主機有不只一個 surface、又寫了 everyone: true 時提出警告,因為它會讓每個 surface 上的所有人都能對話。 |
| 6 | image provider | 有沒有外掛填入 images 槽位。沒有也不算失敗,agent 的頭像是組合出來的角色,不再靠它繪製。 |
| 7 | characters | canvas 能不能把 SVG 轉成圖片;agent 伺服器畫 agent 的圖片需要它。 |
| 8 | PostgreSQL | 資料庫有回應,而且每個外掛的 migration 都能執行。migration 在一個一定會 rollback 的 transaction 裡執行,所以資料庫維持原樣。 |
| 9 | principals | 預演下次啟動會從資料庫已知的人建立哪些 principal;設定裡 owner 的身分若連到別的 principal 就判定失敗,owner 被停用時提出警告。 |
| 10 | Discord token | Discord 接受這個 bot token。 |
| 11 | Discord guild | bot 是 discord.guild 的成員。 |
| 12 | Discord intents | Message Content intent 已開啟。 |
| 13 | Discord channel | 入口頻道存在於這個 guild,而且 bot 在裡面擁有下列權限。 |
| 14 | model login | model 的 provider 有登入資料。 |
| 15 | public URL | http.publicUrl 是格式正確的 http:// 或 https:// 位址。 |
沒有 Discord 的專案會略過檢查 10 到 13,理由是 no Discord is configured;http.publicUrl 沒有值時也會略過檢查 15。寫在 adapters 裡的 Discord adapter,檢查方式與最上層的 discord 相同。
檢查 12 要求 bot 在入口頻道擁有的權限是 View Channel、Send Messages、Send Messages in Threads、Read Message History、Embed Links、Attach Files、Pin Messages、Create Public Threads、Manage Channels 和 Manage Webhooks。 bot 還不在 guild 裡的話,會給你一個邀請連結,連結已經帶好這些權限。
--reachable 旗標
Section titled “--reachable 旗標”doctor --reachable 會再向 public URL 發出請求。除非 bot 正在執行,而且發佈這個位址的通道或 proxy 正常,否則這個請求會失敗。
沒有這個旗標時,檢查 15 只確認位址的格式正確。
這是唯一的旗標,也只有 doctor 接受它;任何其他引數都是用法錯誤。
start 執行不需要網路的檢查:Bun、environment、configuration、plugins、access、image provider、characters、model login 和 public URL。
其中一項失敗時,它把和 doctor 一樣的行印到標準錯誤輸出,並在任何東西連到 Discord 之前,以代碼 1 結束。
否則就啟動 bot。
PostgreSQL 和 Discord 不會事先檢查。
資料庫位址錯誤或 token 被拒絕,會讓開機本身失敗,行程印出訊息並以代碼 1 結束。
先跑 doctor,就能連同修正方式一起找出這些問題。
收到 SIGTERM 或 SIGINT 時,bot 會先讓執行中的工作做完才停止。
它預設最多等三分鐘(設定裡的 drainSeconds);那之後仍在執行的,會寫進 log 並放棄。
啟動和停止的順序,見啟動流程與專案設定。
add plugin
Section titled “add plugin”bunx roundtable add plugin my-notesadd plugin 用 hello 範本建立 plugins/my-notes.ts 和 plugins/my-notes.test.ts,在 roundtable.config.ts 裡 import 這個外掛,並把它列進 plugins。
有三個名稱保留給官方外掛:codex-images、dice 和 release-notice。
用這三個名稱時,add plugin 複製的是現成的外掛和它的測試,不用 hello 範本,註冊方式相同:
bunx roundtable add plugin dicebunx roundtable add plugin release-notice其他任何合法的名稱,都維持使用 hello 範本,所以像 dice-roller 這樣的名稱,建出來的是範本外掛。
用法說明裡列出了保留的名稱。
它先檢查並產生好所有內容,才會寫入,所以被拒絕之後,專案維持原樣。 下列情況它會拒絕:
- 名稱不是用連字號連起來的小寫單字,例如
my-notes。 - 目前的目錄裡沒有
roundtable.config.ts。 plugins/<name>.ts或它的測試已經存在。- 設定檔無法解析、找不到它能用的
plugins清單,或這個名稱已經被拿去做別的用途。訊息會說明要手動加入什麼。
這個指令剛好接受一個名稱;其他情況會印出 usage: roundtable add plugin <name>, or roundtable add package <spec>。
add package
Section titled “add package”bunx roundtable add package pi-web-accessadd package 從 npm 安裝一個 Pi package,並寫好使用它的外掛。
它會執行 bun add <spec>,載入套件的擴充,找出它們註冊的工具,再寫出 plugins/<name>.ts 和 plugins/<name>.test.ts。檔名取套件名稱去掉 scope 的部分,所以 @scope/pi-notes 會變成 plugins/pi-notes.ts。
接著和 add plugin 一樣,在 roundtable.config.ts 裡 import 這個外掛,並把它列進 plugins。
外掛把套件列在 piPackages,所以每個對話 session 都會載入它。
工具列在 agentSelection,因為每一輪只會用到被選用的工具;也列在 requiredTools,套件改版拿掉某個工具時,啟動就會失敗。
它不替任何工具指定 tier:沒有其他外掛指定 tier 的工具只有 owner 能用,要開放就在 roundtable.config.ts 的 toolTiers 調低。
指令會印出它找到的工具。
spec 是 registry 上的名稱,可以帶 scope,也可以帶版本或 tag:pi-web-access、pi-web-access@0.35.0、@scope/name。
下列情況它會在安裝之前拒絕,專案維持原樣:
- spec 不是 registry 名稱,例如 git URL 或本機路徑;或是名稱去掉 scope 之後,不是用連字號連起來的小寫單字。
- 目前的目錄裡沒有
roundtable.config.ts。 plugins/<name>.ts或它的測試已經存在。- 設定檔無法解析、找不到它能用的
plugins清單,或外掛的名稱已經被拿去做別的用途。
每個拒絕訊息都會說明怎麼手動做:用 bun add 安裝,再把套件列進某個外掛的 piPackages。
安裝之後,如果 bun add 失敗、套件的 package.json 沒有在 pi 底下列出擴充又沒有 extensions 資料夾,或有擴充載入失敗,它不會寫出外掛,並告訴你要執行的 bun remove 指令。
它只找得到擴充在載入時註冊的工具;晚一點才註冊的工具,例如連線之後才出現的,要手動加進清單。
upgrade
Section titled “upgrade”bunx roundtable upgradebunx roundtable upgrade --writeupgrade 以 diff 印出改寫成 0.9 寫法的 roundtable.config.ts:owner 與 speakers 改成 access,discord 改成 adapter。
沒有 --write 時它不會改任何東西。
--write 會先確認改寫後的設定服務的人不變,這需要主機執行時的環境變數;無法確認時就拒絕寫入。
--write --unchecked 不做這項確認直接寫入,並印出警告。
principal
Section titled “principal”bunx roundtable principal listbunx roundtable principal create --name Adabunx roundtable principal link <principal> discord:<user id>bunx roundtable principal grant <principal> adminprincipal 在資料庫裡列出並修改主機服務的人:list、show <principal>、create --name <name> [--pronouns he|she|they]、link <principal> <provider>:<subject>、unlink <provider>:<subject>、grant 與 revoke <principal> member|admin|owner,以及 disable 與 enable <principal>。
<principal> 可以是 principal id,或連到它的某個身分。
list 印出的身分寫法,與 roundtable.config.ts 的 access 接受的寫法相同。
執行中的主機在 30 秒內看到變更;之後才啟動的主機立刻看到。
| 代碼 | 時機 |
|---|---|
0 |
指令成功:init、add plugin 和 add package 寫出了檔案、doctor 的每項檢查都通過或被跳過、help 和 --version 印出了內容,或 bot 正常停止。 |
1 |
指令被拒絕或失敗、doctor 有檢查失敗、有檢查讓 start 停下來、引數錯誤、指令不存在,或沒有給指令(會印出用法說明)。 |
用法錯誤會先印出訊息,再印出用法說明。
bot 被信號停止時,如果有 listener、服務或資料庫連線池沒能停下來,結束碼是 1,否則是 0。
檢查印出的訊息和修正方式,見錯誤與修正。