Geen omschrijving

wytfy d31fb24955 feat(native): add shadow DOM, PNG capture and WebView2 input 1 week geleden
.github 7b3b5b3c65 feat(browser): add cgo-free WebView2 and WKWebView workers 1 week geleden
.idea 7b3b5b3c65 feat(browser): add cgo-free WebView2 and WKWebView workers 1 week geleden
agenttools d31fb24955 feat(native): add shadow DOM, PNG capture and WebView2 input 1 week geleden
api d31fb24955 feat(native): add shadow DOM, PNG capture and WebView2 input 1 week geleden
cmd d31fb24955 feat(native): add shadow DOM, PNG capture and WebView2 input 1 week geleden
docs d31fb24955 feat(native): add shadow DOM, PNG capture and WebView2 input 1 week geleden
driver d31fb24955 feat(native): add shadow DOM, PNG capture and WebView2 input 1 week geleden
examples 8248fe92a3 feat(init): initial project 1 week geleden
integration d31fb24955 feat(native): add shadow DOM, PNG capture and WebView2 input 1 week geleden
internal d31fb24955 feat(native): add shadow DOM, PNG capture and WebView2 input 1 week geleden
policy 8248fe92a3 feat(init): initial project 1 week geleden
protocol d31fb24955 feat(native): add shadow DOM, PNG capture and WebView2 input 1 week geleden
scripts 7b3b5b3c65 feat(browser): add cgo-free WebView2 and WKWebView workers 1 week geleden
test-results 7b3b5b3c65 feat(browser): add cgo-free WebView2 and WKWebView workers 1 week geleden
vendor 7b3b5b3c65 feat(browser): add cgo-free WebView2 and WKWebView workers 1 week geleden
.gitignore 7b3b5b3c65 feat(browser): add cgo-free WebView2 and WKWebView workers 1 week geleden
NOTICE 7b3b5b3c65 feat(browser): add cgo-free WebView2 and WKWebView workers 1 week geleden
README.md d31fb24955 feat(native): add shadow DOM, PNG capture and WebView2 input 1 week geleden
README.zh-CN.md d31fb24955 feat(native): add shadow DOM, PNG capture and WebView2 input 1 week geleden
SOURCE-MANIFEST.sha256 d31fb24955 feat(native): add shadow DOM, PNG capture and WebView2 input 1 week geleden
browser.go d31fb24955 feat(native): add shadow DOM, PNG capture and WebView2 input 1 week geleden
browser_test.go 8248fe92a3 feat(init): initial project 1 week geleden
files.go d31fb24955 feat(native): add shadow DOM, PNG capture and WebView2 input 1 week geleden
go.mod 7b3b5b3c65 feat(browser): add cgo-free WebView2 and WKWebView workers 1 week geleden
go.sum 7b3b5b3c65 feat(browser): add cgo-free WebView2 and WKWebView workers 1 week geleden

README.md

CFBrowser v0.1.1

A runnable, cgo-free Go browser automation prototype for ClusterFlow agents.

简体中文 · Usage · ClusterFlow integration · Design · Validation

Implemented engines

Engine What runs Current boundary
CDP Dedicated Chrome/Chromium/Edge process, controlled with chromedp DOM snapshots, browser input, text/tables, waits, screenshots, authenticated/blob downloads
Native Separate Go worker: Windows WebView2 (COM), macOS WKWebView (purego/objc), Linux WebKitGTK (purego) Hidden window, isolated script world, open Shadow DOM snapshots, viewport PNG, synthetic actions, text/tables and waits; Windows also has browser-generated input and bounded full-page PNG

Windows/macOS adapters are implemented as experimental backends. Windows requires the Evergreen WebView2 Runtime; macOS requires 11+ and a logged-in graphical session. This delivery cross-compiles both adapters; Windows/macOS runtime validation remains pending. See Native backends for exact build/test commands and limits.

Build and try

Requires Go 1.24 or later. The module name is a local integration identifier and has not been published. Dependencies are vendored; no Node.js, Python or browser-driver service is needed by the SDK.

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 launches a local dynamic fixture, fills a query, clicks Search, waits for the result, extracts a table and captures a screenshot when supported. It needs no external website or LLM key. The local origin is authorized only for this fixture. To export the demo screenshot, add --export-dir /existing/authorized/folder before demo.

For native WebView on macOS or Linux, run in a graphical session (Linux additionally needs GTK3/WebKitGTK 4.1 runtime libraries):

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

A headless Linux machine needs a display server for this native backend, for example xvfb-run -a .... Hiding a native window does not make GTK independent of a display server. --no-sandbox is an explicit CI escape hatch, never a default or a production recommendation.

Windows: run ./scripts/test-native.ps1 from PowerShell. macOS: run sh scripts/test-native.sh. These scripts build the actual native worker, run ABI tests, execute the native demo and run native-only integration tests without a Chrome/Edge executable. doctor reports static capabilities; only demo and integration tests verify runtime startup. Native supports open Shadow DOM and viewport screenshots; Windows also supports browser-generated input and bounded full-page capture. Native downloads remain unavailable.

Direct integration

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")

See the compilable basic example and tool boundary example.

Tests

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

-race requires a cgo-enabled test toolchain; the distributed application still builds with CGO_ENABLED=0. Enable native real-engine tests with CFBROWSER_NATIVE=1 and CFBROWSER_WORKER=/absolute/path/to/cfbrowser-worker. Read the validation document for complete commands and actual results.

Important runtime boundaries

  • The host supplies api.Owner; models cannot override environment, thread or run identity.
  • A new snapshot invalidates older refs on that page. DOM replacement or navigation also invalidates refs.
  • Action success means the input was dispatched; it does not prove a website transaction succeeded. Unknown outcomes are not retried automatically.
  • networkPolicy=degraded: only explicit top-level navigation is validated. Subresources, redirects and page-generated requests require a trusted network or OS egress controls.
  • Screenshots return file metadata; visual model input is not implemented. Native downloads/uploads, AX snapshots, cross-frame browsing, persistent profiles and proxy configuration are not implemented.
  • Call ClosePage, CloseSession and Manager.Close from the owning host lifecycle. There is no idle reaper or crash recovery service in this prototype.

Browser binaries and native system runtimes are not bundled. See NOTICE and dependency licenses in vendor/.