跳到內容

設定總覽

roundtable.config.ts 放設定和外掛清單。 它用 export default { ... } satisfies RoundtableConfig 匯出一個物件。 不在這一頁的鍵會報錯,並指出最接近的已知鍵:

config <key>: unknown key. Did you mean "<closest>"? The keys here are ...

缺少必填的鍵,或值的種類不對,roundtable doctor 和 roundtable start 都會停下來,並指出是哪個鍵。 下面標了必填的鍵,值都必須是非空字串。

roundtable init 建立的專案,會透過一個小小的 env 輔助函式,從 .env 讀取憑證和 id,檔案裡沒有任何機密。 每個值從哪裡來,見環境變數。

import type { RoundtableConfig } from "pi-roundtable";
import { agents } from "./agents.ts";
import { hello } from "./plugins/hello.ts";
import { selfCompact } from "./plugins/self-compact.ts";
// Credentials and ids come from .env, which Bun loads on its own; nothing secret belongs in this file.
const env = (name: string): string => process.env[name] ?? "";
export default {
name: "Roundtable",
access: {
owners: [
{
name: env("OWNER_NAME"),
principal: env("OWNER_ID"),
identities: [`discord:${env("OWNER_ID")}`],
},
],
},
discord: {
token: env("DISCORD_TOKEN"),
guild: env("DISCORD_GUILD_ID"),
entryChannel: env("DISCORD_ENTRY_CHANNEL_ID"),
},
database: { url: env("DATABASE_URL") },
// Paths are relative to the project directory, where the roundtable command runs.
dataDir: "./data",
model: env("MODEL"),
http: { publicUrl: env("PUBLIC_URL") },
prompts: { shared: "./persona/shared.md" },
agents,
plugins: [selfCompact, hello],
} satisfies RoundtableConfig;
鍵 型別 預設值 作用
name string "Roundtable" bot 所顯示文字裡,主騎士的顯示名稱。

不設 discord,host 就在沒有 Discord 的情況下執行:沒有 Discord 外掛;沒有 agents 時也沒有 agent server 和技能,但外掛透過 context.turns 執行的對話照常運作。 設了 agents,團隊就在支援房間的 surface(例如網頁主控台)裡運作,沒有任何 surface 支援房間時 host 拒絕啟動;見 agent 與頭像。 roundtable init --adapter web 會以網頁聊天為中心建立這種專案。 同樣的設定也可以寫成 adapter:adapters: [discord({ ... })],其中 discord 來自 pi-roundtable/discord。Discord 只能在其中一處設定,不能兩處都設。

鍵 型別 預設值 作用
discord.token string,使用 Discord 時必填 無 bot token。放在 .env。
discord.guild string 無 agent 伺服器的 guild id,agent 的頻道、分類與 #dashboard 都在這裡。不設時,Discord 仍在 bot 加入的每個伺服器服務外掛的 claim、斜線指令與主人的私訊,團隊則像沒有 Discord 時一樣住在 app 的房間:必須設 agents(agentServer 為 false 時除外),由 coordinator 指定協調者,http.publicUrl 變成選填。
discord.entryChannel string,有 discord.guild 時必填,agentServer 為 false 時除外 無 協調者所在頻道的 id。沒有 discord.guild 時設它會出現 ConfigError。
discord.rootCommand string 小寫的 name,其中每一段 a-z、0-9、- 以外的字元換成 - 根斜線指令,不含斜線。見斜線指令。
discord.admin boolean true owner 的對話是否有 discord_* 管理工具。設成 false 會讓 discord-admin addon 不載入。
discord.refusalHint string 無 附加在根指令拒絕非 owner 時的訊息後面的文字,原樣加上。你的語言需要的空格或標點,要自己放進去。
discord.agentMemory "everyone" 或 "owners" "everyone" "owners" 只讓 agent 頻道裡 owner 層級的回合有記憶區塊和記憶工具。
discord.agentSpeakers "everyone" 或 "owners" "everyone" "owners" 只讓 owner 層級的 speaker 能在 agent 和群組頻道開始一輪;admin 或 member 在 Discord 獲准、而這項沒設時,doctor 會警告。
discord.channelContext 物件,或 false {} 一輪會讀進多少被呼叫的訊息周圍的頻道內容:fetch(預設 50,最多 100)、keep(15)、similarity(0.8)、messageChars(500)、botMessageChars(80)、peerMessageChars(4000,用於 discord.peerBots 列出的 bot)、starter(false;true 時討論串的第一則訊息一律納入)、conversation(只能用程式碼設定;指出一輪屬於哪段對話,讓討論串裡第二個發問的人也拿得到前一個人那輪已讀過的內容)、foreignWebhook(只能用程式碼設定)、authors(只能用程式碼設定)和 attachments({ images: 0, maxBytes: 10 MiB })。false 關閉。
discord.peerBots { allow, maxRounds? } 無 host 會回應的其他 bot,讓不同的 bot 能互相對話:allow 列出它們的使用者 id,每項是字串或 { id, guilds?, channels?, yields? }。設 yields: true 時,有人在同一則訊息裡提及或回覆 host 和那個 bot(在該項列出的範圍內),host 就讓給它:只有那個 bot 回答,它可以再提及 host 交棒;只在其中一邊設定。只接受明確的 id,沒有萬用字元,也沒有「所有 bot」;id 不對會讓啟動失敗。名單內 bot 的提及或回覆會像訪客一樣被回應,能用到什麼程度由 access 對它的身分(discord:<id>)決定;bot 持有的 Discord 身分組不會被讀取。maxRounds(預設 3)是同一頻道連續回應它們訊息的次數,有人說話就重新計算。不設就忽略所有 bot。
discord.freshMarker string,或 false ─── new conversation ─── 在伺服器頻道或討論串重新開始對話時,主騎士貼出的分隔線。false 不貼。
discord.memberEvents boolean false 向 Discord 要求特權的 Server Members intent,讓外掛能聽到有人加入伺服器(memberJoined 事件)。要先在 Developer Portal 的 Bot 頁面打開 Server Members Intent,否則連線會被拒;roundtable doctor 會檢查。
discord.voice boolean false 讓外掛透過 DISCORD.voice 加入伺服器的語音頻道,分別聽到每個人說的話,例如記錄會議的外掛。bot 會向 Discord 要求 Guild Voice States intent(不是特權 intent,不必到 Developer Portal 設定),並在啟動時載入語音套件。bot 在要加入的頻道需要「檢視頻道」和「連接」權限。
discord.formatting string,或 false Markdown 會轉成排版,表格除外 以英文告訴模型回覆在 Discord 裡怎麼呈現。false 不告訴模型任何事。
discord.cardGraceSeconds 1 到 86400 的整數 120 一輪為了核准卡或 ask_user 卡片等多久,之後這一輪結束、卡片繼續開著。
discord.cardCopies { keepDays?, keep? },或 false 30 天、最新 100 張 核准卡「複製」按鈕背後的文字,在資料目錄的 card-copies.json 保留多久。agent 對講卡片的全文也照這個設定,保留最新 300 張,存在 intercom-texts.json。false 只留在記憶體。
discord.attachmentDownload { deadlineMs?, idleMs? } 60000 與 10000 一則訊息(連同它回覆的那則)的附件要在多久內下載完,以及單一檔案多久沒收到任何位元組就放棄。各為 1000 到 600000。
agentServer false agent server 照常執行 false 讓有 discord 的 host 不跑 agent server:沒有 agent 團隊、沒有 #dashboard 頻道與置頂訊息、沒有 agent 頻道與路由、沒有協調者,也沒有技能 addon。Discord、存取、記憶、指令與外掛的 claim 照常運作。discord.entryChannel、http.publicUrl 與 discord.guild 都變成選填。與 agents、skills、ops.agent、discord.agentMemory、discord.agentSpeakers、discord.attachmentDownload 同時設定會出現指名兩個鍵的 ConfigError;需要 agent server 的外掛(網頁主控台的 agents 與 rooms 面板、remote-mcp 的預設對話)會讓啟動中止。doctor 會回報 agent server 已關閉,並略過入口頻道檢查。沒有 true;要保留 agent server 就不要寫這個鍵。
adapters adapter 的清單 無 host 使用的聊天管道,各由自己的工廠函式產生。Discord adapter 接受上面這些 discord 設定。以外掛形式提供的聊天管道(例如網頁聊天)仍放在 plugins。
鍵 型別 預設值 作用
database.url string,必填 無 PostgreSQL 連線 URL。
dataDir string,必填 無 行程存放檔案的位置,例如圖片、附件和技能。
workDir string <dataDir>/work agent 共用的工作目錄。
agentDir string <dataDir>/pi Pi 的 agent 目錄,放模型登入。見模型。
scratchDir string <作業系統暫存目錄>/<slug>-scratch,slug 是 discord.rootCommand,沒有 Discord 時是小寫的 name agent 的暫存目錄:它們的 shell 以 TMPDIR 指向這裡,在裡面寫入和刪除不需要核准。
shellEnv { pass?: string[], set?: Record<string, string> } 無 agent 的 shell 除了 PATH、HOME、USER、LOGNAME、SHELL、語系(LANG、LANGUAGE、LC_*)、TZ、TERM、TMPDIR、proxy 與憑證變數之外,還能拿到哪些 host 環境變數:pass 列出更多 host 變數名稱,例如讓 shell 裡的 gh 與 git push 能用的 GH_TOKEN(沒給就一個都不給);set 給固定值。其他 host 變數,不論是不是祕密,都不會進到 shell。
attachments.retention { maxAgeMs, sweepEveryMs? } 無 檔案被某一輪用過、滿 maxAgeMs 之後就移除,並在啟動時以及每隔 sweepEveryMs(預設一小時)清一次。沒設的話,用過的檔案跟著它的對話保留。
conversations.keepDays 以對話種類為鍵、值為整數天數的物件 無 每天掃一次,刪除所列種類中、最後活動已超過天數的已記錄對話。沒列出的種類一律保留。
conversations.keep 由對話紀錄回傳 true 或 false 的函式 無 掃描要刪除某則對話前會先問它;回傳 true 就暫時保留(例如客服單還沒結案的對話),下次掃描會再問一次。函式丟出錯誤時對話會被保留並記進日誌。
鍵 型別 預設值 作用
model string,必填 無 agent 使用的模型,寫成 <provider>/<id>。
thinking "off"、"minimal"、"low"、"medium"、"high" 或 "xhigh" "medium" judge 無法挑出等級時,一輪使用的等級。
judge.model string model 的值 判斷小問題的模型。
judge.threshold 0 到 1 的數字 0.6 judge 要多有把握,它的答案才會被採用。
delegation.model string model 的值 執行委派任務的模型。
delegation.thinking 跟 thinking 相同的等級 "medium" 委派任務的 thinking level。
effortPolicy 從一輪映射到它的 effort 規則的函式 無 取代預設做法,決定由 judge 挑選 thinking 等級的每一輪怎麼判斷。只能用程式碼設定。

每一項的說明見模型。

鍵 型別 預設值 作用
locale "en" 或 "zh-TW" "en" bot 在 Discord 裡所顯示文字的語言。
timeZone string "UTC" 排程和時間戳記使用的 IANA 時區。

見語言與時間。

鍵 型別 預設值 作用
access.owners { name, pronouns?, principal?, identities? } 的清單,必填 無 經營這個 host 的人。第一位是主要 owner,需要 principal(他的 principal id,用他的 Discord 使用者 id 即可);使用 Discord 時還要有一個 discord:<user id> 身分。pronouns 是 "he"、"she" 或 "they"(預設 "they"),提示詞回頭提到 owner 時使用。
access.admins、access.members { identities?, roles?, everyone? } 無 誰擁有這個層級。identities 是 <provider>:<subject> 字串,例如 discord:<user id>。roles 寫成 <surface>:role:<name>,例如 discord:role:<role id>。everyone 是 true(所有 surface),或 surface 的清單。
access.provisioning "admitted"、"linked",或依 surface 列出這兩者的物件 "admitted" admitted:規則放行的人在第一次說話時得到 principal。linked:只服務用 roundtable principal link 連結的身分,以及 owner 設定裡的身分。物件裡沒列的 surface 視為 linked。
access.backgroundStaleDays 1 到 36500 的整數 30 層級只來自規則的人,最多可以多少天沒出現,超過後他的背景回合會被拒絕。
access.selfLink.providers string 清單 無 允許人們透過外掛把自己的帳號連到自己 principal 的身分提供者,例如 ["discord"]。
owner、speakers 0.8 的寫法 無 已棄用:owner: { id, name, pronouns? } 和以 Discord 使用者與身分組 id 寫的 speakers: { admins?, members? }。它們仍可使用,但會印出警告,也不能和 access 同時出現;roundtable upgrade 會把它們改寫掉。
background.perPrincipal { schedules?, delegations? } 無 每個人跨所有對話的上限:最多保留幾個排程(1 到 10000),以及同時執行幾個委派(1 到 1000)。沒設的話,只套用各對話自己的上限。
toolTiers 以工具名稱為鍵、值為 "owner"、"admin" 或 "member" 的物件 {} 每個指定工具最低需要的層級。它會蓋過核心和外掛原本決定的層級。
prompts.shared string,在 prompts 裡必填 套件附帶的提示詞 檔案路徑,這份檔案是每個 agent 提示詞的開頭。啟動時讀一次。
prompts.guest string 套件附帶的 guest prompt 檔案路徑,對 owner 以外的說話者,這份檔案取代共用提示詞。

沒有 admins 或 members 時,只有 owner 能跟 agent 說話。 見存取層級。

鍵 型別 預設值 作用
agents { name, displayName, prompt, character?, channelId? } 的清單 [] 第一批團隊,只建立一次。已經存下來的 agent 不會被覆寫,所以之後請在 Discord 裡修改 agent。沒有 Discord 時,種子 agent 沒有 channelId。
coordinator string agents 的第一位 沒有 Discord 或 discord.guild 時,接手主人一般請求的 agent;必須是 agents 之一,也不能被封存。有 discord.guild 時設它會出錯,因為 discord.entryChannel 裡的 agent 就是協調者。
team.id string discord.guild 的 id,否則 local 團隊的資料列(agent、群組、技能、提示詞、預設組)存放時用的 id,與 Discord guild 無關。設定後請不要再改。
team.formerIds string[] 無 團隊先前存放時用過的 id,例如已離開的 guild。每次啟動時,這些 id 的資料列會搬到團隊的 id(團隊已有的同名資料列不動);沒有 Discord 頻道時,搬過來的 agent 與群組會清掉原本帶的頻道 id,不再往已刪除的頻道發訊。
characters.skins 剛好 6 個 #rrggbb 顏色的清單 套件附帶的六個 所有 agent 角色使用的膚色,由角色的 skin 索引(0 到 5)挑選:網頁主控台、圓桌與 agent 在 Discord 的圖片都會套用。pi-roundtable/characters 的 EAST_ASIAN_SKINS 是一組現成的亞洲淺膚色。agent 保留已存的索引,換色不需要遷移。清單長度不對或顏色格式錯誤會讓啟動失敗。
characters.refreshAvatars boolean false 每次 agent server 啟動時,用主機的膚色把每個 agent 在 Discord 的圖片重新畫一次,圖片不同才換上。適合在角色改版或更換 characters.skins 後,讓沒人儲存過的 agent 追上網頁主控台的樣子。它在啟動後於背景執行、不拖慢啟動,圖片沒變的 agent 會略過,並記錄一行摘要(重畫、未變、失敗各幾個);單一 agent 失敗不影響其他。仍用舊手繪圖片的 agent 會被覆蓋。
avatar string 套件附帶的一張簡單 bot 圖片 0.23 起已棄用且被忽略:agent 是組合出來的角色。設了它啟動時會記一則警告,1.0 移除。
http.publicUrl string,使用 Discord 時必填,agentServer 為 false 時除外 無 能從網際網路連到這個行程的位址。Discord 從這裡取頭像。
http.port 1 到 65535 的整數 3000 行程監聽的 TCP port。
http.hostname string 無 監聽綁定的 hostname。
http.socketPath string 無 監聽用的 unix socket 路徑,取代 TCP port。設定後,port 和 hostname 就不使用。
http.socketMode 0 到 0o777 的整數 0o660 socket 檔案的權限位元。只有在以其他使用者身分執行的 proxy 需要時才放寬。

沒有 Discord 時,http 可以不設:沒有外掛提供 HTTP 時就省略,host 不會開 listener。 網頁聊天需要它。

agent 做的大部分事都由一個人開頭,並在那個人所在的地方結束:訊息在它來的那段對話裡被回覆,卡片在那裡等,排程在建立它的對話裡觸發。選填的 routing 只管沒有人在場的事:外部 webhook 在 agent 的 place 裡的貼文、沒指定對話的 message_agent 呼叫、agent 的開場任務,以及行程自己的錯誤回報。不寫 routing,這些事都落在這個鍵出現之前原本的地方。

這裡與程式碼用到的詞:

  • Surface:一個聊天轉接器,用它的 key 前綴命名:discord、app(pi-roundtable-web)、webchat、line。一個 host 可以有好幾個。
  • Place:agent 在某個 surface 上的對話:在 Discord 是它的頻道,在有 room 的 surface 是它的 room <surface>:agent.<name>。剛好只有一個 surface 有 room 時,web 就代表它。
  • Primary place:agent 主動做的工作落地的唯一地方。除非你指定 surface,否則是 auto:有 Discord 頻道就用它,沒有就用第一個有 room 的 surface 上的 room。
  • Named place:host 層級、有名字的目的地。core 宣告了 ops(錯誤回報);它可以是一個對話 key,也可以是某個 agent 的 primary place。
  • Mirror(保留):會收到 agent 在 primary place 所貼內容的唯讀副本的 place。Answerer(保留):回答某個 surface 對話的 claim。兩者在區塊裡都有位置,但都還沒做:設了就會讓啟動中止並指出該鍵。誰回答仍由 claim 的優先序決定。
鍵 值 預設值 它決定什麼
routing.agents.<name>.primary auto,或 surface 名稱 auto agent 的 primary place。用 "*" 取代名稱就是所有 agent 的預設;agent 自己的鍵逐鍵優先。名稱對之後才建立的 agent 一樣適用。
routing.agents.<name>.integration origin、primary,或 surface 名稱 origin 外部 webhook 在 agent 頻道的貼文,它的回報那一輪在哪裡跑。貼文本身留在原處;那一輪會寫出它來自哪個 place。目的地已經不在時,那一輪改在貼文發出的地方跑並記一則警告,絕不丟棄。
routing.agents.<name>.agentMessage origin-surface、latest、primary,或 surface 名稱 origin-surface 呼叫沒指定對話時 message_agent 送到哪。origin-surface 是 agent 在寄件者所在 surface 上的位置(從 room 發出就是它的 room,從 Discord 發出就是它的 Discord 頻道);沒有時退到 primary place,並記一筆 log。latest 是 agent 上次跑回合的那一段,但只限寄件者所在的 surface,否則同 origin-surface。primary 把訊息固定送到 primary place,即使是從 room 送進 Discord。呼叫裡明確指定對話,勝過所有規則。
routing.agents.<name>.opening origin-surface、primary origin-surface agent 的開場任務(agent_create 的 task)在哪裡跑:agent 在建立請求來源 surface 上的 place,沒有就用它的 primary place;或一律用它的 primary place。
routing.agents.<name>.mirror surface 名稱的清單 無 保留;非空清單會讓啟動中止。
routing.places.ops "<surface>:<id>",或 { agent } 無 行程自己的錯誤回報送到哪,和 ops.conversation、ops.agent 一樣。agent 的寫法會落在該 agent 的 primary place,要有 agent server,但不必有 Discord。最上層的 ops 是已棄用的別名,1.0 會移除;兩者只能設一個。
routing.surfaces.<name>.agentPlaces all all 這個 surface 上是否每個 agent 都有 place;目前每個 surface 都是。none 是保留值,會讓啟動中止。
routing.surfaces.<name>.answeredBy claim 名稱 無 保留;設了會讓啟動中止。

警報在網頁 app 處理、原始貼文留在 Discord:Infra 的 primary place 是它的網頁 room,它的 webhook 回報在那裡跑,host 的錯誤回報也落在那裡。其他 agent 照舊留在 Discord。

routing: {
agents: { infra: { primary: "app", integration: "primary" } },
places: { ops: { agent: "infra" } },
},

不以 Discord 為中心的 host(例如客戶走 LINE、員工用 Slack 的客服台)可以讓每個 agent 都進網頁 room,其餘用對話 key 指名:

routing: {
agents: {
"*": { primary: "app" },
triage: { integration: "primary", agentMessage: "primary" },
},
places: { ops: "slack:C0OPS" },
},

每個錯誤都會讓啟動以 ConfigError 中止,並指出鍵與修法:

  • primary、integration 或 agentMessage 寫了沒有外掛註冊的 surface,或一個不放 agent place 的 surface(沒有 room 的 surface,或 agent 沒有 Discord 頻道時的 discord);訊息會列出已註冊的 surface。這項在每個外掛都註冊完自己的 surface 之後才檢查;
  • 屬於別的鍵的值,例如 integration 寫 latest,或 agentMessage 寫 origin;
  • 不是 agent 名稱也不是 "*" 的 agent 鍵,以及沒有人宣告的 places 名稱(訊息會列出已宣告的名稱);
  • 既不是對話 key <surface>:<id> 也不是 { agent } 的 place;
  • 最上層的 ops 和 routing.places.ops 同時設定;
  • 在沒有 agent server 的 host 上設了 routing.agents、routing.surfaces 或 agent 的 place;
  • 上面的保留鍵。

規則裡寫了、但團隊還沒有的 agent,只會在 log 裡出現警告:它存在之後規則就生效。程式用 AGENTS.routes 讀這張表(primary、placeOn、of、place)。

鍵 型別 預設值 作用
skills false,或 { builtinDir?, reposDir?, packages? } 開啟,builtinDir 是套件附帶的技能,reposDir 是 <dataDir>/repos false 會讓 skills addon 不載入:agent 不帶技能,也沒有技能工具。已存的技能仍留在資料表裡。packages 列出主機安裝的 npm 套件:它們 pi.skills 資料夾裡的每個技能都會以唯讀方式提供,可以像其他技能一樣被帶著、放進群組。套件沒裝、套件沒有技能,或技能名稱和別的技能重複時,啟動會失敗,訊息會指出該怎麼改。
memory boolean true false 會讓 memory addon 不載入:沒有記憶工具,也沒有記憶的提示詞區塊。資料表維持原樣。
ops.agent string 無 routing.places.ops: { agent } 的已棄用別名,1.0 移除。負責調查行程自身錯誤的 agent 名稱。需要 Discord。
ops.conversation string 無 routing.places.ops: "<surface>:<id>" 的已棄用別名,1.0 移除。不交給 agent,而是回報到一段對話,寫它的 key <surface>:<id>。這段對話要有 chat surface 服務、要由一個接收背景回合的外掛 claim 擁有,還要有外掛提供 owner 背景目標(有 Discord 時由 agent server 提供),否則 host 不會啟動;網頁聊天不接收錯誤回報。ops.agent 和 ops.conversation 擇一設定。
drainSeconds 1 到 3600 的整數 180 關機時,等執行中的回合多少秒才把它們停掉。給服務管理員(如 systemd 的 TimeoutStopSec)的停止逾時要多一分鐘。
interimText "on" 或 "off" "on" 一輪是否邊做邊貼出它在最終答案之前寫的文字。"off" 只貼最終回覆。
interimPrimaryChars 1 到 100000 的整數 400 中間文字達到這個長度就當作一般訊息貼出;較短的敘述放進一則小小的進度訊息。
plugins 外掛物件的清單 [] 你的外掛。它們在內建外掛之後,依列出的順序啟動。

設了 ops.agent(或 routing.places.ops 裡的 agent)之後,每一筆 error 和 fatal 的 log 都會回報給那個 agent,成為它 primary place 裡的一則訊息和一輪回報;設了 ops.conversation(或 routing.places.ops 裡的對話 key)則回報到那段對話,由認領它的 claim 執行回報那一輪。 同一個錯誤一小時內最多回報一次,每小時最多送出五筆回報。

webhook 在 agent 頻道裡的貼文(例如 CI bot 的通知)會用貼文的文字替那個 agent 開始一輪回報,除非 routing 把它送到 agent 的 primary place,否則就在那個頻道裡。只有 embed 的貼文也算:它的標題、說明、欄位、頁尾和連結會當作純文字讀進來,最多 4,000 個字元,所以沒有訊息文字的警報一樣會被回應。

addon 加了什麼、外掛怎麼啟動,見 Services and addons。