Web Use 技术规格

公开命名与兼容边界

三个执行 backend

设置只影响新的 WebSession。session 创建后 backend 冻结；失败、超时或 stale frame 都不能自动切换 backend，避免重复点击和重复提交。

官方 MCP backend 的每个 WebSession 独占一个私有 MCP 进程，用 npx --prefer-offline 启动。两个包都固定到精确版本，缓存中的副本可以直接使用，不再向 registry 校验；因此网络很慢或断开时，启动不会超过 MCP 启动超时。启动超时后，在它自己的 event loop 上取消挂起的 supervisor，在 loop 关闭前结束 npx 子进程。私有进程之后停止时，同一 WebSession 的下一次 observe 启动新进程并重新绑定同一个 exact target，这次重启是只读的。act 绝不通过需要重启的进程写入，因为 upstream ref 没有随进程保留：它返回 computer_use_backend_unavailable、action_dispatched=false、observe_required=true，并使当前 frame 失效。backend 始终不变。

BrowserContext、Window、顶部标签与 Page

目标结构同时返回 tab_entries 和 pages：前者回答窗口如何排列，后者列出 Agent 可以控制的网页。一个分屏 tab entry 有两个 Page，因此示例窗口是 3 个顶部标签项、4 个 Page。single entry ID 直接取 tab:<tab_id>，split entry ID 直接取 group:<CenterTabGroup.id>；pane ID 由 group 与当次 order 派生。这里不增加数据库表、第二套 registry 或后台进程。下面只展示 identity、布局和 token；title、origin、opener 与 capabilities 延用现有 Page 字段。

{
  "browser_context_id": "ctx_1",
  "window_id": "win_1",
  "inventory_revision": 42,
  "active_tab_entry_id": "group:g3",
  "focused_page": "p4",
  "tab_entries": [
    { "id": "tab:w:google", "mode": "single", "pages": ["p1"] },
    { "id": "tab:w:github", "mode": "single", "pages": ["p2"] },
    {
      "id": "group:g3",
      "mode": "split",
      "pages": ["p3", "p4"],
      "split": {
        "axis": "horizontal",
        "ratio": 0.5,
        "panes": [
          { "pane_id": "pane:g3:0", "order": 0, "page": "p3" },
          { "pane_id": "pane:g3:1", "order": 1, "page": "p4" }
        ]
      }
    }
  ],
  "pages": [
    { "page": "p1", "tab_id": "w:google", "tab_entry_id": "tab:w:google", "visible": false, "focused": false, "placement": { "mode": "single" }, "page_context_token": "pct_…" },
    { "page": "p2", "tab_id": "w:github", "tab_entry_id": "tab:w:github", "visible": false, "focused": false, "placement": { "mode": "single" }, "page_context_token": "pct_…" },
    { "page": "p3", "tab_id": "w:bilibili", "tab_entry_id": "group:g3", "visible": true, "focused": false, "placement": { "mode": "split", "pane_id": "pane:g3:0", "order": 0 }, "page_context_token": "pct_…" },
    { "page": "p4", "tab_id": "w:youtube", "tab_entry_id": "group:g3", "visible": true, "focused": true, "placement": { "mode": "split", "pane_id": "pane:g3:1", "order": 1 }, "page_context_token": "pct_…" }
  ]
}

axis 与 order 是规范字段；left/right/top/bottom 由当次 bounds 派生，不能作为 Page identity。当前 UI 主要使用水平双 pane，但接口不把“右侧网页”写成固定目标。移动 Page、调整比例或切换 active tab entry 后，下一次 list_pages 返回新布局并递增 inventory_revision；受影响的 visible Page 继续通过 geometry revision 阻止旧布局坐标生效。一个窗口最多只有一个 focused_page，但 active split 中可以有两个 visible=true 的 Page。

开源、开放接口与不可直接复用部分

这里没有“CDP 只能由 Claude 使用”的限制。Anthropic 官方工具编排、扩展实现和产品权限层没有公开可复用源码；截图与坐标点击所用的 CDP 命令是公开接口。第三方 clean-room 项目可以作为实现参考，但不代表 Anthropic 官方实现已经开源。

Agent 只需要五个 command

web_use({ command: "list_pages" })
web_use({ command: "observe", page_context_token: "pct_…", arguments: { detail: "interactive" } })
web_use({ command: "act", web_session_id: "cs_…", arguments: { action: "click", expected_frame_id: "f_…", ref: "e1" } })
web_use({ command: "verify", web_session_id: "cs_…", arguments: { action: "verify", expected_frame_id: "f_…", assertion: "text_contains", value: "Saved" } })
web_use({ command: "close", web_session_id: "cs_…" })

list_pages 的目标返回全部已登记 OpenProgram window 的 group-aware snapshot：windows[] 分别保存每个窗口的 window_id、inventory_revision、active/focused identity 与 tab_entries；扁平 pages 让 Agent 直接选择 Page，每项携带所属 window_id。原顶层窗口字段继续表示发起任务的 primary window，以兼容现有调用方。每个 Page 包含稳定的 tab_id、所属 tab_entry_id、placement、title、origin、focused、visible、可选 opener_tab_id 与一次性 page_context_token。Agent 不用 window、tab entry 或 pane 执行动作，只在首次 observe 中原样回传目标 Page token。token 绑定调用 owner、window_id、exact Page target 和 server-owned page/access revision；缺少、重放、跨 owner 使用、连接重建或 target replacement 必须在 backend 调用前拒绝。同一 owner 对同一 Page 和同一 backend 重复发起不带 web_session_id 的 observe 时，Runtime 复用已有 WebSession 并返回同一 ID；不同 owner 或不同 backend 仍按排他 lease 拒绝。聊天 owner 固定为当前 session 与 assistant turn；turn 无论正常完成、重试、取消或异常结束，dispatcher teardown 都释放该 owner 的全部 WebSession 和 Page lease，不依赖模型显式调用 close。首次 observe 之后，每次 observe、act 和 verify 都重新验证 exact binding。visible Page 继续验证 geometry revision；background Page 通过不改变 tab、store 或窗口焦点的 resolve path 校验 target。web_use 的 Page inventory、WebSession registry 与 renderer WebSocket registry 必须在 worker 主进程内执行：聊天中的 runtime card 可以保留 agentic function UI，但不得把该工具迁移到隔离子进程。GUI Agent Harness 的长循环如在子进程运行，只能经父进程 bridge 调用同一 worker-owned WebSession，并原样传递 revision；任一不一致即返回 page_context_stale，且不得执行页面动作。

list_pages 不依赖发起窗口。发起窗口或本轮 binding 断开时，worker 列出其余所有已登记窗口；workflow 子进程仍限定在自己的发起窗口内，只会再次列出该窗口。没有任何 Desktop 窗口登记时（例如 worker 或 App 重启后 App 正在重新打开），发现流程最多等待 20 秒，等窗口重新登记；仍然没有就返回 desktop_unavailable 与 retry_command=list_pages，而不是抛出异常。在线的发起窗口若 inventory 请求失败，仍立即失败，绝不提升其他窗口。

page_context_token 在每个命令中都指定它的 Page。act 或 verify 只带 token、没有存活的 web_session_id 时，复用该 token 已打开的存活 WebSession。token 尚未使用时，Runtime 先用一次只读 observe 打开 WebSession；随后 navigate、screenshot、wait 与不带 ref 的 verify 在这个 frame 上继续执行。ref 或坐标动作返回这次 observation 并带 action_performed=false，因为它们的目标必须来自调用方读过的 observation。token 绝不回退到该 owner 在其他 Page 上最近的 WebSession；与 token 同时出现的未知 web_session_id 让位于 token。

已结束的句柄可以恢复，但不会重放。registry 在内存中有界地只保留已结束 WebSession（turn 结束、binding 丢失、启动失败）以及过期或被已结束 WebSession 消费的 token 的精确 window_id/tab_id。同一个 chat 的各个 turn owner 跨 turn 共用一个作用域；其他 owner 只匹配自己。之后同一作用域内的 page_context_not_found、page_context_consumed 或 web_session_not_found 会带 recovery_tab_id、recovery_window_id 与 recovery_command=observe。Agent tool 随即列出 Page，用新 token observe 这个精确 tab，并返回带 recovered_page=true 与 previous_action_replayed=false 的 observation。它绝不重放上一个命令，也绝不打开它不知道的 URL。调用方主动 close 的 WebSession 不会被记住。没有记住的 tab 时（例如 worker 重启清空了 registry），失败结果带当前 pages 与新 token，以及一条指令：用任务 Page 的 token 执行 observe。这类失败都带一条 message，写明下一次调用。

网页 popup 创建独立 web tab 和独立 WebContents/Page，并保存 opener_tab_id。popup 不替换 opener，也不隐式转移现有 WebSession；下一次 list_pages 发现 popup，Agent 使用它的 token 显式建立新 session。GUI Agent Harness 在每次写动作后刷新有界 Page inventory，并只通过 token 切换 Page。跨窗口聚合只扩展发现范围，不改变 exact Page binding、Page lease 或 session 生命周期。

每个可见 web tab 还持有 renderer-owned 单调 geometry_revision。现有 bounds lifecycle 在 mount、resize、ancestor scroll、pane 重排、窗口 resize、pane 显隐与 transfer 时测量 viewport-relative bounds；只有规范化后的 x/y/width/height 或应用内可见性变化才递增 revision，focus 变化不递增。发送 turn 时，surface ref 带当前 revision；preview 必须在调用 native preview 前验证并回显同一 revision。WebSession 保存该值，后续 observe、act 和 verify 经父子进程 bridge 原样传到 exact renderer；renderer 在调用 Electron activate 前再次比较。缺失的旧客户端 revision 保持兼容，但一旦 capability 含有非零 revision，任何不一致都返回 page_context_stale，不得调用 native preview、activate 或 backend。Page identity 与 lease 不因单纯 geometry 变化而重建；调用方重新 list/observe 后继续使用同一 Page。这里的可见性是 OpenProgram 内部 pane 布局状态，不是 macOS 窗口层级、遮挡或最小化状态。

成本与功能边界

• Page 在左、右、上或下由真实 pane geometry 计算；不写死“右侧”。
• 操作 exact Page 不要求 OpenProgram 或目标 pane 置前，不使用 OS 鼠标、桌面坐标或整屏截图。
• 同一 Page 的写动作排他；任何写动作后重新观察。
• 截图不得写入本地 artifact、最终结果、completion evidence、tool-result 文本或 DAG prompt text；本地只保留“已附图”、frame 与 viewport 元数据。图片已发送给所选模型 provider 时，provider 侧保留规则仍由对应服务条款决定。
• 正常返回、provider error、timeout 与 cancel 都执行同一释放逻辑；不增加 retention 设置项、后台清理进程或图片目录。
• 登录、CAPTCHA、敏感提交和不可逆动作返回 needs_user。
• 网页内容是不可信数据，不能改变 target、权限、mode 或动作数量。

实施顺序

发布前必须证明

1. 工具面：浏览器控制只有一个 web_use。Desktop Page inventory 已登记时即可使用；turn-start preview 只是当前 Page 的上下文增强，单次 preview 失败不得移除工具或改为公开会启动独立浏览器的旧工具。Agent 先调用 list_pages，再用返回的 page_context_token 选择 exact Page。
2. Page 隔离：list_pages 可以列出其他窗口的 Page；选择 A 后，对 B、chat Page 和其他窗口未选 Page 的读写调用次数都是 0。
3. 分组结构：Google、GitHub、Bilibili/YouTube 分屏返回 3 个有序 tab_entries 和 4 个唯一 Page；第三项为 split，pane order 与实际 UI 一致。
4. 布局与身份：交换 split pane、调整 ratio 或拆分后，Page identity 保持且 inventory_revision 更新；受影响 visible Page 的旧 geometry 在写入前 stale，不得新建另一套 split action。
5. 可见与焦点：active split 的两个 Page 都是 visible，只有一个 focused；前两个 single Page 是 background。切换 active entry 后下一 snapshot 反映新状态。
6. 弹窗清单：A 打开的 popup C 单独出现并带 opener_tab_id=A；每个 token 只消费一次。
7. 后台 Page：选择 B 后读取和动作只到达 B；active tab、visible ids、BrowserWindow focus 与系统鼠标均不变化。
8. popup 切换：A 的 session 不因 C 创建而改绑；GUI Agent 只有选择 C 的 token 后才建立 C session，关闭 C 后其 token/session 在下一动作前失效。
9. backend 冻结：设置变更不影响当前 WebSession，只影响下一 session。
10. 副作用唯一：backend failure 不触发另一 backend；一个 Action 最多一次真实写入。
11. 跨 backend 一致：同一任务得到相同 Page/frame 生命周期、权限、reason code 和 verification。
12. 页面感知：页面换到 chat 左侧或右侧后，下一 turn relation 与 preview 正确更新。
13. 跨窗口发现：两个已登记 OpenProgram window 返回两个有序 window snapshot；同名 tab/page 不合并，每个 token 仍解析到原 connection、window_id 与 target。
14. 窗口状态独立：DOM/ref 与 viewport screenshot 直接作用于相同 Page/WebContents；macOS 窗口层级、遮挡、位置与最小化状态不进入 Web Use 的选择、截图或动作条件，且没有窗口 focus、bringToFront()、整屏截图或 OS input 调用。
15. Agent 光标：三个 backend 的 click command 都只在 exact Page 内临时启用捕获监听器；真实 pointer event 到达时，在该 viewport 坐标显示无文本、aria-hidden、pointer-events:none 的光标与点击波纹，并在 900ms 内移除。用户点击、失败且未产生 pointer event 的动作、其他 Page 和系统鼠标不受影响；反馈渲染失败不得改变 click 结果。
16. 视觉限制：普通 DOM 流截图数为 0；canvas 流每次 observation 最多 1 张。
17. 图片保留：截图只出现在紧邻的一次 provider request；同一请求的文字提示不含原始 bytes/base64，返回或异常后调用方 content 与 ToolReturn 不再持有图片，最终 artifacts 仍为空。
18. 失败诚实性：空 assertion、stale frame、timeout、cancel、target lost 都不能返回 succeeded。
19. Chat 稳定：GUI tool update 不重建历史 message/avatar/markdown DOM。
20. 安装版双窗口事务：只连接默认 18100 的 /Applications/OpenProgram.app，通过正式 preload transfer API 创建真实隐藏目标窗口；目标 renderer 完成 inspect/accept/stage 后由源端拒绝临时 payload，事务必须回滚并关闭目标窗口。验收前后的窗口集合、源窗口 tab 状态和持久存储必须一致。

Backend parity suite 的规范矩阵

同一组用例必须通过 WebUseSessionRegistry.execute() 依次运行 playwright_mcp、chrome_devtools_mcp 与 open_claude_chrome 的真实 adapter class。官方 MCP 的进程和网络边界可由记录调用的 test client 代替，但不得用三个同构 fake adapter 代替生产映射。矩阵比较 OpenProgram 的规范化结果，不比较上游特有的 ARIA 文本、ref 名称或诊断文字。

当前实现证据

表中的“已实现”表示当前 multi-backend、geometry、transfer、视觉 artifact 生命周期与 parity suite。专用 permission card 仍属于 UI 后续项，不是当前功能实现的发布条件。当前实现与验证证据维护在 实施记录。

需要实现者展开时再读

官方参考

• Playwright BrowserContext 与 Playwright Pages
• Microsoft Playwright MCP 与 官方 MCP introduction
• Claude Code Desktop Browser、Claude Code with Chrome 与 Claude Code license
• Chrome DevTools Protocol、Page.captureScreenshot 与 Input.dispatchMouseEvent
• Electron Debugger、Chrome debugger API 与 Native Messaging
• Anthropic Computer Use
• OpenAI Computer Use