網頁聊天套件
pi-roundtable-webchat 是以外掛形式提供的聊天管道。
經 OpenID Connect 供應商登入的人,可以從網頁或瀏覽器擴充功能跟主騎士聊天,每個人有自己的私人對話。
一輪執行時,它寫的文字和用的工具會即時顯示;暫緩的工具呼叫會用核准卡詢問對話的主人。
它不需要 Discord:設定裡沒有 discord、外掛清單列了 webChat({ ... }) 的 host,就是只有網頁的主騎士。
建立網頁聊天專案
Section titled “建立網頁聊天專案”npx pi-roundtable init my-desk --adapter webcd my-deskbun installdocker compose up -dcp .env.example .env # 然後填入內容bunx roundtable doctorbunx roundtable start這個專案在 plugins 列出 webChat({ ... }):一個 OpenID Connect verifier、一份頂層的 access(由 token 角色決定 member 與 admin),以及一個 persona assistant,提示詞是 persona/assistant.md。
這個 persona 在 selection 寫明它的工具,所以之後加入的外掛帶來的工具,要寫進名稱才會出現。
host 監聽 127.0.0.1:3000;請透過反向代理用 HTTPS 對外提供服務,並把 CHAT_ORIGINS 設成會開啟聊天的網頁。
它寫出的每個檔案,見 init --adapter web。
加進既有的 host
Section titled “加進既有的 host”bun add pi-roundtable-webchatimport { readFileSync } from "node:fs";import { oidcJwtVerifier, webChat } from "pi-roundtable-webchat";
export default { // ...你的 roundtable 設定,含 http: { port: 3000, hostname: "127.0.0.1" }... access: { admins: { roles: ["web:role:Helpdesk.Admin"] }, members: { roles: ["web:role:Helpdesk.User"] }, }, plugins: [ webChat({ verifier: oidcJwtVerifier({ jwksUrl: "https://login.example.com/keys", issuers: ["https://login.example.com/"], audiences: ["api://helpdesk"], }), origins: ["https://chat.example.com"], personas: [ { kind: "helpdesk", label: "Helpdesk", prompt: () => readFileSync("./persona/helpdesk.md", "utf8"), selection: { tools: [], groups: [] }, }, ], }), ],};它與 pi-roundtable 同步發版,需要一個 HTTP listener(設定裡的 http)。
這些選項寫錯時,設定載入就會丟出錯誤,所以 roundtable doctor 會在 host 啟動前指出問題。
瀏覽器先帶著 Authorization: Bearer <token> 呼叫 POST /chat/tickets 取得一次性 ticket,再開啟 /chat/socket,提出 roundtable.webchat.v1 和 ticket.<ticket> 兩個 subprotocol。
其他用戶端則在 upgrade 時直接帶 bearer token。
token 從不出現在 URL 裡。
每則 WebSocket 訊息是一個帶 type 的 JSON 物件。
用戶端送出 send、stop、approval、answer 和 auth;伺服器回應 ready、accepted、typing、stoppable、progress、reply、failed、prompt、prompt_closed、reauth 和 error。
progress 顯示這一輪寫的文字和執行的工具,不含思考過程,也不含工具的完整參數;reply 是完整 markdown 的回答。
REST API 可以列出一個人的對話、開新對話、讀取對話訊息。
每種 frame、錯誤碼、關閉碼和上限,見套件 README(英文)。
網頁聊天會告訴模型完整 Markdown 都能顯示,包括表格:每一輪在這裡回覆的對話,系統提示詞都會在人設之後附上一小段格式指引(英文)。
用戶端顯示能力較弱時,可設定 formatting: "…" 取代這段文字,或設定 formatting: false 什麼都不告訴模型。
- 私人對話。 對話屬於開啟它的人。host 的對話登錄在第一輪記下這個人,claim 在每一輪之前檢查:在網頁聊天裡只有這個人能列出、讀取、發言、停止或回答它。擁有者仍可以透過擁有者主控台讀取,營運者也能從資料庫和資料目錄讀到。
- token。 每次 REST 呼叫、每次 upgrade、每個
authframe 都會檢查 token。預設只接受個人的 access token;沒有 scope 或 app role 的 token、只代表應用程式的 token 都會被拒絕。token 到期時 socket 會關閉。 - 來源。
origins必填,每次 upgrade 和每個瀏覽器請求都會檢查。 - 上限。 每個人的 socket、ticket、每小時新開的對話,以及同時執行或排隊的回合數都有上限。
- 核准。 暫緩呼叫的核准卡只送給對話的主人,而且要有這個呼叫需要的 tier。
- 提問。 騎士可以在同一張卡片上問最多四個相關的問題,但這張卡片只送給已宣告能顯示它的用戶端;其他用戶端會改成一次問一題。frame 的清單見套件的 README。
- owner。 沒有任何 token claim 能讓人成為 owner:owner 要用 speaker id 列出,格式是
oidc:<base64url(issuer)>:<subject>。
verifier 本身是通用的;安不安全,取決於你怎麼把它指向自己的供應商。
有人登入之前,請先讀 README 的供應商設定:用跨 app 註冊都不變的 claim 識別人、固定租戶、只接受 access token,而且只合併同一個租戶的 issuer。
對 Microsoft Entra ID v2 的 access token,entraV2Check({ tenant, scope, guests? }) 是現成的 check:它固定 tid,要求 ver 為 "2.0"、scp 含委派的 scope,而且除非設 guests: true,只接受成員(acct 為 0 或 "0")。
測試時,pi-roundtable-webchat/testing 匯出 testIssuer:它在本機 port 上跑一個 OpenID provider,用 sign({ claims }) 簽 token,並在 jwksUrl 提供 JWKS。
host 其他部分信任哪些東西,見安全性。
目前還不支援
Section titled “目前還不支援”- 附件:訊息只有文字。
- 排程與委派回報:網頁對話不接受背景回合,所以 persona 的
selection不要放schedule_*和delegate_task。 - 網路工具:除非允許使用者讓 host 抓取任何位址(包含內部位址),否則不要放
web_search和fetch_content。 - 錯誤回報:
ops.conversation不能指向網頁對話,因為網頁對話只有登入的本人能開;指向網頁對話時 host 不會啟動。請回報到其他 surface 的對話,或在有 Discord 時交給 agent。 - agent team 沒有網頁版的房間。
- 同一個人用兩個供應商登入,或同時用 Discord 和網頁,會有兩個 speaker id、兩份記憶。