INTEGRATION.zh-CN.md 8.3 KB

ClusterFlow 集成文档

本交付是独立原型库,不会自动修改上传的 ClusterFlow 或添加设置 UI。附带的 Tool Bus 适配器已经在 ClusterFlow-202611051139.zip 的独立副本中,用 Go 1.25.0 编译并通过测试。

1. 引入本地模块

建议将 cfbrowser 和 clusterflow 放在同级目录。在 ClusterFlow 中执行:

go mod edit -require=clusterflow.dev/cfbrowser@v0.0.0
go mod edit -replace=clusterflow.dev/cfbrowser=../cfbrowser
go mod tidy

该路径是本地集成标识,尚未发布公共模块;未来发布后替换为真实仓库/tag。若主项目使用 vendor,需要重新生成主项目的 vendor;依赖库自身的 vendor 不会自动成为宿主 vendor。

SDK 最低 Go 1.24,宿主继续保留 Go 1.25 基线。chromedp/cdproto 与 purego 已固定版本,不追随移动分支。

2. 复制已经验证的注册适配器

压缩包内来源 ClusterFlow 目标位置
examples/clusterflow/register_browser.go.example internal/clusterflowtools/browser_prototype.go
examples/clusterflow/register_browser_test.go.example internal/clusterflowtools/browser_prototype_test.go

使用 .example 扩展名是为了避免独立 SDK 模块直接导入另一个项目的 internal 包。复制进 ClusterFlow 并改为 .go 后,符合 Go internal 访问规则。

CGO_ENABLED=0 go test ./internal/clusterflowtools -run TestPrototypeBrowserRegistry -count=1

适配器注册 8 个 builtin.browser 工具,映射当前工具风险级别、限制参数 32 KiB,并从 ExecutionScope 生成 Owner。模型不能传入或覆盖归属身份。

当前显示标题暂用模型工具名;接入 UI 时,在 aiAgentToolLabels.ts 和现有 locale 中加入本地化标题。

3. 由 Workspace/应用生命周期持有 Manager

功能启用后创建一个 Manager,不要每轮模型回复都新建:

manager, err := cfbrowser.New(cfbrowser.Config{
    Executable: configuredBrowserPath,
    Timeout: time.Duration(toolTimeoutSeconds) * time.Second,
    MaxResultBytes: maxToolResultBytes,
}, &cdp.Driver{})
if err != nil {
    return err
}
browserTools := &agenttools.Service{Manager: manager}

Windows/macOS/Linux 可替换为 native.Driver 并配置 worker 路径;新 Windows/macOS 实现须在目标机器通过原生脚本验收后使用,见原生部署说明。程序路径、授权目录根和网络策略属于宿主配置,不是模型参数。

将 service 存入 workspace 的依赖结构,AgentAccess 可暴露窄接口:

func (a *AgentAccess) AgentBrowserTools() *agenttools.Service {
    return a.workspace.browserTools
}

需要在宿主实际代码中添加字段并完成启动初始化;关闭功能时返回 nil。将 Manager.Close 接入 Workspace shutdown,在配置依赖关闭前停止新请求并清理。SDK 无 cgo 不改变 Wails 主应用自身的平台构建要求。

Native worker 与 Wails 自身前端 WebView 独立,按宿主 OS/架构构建分发;从应用资源目录解析绝对路径,不能依赖当前工作目录。Windows 指向 cfbrowser-worker.exe;macOS bundle 指向 CFBrowserWorker.app/Contents/MacOS/cfbrowser-worker。Manager 每 session 创建独立 worker 与数据存储。发行时一起签名;macOS hardened runtime/公证须在真实安装包中另行验证。既有八个工具、Owner 映射和权限分类无需更改。

manager, err := cfbrowser.New(cfbrowser.Config{
    Timeout: 30 * time.Second,
}, &native.Driver{WorkerPath: absoluteWorkerPath})

导入 native "clusterflow.dev/cfbrowser/driver/native"。Native 无需配置完整浏览器路径;由 worker 加载系统 WebView。禁止把内部 Evaluate RPC 暴露给模型。

4. 在运行工具目录快照之前注册

最小原型接入可以在 agentservice.registryForSettings 中,combined.Snapshot 之前直接注册:

if settings.BuiltinToolsEnabled {
    if provider, ok := s.backend.(interface {
        AgentBrowserTools() *agenttools.Service
    }); ok && provider.AgentBrowserTools() != nil {
        if err := clusterflowtools.RegisterPrototypeBrowserTools(combined, provider.AgentBrowserTools()); err != nil {
            return nil, err
        }
    }
}

补充 agenttools import。该方式保留现有 BuildRegistry backend 契约,直接从真实 AgentAccess 取得 service,不依赖 agentRegistryBackend 自动提升额外方法。

如果改成在 clusterflowtools.BuildRegistry 内注册,则必须给 agentRegistryBackend 显式转发可选接口;嵌入原有 Backend 接口不会自动暴露具体值的其他方法。两条路径择一,避免重复注册。

工具目录继续是每次 Run 的 snapshot,设置变化影响后续运行;归属和取消在执行时检查。

5. 保留归属与权限语义

直接使用 Runner 传入的 scope:

owner := api.Owner{
    EnvironmentID: scope.EnvironmentID,
    ThreadID: scope.ThreadID,
    RunID: scope.RunID,
    SSHSessionID: scope.SessionID,
}
  • 后台调用不能重新读取 Vue 当前选中的 SSH 标签作为执行环境。
  • 子 Agent 即使继承 Thread 和 SSH Session,也应使用其自己的 RunID。
  • session/navigate/act 保持 External 风险,Full Access 按现有通用策略继续执行。
  • snapshot/read/wait/capture/files 为当前已归属资源上的 Read 工具。
  • SDK Service 不负责弹出 ClusterFlow 的审批提示,应从现有 Tool Bus/Runner 进入,或由其他宿主实现同等策略。

SDK Wait 支持取消,但这不自动等于完成应用内暂停/补充 prompt 唤醒契约。未接入并验证 Runner 行为前,不要直接声称 RuntimeBehaviorPassiveWait 已完整集成。

6. 文件授权与 SSH 传输

8 个基础工具只返回文件 ID。Export 是可信宿主 API,未开放为可任意指定绝对路径的模型工具。

若要添加导出工具,模型参数只包括 fileId/localGrantId/相对路径。宿主复用 localfiles 服务解析真实授权、保持根目录身份/撤销语义,并将可信 root 传给 Manager.Export。授权撤销应取消对应导出;一次路径预检查不能替代现有授权生命周期。

导出成功后,沿用当前 cf_file_transfer_start,把授权本地目录中的文件上传到对应 SSH。不能为库的私有下载目录伪造 grant ID。

浏览器下载保留了登录态、POST/blob 语义,应直接复用已下载文件,不要再用无 cookie 的 HTTP client 拉取一次。Native 下载/上传尚未实现。

7. 界面与模型消息

初步集成可复用 AgentToolCallCard 和现有设置组件,只添加浏览器开关、引擎选择、浏览器/worker 路径与能力状态。正常用户流程无需暴露 CDP 端口、原生回调等实现参数。

当前上传源码的 Agent Message 走文本链路。返回截图 file ID 不代表模型可以看图;视觉输入需要 content-parts、provider 序列化、附件持久化和 usage/上下文支持,不能将 base64 塞进工具文本就宣称接通视觉。

SSH 隧道只授权用户已配置的精确地址/端口。当前网络策略仅校验显式顶层导航,尚未实现完整出站网关。Go HTTP client 的代理配置不能直接安装进 Chromium/WebKit,本版代理功能明确不支持。

8. 生命周期约定

宿主事件 集成动作
切换 SSH 标签/Thread 展示 不改后台资源 Owner,不取消正在运行的任务
取消 Run 取消操作 context,适当时显式关闭该 Run 的 session
Run 完成 导出需保留文件并关闭 session;本版没有自动 idle 回收
删除 Thread/环境 宿主关闭对应归属的 session
应用退出 拒绝新请求、取消在途操作、调用 Manager.Close
引擎崩溃/IPC 断开 废弃旧引用,不自动重放可能产生副作用的动作

需要崩溃后的进程树清理保证、持久 profile 或 lease 时,先实现长期设计中的操作系统监督与 lease 策略,再作为生产服务开放。

9. 集成验收

先运行 SDK demo/真实浏览器测试,再将适配器测试放入实际应用源码运行。随后用两个 SSH 环境并行运行 Agent,检查引用、cookie、文件、工具卡片不串会话,并验证实际 Runner 的停止/暂停和应用退出行为。本交付验证了注册接缝,没有宣称已经验证 Wails UI 与完整应用生命周期。