第 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。