浏览器与桌面自动化

wesgine 的三层浏览器/桌面自动化架构：Headless Browser、Playwright、Desktop Agent。

三层架构

Headless Browser

服务端运行 chromedp（无头 Chrome），用于不需要登录态的匿名网页抓取。

CellSpec 声明

CellSpec{
  HeadlessBrowser: &HeadlessBrowserConfig{...},
}

非 nil 即启用。

API

GET /headless-browser/state    # 状态查询

Playwright

管理 Playwright MCP 子进程，支持两种模式：

CellSpec 声明

CellSpec{
  Playwright: &PlaywrightConfig{...},
}

API

GET /playwright/status         # 连接状态
PUT /playwright/token          # 更新扩展 auto-connect token

安全阀：browser_wait_for_user

浏览器自动化内置 HITL 安全阀——browser_wait_for_user。当浏览器操作需要人类干预时（如验证码、登录确认），Agent 触发此工具暂停等待用户操作。

此工具在 Cell boot 时无条件注册（AlwaysOn），不受 CellSpec 配置控制。

Desktop Agent

桌面自动化 Device Agent SDK，二进制运行在客户端（运行时隔离，AX-5 物理边界）。

CellSpec 声明

CellSpec{
  Desktop: &DesktopConfig{
    Command: "/path/to/device-agent",
    Transport: "stdio",  // 或 "sse"
  },
}

API

GET /desktop/status            # 连接状态

与 Playwright 的关系

• Playwright：控制浏览器（网页自动化）
• Desktop Agent：控制操作系统（截屏、剪贴板、应用启动等）

二者正交，可同时启用。

各产品使用方式

运行时位置（AX-5）

wesgine 提供 adapter 代码（共享维护），但 Desktop binary 运行在客户端：

wesgine 服务端
  ├── Headless Browser（chromedp，服务端进程内）
  ├── Playwright MCP（服务端子进程 + 可选用户浏览器）
  └── Desktop adapter 代码（编译在消费应用中）
        ↓ stdio / sse
客户端设备
  └── Device Agent binary（运行时在客户端）

安全约束

• Headless Browser 无用户身份（匿名）
• Playwright user 模式需要用户浏览器扩展
• Desktop Agent 通过 MCP 协议走 Cell 治理链路
• browser_wait_for_user 是 HITL 安全阀，AlwaysOn

相关文档

• HITL 交互 → hitl-interaction.md
• CellSpec 概览 → cellspec-overview.md
• MCP 集成 → mcp-integration.md