服務與 addon
服務是某個外掛建出來、其他外掛來讀取的東西,例如排程的儲存,或 agent 團隊。
每個服務有一個用 serviceKey<T>(id) 做出來的 key。
T 是一個介面,稱為 port,所以只要方法相同,任何物件都能當這個服務。
要提供它,或在測試裡做一個假的,都不需要內建的 class。
外掛把自己提供的 key 列在 provides,再從 setup 用 services.provide(KEY, value) 逐一提供。
key 的 id 要加上你自己的前綴,因為 id 相同的兩個 key 就是同一個服務。
export const NOTE_INDEX = serviceKey<NoteIndex>("my-notes.index");
export const notes = definePlugin({ name: "my-notes", provides: [NOTE_INDEX], setup: ({ services }) => { services.provide(NOTE_INDEX, { add, all }); return { services: [{ name: "notes-ready" }] }; },});完整版是 shared-services.ts。
| 呼叫 | 作用 |
|---|---|
services.get(KEY) |
回傳服務;找不到時丟出 PluginError,訊息會指出 key,以及該先註冊哪個外掛。 |
services.find(KEY) |
回傳服務;沒有任何已註冊的外掛宣告它時,回傳 undefined。如果有外掛宣告了這個 key 卻還沒 setup,它仍然會丟出錯誤,因為那是順序上的失誤。 |
services.lazy(KEY) |
回傳一個函式,等所有外掛都 setup 完之後,用它取得服務。提供服務的外掛排在你後面時用它,並且要在啟動之後才執行的地方呼叫,例如服務的 start、handler 或其他 callback。在 setup 期間呼叫會丟出 NotLinkedError。 |
services.provide(KEY, value) |
只能在 setup 裡呼叫,只能用在你的 provides 裡列出的 key,每個 key 只能一次。 |
如果你在 setup 期間用 get 讀服務,要把它的 key 列進 requires。
這樣順序錯了,會在任何 migration 或 setup 之前就被拒絕,訊息裡會寫出兩個外掛的名稱。
這個 key 必須由註冊在你前面的外掛提供。
用 find 讀的服務,不必列進 requires。
外掛宣告了某個 key 卻沒有提供,會在它的 setup 回傳時被拒絕。
兩個外掛宣告同一個 key,會在任何 setup 之前被拒絕。
內建外掛提供下列 key,全部從 pi-roundtable 匯出:
| Key | 由誰提供 | 內容 |
|---|---|---|
AGENTS |
agent-server |
agent 團隊、唯讀的目錄、每一輪 agent 所跑的 runtime、核准,以及頭像 |
SKILLS |
skills(addon) |
agent 帶的技能,以及用來列出、連結和掛上技能的 registry |
SCHEDULES |
schedule-store |
儲存的排程:create、get、update、remove、due、claim |
PRECHECKS |
prechecks |
host 以名稱註冊的預檢:register、get、list |
MEMORY |
memory(addon) |
每位 speaker 的記憶:list、add、search、update、remove |
BACKGROUND_TURNS |
modules |
沒有人寫訊息觸發的輪次:排程、委派,以及錯誤回報 |
DELEGATION |
modules |
啟動背景任務,以及哪些頻道有任務正在執行 |
你的外掛在內建外掛之後執行,所以上面每個 key 都讀得到。
Discord 連線的 key DISCORD 來自 pi-roundtable/discord,因為它的 port 用到 discord.js 的型別。
在 Discord 發文:DISCORD.poster
Section titled “在 Discord 發文:DISCORD.poster”DISCORD(來自 pi-roundtable/discord)有一個 poster:給你的外掛自己發文用的 Discord REST API,走 Discord 外掛自己的 client 和它的限速。
請從服務的 start 起使用,不要在 setup 裡呼叫(Roundtable.check() 也會跑 setup);建立它不會送出任何請求。
const { poster } = services.get(DISCORD);const posted = await poster.post(channelId, { webhook: "relay", username: "Ann", content: "Hello" });await poster.edit(channelId, posted.messageId, { content: "Hello again" }, ["relay"]);- webhook 的名稱由你決定:
post會在頻道裡找 bot 建的同名 webhook,沒有就建立。webhook 名稱和username是 1 到 80 個字元,不能含 “discord” 或 “clyde”;不合的在送出請求前就以invalid失敗。 - 發文、編輯、卡片和私訊都不會 ping 到沒指名的人:請求一律帶
allowed_mentions的parse: [],只有你列在mentions的人會被 ping。 - 卡片是 Components V2 訊息。
editCard會讓它維持這個型態;用say發的訊息不能改成卡片(rejected),而釘選時 Discord 發的那則通知是 bot 的訊息,沒有人能編輯它。 - 卡片可帶
thumbnail(標題旁的小圖)與image(文字區塊下方的圖),各為{ url, description? },網址須是https;editCard會保留它們。postCard透過你的 webhook 發卡片,顯示該 webhook 的名稱與頭像,editWebhookCard編輯它;這個 webhook 是 bot 自己建立的,所以卡片上的按鈕會送到你的 interaction 處理器。 - 帶
preview(一行純文字)的卡片會改以傳統訊息送出:preview 成為訊息的content,也就是推播與桌面通知顯示的字,卡片本身是一個 embed,按鈕與選單照常。沒有preview的卡片,通知是空白的。poster 無法改變訊息的型態:Components V2 卡片不能編輯成 preview 卡片,反過來也不行(rejected)。 channelKind(channelId)回報頻道是text、category、thread、forum、forum_post還是other;在討論串裡寫的訊息則由InboundMessage.thread({ parentId, parentKind })說明。討論串或論壇貼文裡被提及時,就地回覆,不要再開討論串。forumTags與setForumTags讀取並整組取代論壇的標籤(帶著標籤的id就會保留它);createForumPost(forumId, { name, card | content, appliedTags?, autoArchive? })開一則貼文並附上第一則訊息(卡片或文字),第一則訊息的 id 就是討論串的 id,所以可用editCard(threadId, messageId, card)編輯;setPostTags改貼文標籤,renameChannel可為貼文改名;貼文已封存時,這兩個呼叫會在同一個請求裡重新開啟它,editCard編輯貼文的第一則訊息也會先重新開啟封存的貼文。封存討論串裡的其他訊息,editCard會被 Discord 拒絕(rejected),要先setThreadArchived(threadId, false)。- Discord 允許頻道 10 分鐘內改名 2 次。
renameChannel不會把第 3 次排隊:10 秒後以unavailable失敗,之後也不會再送出。 threadCloser讀 audit log(要有 View Audit Log,否則forbidden),範圍是最近 50 筆討論串更新;Discord 自己的自動封存會讀成unknown。- 失敗一律是
DiscordPosterError,有kind(invalid、channel_gone、message_gone、forbidden、rejected、unavailable);訊息裡不會有 URL 或 token。
完整的呼叫清單和規則在指南的 Posting through DISCORD.poster(英文)。
自己做的 DISCORD 替身也要有 poster;fakeDiscord() 和 testHost 會給一個 fakeDiscordPoster()。
預檢在排程那一輪開始前,決定要不要叫醒 agent。 在 setup 裡註冊,agent 再用名稱把它掛到排程上。
definePlugin({ name: "recovery-precheck", setup: ({ services }) => { services.get(PRECHECKS).register({ name: "health.recovery", description: "Reads last night's HRV; wakes you when it is a fifth or more under its baseline.", timeoutMs: 15_000, run: async ({ schedule, firedAt, signal }) => { const { hrv, baseline } = await readRecovery(signal); return hrv >= baseline * 0.8 ? { wake: false, note: `HRV ${hrv} ms, as usual.` } : { wake: true, context: `HRV ${hrv} ms against ${baseline} ms.` }; }, }); return {}; },});{ wake: false, note? } 會略過這一輪,並把 note 以 bot 自己的小字訊息貼出;bot 的訊息不會觸發新的一輪。
{ wake: true, context } 會照常執行這一輪,context 放在「Precheck found」標題下。
拋出例外或逾時(預設 60 秒,可用 timeoutMs 調整)時,這一輪會帶著錯誤照常執行。
測試時用 pi-roundtable/testing 的 fakePrechecks(),以 servicePair(PRECHECKS, registry) 交給 plugin。
若要讓 agent 自己寫預檢,註冊一次腳本執行器:從 pi-roundtable-sandbox 呼叫 services.get(PRECHECKS).useScriptRunner(precheckScriptRunner({ image, runRoot, uid, gid, grant }))。
grant({ channel, target }) 回傳這個排程的腳本能呼叫的 MCP server 與 tools,不能超過該 agent 原本的權限;腳本在隔離容器裡執行,只碰得到這些。
取代內建服務
Section titled “取代內建服務”外掛同時把某個 key 列在 provides 和 replaces,就接手了那個服務。
host 會丟掉原本提供它的內建外掛,把你的外掛放在那個外掛原來的位置 setup。
被丟掉的外掛,它的 migration 和 setup 都不會執行。
你的替代外掛能讀到排在那個位置之前的外掛所提供的服務,之後的讀不到。
definePlugin({ name: "my-schedules", provides: [SCHEDULES], replaces: [SCHEDULES], setup: ({ services }) => { services.provide(SCHEDULES, myStore); return {}; },});host 會拒絕無法補齊的替換。
例如 BACKGROUND_TURNS 和 DELEGATION 都來自同一個 modules 外掛,所以要一起換,不然就都不換。
每一則拒絕訊息和它的修正方式,列在指南的取代內建服務(英文)。
pi-roundtable/kit 的 OpsAlerts 不是服務:外掛為自己的故障(例如推送失敗)建一個,再傳到會發出告警的地方。
它透過你給的 sink 發出一則短文字;sink 是一個函式,把文字送到負責維運的人會看的地方,所以不涉及任何 Discord 型別。
const alerts = new OpsAlerts({ sink, logger, kinds: { push: "LINE 推送" } });await alerts.raise("push:group-7", "群組推送失敗。", { code: "429" });alerts.faults(); // 每個類型最後一次的故障,給狀態指令用每則告警都有一個 key,類型是 key 第一個冒號前的字。
同一個 key 一小時只發一次,同一個類型一小時最多發八則(windowMs 與 kindCap 可以調整),所以影響範圍很大的故障不會洗版。
被擋下的只會記在 faults() 的計數裡,不會另外發彙總貼文。
告警在 raise 當下就發送;發送失敗(sink 丟出錯誤或回傳 false)會歸還 key,下一次 raise 會再試,而且 raise 永遠不會丟出錯誤。
info: true 代表消息而不是故障:每個 key 只發一次,不計入類型的上限,也不列在 faults()。
sink 也會拿到挑選圖片或路由所需的資訊:sink(text, { kind, key, code?, info?, severity? }),其中 severity 是 "info"、"warning" 或 "critical",照 raise 給的值傳入。只接收文字的 sink 照常運作。
故障結束時,alerts.resolve("push:group-7") 會歸還 key,並呼叫 sink 選用的 resolved({ kind, key }),讓它把已發出的告警標成已恢復(例如編輯那則訊息);之後 faults() 會在該類型上顯示 clearedAt。
對同一個 key 重複 resolve,或 resolve 一個從未發出的 key,什麼都不會發生。
Codex 畫圖
Section titled “Codex 畫圖”pi-roundtable/kit 的 drawCodexImage 和 createCodexImages,是官方 codex-images 外掛背後的客戶端和外掛,給想自己畫圖、或想用它們組出自己 images provider 的專案。
drawCodexImage 接收 openai-codex 登入的 token、提示詞和選用的參考圖,回傳 PNG 位元組,以及 Codex 說它實際畫的提示詞:
const { data, revisedPrompt } = await drawCodexImage({ token, prompt, signal });它會隨 signal 中止,五分鐘後停止,超過 32 MiB 的回應會被拒絕。
Codex 拒絕提示詞時會丟出 ImageNotGeneratedError,同一個提示詞再問還是一樣。
createCodexImages({ fetch?, model?, onMissingLogin? }) 是外掛本身:每次畫圖都重新讀取登入,並把這次畫圖的 signal 傳下去。
它用的是 ChatGPT 的 Codex 後端,OpenAI 並沒有為這種用途提供文件,所以可能隨時失效,不會另行通知。
記憶、技能和 Discord 管理是內建外掛;設定沒有把它們關掉,host 就會加進來。 三個預設都是開的。
| Addon | 在 roundtable.config.ts 的開關 |
它新增什麼 | 關掉時 |
|---|---|---|---|
| 記憶 | memory: false |
記憶資料表、memory_add、memory_search 和 memory_remove 工具,以及每個 system prompt 裡的記憶區塊 |
沒有記憶工具,也沒有那個區塊 |
| 技能 | skills: false |
技能資料表、agent session 的技能工具(skill_link、skill_create、agent_skills 等),以及每個 agent 都帶的技能 |
沒有技能工具,任何 session 都沒有技能。agent_create 少了 skills 參數,傳了這個參數的呼叫會被拒絕 |
| Discord 管理 | discord: { admin: false } |
讀取和管理伺服器、給 owner 用的 discord_* 工具 |
沒有 discord_* 工具 |
關掉的 addon,它的資料表和資料列都不會被動到,所以再打開時會看到原樣。
skills 開著的時候,還接受兩個目錄和技能套件:skills: { builtinDir, reposDir, packages }。
packages 列出已安裝的 npm 套件,它們 pi.skills 資料夾裡的每個技能都以唯讀方式提供,在目錄裡是 { kind: "package", package };套件沒裝、套件沒有技能,或技能名稱和別的技能重複時,啟動會以 PluginError 失敗,訊息會指出該怎麼改。
你的外掛如果沒有某個 addon 也能運作,就用 find 讀它的服務;addon 關著時會得到 undefined。
沒有它就不能運作的外掛用 get,失敗時的訊息會指出是哪個開關:
service roundtable.memory is not provided. The memory addon is switched off (config memory: false). Switch it on, or provide the service from a plugin of your own.關掉某個 addon,再加一個你自己的外掛來提供同一個 key,效果與 replaces 相同。