# 使用文档 版本:0.1.0 原型。选择后端前,请先了解实际能力范围。 ## 1. 环境与构建 需要 Go 1.24+,主要原因是安全文件根目录操作使用 `os.OpenRoot`。第三方依赖已放入 vendor,SDK 不依赖 Node.js、Python、Playwright 服务或 ChromeDriver。 ```sh 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+)。详细命令见[原生构建与测试](NATIVE.zh-CN.md)。 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. 命令行 所有选项放在命令前。 ```sh ./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 配置与归属 ```go 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 ```go 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. 观察与操作 ```go 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. 读取、等待和限额 ```go 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,直到所需文件完成导入;进行中和取消的下载不会被返回为已完成文件。 ```go 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 的模型参数示例: ```json {"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 中: ```json {"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 再解析。适用于可信桌面/网络环境的初步集成,不能将其当作严格多租户网页沙箱。生产出站网关仍属于后续设计。