README.zh-CN.md 4.7 KB

CFBrowser v0.1.1

面向 ClusterFlow Agent 的可运行 Go 浏览器操作原型库,新增库与 worker 可使用 CGO_ENABLED=0 构建。

English · 使用文档 · ClusterFlow 集成 · 完整设计 · 测试报告

当前已实现

后端 运行方式 已实现边界
CDP chromedp 控制专用 Chrome/Chromium/Edge 进程 DOM 快照、浏览器输入、文本/表格、等待、截图、认证下载和 blob 下载
Native 独立 Go worker:Windows WebView2(COM)、macOS WKWebView(purego/objc)、Linux WebKitGTK(purego) 隐藏窗口、隔离脚本世界、开放 Shadow DOM 快照、视口 PNG、合成操作、文本/表格和等待;Windows 增加可信输入与有界整页 PNG

Windows/macOS 原生后端已实现,当前标记为 experimental:Windows 需要 Evergreen WebView2 Runtime;macOS 需要 11+ 及已登录的图形会话。本次完成交叉编译,Windows/macOS 实机验收仍待执行。详见原生后端说明。

构建并试用

需要 Go 1.24 或更高版本,可接入当前 Go 1.25 的 ClusterFlow。模块路径是本地集成标识,尚未发布到公共 Go 模块仓库。依赖已包含在 vendor/;SDK 运行不需要 Node.js、Python 或单独的 WebDriver 服务。

CGO_ENABLED=0 go build -buildvcs=false -mod=vendor -o bin/cfbrowser ./cmd/cfbrowser
CGO_ENABLED=0 go build -buildvcs=false -mod=vendor -o bin/cfbrowser-worker ./cmd/cfbrowser-worker
./bin/cfbrowser --browser /path/to/chrome doctor
./bin/cfbrowser --browser /path/to/chrome demo

demo 会启动本地动态测试页面,自动填写查询、点击搜索、等待结果、提取表格,并在后端支持时截图。无需联网访问第三方网站,也不需要模型 API Key;本地 origin 仅在该 demo 中获得明确授权。若要导出截图,在 demo 前添加 --export-dir /existing/authorized/folder。

Linux Native 需要发行版对应的 GTK3/WebKitGTK 4.1 运行库,以及可用图形会话:

./bin/cfbrowser --engine native --worker ./bin/cfbrowser-worker demo

没有桌面的 Linux 环境需要显示服务器,例如 xvfb-run -a ...。隐藏窗口仍依赖显示环境。--no-sandbox 仅供明确隔离的 CI 环境使用,默认不开启。

Windows 可在 PowerShell 运行 ./scripts/test-native.ps1;macOS 运行 sh scripts/test-native.sh。脚本会构建原生 worker、执行 ABI 测试、原生 demo 和仅 Native 的集成测试,无需指定 Chrome/Edge 程序。doctor 只报告静态能力;demo 和集成测试才验证真实运行。Native 支持开放 Shadow DOM、三平台视口截图,Windows 还支持可信输入和有界整页截图;Native 下载仍未实现。

直接集成

manager, err := cfbrowser.New(cfbrowser.Config{}, &cdp.Driver{})
if err != nil {
    return err
}
defer manager.Close()

owner := api.Owner{EnvironmentID: "ssh1", ThreadID: "thread1", RunID: "run1"}
session, err := manager.CreateSession(ctx, owner)
if err != nil {
    return err
}
page, err := manager.NewPage(ctx, owner, session.ID)
if err != nil {
    return err
}
_, err = manager.Navigate(ctx, owner, session.ID, page.PageID, "https://example.org", "goto")

完整可编译示例见 basic 和 Agent 工具边界。

测试

go test ./... -coverprofile=test-results/unit.cover
go test -race ./...
CFBROWSER_INTEGRATION=1 CFBROWSER_EXECUTABLE=/path/to/chrome go test ./integration -v

-race 本身需要启用 cgo 的测试工具链,这不改变正式库可以无 cgo 构建的事实。增加 CFBROWSER_NATIVE=1 和 CFBROWSER_WORKER=/absolute/path/to/cfbrowser-worker 可运行原生后端真实测试;完整命令与实际结果见测试报告。

使用边界

  • Owner 由宿主的 Environment/Thread/Run/SSH Session 提供,模型参数不能覆盖身份。
  • 新快照会使同页旧引用失效;DOM 替换和导航也会导致旧引用失效。
  • 动作返回 dispatched 只表示已派发,不证明站点事务成功;不确定结果不会自动重试。
  • 网络策略明确为 degraded,目前只校验显式顶层导航;重定向、子资源和页面主动请求需要可信网络或操作系统出站控制。
  • 截图返回文件信息,尚未接通模型视觉消息。Native 下载、文件上传、AX tree、跨 frame、持久 profile 和代理配置尚未实现。
  • 宿主需按生命周期调用 ClosePage、CloseSession、Manager.Close;本原型没有空闲回收或崩溃自动恢复服务。

源码包不包含浏览器程序和系统运行库,授权说明见 NOTICE,第三方依赖许可证保留在 vendor/。