第 9 章：内嵌浏览器、Design Mode 与 Computer Use

目标：理解 Orca 如何把真实 Chromium 页面变成 workspace 资源，并安全地同时服务用户、Agent、CLI 和移动端。

1. Browser tab 不是 iframe

Orca 的内嵌浏览器需要真实登录态、下载、弹窗、证书、DevTools/CDP、截图和自动化。它由 Electron guest WebContents 承载，而 React renderer 只渲染控制 UI 和位置。

2. BrowserManager 的职责

browser-manager.ts 管理：

• page 创建、注册、关闭和 worktree 归属；
• navigation state、title、favicon、loading；
• guest bounds、visible/focus；
• popup、permission、certificate；
• download 路径与冲突预留；
• session profile、user agent、mobile emulation；
• renderer 事件广播；
• automation 临时可见性 token。

guest 的所有权在 main，因为 renderer reload 不应自动摧毁浏览器 session。

3. Workspace-scoped browser identity

一个 browser tab 同时有：

• Orca UI tabId；
• browserWorkspaceId；
• main 分配的 browserPageId；
• Electron webContentsId；
• session partition/profile。

Agent/CLI 使用 browserPageId 作为目标，不应依赖 UI tab 下标。下标和 snapshot element ref 都会因导航或 tab 切换失效。

4. Session 与 Cookie 导入

Browser session registry 为每个 profile 创建持久 partition，并单独保存 metadata。Cookie import 支持 Chromium 系浏览器、Firefox、Safari 等不同格式与平台加密方式。

导入流程必须处理：

• 用户选择的 profile；
• 复制 SQLite，避免锁住真实浏览器数据库；
• macOS Keychain / Linux key / Windows DPAPI；
• cookie domain、SameSite、expiry 与 URL 重建；
• schema 差异和无效记录；
• 不在日志中泄露 cookie value。

该系统位于 browser-cookie-import.ts。

5. CDP Bridge：结构化浏览器控制

CdpBridge 通过 Chrome DevTools Protocol 提供：

• DOM / accessibility snapshot；
• click、focus、type、key；
• screenshot、PDF；
• navigation 与 wait；
• console/network capture；
• JS eval；
• upload、storage、cookie。

它维护每个 tab 的命令队列和 capture log。命令必须串行化到正确 page；导航后旧 element ref 失效，调用者需要重新 snapshot。

6. AgentBrowserBridge：CLI 与内嵌页的桥

Agent-facing 命令最终进入 AgentBrowserBridge：

1. 解析 Agent Browser CLI args；
2. 去除外部 target 参数；
3. 按 workspace/page 解析目标；
4. 排队执行，设置 90 秒级 timeout；
5. 把结果格式化为 Agent 可读文本/JSON；
6. 连续超时达到阈值时清理 stale session。

文本参数、clipboard 写入都有显式字节上限。页面内容被视为不可信数据，不是控制指令。

7. Design Mode：从页面元素到 Agent 上下文

Design Mode 的目标不是普通 inspect element，而是把用户点击的真实 UI 转成可执行上下文：

• 元素 HTML 与可见文本；
• computed style / selector；
• bounding rect；
• cropped screenshot；
• 页面 URL 和 workspace 文件语境。

这些信息被组装到 Agent prompt，使 Agent 能从“按钮看起来太挤”定位到 DOM/CSS，而不用手工描述。

8. Headless browser backend

orca serve 没有普通 BrowserWindow，但移动/CLI 仍可能需要 browser。若虚拟显示可用，runtime 安装 offscreen backend；否则在 capability 中明确标记 unavailable。

这里不能伪造成功：没有 display 的 Chromium、权限或 GPU 路径与桌面不同，客户端必须根据 runtime capability 决定是否展示功能。

9. 证书与权限

Browser guest 与 Orca app UI 具有不同信任级别：

• certificate challenge 带 guest context 和 TTL；
• grant 数量有界；
• 只支持明确的证书错误类型；
• popup 使用安全 window options；
• permission policy 有 allowlist；
• webContentsId 必须属于注册 guest；
• browser renderer 不能调用 app clipboard/UI 特权通道。

这是 Electron 应用中非常关键的隔离：加载任意网页的 guest 绝不能获得 preload 的主应用能力。

10. 下载

下载路径需要：

• 清理 Windows 保留字符；
• 防止路径穿越；
• 避免同名覆盖；
• 维护 active reservation；
• 将 completed/cancelled/interrupted 状态回传正确 page。

下载是由 session 产生的主进程副作用，不应由页面直接决定绝对路径。

11. Computer Use 与 Browser Control 的边界

Browser control 操作内嵌网页；Computer Use 操作桌面可见 UI。后者包含：

• macOS native helper；
• screenshot / coordinate / accessibility；
• mouse、keyboard、scroll；
• 系统权限检查；
• smoke test 与打包验证。

两者都能“点击”，但 authority 不同：

能力	Browser	Computer Use
目标	注册 browser page	屏幕/应用
语义	DOM/CDP	像素/AX/系统事件
登录态	browser session	真实桌面 app
headless	可选 offscreen	通常需要可见 display
安全边界	guest page	OS 辅助功能权限

12. 移动端怎样看到 browser

runtime 把 browser tab 投影为 RuntimeMobileSessionBrowserTab，包含 page id、URL、loading、back/forward 和错误。手机发操作给 host，host 的 BrowserManager 执行；手机不直接连接网页。

这样 cookie、certificate 和实际 Chromium 都留在开发主机。

13. 源码导航

• BrowserManager：src/main/browser/browser-manager.ts
• CDP：src/main/browser/cdp-bridge.ts
• Agent bridge：src/main/browser/agent-browser-bridge.ts
• session registry：src/main/browser/browser-session-registry.ts
• renderer pane：src/renderer/src/components/browser-pane/BrowserPane.tsx
• Computer Use：src/main/computer/