跳到內容

Web 套件

pi-roundtable-web 是 host 的 owner app:在 host 的 HTTP listener 上提供一個網頁,owner 可以在這裡跟 agent 團隊對話、回答核准卡、中止一輪執行、傳檔案、切換 yolo 與長時間執行模式,有事等著處理時,手機也會收到通知。 最早的 console 功能也還在:查看對話 transcript、讀寫記憶筆記、看團隊狀態。

這個外掛本身就是一個聊天管道,所以 agent 團隊可以只活在網頁裡:沒有 Discord 的 host 也能完整運作。 每個啟用中的 agent 和群組都有自己的房間,Home 是協調者的房間。 房間是獨立的對話,跟同一個 agent 在 Discord 頻道裡的對話分開。

終端機視窗
bun add pi-roundtable-web pi-roundtable

需要 Bun 1.4.4 以上、>=0.50.0 <0.51.0 的 pi-roundtable。 app 必須跟 host 的資料目錄在同一台機器上執行,金鑰和檔案放在 <dataDir>/web/。 host 要有 agent 團隊(設定裡的 agents)。驗證不能省略:選 none、password,或像 Cloudflare Access 這樣的 verifier。 要安裝成 app、收通知,網址必須是 HTTPS。

import { cloudflareAccess, webConsole } from "pi-roundtable-web";
export default {
// ...其他 roundtable 設定,有 `agents`,不寫 `discord` 也可以...
plugins: [webConsole({
verifier: cloudflareAccess({
teamDomain: "example.cloudflareaccess.com",
audience: process.env.CONSOLE_ACCESS_AUD ?? "",
email: "owner@example.com",
}),
origin: "https://app.example.com",
})],
};

打開 https://app.example.com/console/,看到的就是 app。

位置 功能
Rooms 先是 Home,接著是 agent、群組和派工 thread,並以徽章標出執行中、有卡片等待、yolo 與長時間執行。thread 是一張張卡片:把已完成的卡片向右滑、長按、右鍵,或在它上面按 Delete,就能從列表清掉,幾秒內可按「復原」。聊天室列表的選單(各分組的選單也有)可以一次「全部標為已讀」,或「清除所有已結束的討論串」,同樣能復原。
房間 訊息帶作者的角色圖,支援 Markdown 和檔案,有即時進度列,輸入框可上傳檔案、按 Stop 中止。
卡片 附細節的核准、問題、問卷,以及一輪執行碰到時間上限時的卡片,任何一位 owner 都能在房間裡回答。
Agent 檔案 名稱、提示詞、模型、思考程度,以及角色編輯器。
Schedules 團隊的排程,取消前會先確認。
Table 圓桌就是評議會:一個 agent 群組(最多八位成員)站在座位上,群組的聊天室以對話框顯示在下方。用面板勾選成員,可以直接改寫這個群組,或把勾選的結果另存成新的評議會。owner 的圓桌不讓 host 房間入座;那些房間在房間列表裡。成員或管理員只有在 host 為該層級列出它時才有;那時它讓他們能列出的 host 房間入座,最多八個。
檔案 騎士的工作區:檔案樹、CodeMirror 語法高亮的檔案,以及編輯器;存檔時會檢查騎士有沒有同時改過,也能新增、重新命名、刪除(刪除會進可還原的垃圾桶)。
Settings 色彩模式與外觀、安裝、這台裝置的通知,以及登出。

檔案頁只給 owner 看騎士的工作目錄、暫存目錄(以及你用 workspace.roots 加的位置)。每次存檔都會對照讀取時的雜湊值,.git 一律唯讀,指到位置外的符號連結不會被開啟,編輯器的程式碼要到開啟檔案時才載入。完整規則見 README。

圓桌在有 WebGL 的瀏覽器上是 3D 場景,沒有時是 SVG 圓桌;在頁面網址加上 ?nogl 就能看 SVG 版。 座位名稱至少畫成 11 px;畫布小到做不到時,圓桌下方會把座位列成按鈕。

一輪執行會等卡片 cardGraceSeconds 秒(預設 120);時間到就不等答案繼續往下,卡片仍保留一天。 之後才給的答案,會在該房間開啟新的一輪。 檔案不限類型,大小上限是 uploadMaxBytes(預設 100 MiB),以串流寫入磁碟再交給 agent;Cloudflare 免費方案限制 request body 為 100 MB。

房間選單有兩個開關,按房間記錄,重啟後仍然有效。 Yolo 會直接核准規則允許的暫緩呼叫,不開卡片,並在房間裡為每一次核准留一行紀錄。 它不會核准 webhook 或報告觸發的那輪、指定了核准人的呼叫,以及只有發言者本人能回答的卡片;破壞性的類別(sudo、rm、磁碟、電源、服務、docker、防火牆、套件、強制推送、hard reset、gh、crontab)一律照問。 單純的 git push 和工作區外的寫入會被核准,而推到 main 可能就是部署;要讓它也詢問,就把 shell.push 列進 host 設定的 autonomy.yolo.card。 Yolo 模式下問題卡片和逾時卡片仍然會出現,但等待時間比較短(預設 30 秒和一分鐘),沒回答也不會讓工作停下:agent 照它自己的最佳選擇繼續,並說明它做了什麼假設;逾時卡片則會自動讓這一輪繼續,最多到長時間執行的上限。 長時間執行讓一輪執行超過時間上限後自動繼續,最多做到 autonomy.longRunning.maxSeconds(預設四小時),之後開卡片詢問,無法顯示卡片時就中止。 任一模式開著時,畫面上會有橫幅提示。 臨時騎士的房間即時沿用建立它的那個對話的模式:橫幅會註明模式來自哪裡,要切換就到那個對話去切。 類別清單和防護規則見核心指南。

agent 都以組合出來的角色呈現。 頁面有 Modern 與 Camelot 兩種外觀(Camelot 白天是羊皮紙、夜晚是夜間城堡,配上金色線條、盾形外框和蠟封),各有淺色與深色,在 Settings 依裝置選擇。 appearance.look 設定 host 的預設外觀。

appearance.home: "chats" 讓 app 開在聊天列表,而不是整理過的房間列表;沒設這個選項的 host 維持房間列表。 釘選的房間是上方的大頭像(首頁在最前面,帶星號),資料夾變成篩選用的 chip,篩選下方依最新活動排序的同一份列表,最後一列收合的入口通向已隱藏的房間與封存。 房間可以從選單隱藏:它照常回應、跑排程、推播,只是離開首頁與切換器;隱藏狀態像釘選一樣由所有 owner 共用(PUT api/rooms/<key>/hidden)。 其他功能(整理、排程、檔案、設定)都在格狀按鈕後面,手機是底部面板,寬螢幕是浮出面板;沒有分頁列也沒有側欄,1024 px 以上首頁是 380 px 的欄位,開啟的房間佔滿其餘空間。 派工串與臨時騎士在房間標頭的控制項裡查看。

正式騎士的聊天室可以接收外部的 JSON 發文,就像 Discord Webhook 發在它的頻道一樣:以 { "content": "...", "username": "..." }(或任何 JSON,會顯示成程式碼區塊;最多 16 KB、每分鐘 30 則)POST <mountPath>/hooks/<id>/<token>,內容會標上 Webhook 顯示在聊天室,並以不可信輸入啟動騎士的回報。 這個路徑不需要登入,所以前面的登入 proxy 必須放行 <mountPath>/hooks/;webhookOrigin 可為網址指定另一個公開主機名稱。 owner 在騎士設定的 更多 分頁建立與撤銷 Webhook,也可以在 Webhook 頁面(#/webhooks,頁面名稱 webhooks;明確列出 panes 的主機要自己加上)一次管理所有騎士的 Webhook;騎士自己則用 webhook_create、webhook_list 和 webhook_revoke,只限自己的聊天室。 網址只顯示一次,只儲存 token 的雜湊。

app 是 PWA:manifest 的範圍限於 mount 路徑,service worker 只快取頁面外殼、不快取資料,圖示可用 icons.dir 換掉內建的一組。分頁圖示預設是圓桌的標誌;manifest 與圖示不需登入就能取得,登入頁與連結預覽才有圖示。 從瀏覽器的安裝選項或 Settings 安裝;iPhone 和 iPad 要用「分享」再「加入主畫面」,並從主畫面開啟。

Web Push 會在 owner 沒有任何頁面開著、看得到的時候喚醒裝置:卡片開啟時(「Card waiting」,或「Long-running cap reached」)、agent 自己在房間發話時,以及 host 發出的通知。 每位 owner 在 Settings 按裝置開啟推播,也能在那裡移除裝置。 除非 origin 是 https,否則要設定 push.subject(mailto: 位址或 https: 網址);VAPID 金鑰在第一次啟動時產生,放在 <dataDir>/web/vapid.json,這個檔案必須在重啟後保留。 推播的 endpoint 必須是 https,且屬於允許的推播服務;push.endpointHosts 可以加入更多。 push.preview 關閉時,通知不帶任何訊息內容。 預設在主控台時區的 23:00 到 08:00 之間,agent 的發話與通知不會推播,卡片仍會;push.quietHours({ start, end },格式為 HH:MM,或 false)可以改這個時段,Settings 會以唯讀方式顯示。

選項 預設值 用途
auth 必填,或用 verifier { mode: "none" }、{ mode: "password" }、{ mode: "verifier", verifier } 或 { mode: "oidc", ... }。
verifier 無 verifier 模式的簡寫:cloudflareAccess(...) 或自訂函式。兩者同時給會出錯。
origin 必填 瀏覽器看到的 scheme 和 host。寫入操作必須帶上完全相同的 Origin。
webhookOrigin origin 傳入 Webhook 網址開頭的 scheme 和 host,用於公開的 Webhook 主機名稱和主控台不同時。
ownerId 主要 owner 已棄用:沒有回報身分的 verifier 所代表的 principal。
dataDir ./data host 資料目錄,其中有 sessions/ 和 web/。
mountPath /console route prefix。
listener public 提供 app 的 HTTP listener。
routing hash path 保留 mount 下的頁面路徑與 history 導航。
admission owners owners 只讓 owner 進入;access 讓 IDENTITY 在這個 surface 上接納的所有人進入(owner、admin、成員)。見「成員與關卡」。
modes 開啟 設為 false 就不提供 yolo 與長時間執行開關;PUT api/rooms/<key>/mode 回 404。
panes rooms、table、workspace、overview、schedules、conversations、notes、presets、webhooks 可再選 skills、connectors 並指定順序;presets 列出每位騎士的臨時騎士範本,webhooks 列出每位騎士的傳入 Webhook;schedules、table、workspace、presets 和 webhooks 需要 rooms,workspace 還要有可顯示的位置。明確列出的清單照寫的為準。admission: "access" 時預設會加上 profile,也可以用 { owner, admin?, member } 依身分層級分別設定;owner 專屬的頁面裡,只有 table 能列給成員或管理員(該層級也要有 rooms)。
workspace 騎士的目錄 檔案頁顯示什麼。workspace.roots 加入更多位置,每個有 workspace.roots.id、workspace.roots.label、workspace.roots.dir 和 workspace.roots.writable(沒設就是唯讀);workspace.agents、workspace.scratch 設為 false 就不顯示騎士的工作目錄或暫存目錄。dir 是 dataDir 或包含它時會無法啟動。
surface app app 房間的 key 前綴。改了它,所有房間都會重新開始。
cardGraceSeconds 120 一輪執行等卡片的秒數,大於 0、最多 3600。
uploadMaxBytes 100 MiB 一個人能上傳的單檔上限,1 byte 到 4 GiB。
uploads { keepDays: 30 } uploads.keepDays:app 騎士房間裡已儲存檔案的保留天數,1 到 3650。宿主房間種類自己的 retention.fileDays 管它自己的房間。
push https origin 時開啟 Web Push;金鑰見下表。
icons 內建圖示 { dir }:放五個安裝圖示的目錄。
appearance { look: "modern", home: "rooms" } { look, home }:appearance.look 是 modern 或 camelot;appearance.home 是 app 開啟的首頁,rooms(整理過的房間列表)或 chats(聊天列表)。
title Roundtable 頁面標題(直接寫在送出的 HTML 裡,也是 og:title),也是安裝後 app 的名稱。
description 由 title 推得 <meta name="description"> 與 og:description,給搜尋結果與連結預覽用。
presentation 英文 { locale, messages } 設定語言、日期格式與在地化文字;dictionary key 是英文原文。zh-TW 會使用內建的繁體中文(臺灣)文字,messages 可逐個 key 覆寫。
features 無 物件或接收公開 setup context 的 factory,提供 party 狀態、排程數、對話清理、skills 與 connectors。
relayNotes remote MCP relay note 顯示訊息前要移除的 relay 前綴。
exclude 無 (key, record?) predicate,指定哪些對話不得列出或讀取;record 是 registry 對該對話的記錄。
assetDir 套件的 dist/ 已建置頁面的目錄;只應在測試時設定。
欄位 預設值 用途
auth.mode 必填 none、password、verifier 或 oidc。
auth.trustNetwork false 只用於 none:允許對本機以外開放的 TCP listener。
auth.passwordEnv ROUNDTABLE_WEB_PASSWORD 只用於 password:存放密碼的環境變數,至少 12 個字元。
auth.sessionDays 30 只用於 password:登入有效幾天,1 到 365。
auth.principal 主要 owner 用於 none 與 password:session 代表的 principal。
auth.verifier verifier 模式必填 只用於 verifier:request verifier。
auth.issuer 必填 只用於 oidc:提供者確切的 iss,https 網址。
auth.discoveryUrl <issuer>/.well-known/openid-configuration 只用於 oidc:啟動時讀取各端點的位置。
auth.clientId 必填 只用於 oidc:用戶端 id;redirect URI 是 <origin><mountPath>/auth/callback。
auth.clientSecretEnv 無 只用於 oidc:存放用戶端密鑰的環境變數;不設就是使用 PKCE 的公開用戶端。
auth.scopes openid、profile 只用於 oidc;offline_access 會被拒絕。
auth.subjectClaim sub 只用於 oidc:指出這個人是誰的 claim。
auth.nameClaim name 只用於 oidc:名稱所用的 claim。
auth.rolesClaim roles 只用於 oidc:值會成為 app:role:<name> 的 claim;false 表示不讀。
auth.check 無 只用於 oidc:依 claims 決定這個 token 能不能接受。
auth.endSession false 只用於 oidc:登出時是否一併登出提供者。
auth.reauthHours 不會 只用於 oidc:過了這麼多小時就再向提供者確認。
auth.storeClaims 無 只用於 oidc:隨 session 保存的 id_token claims。
auth.onSessionVerified 無 只用於 oidc:(principalId) => void,request 或 socket 證明 session 仍有效時呼叫(每個 session 每五分鐘最多一次)。
push.preview true 通知是否顯示訊息的前 120 個字元。
push.quietHours { start: "23:00", end: "08:00" } 不推播 agent 發話與通知的時段,以主控台時區的 HH:MM 表示;卡片一律推播。false 關閉勿擾時段。
push.endpointHosts 無 額外允許的推播服務主機;開頭的 *. 代表所有子網域。
push.tiers ["owner"] 哪些身分層級的人可以訂閱並收到推播。
push.subject https 時為 origin VAPID 聯絡資訊:mailto: 或 https: 網址。沒有的話推播關閉。
push.sender "internal" 由誰簽署並送出推播:這個行程本身,或 { external: { publicKey, subscribePath? } },也就是由你另外執行、持有 VAPID 金鑰的送出行程,app 自己不持有金鑰。
push.content internal 為 "full",external 為 "none" 推播帶出 app 的內容:標題與預覽("full"),或只有種類、標籤與數量("none")。
push.transports 無 送出行程除了 web-push 之外還負責的傳輸名稱,例如 slack;通知的 via 只能指定這些。
onboarding.links 無 把提供者對應到 "required"(用關卡擋住 app)或 "nudge"(只提醒);每個都需要透過 WEB_APP 註冊的 LinkProver。
onboarding.push "off" "required" 或 "nudge" 會請對方開啟推播並收到一則測試通知。
onboarding.pushWaiver false 讓對方可以略過必要的推播步驟。

通知是等某一個人處理的事。host 用 Notices.raise 發出,並帶 open 目標,也就是 { room, message? } 或 { page, query? },處理完用 Notices.resolve 收回。它的 tag 同時是去重的鍵、推播的標籤與確認的鍵,通知對象的瀏覽器看得到它,所以別把不該讓他們看到的私有 id 放進去。它會出現在通知鈴與 app 圖示上;一般通知在對方的勿擾時段只留在通知鈴,緊急通知照常響。點通知或推播,不論 app 開著或關著,都會打開確切的那個房間或頁面。

對方在開啟 app 前要完成什麼,由 onboarding 設定(上表的 links、push 與 pushWaiver)。 個人資料頁會列出對方連結過的帳號,讓他連結或解除 host 的 LinkProver 允許的帳號,選擇用哪個帳號當作他在 app 裡的名稱(顯示為),並設定自己的勿擾時段。

設成 push.sender: { external } 時,app 不持有 VAPID 金鑰:它把每則推播排進 web_push_outbox,由你用 pi-roundtable-web/push-sender 的 runPushSender 另外執行的行程,經它的傳輸簽署並送出,也可以在 subscribePath 提供訂閱路由。這些路由只在帶 app 的 session cookie 時回應,GET 以外的請求必須帶與主控台完全相同的 Origin。

admission: "access" 讓 host 的 IDENTITY 在這個 surface 上接納的所有人進入,auth 要用 oidc(或會回報是誰登入的 verifier)。 已連結的人只會被讀取(IDENTITY.peek);沒連結的人,只有在 access.provisioning.app 為 admitted 時才會當成新 principal 接納。 回報的身分資料是局部的,所以在這裡登入不會調降別處記錄的層級。被停用的 principal,或規則沒有給任何層級的人,會得到 403。

src/authz.ts 裡的一張表會在任何處理器看到請求之前先判定它,表裡沒有的路由對所有人都回 404。 owner 能用騎士房間、總覽與其他僅限 owner 的頁面;成員能用自己的對話、筆記與排程、host 的房間與頁面,以及自己的個人資料。 成員的 socket 不會收到任何騎士房間的內容,不論是即時發生的,還是連線當下補送的;卡片也只有它自己的對象能回應。 成員或管理員的圓桌(host 有為該層級列出時)只讓他們能列出的 host 房間入座:座位亮不亮看那個房間自己的訊息,這些訊息只送到有權讀該房間的 socket;點座位會進那個房間的頁面,能寫什麼由房間種類的 access 決定。 還有必要的設定步驟沒做完時,app 會停在那些步驟上:只有個人資料、設定,以及完成步驟的頁面能用,直到最後一步完成。 連結可以帶 ?next=,值可以是 profile、notices、settings、room:<key> 或 p:<page>;其他值一律捨棄。

OpenID Connect 用 authorization code 加 PKCE 登入,在 callback 只檢查一次 id_token,之後由 app 自己在 web_sessions 保存伺服器端的 session:HttpOnly cookie 裡是隨機 id,資料庫只存它的 SHA-256。sessionDays 天沒有來訪 session 就結束;登出會刪除它。reauthHours 會讓提供者再確認一次(能的話無聲完成;已開啟的 socket 在 session 超過時限後會被當作登出而關閉),storeClaims 則把指定的 claims 跟 session 一起保存。onSessionVerified(principalId) 在 session 仍有效時被呼叫(每個 session 每五分鐘最多一次),讓 host 把只開著 app 的人也算作在線;它丟出的錯誤只會記進日誌,不會讓 request 失敗。

模式 owner 是誰 適用情況
verifier verifier 回報的那個人,且已連結到某位 owner。 由 Cloudflare Access 之類的 proxy 負責登入。這是唯一一個 host 上的 agent 偽造不了的模式。
password 輸入密碼後的主要 owner。 app 對網際網路開放,前面沒有負責登入的 proxy。
none 主要 owner,誰連得到 listener 誰就是。 只有 owner 連得到 listener:unix socket 或 loopback TCP。
oidc 提供者回報的那個人,依 IDENTITY 連結到 principal 的身分而定;admission: "access" 時也包含成員與 admin。 人們用你自己的 OpenID Connect 提供者登入。

password 提供不需要 script 的登入頁;每次失敗要多等一秒,15 分鐘內失敗十次,這段時間內所有登入都會被鎖住(這是全域限制,因為 proxy 後面看不到可信的 client 位址);成功後設定簽署過的 HttpOnly、SameSite=Strict cookie,換密碼會讓舊 cookie 全部失效。 none 必須明確寫出來,每次啟動都會警告,而且除非設了 trustNetwork,否則會拒絕不是 loopback 的 TCP listener。

以 host 使用者身分執行 shell 的 agent,能碰到那位使用者碰得到的一切。 用 none 時,它可以經由 socket 以 owner 身分呼叫 app,核准自己被暫緩的動作,甚至打開 yolo;用 password 時,它可以讀到密碼和 session 金鑰。 兩者都擋得住來自網路的攻擊,但擋不住 host 上被攻陷的 agent。 只有 verifier 擋得住,因為 agent 偽造不出簽署過的 token。 host 上的 agent 會執行指令時,請繼續用 Cloudflare Access(或其他會簽署的 proxy)。

內建的 cloudflareAccess verifier 會驗證 Access 簽署的 token、team、audience 和允許的 email。 若自訂 verifier 信任 proxy header,只有在 client 無法直接連上 listener,而且 proxy 會移除 client 自帶的同名 header 時才安全。 API、SSE、WebSocket、頁面和靜態資源都先驗證,再讀取資料;寫入操作要有完全相符的 Origin,頁面也不會送出 CORS header。 agent 的輸出是不含 raw HTML 的 Markdown,儲存的檔案一律以下載方式提供,並套用 sandbox 政策。 Transcript 會顯示 tool arguments 和結果,工具處理過的 secret 可能出現在裡面;可以用 panes 或 exclude 限縮資料。

不是騎士的宿主外掛可以在 app 裡擁有自己的房間,例如客服信箱,一封信件串一個房間。外掛在 requires 列出 WEB_APP,並在 setup 呼叫 registerRoomKind、registerPage。宿主用的型別(WEB_APP、WebApp、HostRoomKind、HostPage、HostCard、Viewer、OpenTarget、ActionResult、LinkProver、OnboardingStep、Notices)由 pi-roundtable-web 匯出。請保留 WebApp 物件,並在用到時才讀 rooms、notices、pages、onboarding、push:外掛啟動前讀取會丟錯,notices.onAck 也只能在啟動後掛。HostRoomKind.buttons 可以回傳 Promise。

  • 存取權由房間種類的 access(viewer, id) 決定,每次讀取、frame、傳訊、卡片回應、上傳與取檔都會重問;回傳 undefined 就是 404。它回答這個人能做什麼:讀、傳 note 或 turn、按按鈕。
  • 訊息用 app.rooms.post 發出,作者種類有 external(純文字,附宿主給的標籤,例如「客戶」)、member、assistant 與 notice(Markdown)。reference 用來再找到同一則訊息,edit 與 remove 修改或刪除。
  • 近期訊息:app.rooms.context(room, { limit?, messageChars? }) 以 CHANNEL_CONTEXT.read 給 turn 的同一種區塊({ messages, text })回傳房間近期的訊息:騎士上次發言之後說的話,最新的 limit 則(預設 15,最多 100),外人的話標為 external,不含通知行。用在 turn 由房間的 send hook 發起、沒有任何訊息指向騎士的時候。它不會把訊息標成已交付,所以重試時讀到的一樣。
  • 卡片有標題、內文、色調、狀態、連結與按鈕;按鈕可以開表單(文字、多行文字、網址、可設 initial 與 search 的單選、複選),伺服器會先檢查再交給房間種類的 act。只有卡片狀態是 open 時才顯示按鈕。騎士的核准與提問卡片沿用騎士自己的提示範圍。
  • 寫入方式:檢視者能傳 note 也能傳 turn 時,房間在輸入列上方只顯示一個 @AI 開關(關 = 只給房間裡的人看的內部備註,開 = 請騎士回應),輸入框的提示跟著開關變;只能用一種方式傳的人沒有開關。房間種類可以用 sendWording: { note?: { placeholder }, turn?: { label, placeholder } } 自訂用字,只收純文字,label 最多 40 字、placeholder 最多 100 字。在輸入框開頭自己打 @AI 等同打開開關:它在的時候開關顯示為開,頁面會明確以 turn 送出,並把開頭的 @AI 從文字裡去掉。只有親手打的才算;出現在文字後段、貼上的文字,或 a@ai.com 這類位址裡的 @AI 都只是文字。伺服器從不讀文字來判斷,所以開頭是 @AI 的 note 訊息仍是備註。沒有開關的房間把它當一般文字。
  • 圖示:頁面或房間種類可以給 icon,值是 HOST_ICONS 的其中一個(型別 HostIconName):chat、link、activity、users、megaphone、qr、settings、bell、file、list、shield、lock、sparkle。頁面的圖示顯示在導覽列,房間種類的圖示顯示在聊天室清單的區段標題旁;不在清單內的名稱會顯示預設圖示。
  • 連結與圖片:app.rooms.link(room, messageId?) 回傳開啟房間並標出該則訊息的網址;![alt](file:<id>) 顯示用 saveFile 或 app.pages.saveAsset 存下的 PNG、JPEG、WebP,只給有權看該房間或頁面的人。
  • 頁面在 <mount>/p/<id>,由 Markdown、清單、表單與卡片區塊組成;visible(viewer) 每次都會重問,app.pages.changed(id?) 讓檢視者重新取得內容。
  • 保留期限:房間種類的 retention: { textDays, fileDays } 會刪除過期的訊息、作者名稱、卡片與檔案,從每則訊息的時間起算(卡片從首次發出時起算)。在 card 或 updateCard 帶 keep: true 的卡片(例如工單未結案時釘住的那張)只要宿主持續帶著它,清理就會略過。
  • 已讀標記:app 記錄每個人在每個房間讀到哪裡(宿主房間與騎士房間一樣)。清單與側欄顯示未讀數,進房間時在新訊息處出現「新訊息」分隔線,每則訊息下方顯示讀到這裡的人(「已讀 2」,附頭像)。

房間、清單與頁面的程式碼在第一次開啟時才載入,app 的首次載入大小不變。

Overview 也會列出既有的 owner 工作區與外部 agent 對話。 features.party 用 contains(key) 和回傳 PartyView[] 的 list() 提供分開儲存的 party 頻道狀態。 features.schedules.count(key) 補上工作區排程數。 features.cleanup 提供 startFresh(key) 和回傳 deleted/busy 的 deleteConversation(key)。 套件先驗證 key 格式、歸屬、排除條件及既有檔案,再呼叫清理 hook;頁面會先確認,忙碌時的刪除回 409。 沒有 cleanup hook 時,對話仍是唯讀。

features.skills.catalog() 提供來源、描述、群組、使用者與檔案遺失狀態。 read(name) 只能讀 catalog 選出的項目,回傳 { frontmatter, body },不能接受 request 指定的檔案路徑。 設 errorDetail: true 時,API 會在回應中列出 missing 文字或讀取錯誤(最多 300 字符);不設時則只回傳固定訊息。 features.connectors 提供 gateways()、servers()、usedBy(server) 和選用的安全 adminUrl。 啟用 Skills/Connectors 卻沒有對應 hook 時,啟動會失敗。

Feature factory 接收公開 plugin setup context,可直接綁定既有 stores,不改 table、grant 或 session 路徑。 額外的 service 依賴應列在 host wrapper 的 requires。 應用程式專屬名稱與文字放在 presentation,不需複製 server 或 React 頁面。

完整的威脅模型、Cloudflare 設定步驟、自訂 verifier 範例、WebSocket 通訊協定和選項驗證方式,見 pi-roundtable-web README(英文)。