browserctl：为AI智能体设计的持久化浏览器自动化工具

browserctl是一款专为AI智能体和开发者工作流打造的持久化浏览器自动化守护进程与CLI工具，通过命名会话保持浏览器状态，支持AI友好的DOM快照和Ruby DSL工作流编排。

browserctl是一款由Ruby编写的持久化浏览器自动化守护进程和命令行工具，专为AI智能体和开发者工作流设计。与大多数自动化工具不同，browserctl采用"有状态"架构：浏览器会话在后台持续运行，跨命令保持cookies、localStorage、打开的标签页和页面状态。这种设计特别适合需要长期保持登录状态、跨多个步骤执行任务的AI智能体。

browserctl的最大特色是支持命名页面句柄（named page handles）。用户可以通过简单的命令创建和管理多个浏览器页面，每个页面都有独立的名称和状态。例如：

browserctl open login --url https://example.com/login
browserctl open dashboard --url https://example.com/dashboard

这种方式让AI智能体可以在不同页面间自由切换，无需重复登录或重新加载状态。

为了让AI智能体更容易理解页面结构，browserctl提供了独特的快照功能。执行snap命令后，工具会返回一个精简的JSON数组，包含页面上所有可交互元素的信息：

[
  {
    "ref": "e1",
    "tag": "input",
    "text": "",
    "selector": "form > input[name=email]",
    "attrs": {
      "type": "email",
      "name": "email",
      "placeholder": "Enter email"
    }
  },
  {
    "ref": "e2",
    "tag": "button",
    "text": "Sign in",
    "selector": "form > button",
    "attrs": {
      "type": "submit"
    }
  }
]

这种格式对AI来说非常友好，既保留了必要的信息，又避免了冗余的HTML标签，大大降低了token消耗。

传统的自动化工具依赖CSS选择器定位元素，但选择器往往因页面结构变化而失效。browserctl引入了"ref"机制：每次快照会为每个可交互元素分配一个唯一引用ID（如e1、e2），后续操作可以直接通过ref进行，无需关心底层选择器。

browserctl fill login --ref e1 --value user@example.com
browserctl click login --ref e2

这种方式大大降低了自动化脚本的维护成本，即使页面DOM结构发生变化，只要元素功能不变，脚本依然能够正常工作。

browserctl内置了强大的Ruby DSL，支持将一系列操作编排成可复用的工作流。工作流文件使用声明式语法，支持参数化、步骤重试、超时控制等高级特性：

Browserctl.workflow "smoke_login" do
  desc "Log in and confirm the dashboard loads"
  
  param :email, required: true
  param :password, required: true, secret: true
  param :base_url, default: "https://app.example.com"
  
  step "open login page" do
    page(:login).goto("#{base_url}/login")
  end
  
  step "submit credentials" do
    page(:login).fill("input[name=email]", email)
    page(:login).fill("input[name=password]", password)
    page(:login).click("button[type=submit]")
  end
  
  step "verify dashboard" do
    page(:login).wait_for("[data-test=dashboard]", timeout: 10)
    assert page(:login).url.include?("/dashboard")
  end
end

此外，browserctl还支持录制功能，可以将手动操作自动转换为工作流脚本，极大降低了自动化测试的编写门槛。

特性	browserctl	Playwright/Selenium
会话持久化	✓	✗（每次脚本独立生命周期）
命名页面句柄	✓	✗
AI友好的DOM快照	✓	✗
轻量级CLI接口	✓	✗
完整的浏览器自动化API	—	✓
并行多浏览器测试	—	✓

从对比可以看出，browserctl更适合需要长期保持浏览器状态的场景，如AI智能体、迭代式开发工作流或轻量级冒烟测试。而对于需要并行测试、多浏览器支持或完整程序化API的场景，Playwright和Selenium依然是更好的选择。

browserctl采用客户端-守护进程架构。守护进程browserd在后台运行，通过Unix socket（默认位于~/.browserctl/browserd.sock）监听命令。它基于Ferrum库（Chrome DevTools Protocol的Ruby封装）管理浏览器实例。

客户端browserctl通过JSON-RPC协议与守护进程通信，将命令发送给守护进程并打印结果。工作流则在本地进程中运行，通过相同的客户端与守护进程交互。这种架构既保证了状态持久化，又提供了简洁的命令行接口。