Web Use 技术规格

公开命名与兼容边界

三个执行 backend

设置只影响新的 WebSession。session 创建后 backend 冻结；失败、超时或 stale 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 绑定 MCP control connection、window_id、exact Page target 和 server-owned page/access revision；缺少、重放、跨连接使用、连接重建或 target replacement 必须在 backend 调用前拒绝。首次 observe 之后，每次 observe、act 和 verify 都重新验证 exact binding。visible Page 继续验证 geometry revision；background Page 通过不改变 tab、store 或窗口焦点的 resolve path 校验 target。跨进程调用必须把 WebSession 保存的 revision 原样交给父 worker，任一不一致即返回 page_context_stale，且不得执行页面动作。

网页 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，不暴露 backend 自带的第二套工具。
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. popup inventory：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. Page Awareness：页面换到 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. 视觉限制：普通 DOM 流截图数为 0；canvas 流每次 observation 最多 1 张。
16. 图片保留：截图只出现在紧邻的一次 provider request；同一请求的文字提示不含原始 bytes/base64，返回或异常后调用方 content 与 ToolReturn 不再持有图片，最终 artifacts 仍为空。
17. 失败诚实性：空 assertion、stale frame、timeout、cancel、target lost 都不能返回 succeeded。
18. Chat 稳定：GUI tool update 不重建历史 message/avatar/markdown DOM。
19. 安装版双窗口事务：只连接默认 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