# ClusterFlow 集成文档 本交付是独立原型库,不会自动修改上传的 ClusterFlow 或添加设置 UI。附带的 Tool Bus 适配器已经在 `ClusterFlow-202611051139.zip` 的独立副本中,用 Go 1.25.0 编译并通过测试。 ## 1. 引入本地模块 建议将 cfbrowser 和 clusterflow 放在同级目录。在 ClusterFlow 中执行: ```sh 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 访问规则。 ```sh 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,不要每轮模型回复都新建: ```go 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 实现须在目标机器通过原生脚本验收后使用,见[原生部署说明](NATIVE.zh-CN.md)。程序路径、授权目录根和网络策略属于宿主配置,不是模型参数。 将 service 存入 workspace 的依赖结构,AgentAccess 可暴露窄接口: ```go 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 映射和权限分类无需更改。 ```go 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 之前直接注册: ```go 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: ```go 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 与完整应用生命周期。