설명 없음

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

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/.