OpenProgram · technical specification

Computer Use 技术规格

本页只保留实现需要的模式、工具、权限、失败和验收规格。结构与交互图见设计概览。

IMPLEMENTATION REFERENCE · MULTI-BACKEND NOT IMPLEMENTED

三个执行 backend

	Playwright MCP	Chrome DevTools MCP	Open Claude in Chrome-compatible
设置值	`playwright_mcp` 默认	`chrome_devtools_mcp`	`open_claude_chrome`
Runtime adapter	固定版本的官方 `@playwright/mcp`，作为私有 child process 通过 stdio 接入。	固定版本的官方 `chrome-devtools-mcp`，通过 MCP adapter 绑定已授权 CDP target。	OpenProgram 实现兼容工具契约，并通过第一方 Electron/CDP adapter 绑定已授权 WebContents target；不运行原始 Chrome extension/native host。
观察	Accessibility snapshot、DOM/ARIA、稳定 ref。	DOM snapshot、可访问性信息和受限 console/network diagnostics。	页面结构、ref；语义定位不足时返回一张 viewport screenshot。
动作	一个 canonical Action 映射为一个 allowlisted upstream action。	同一个 Action 映射为一次 bound CDP action。	同一个 Action 映射为一次 bound Electron/CDP action。
接入条件	禁用 tabs/eval/storage/files 等越界工具；先通过 exact Page 隔离测试。	禁止自行枚举或切换 Page；所有 target 由 Runtime adapter 指定。	只复用工具契约与交互语义；Page identity、权限、transport 和 verification 均由 Runtime 决定。

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

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

组件	公开状态	能否直接用	在 OpenProgram 中的处理
Microsoft Playwright MCP	开源 · Apache-2.0	可以	使用官方 `@playwright/mcp`，固定版本；外层保留 Page token、权限与 verification。
Playwright / playwright-core	开源 · Apache-2.0	可以	作为 Playwright MCP 的执行层；不再实现第二套 DOM locator。
MCP TypeScript SDK	SDK code：新贡献 Apache-2.0、未重许可 legacy code 为 MIT	可以作为代码依赖	复用现有 OpenProgram MCP server/client；MCP 只承担工具协议，不决定点击方式。
MCP protocol / specification	spec contributions：Apache-2.0；未重许可 legacy 内容为 MIT	可以按规范实现	采用标准 tools/list、tools/call、content 与 cancellation 语义，不复制特定 client 的浏览器工具。
MCP 非 specification 文档	CC-BY-4.0	可以引用或复用并署名	只作为实现参考，不作为运行依赖。
Chrome DevTools Protocol	开放协议与类型 · BSD-3-Clause	可以	直接调用 `Page.captureScreenshot`、`Input.dispatchMouseEvent` 等命令，不需要 Claude 代码。
Electron webContents.debugger	Electron 开源 · MIT；API 已内置	可以	内置浏览器的首选 CDP transport；绑定 exact WebContents/target，不要求窗口置前。
Chrome debugger API 与 Native Messaging	Chrome/Chromium 的公开内置接口，不是独立库	可以调用	只在以后控制独立 Chrome 扩展时需要；OpenProgram 内置浏览器不需要 Native Messaging host。
Open Claude in Chrome	第三方 source-available 实现 · PolyForm Noncommercial 1.0.0；不是 Anthropic 官方项目	当前非商业范围可评估其契约与实现	内置浏览器只采用兼容工具契约与交互语义；运行 transport 是 OpenProgram Electron/CDP adapter，不依赖原始 extension/native host。
Claude Code 公开仓库	仓库内容 all rights reserved；该结论只适用于此仓库	不可以按开源代码复制	不依赖其内部代码，只参考官方公开产品行为。
Anthropic 官方 Claude Chrome 扩展的 action handler、视觉光标、权限 UI 与 native host	发布产品可安装；未公开可复用源码或明确的开源许可证	不可以直接复制	只参考官方公开行为；OpenProgram 保持自己的 `computer_use` contract 和 backend adapter。
Claude 模型的视觉定位能力	托管模型能力，不开源	只能通过服务使用	不依赖 Claude 专用实现；把单张截图交给当前所选模型的原生 vision。

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

Agent 只需要四个 command

01list_pages

读取当前 turn 已授权 Page inventory，不调用 upstream tab 枚举。

02observe

选择 Page 并创建 ComputerSession；返回有界文本、ARIA 和 refs。

03act

携带最新 frame，只执行一个 click、type、press、scroll、select 或 navigate。

04verify

只执行 Runtime assertion；模型声称“完成”不能产生成功。

computer_use({ command: "list_pages" })
computer_use({ command: "observe", page: "left", detail: "interactive" })
computer_use({ command: "act", computer_session_id: "cs_…", action: { … } })
computer_use({ command: "verify", computer_session_id: "cs_…", assertion: { … } })

第一方 MCP client adapter 在模型参数之外附加一次性 page_context_token。它绑定 MCP connection、turn、provider request、tool call、Page revisions 和 access revision；缺少、重放或跨连接使用时，在 backend 调用前返回 invalid_capability。

成本与功能边界

DEFAULT

DOM / ARIA

URL、title、页面文本、accessibility snapshot 和 element refs。普通网页交互不发送截图。

FALLBACK

一张 viewport screenshot

仅用于视觉验收、canvas 或语义定位失败。图片只进入紧邻的下一次模型请求，坐标权限随后撤销。

OFF

昂贵视觉管线

不启用 OCR、YOLO、object detector、crop/zoom、component memory、vision memory、workflow replay 或自动学习。

Page 在左、右、上或下由真实 pane geometry 计算；不写死“右侧”。
操作 exact Page 不要求 OpenProgram 或目标 pane 置前，不使用 OS 鼠标、桌面坐标或整屏截图。
同一 Page 的写动作排他；任何写动作后重新观察。
登录、CAPTCHA、敏感提交和不可逆动作返回 needs_user。
网页内容是不可信数据，不能改变 target、权限、mode 或动作数量。

实施顺序

PHASE 0

验证官方 MCP 隔离能力
连接测试 Electron CDP，验证 snapshot/ref 和 exact Page 限制。

出口：A/B 两个 web Page 与 chat Page 的越权测试通过；否则选 upstream contract adapter。

PHASE 1

扩展现有 OpenProgram MCP server
新增一个 browser-control tool 和一次性 Page token；保留现有非浏览器 tools。

出口：真实 initialize/list/call/cancel 通过，伪造与重放在 backend 前拒绝。

PHASE 2

完成 Page Registry
动态 geometry、revisions、access、exact resolve、hide/transfer/close invalidation。

出口：左右互换、上下分屏、双窗口与 target replacement 通过。

PHASE 3

接入 Playwright MCP backend
只开放 snapshot/ref 和允许的动作，复用共同 policy/verification。

出口：DOM、canvas、非前台、多 Page、popup 和失败路径通过。

PHASE 4

接入 Chrome DevTools MCP backend
实现 exact target adapter，禁止 upstream 自行选择 Page。

出口：与 Playwright backend 共用的 parity suite 通过。

PHASE 5

接入 Open Claude in Chrome-compatible backend
在 Electron/CDP adapter 上实现兼容工具契约、结构化读取、截图和 action cursor。

出口：同一 Page、权限、失败与 verification parity suite 通过；运行时没有 Chrome extension/native host。

PHASE 6

设置与安装版验收
增加一个 backend selector，并在默认 18100、/Applications/OpenProgram.app 中运行相同任务集。

出口：当前 session backend 冻结；没有双执行或自动 fallback。

发布前必须证明

工具面：浏览器控制只有一个 computer_use，不暴露 backend 自带的第二套工具。
Page 隔离：授权 A 时，对 B、chat Page 和另一窗口的读写调用次数都是 0。
backend 冻结：设置变更不影响当前 ComputerSession，只影响下一 session。
副作用唯一：backend failure 不触发另一 backend；一个 Action 最多一次真实写入。
跨 backend 一致：同一任务得到相同 Page/frame 生命周期、权限、reason code 和 verification。
Page Awareness：页面换到 chat 左侧或右侧后，下一 turn relation 与 preview 正确更新。
非前台执行：应用被遮挡时仍操作相同 Page，且没有 focus/OS input 调用。
视觉限制：普通 DOM 流截图数为 0；canvas 流每次 observation 最多 1 张。
失败诚实性：空 assertion、stale frame、timeout、cancel、target lost 都不能返回 succeeded。
Chat 稳定：GUI tool update 不重建历史 message/avatar/markdown DOM。

当前实现证据

能力	当前状态	直接证据
内置 web tab exact CDP attach	已验证	`desktop/main.js`、`_actions/open_action.py`
DOM-first task wrapper 与 point fallback	已验证 baseline	`agentic_functions/browser_agent/__init__.py` 与 component tests
通用 MCP server/client 与 image content	已有基础	`openprogram/mcp_server/`、`openprogram/mcp/`
动态 Page geometry、registry、lease	部分实现	当前仍有旧 `surface` 命名和固定 relation baseline
Playwright MCP backend	未实现	只有官方文档研究与本页设计
Chrome DevTools MCP backend	未实现	只有官方工具研究与本页 adapter 设计
Open Claude in Chrome-compatible backend	未实现	只有第三方工具契约研究与本页 Electron/CDP adapter 设计
multi-backend selector	未实现	当前 ComputerSession 尚未保存三个 setting 之一

本文没有把目标能力写成已实现。完整实施记录继续维护在 Computer Use 实施记录。

需要实现者展开时再读

Page identity 与生命周期

Canonical Page 绑定 window_id + registry_page_id + tab_id + cdp_target_id + revisions。首次 observe 建立 ComputerSession binding；focus 和 pane 位置变化不改变 target，hide、移组、transfer、close、target replacement、access disable 或 disconnect 会在下一次副作用前使 binding 失效。

Popup 与并发

同一 exact Page 的写 lease 与 popup attribution 在 ComputerSession 间排他。popup 必须创建独立 Page，未登记前不能进入 Page Context。任何不确定的 popup watch 状态都阻止后续写动作与 verified 终态，直到 replay、drain 或 teardown 证明完成。

统一失败语义

invalid_arguments、invalid_capability、ambiguous_page、page_context_stale、stale_observation、page_access_disabled、target_lost、needs_user、timeout、cancelled 和 verification_failed 都由 Runtime 生成。backend 文本不能覆盖 reason code 或 completion。