跳到主要内容

浏览器 CDP Supervisor

CDP supervisor 填补了 Kopi Agent 浏览器工具链中两个长期存在的缺口:

  1. 原生 JS 对话框(alert/confirm/prompt/beforeunload)会阻塞 页面的 JS 线程。没有 supervisor 时,agent 无法得知对话框 已被打开——后续的工具调用会挂起或抛出难以理解的错误。
  2. 跨域 iframe(OOPIF) 对顶层的 Runtime.evaluate 不可见。agent 能在 DOM snapshot 中看到 iframe 节点,但在没有附着到子 target 的 CDP session 之前,无法在其内部点击、输入或 eval。

supervisor 通过为每个浏览器任务保持一条到后端 CDP endpoint 的持久 WebSocket 连接来同时解决这两个问题:把待处理的对话框和 frame 结构 注入 browser_snapshot,并暴露一个 browser_dialog 工具用于显式响应。

后端支持​

后端对话框检测对话框响应Frame 树通过 browser_cdp(frame_id=...) 的 OOPIF Runtime.evaluate
本地 Chrome(--remote-debugging-port)/ /browser connect✓✓ 完整流程✓✓
Browserbase✓(通过 bridge)✓ 完整流程(通过 bridge)✓✓
Camofox✗ 无 CDP(仅 REST)✗通过 DOM snapshot 部分支持✗

Browserbase 的特殊行为。 Browserbase 的 CDP proxy 内部使用 Playwright, 会在约 10 毫秒内自动关闭原生对话框,因此 Page.handleJavaScriptDialog 根本来不及。 supervisor 通过 Page.addScriptToEvaluateOnNewDocument 注入一段 bridge 脚本,用指向 magic host(kopi-dialog-bridge.invalid)的同步 XHR 覆盖 window.alert/confirm/prompt。Fetch.enable 会在这些 XHR 触达网络之前拦截它们——对话框于是变成 supervisor 捕获的一个 Fetch.requestPaused 事件,而 respond_to_dialog 通过 Fetch.fulfillRequest 用一段 JSON body 完成响应,由注入的脚本解码。

从页面的角度看,prompt() 仍然返回 agent 提供的字符串。 从 agent 的角度看,无论哪种方式都是同一个 browser_dialog(action=...) API。

Camofox 不受支持——没有 CDP 接口,仅提供 REST。

架构​

CDPSupervisor​

每个 Kopi Agent task_id 对应一个在后台 daemon 线程中运行的 asyncio.Task。它保持一条到后端 CDP endpoint 的持久 WebSocket 连接,并维护:

  • 对话框队列 —— 带 {id, type, message, default_prompt, session_id, opened_at} 的 List[PendingDialog]
  • Frame 树 —— 包含父子关系、URL、origin、是否为跨域子 session 的 Dict[frame_id, FrameInfo]
  • Session 映射 —— Dict[session_id, SessionInfo],以便交互工具在执行 OOPIF 操作时 能路由到正确的已附着 session
  • 最近的 console 错误 —— 保留最近 50 条的环形缓冲区,用于诊断

附着时订阅:

  • Page.enable —— javascriptDialogOpening, frameAttached, frameNavigated, frameDetached
  • Runtime.enable —— executionContextCreated, consoleAPICalled, exceptionThrown
  • Target.setAutoAttach {autoAttach: true, flatten: true} —— 暴露子 OOPIF target;supervisor 会在每个 target 上 启用 Page+Runtime

通过 snapshot 锁实现线程安全的状态访问;工具处理器(同步)读取 冻结的 snapshot,无需 await。

生命周期​

  • 启动: SupervisorRegistry.get_or_start(task_id, cdp_url) —— 由 browser_navigate、Browserbase session 创建、 /browser connect 调用。幂等。
  • 停止: session 拆除或 /browser disconnect。取消 asyncio 任务, 关闭 WebSocket,丢弃状态。
  • 重新绑定: 如果 CDP URL 发生变化(用户重新连接到新的 Chrome), 旧的 supervisor 会被停止并启动一个全新的实例——状态绝不会跨 endpoint 复用。

对话框策略​

可通过 browser.dialog_policy 下的 config.yaml 配置:

  • must_respond(默认)—— 捕获并在 browser_snapshot 中呈现,等待显式的 browser_dialog(action=...) 调用。若 300 秒安全超时后仍无响应,则自动关闭并记录日志。 这样可以防止有缺陷的 agent 无限期卡住。
  • auto_dismiss —— 记录并立即关闭;agent 事后通过 browser_snapshot 内的 browser_state 看到它。
  • auto_accept —— 记录并接受(适用于 beforeunload,这类流程希望干净地 导航离开)。

策略按任务设定;不支持按对话框单独覆盖。

Agent 接口​

browser_dialog 工具​

browser_dialog(action, prompt_text=None, dialog_id=None)
  • action="accept" / "dismiss" → 回应指定的或唯一的待处理对话框(必填)
  • prompt_text=... → 提供给 prompt() 对话框的文本
  • dialog_id=... → 当多个对话框排队时用于消歧(少见)

该工具只负责响应。agent 在调用前从 browser_snapshot 的输出中读取待处理的对话框。

browser_snapshot 扩展​

当 supervisor 已附着时,向现有 snapshot 输出中添加三个可选字段:

{
"pending_dialogs": [
{"id": "d-1", "type": "alert", "message": "Hello", "opened_at": 1650000000.0}
],
"recent_dialogs": [
{"id": "d-1", "type": "alert", "message": "...", "opened_at": 1650000000.0,
"closed_at": 1650000000.1, "closed_by": "remote"}
],
"frame_tree": {
"top": {"frame_id": "FRAME_A", "url": "https://example.com/", "origin": "https://example.com"},
"children": [
{"frame_id": "FRAME_B", "url": "about:srcdoc", "is_oopif": false},
{"frame_id": "FRAME_C", "url": "https://ads.example.net/", "is_oopif": true, "session_id": "SID_C"}
],
"truncated": false
}
}
  • pending_dialogs —— 当前正阻塞页面 JS 线程的对话框。 agent 必须调用 browser_dialog(action=...) 来响应。在 Browserbase 上为空, 因为它们的 CDP proxy 会在约 10 毫秒内自动关闭对话框。

  • recent_dialogs —— 最多保留 20 条最近关闭对话框的环形缓冲区,带有一个 closed_by 标记:"agent"(我们响应了)、"auto_policy"(本地的 auto_dismiss/auto_accept)、"watchdog"(must_respond 超时触发),或 "remote"(浏览器/后端替我们关闭了它,例如 Browserbase)。 Browserbase 上的 agent 正是通过它来了解到底发生了什么。

  • frame_tree —— 包含跨域(OOPIF)子 frame 的 frame 结构。 上限为 30 条 + OOPIF 深度 2,以限制广告繁多的页面上的 snapshot 体积。 truncated: true 会在达到上限时提示;需要完整树的 agent 可以用 browser_cdp 配合 Page.getFrameTree。

这些内容都不需要新增工具 schema——agent 读取它本来就会请求的 snapshot 即可。

可用性门控​

两个接口都以 _browser_cdp_check 为前提(只有在 CDP endpoint 可达时 supervisor 才能运行)。在 Camofox / 无后端的 session 中,对话框工具会被隐藏, snapshot 也不会包含新增字段——不会造成 schema 膨胀。

跨源 iframe 交互​

browser_cdp(frame_id=...) 会路由 CDP 调用(尤其是 Runtime.evaluate), 它通过 supervisor 已建立连接的 WebSocket,使用 OOPIF 的子级 sessionId。agent 会从 browser_snapshot.frame_tree.children[] 中选取 frame_ids(其中 is_oopif=true),并将其 传递给 browser_cdp。对于同源 iframe(没有专用的 CDP session), agent 会改用来自顶层 Runtime.evaluate 的 contentWindow/contentDocument —— 当 frame_id 属于 非 OOPIF 时,supervisor 会报出一个指向该回退方案的错误。

在 Browserbase 上,这是与 iframe 交互的唯一可靠途径 —— 无状态的 CDP 连接(按 browser_cdp 调用建立)会遇到签名 URL 过期的问题,而 supervisor 的长连接则能保持有效的 session。

文件布局​

  • tools/browser_supervisor.py — CDPSupervisor, SupervisorRegistry, PendingDialog, FrameInfo
  • tools/browser_dialog_tool.py — browser_dialog 工具处理器
  • tools/browser_tool.py — browser_navigate start-hook(启动钩子)、browser_snapshot 合并、/browser connect 重新附加、_cleanup_browser_session 清理
  • toolsets.py — 在 browser、kopi-acp、kopi-api-server 以及核心 toolsets 中注册 browser_dialog(取决于 CDP 可达性)
  • kopi_cli/config.py — browser.dialog_policy 和 browser.dialog_timeout_s 的默认值

非目标​

  • Camofox 的检测/交互(上游缺口,另行跟踪)
  • 向用户实时流式传输 dialog/frame 事件(需要 gateway 钩子)
  • 跨 session 持久化 dialog 历史(仅限内存)
  • 针对每个 iframe 的 dialog 策略(agent 可以通过 dialog_id 来表达)
  • 取代 browser_cdp —— 它仍作为处理长尾场景(cookies、视口、网络限速)的逃生舱

测试​

单元测试(tests/tools/test_browser_supervisor.py)使用一个 asyncio 模拟 CDP 服务器,该服务器实现了足够的协议,以覆盖所有状态转换: attach、enable、navigate、dialog 触发、dialog 关闭、frame attach/detach、 子级 target attach、session 拆卸。真实后端 E2E(Browserbase + 本地 Chromium 系列浏览器)需手动执行 —— 通过 /browser connect 连接到 一个实时的 Chromium 系列浏览器,并执行上文所述的 dialog/frame 测试 用例。