版本:0.1.0 原型。选择后端前,请先了解实际能力范围。
需要 Go 1.24+,主要原因是安全文件根目录操作使用 os.OpenRoot。第三方依赖已放入 vendor,SDK 不依赖 Node.js、Python、Playwright 服务或 ChromeDriver。
mkdir -p bin test-results
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
go test -mod=vendor ./...
PowerShell 中先执行 $env:CGO_ENABLED="0",再运行 go build -buildvcs=false -mod=vendor -o bin/cfbrowser.exe ./cmd/cfbrowser。另外将 ./cmd/cfbrowser-worker 构建为 bin/cfbrowser-worker.exe。Windows 使用已安装的 Evergreen WebView2 Runtime,macOS 使用系统 WKWebView(11+)。详细命令见原生构建与测试。
CDP 需要自行安装 Chrome/Chromium/Edge,或使用已有可执行文件;无头任务也可使用 Chrome Headless Shell。库不会自动下载或安装浏览器。
Linux Native 需要 GTK3 与 WebKitGTK 4.1 运行库。例如适配的 Ubuntu 环境可安装 libgtk-3-0t64 libwebkit2gtk-4.1-0。不同发行版包名与版本不同;Rocky 9 尚未实机运行验证,不能将 4.0/6.0 的库强行软链接成 4.1。
Native 还需要 X11/Wayland 图形环境,CI 可使用 Xvfb。Headed=false 表示隐藏顶层窗口,不代表 GTK 可以不依赖显示服务器运行。
所有选项放在命令前。
./bin/cfbrowser --browser /path/to/chrome doctor
./bin/cfbrowser --browser /path/to/chrome demo
./bin/cfbrowser --browser /path/to/chrome --export-dir /existing/folder demo
./bin/cfbrowser --engine native --worker ./bin/cfbrowser-worker demo
./bin/cfbrowser --engine native --worker ./bin/cfbrowser-worker --diagnostics demo
./bin/cfbrowser --browser /path/to/chrome serve
doctor 返回功能实现状态和可执行文件发现结果,并明确输出 runtimeVerified=false;它不会启动浏览器,也不验证 GTK 显示连接。demo 才会实际驱动引擎完成动态页面操作。
| 选项 | 含义 |
|---|---|
--engine cdp/native |
明确选择引擎,不静默切换 |
--browser PATH |
宿主配置的 Chromium 程序路径 |
--worker PATH |
宿主配置的原生 worker 路径 |
--headed |
从启动时显示窗口;不等于已实现交互接管系统 |
--allow-origin ORIGIN |
授权精确私有 origin,包含端口,可重复 |
--data-dir DIR |
私有实例临时目录的父目录,Close 时清理实例 |
--export-dir DIR |
仅用于 demo 的截图导出授权根,必须已存在 |
--no-sandbox |
隔离 CI 的显式例外,默认关闭,适用于 Chromium/WebKit |
--diagnostics |
输出原生引擎 stderr,仅诊断时使用,可能带站点/运行信息 |
demo 只自动授权自己的临时 HTTP origin,不会授权全部 localhost。导出文件已存在时返回错误,不覆盖。
manager, err := cfbrowser.New(cfbrowser.Config{
Executable: "/path/to/chrome",
MaxSessions: 2,
MaxPages: 3,
MaxResultBytes: 64 * 1024,
MaxDownloadBytes: 100 * 1024 * 1024,
Timeout: 30 * time.Second,
Policy: policy.URLPolicy{
AllowOrigins: []string{"http://127.0.0.1:18900"},
},
}, &cdp.Driver{})
Native 改用 &native.Driver{WorkerPath: "/path/to/cfbrowser-worker"};native 为 clusterflow.dev/cfbrowser/driver/native 的 import alias,可额外配置仅宿主使用的 Diagnostics io.Writer。
检查错误后再使用 Manager,并在宿主退出时 defer manager.Close。Owner 来自真实执行上下文:EnvironmentID、ThreadID、RunID 必填,SSHSessionID 可选,但填写后参与归属比较。子 Agent 必须使用其自己的 RunID。
每 session 对应独立浏览器进程或原生 worker。同 session 的页面共享 cookie/storage,不同 session 隔离。新 Run 不能凭旧 ID 接管旧 session;当前没有 lease 转移。
DataDir 只是临时目录的父目录,不是持久登录 profile。关闭 session 会删除托管下载,重要文件应先导出。Manager.Close 删除该实例全部私有目录。
owner := api.Owner{EnvironmentID: "ssh1", ThreadID: "thread1", RunID: "run1", SSHSessionID: "connection1"}
session, err := manager.CreateSession(ctx, owner)
// Check err before using session.
page, err := manager.NewPage(ctx, owner, session.ID)
// Check err before using page.
| Manager 方法 | 用途 |
|---|---|
Capabilities(ctx) |
查询后端功能实现状态 |
CreateSession(ctx, owner) |
预留配额,启动独立引擎 |
Sessions(owner) |
只列出当前 Owner 的 session |
NewPage(ctx, owner, sessionID) |
新建受管页面 |
Navigate(ctx, owner, sessionID, pageID, url, operation) |
goto/back/forward/reload |
Snapshot(ctx, owner, sessionID, pageID, request) |
有界语义快照与新引用 |
Act(ctx, owner, sessionID, pageID, request) |
执行一次经过校验的动作 |
Read(ctx, owner, sessionID, pageID, request) |
有界文本/表格读取 |
Wait(ctx, owner, sessionID, pageID, request) |
可取消条件等待 |
Capture(ctx, owner, sessionID, pageID) |
CDP viewport PNG 截图入托管目录 |
Files(ctx, owner, sessionID) |
导入已完成下载并列出文件元数据 |
Export(ctx, owner, sessionID, fileID, authorizedRoot, relativePath) |
授权根内导出,不覆盖 |
ClosePage(ctx, owner, sessionID, pageID) |
关闭页面并释放页面配额 |
CloseSession(owner, sessionID) |
关闭所属引擎并删除 session 文件 |
Close() |
幂等退出整个 Manager |
同页操作由可取消的队列串行执行,不同页可并行。配额统计受管页面;页面主动打开的任意弹窗不属于本原型页面 API 的完整资源沙箱范围。
snapshot, err := manager.Snapshot(ctx, owner, sessionID, pageID, api.SnapshotRequest{
Mode: "interactive", MaxBytes: 12 * 1024, MaxElements: 100,
})
result, err := manager.Act(ctx, owner, sessionID, pageID, api.ActionRequest{
SnapshotID: snapshot.SnapshotID,
Ref: "e1",
Action: "fill",
Value: "La2O3",
})
快照支持 compact / interactive;kind=dom-semantic,不是完整 AX tree。实际动作的 ref 应从返回列表查找,不能假设 e1 永远指向同一元素。引用存放在隔离脚本世界内,不依赖页面可改写的 data 属性。密码和 file-input 的 value 不返回。
新快照保守地使同页全部旧引用过期。DOM 替换、元素角色/名称/链接变化和导航也可能使引用失效。
| 动作 | CDP | Native(三平台) |
|---|---|---|
| click | 浏览器派发鼠标输入 | 合成 DOM click |
| hover | 浏览器鼠标输入 | 不支持 |
| fill | 浏览器快捷键全选与文本输入 | 原生 value setter + input/change 事件 |
| type | 浏览器文本输入 | 不支持 |
| press | Enter、Tab、Escape、上下箭头、Backspace | 不支持 |
| select/check/uncheck/scroll | 有界 DOM 操作 | 有界 DOM 操作 |
InputKind 返回 browser 或 synthetic;CDP 的 select/check/scroll 也属于 DOM 操作。effect=dispatched 仅代表已派发;连接在副作用动作期间丢失时返回 BROWSER_ACTION_OUTCOME_UNKNOWN,宿主应先观察再决定是否重试。SDK 不会自动重放动作。
text, err := manager.Read(ctx, owner, sessionID, pageID, api.ReadRequest{Mode: "text", MaxBytes: 24576})
table, err := manager.Read(ctx, owner, sessionID, pageID, api.ReadRequest{Mode: "table", Ref: tableRef, SnapshotID: snapshotID})
err = manager.Wait(ctx, owner, sessionID, pageID, api.WaitRequest{Kind: "text", Value: "Results", TimeoutMS: 5000})
等待支持 ready、URL 子串、text、textGone,不默认等待 networkidle,也不会调用模型。调用 context、Manager.Timeout、Wait.TimeoutMS 中最早的截止时间生效。
快照/读取按最终 JSON UTF-8 字节计算预算,包含转义和元数据。快照最多扫描 4000 个 DOM 元素、返回 150 个引用,并限制名称、值和文本。标签与表格提取也有数量上限。truncated=true 表示结果不完整;本版没有分页 continuation 或差量协议。
CDP 使用浏览器网络栈下载,因此可以保留 cookie、Referer、POST 响应和 blob 语义。宿主以可取消的等待轮询 Files,直到所需文件完成导入;进行中和取消的下载不会被返回为已完成文件。
files, err := manager.Files(ctx, owner, sessionID)
// Check err and select an expected file before exporting it.
info, err := manager.Export(ctx, owner, sessionID, files[0].ID, authorizedRoot, "paper.cif")
authorizedRoot 必须由宿主从真实本地目录授权中解析,不能由模型指定任意绝对路径。os.OpenRoot 限制根目录边界,阻止符号链接逃逸;目标父目录需已存在,文件默认不覆盖。文件只返回 ID、清理后的名称、MIME、大小和 SHA-256,不向模型返回内部绝对路径。
默认下载单文件 100 MiB、每 session 64 个托管文件、截图 4 MiB。Chromium 下载进度取消不等于抵抗恶意服务器的操作系统磁盘配额,严格限额需宿主配合。Native 下载/截图、文件上传尚未实现。
通过 agenttools.Catalog 获取 8 个工具,通过 agenttools.Service{Manager: manager}.Call(ctx, owner, name, arguments) 执行。宿主先执行原有权限策略,SDK 不替代 ClusterFlow 的授权系统。
cf_browser_session 的模型参数示例:
{"operation":"create"}
结果包括 session 和初始 page,后续使用 navigate/snapshot/act/read/wait/capture/files。session 还支持 list、newPage、closePage、close。
CLI serve 采用 4 字节大端长度 + UTF-8 JSON,最大单帧 512 KiB,支持 capabilities / tools.list / tools.call / request.cancel。Owner 只出现在可信宿主 envelope 中:
{"version":1,"id":1,"method":"tools.call","params":{"owner":{"environmentId":"ssh1","threadId":"t1","runId":"r1"},"name":"cf_browser_session","arguments":{"operation":"list"}}}
deadline 可选,为 Unix 毫秒时间戳。响应回显 id、version=1,并提供 result 或稳定错误码。最多 32 个在途请求。原生 worker 的内部 Evaluate 方法只供可信 SDK 使用,不能注册为模型工具。
python3 scripts/pipe_demo.py ./bin/cfbrowser serve 可以验证协议,不启动浏览器。Python 只是示例客户端,不是库运行依赖。EOF 会取消 handler 并清理 Manager;协议 stdout 与引擎 stderr 分离。
--browser msedge.exe 是 CDP 使用完整浏览器时的配置;--engine native 无需该参数。Windows Native 经 COM 嵌入 WebView2,不通过调试端口启动完整 Edge。当前 URL 策略只检查显式顶层导航,不能约束所有重定向、子资源、Service Worker、WebSocket 或 DNS 再解析。适用于可信桌面/网络环境的初步集成,不能将其当作严格多租户网页沙箱。生产出站网关仍属于后续设计。