第 1 步：用 capabilities 握手
在做任何假設之前，先問問引擎它會說什麼：value 為：
envelopeSchema 與 readySchemaVersion 對照你的解析器所預期的版本。outputJsonCommands 是從實際註冊的指令讀出來的，因此它永遠不會和你正在執行的這個版本脫節。
第 2 步：以機器可讀輸出啟動工作階段
--allow-control 會解鎖一組有邊界的動作動詞（storage、reload、open、inspect）。只有在你確實需要 extension eval 時才加上 --allow-eval，它會執行任意程式碼，並寫出一個 0600 權限的工作階段權杖。
在 --output json 之下，指令會印出一個 started 信封，失敗同樣以信封形式回來。人類可讀的文案會移到 stderr，因此 stdout 始終可以解析。
想逐一影格追蹤整個工作階段，就在環境中設定 EXTENSION_OUTPUT=ndjson，並讀取生命週期串流。
第 3 步：在 runtime attached 設下關卡
就緒分成兩個階段，而太早動作是 agent 最常見的失敗方式：ready.json回報status: "ready"。這只代表編譯完成，僅此而已。- 契約帶有
runtime: "attached"與executorAttachedAt。這時 service worker 已經連上，可以被驅動了。
dist/extension-js/chromium/ready.json，直到 runtime 等於 "attached" 之後，再執行任何動作動詞。關於讓你避開過期契約的新鮮度與 pid 存活規則，請見 ready.json。
第 4 步：執行動作並讀取信封
每個動作動詞都接受--output json，並回一個 schema-1 的結果信封：
ok 與 error.code 分支，絕不要依 error.message。錯誤碼表在各版本之間保持穩定。
用 —ai-help 探索 CLI
extension --ai-help --output json 會印出一份機器可讀的自我描述。有兩個機制對呼叫端很重要：
--ai-help會繞過引數解析器。它在任何子指令解析之前就執行，所以即使呼叫方式本身無效，它也照樣有效。- 酬載可能超出一個管線緩衝區，因此行程會在結束前先把 stdout 排空。請一路讀到 EOF。
capabilities.readyContract 這一區會列出契約路徑、狀態、欄位與事件類型，因此 agent 不必依賴這個文件網站也能自行設定。
讓 agent 保持誠實的規則
- 永遠不要解析漂亮的終端機輸出。你需要的每一項事實都有對應的機器可讀介面。
- 在信任
ready.json之前，先確認pid是否存活以及契約是否夠新。 - 用
runId把ready.json、events.ndjson與logs.ndjson串起來。 - 用
ready.json裡的browserPid關閉瀏覽器，絕不要靠比對行程名稱。 - 把未知的信封欄位視為附加內容。schema 只會生長，不會破壞相容性。
下一步
- 把契約細節放在手邊：ready.json 與結果信封。
- 用 CI 範本把同一套迴圈接進 CI。