USAGE.zh-CN.md 12 KB

使用文档

版本:0.1.0 原型。选择后端前,请先了解实际能力范围。

1. 环境与构建

需要 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 可以不依赖显示服务器运行。

2. 命令行

所有选项放在命令前。

./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。导出文件已存在时返回错误,不覆盖。

3. Manager 配置与归属

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 删除该实例全部私有目录。

4. 生命周期与 API

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 的完整资源沙箱范围。

5. 观察与操作

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 不会自动重放动作。

6. 读取、等待和限额

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 或差量协议。

7. 下载与导出

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 下载/截图、文件上传尚未实现。

8. Agent 工具与私有管道

通过 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 分离。

9. 常见问题与边界

  • BROWSER_ENGINE_NOT_FOUND:配置真实浏览器;安装 WebView2 runtime 不等于已安装完整 Edge。
  • Native 启动失败:Windows 检查 Evergreen WebView2 Runtime 与架构;macOS 检查 11+、已登录图形会话、worker 签名及 ATS 配置;Linux 检查 GTK/WebKitGTK 4.1 ABI 与显示连接。仅在本地诊断时开启 diagnostics。
  • --browser msedge.exe 是 CDP 使用完整浏览器时的配置;--engine native 无需该参数。Windows Native 经 COM 嵌入 WebView2,不通过调试端口启动完整 Edge。
  • BROWSER_STALE_REF:重新获取 snapshot,用新的引用。
  • BROWSER_TARGET_NOT_ACTIONABLE:元素隐藏、禁用或被遮挡,等待或重新观察。
  • BROWSER_NETWORK_BLOCKED:在宿主中为任务配置精确私有 origin,不开放全部内网。
  • Native 不支持 type/press/hover、截图或下载:改用 CDP,或处理能力不支持错误。
  • 本原型没有 idle TTL、profile 接管、通用 popup/dialog API、代理注入、OS Job Object 或完整崩溃恢复。

当前 URL 策略只检查显式顶层导航,不能约束所有重定向、子资源、Service Worker、WebSocket 或 DNS 再解析。适用于可信桌面/网络环境的初步集成,不能将其当作严格多租户网页沙箱。生产出站网关仍属于后续设计。