dev、start 與 preview 會為每一次生命週期轉換串流輸出一個 schema-1 影格。每個影格本身就是獨立成行的一個完整結果信封。
開啟這道串流
這道串流由EXTENSION_OUTPUT 環境變數決定。把它設為 json 或 ndjson,影格就會獨佔 stdout:
影格狀態
每個影格的
value 都帶有工作階段身分:command、browser、distPath、pid、port,以及已知時的 readyPath、eventsPath、runId、instanceId 與 toolchainVersion。
在工作階段開始之前就被拒絕的執行只會送出一個 failed 影格,不會有 starting 影格。缺少 manifest、設定檔載入失敗,以及遠端 URL 沒有可用的封存檔,都會以這種方式結束。
編譯失敗
compile-failed 影格會把編譯器輸出放在 value.output 裡,因此你永遠不必去刮 stdout。這段輸出已去除 ANSI 控制碼,並以 2000 個字元為上限。當上限把它截斷時,該影格會設定 truncated: true。
一次工作階段中的第一次失敗使用錯誤碼 E_FIRST_COMPILE,之後每一次都使用 E_COMPILE。
該影格也會帶著 error.details,每條診斷一個條目,各自帶有錯誤碼、檔案和位置,錯誤排在前面,結構見結果信封中的「編譯診斷」一節。清單上限為 20 條,當輸出或清單任一被截斷時,都會設定 truncated: true。
ready 遵循契約
ready 影格在送出之前會先讀取 ready.json。編譯可能成功,而瀏覽器卻拒絕了這個擴充功能,發生這種情況時契約會停留在 error。
這種情況下,串流改為發出一個錯誤碼為 E_READY_ERROR_STATUS 的 failed 影格,並由 value.readyCode 指出契約自身的錯誤碼。
瀏覽器根本沒有啟動,或在擴充功能載入之前就結束時,送達的也是同一個影格。這時 value.readyCode 是 browser_launch_failed 或 browser_exited。Firefox 的除錯器始終沒有回應時,視為啟動失敗。
--chromium-binary 或 --gecko-binary 固定的執行檔有問題時,readyCode 同樣是 browser_launch_failed,但其影格帶 status: "usage" 與 error.code: "E_BROWSER_BINARY_INVALID",這也是每個命令對這種固定路徑給出的代碼。
Chromium 的 dev 工作階段在瀏覽器起來之後 CDP 連線失敗時,仍然會送出 ready,因為瀏覽器在執行。該影格會把故障放在 warnings 裡,形式為 E_CDP_...: message,與契約蓋上的 cdpFaultCode 和 cdpFaultMessage 是同一對值,見 ready.json。在故障修復前,reload 與 HMR 無法接上。
瀏覽器結束
一個背景監看器每秒輪詢一次ready.json,尋找啟動器寫下的結束戳記。當 browserExitedAt 出現時,串流會發出一個 browser-exited 影格。
影格的錯誤碼取決於契約中的證據:
E_PROFILE_LOCKED:契約顯示設定檔被鎖定。瀏覽器根本沒有啟動,另一個工作階段正佔用該設定檔。E_BROWSER_LAUNCH:其餘所有非預期的結束。
value 會帶有 exitCode 與 browserExitedAt。
後續步驟
- 在 ready.json 中閱讀這些影格背後的契約。
- 在 用 agent 驅動 CLI 中了解如何從 agent 驅動整個迴圈。

