浏览器自动化

Wesclaw 提供三层浏览器与桌面自动化能力，覆盖从服务端匿名抓取到用户浏览器操作的完整场景。

三层自动化架构

┌─────────────────────────────────┐
│ Cell (per-tenant 隔离域)         │
│  ├── HeadlessBrowser (可选)      │ ← 服务端 chromedp
│  ├── Playwright (可选)           │ ← 用户浏览器扩展
│  └── Desktop Agent (可选)        │ ← 客户端原生二进制
└─────────────────────────────────┘

Playwright 配置

Playwright 用于需要用户登录态的浏览器自动化场景。

启用方式

在 CellSpec 中配置 .Playwright 字段（非 nil 即启用）：

spec := wesgine.CellSpec{
    Playwright: &wesgine.PlaywrightConfig{
        // 用户浏览器模式
    },
}

工作流程

1. 安装浏览器扩展：用户安装 Wesclaw 浏览器扩展
2. 自动连接：扩展通过 auto-connect token 连接到 Cell
3. Agent 操作：Agent 通过 cell.Playwright() Handle 控制浏览器

管理 API

使用示例

# 检查 Playwright 连接状态
GET /cells/main/playwright/status

# 响应示例
{
  "connected": true,
  "browser": "chrome",
  "version": "126.0"
}

HeadlessBrowser 配置

HeadlessBrowser 用于匿名网页抓取，不需要用户登录态。

启用方式

spec := wesgine.CellSpec{
    HeadlessBrowser: &wesgine.HeadlessBrowserConfig{
        // 配置选项
    },
}

CellSpec.HeadlessBrowser 非 nil 即启用。

运行时位置

HeadlessBrowser 运行在服务端，使用 chromedp（Chrome DevTools Protocol）：

Cell → adapter/headless-browser/ → chromedp → Chrome 实例

查看状态

GET /cells/main/headless-browser/state

浏览器 HITL（browser_wait_for_user）

browser_wait_for_user 是浏览器自动化的安全阀，属于 AlwaysOn 工具：

工作方式

1. Cell boot 时无条件注册此工具
2. 当 Agent 遇到需要用户手动操作的页面（如登录、验证码），暂停自动化
3. 通知用户进行操作
4. 用户完成后，Agent 继续执行

触发场景

关键特性

• AlwaysOn：不需要显式配置，Cell boot 自动注册
• 安全阀：防止自动化在不应操作的页面继续执行
• HITL 类型：属于 Agent 主动交互，不是治理链产生

Playwright vs HeadlessBrowser 选型

决策树

需要浏览器自动化？
├── 否 → 不配置任何浏览器选项
├── 需要用户登录态？
│   ├── 是 → Playwright（mode=user + 浏览器扩展）
│   └── 否 → HeadlessBrowser（服务端 chromedp）
└── 需要桌面应用自动化？
    └── 是 → Desktop Agent（CellSpec.Desktop）

对比表

常见误区

连接状态查看

Playwright 状态

GET /cells/{id}/playwright/status

返回浏览器扩展的连接状态、浏览器类型和版本。

HeadlessBrowser 状态

GET /cells/{id}/headless-browser/state

返回 Headless 浏览器实例的运行状态。

Desktop Agent 状态

GET /cells/{id}/desktop/status

返回桌面 Agent 的连接状态。

Desktop Agent

Desktop Agent 是 Wesclaw 独有能力（其他产品无此特性），通过原生二进制实现桌面自动化。

配置方式

spec := wesgine.CellSpec{
    Desktop: &wesgine.DesktopConfig{
        Command:   "/path/to/wesclaw-device-agent",
        Transport: "stdio",
    },
}

提供的工具

关键约束

• wesgine 提供 adapter/desktop/ 标准 adapter
• Wesclaw 负责编译/打包原生二进制
• 客户端只有一个物理桌面 → device agent 内部 mutex 保证串行
• 断开时（Electron 关闭）→ MCP tools 从 Cell 视图消失

故障排查