extension logs --follow 與動作類指令底下的那一層。只有當你要針對這個 socket 打造自己的 harness 時,才需要這個頁面。其餘情況一律以 CLI 指令為受支援的介面。
dev 伺服器把這個通道掛在 ready.json 所公布的 controlPort 上的 /extjs-control 路徑。用戶端以信封版本 1 加上一個角色打招呼,角色為 producer、consumer 或 controller。
extension-develop 套件會從它的 bridge-entry 模組匯出本頁提到的每一個型別與常數,因此 harness 永遠不必把這些線路字串抄進自己的原始碼。
LogEvent(版本 1)
每個訊框一筆記錄,帶有v: 1。broker 在接收時指派 seq,並把 runId 正規化為該工作階段 ready.json 中的值,讓這些列能與契約對上。
已知時,可選的定位欄位會一併附上:
url、hostname、tabId、frameId、windowId、title、stack、errorName、sourceExtensionId、incognito,以及一個自由格式的 data 物件。
dx.signal 事件是執行期針對 dev 迴圈本身提出的結構化診斷。請依它的 code 與 status 分支處理,並把 remediation 呈現給使用者。這個結構是先於它的產生者預留下來的:目前還沒有任何發送端推出,所以今天串流裡的每個事件帶的都是 log。
ReadyFrame 與 capabilities
交握成功後,伺服器會回覆一個 ready 訊框:capabilities 告訴 controller 這個工作階段會接受什麼:eval、storage、reload、可開啟的介面,以及用於深層 DOM 檢查的 deepDom。deepDom 是一個橋接 capability 欄位,不是 CLI 旗標。bufferedFrom 是仍可重播的最舊緩衝 seq。
GapFrame
broker 寧可丟掉記錄也不會卡住,而且它會明說。gap 訊框會回報你少了多少筆記錄,以及原因:reason 是 ring_overflow、rate_limit、disk_slow 或 slow_consumer 其中之一。
CommandFrame 與結果
controller 發出指令時要帶上cmdId、一個 op,以及一個目標情境:
回應是一個結果訊框,帶有相同的
cmdId、ok、可選的 value,以及在相關時出現的 truncated 與 durationMs。指令訊框要求工作階段是以 --allow-control 啟動的,而 eval 另外還要求 --allow-eval。
拒絕碼
當 guest 端拒絕一道指令時,結果訊框的error.code 會在瀏覽器自己那句話旁邊帶上一個機器名稱。請依代碼分支,絕對不要依文字敘述分支:
匯出的常數為
REFUSAL_NEEDS_HEADED_WINDOW、REFUSAL_NEEDS_USER_GESTURE、REFUSAL_SURFACE_NOT_OPEN 與 REFUSAL_API_UNAVAILABLE。
WebSocket 關閉碼
4000 區段的關閉碼都是刻意的拒絕,絕不是傳輸失敗:伺服器的其他訊框
伺服器也會廣播一些 dev 迴圈的訊框,harness 應該要能容忍它們,也可以加以利用:reload:送給 service worker producer 的一次性重新載入訊號,帶有reloadType,值為full、service-worker、content-scripts或page。其中page這一種只做通知。ping:一個保持連線的訊框,用來重置 MV3 service worker 的閒置計時器。忽略它即可。
後續步驟
- 只要 CLI 指令足夠就優先使用它們,從 ready.json 開始。
- 用 錯誤碼 把橋接失敗對應到信封中的錯誤碼。

