浏览器 CDP Supervisor
CDP supervisor 填补了 Kopi Agent 浏览器工具链中两个长期存在的缺口:
- 原生 JS 对话框(
alert/confirm/prompt/beforeunload)会阻塞 页面的 JS 线程。没有 supervisor 时,agent 无法得知对话框 已被打开——后续的工具调用会挂起或抛出难以理解的错误。 - 跨域 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,frameDetachedRuntime.enable——executionContextCreated,consoleAPICalled,exceptionThrownTarget.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,FrameInfotools/browser_dialog_tool.py—browser_dialog工具处理器tools/browser_tool.py—browser_navigatestart-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 测试
用例。