跳到內容

服務與 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(來自 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 原本的權限;腳本在隔離容器裡執行,只碰得到這些。

外掛同時把某個 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,什麼都不會發生。

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 相同。

完整內容見外掛指南的服務和 Addon(英文)。