# CFBrowser v0.1.1 面向 ClusterFlow Agent 的可运行 Go 浏览器操作原型库,新增库与 worker 可使用 `CGO_ENABLED=0` 构建。 [English](README.md) · [使用文档](docs/USAGE.zh-CN.md) · [ClusterFlow 集成](docs/INTEGRATION.zh-CN.md) · [完整设计](docs/DESIGN.zh-CN.md) · [测试报告](docs/VALIDATION.zh-CN.md) ## 当前已实现 | 后端 | 运行方式 | 已实现边界 | | --- | --- | --- | | 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 实机验收仍待执行。详见[原生后端说明](docs/NATIVE.zh-CN.md)。 ## 构建并试用 需要 **Go 1.24 或更高版本**,可接入当前 Go 1.25 的 ClusterFlow。模块路径是本地集成标识,尚未发布到公共 Go 模块仓库。依赖已包含在 `vendor/`;SDK 运行不需要 Node.js、Python 或单独的 WebDriver 服务。 ```sh 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 运行库,以及可用图形会话: ```sh ./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 下载仍未实现。 ## 直接集成 ```go 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](examples/basic/main.go) 和 [Agent 工具边界](examples/agent-loop/main.go)。 ## 测试 ```sh 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](NOTICE),第三方依赖许可证保留在 `vendor/`。