WebSocket 端点
连接参数
Browser Extension / Desktop App
Web Client
连接生命周期
消息类型
1. 节点注册 (register)
浏览器扩展和桌面应用连接后,应发送register 消息注册节点信息:
客户端 → 服务端:
2. 心跳机制 (heartbeat)
节点定期发送心跳以维持连接状态。服务端会更新 NodeManager 中的节点状态。 客户端 → 服务端:3. Ping/Pong 保活
所有三种客户端(Extension、Desktop、Web)都支持 ping/pong 保活: 客户端 → 服务端:对于 Extension 和 Desktop 客户端,
ping 消息会同时触发 NodeManager 心跳更新。4. 工具调用(JSON-RPC 2.0)
服务端通过 WebSocket 向节点发送 JSON-RPC 2.0 请求来调用工具。这是 MCP(Model Context Protocol)格式。 服务端 → 客户端(请求):MCP Result 内容类型
result.content 数组中的每个项可以是:
服务端解析响应时,会提取
text、image 和 _screenshot 字段,并将 isError 映射为 success 状态。默认超时时间为 60 秒。5. Legacy MCP 响应 (mcp_response)
6. 状态更新 (status)
客户端可以发送状态更新消息:7. Workflow 执行
Web 客户端请求 Workflow 列表
Web 客户端 → 服务端:workflows_list 消息会自动转发给 Web 客户端。如果扩展未连接,返回:
Web 客户端执行 Workflow
Web 客户端 → 服务端:task_complete 消息后,服务端会通知 Web 客户端:
扩展端 Workflow 完成通知
Extension → 服务端:Workflow 执行的默认超时时间为 300 秒(5 分钟)。
错误处理
连接拒绝
当缺少必要参数时,服务端会关闭连接:断线处理
当 WebSocket 连接断开时,服务端会自动:- 从 ConnectionManager 中移除连接
- 从 NodeManager 中注销节点(Extension/Desktop)
- 清理所有挂起的请求
ConnectionManager API
ConnectionManager 是 WebSocket 网关的核心单例,管理所有连接的生命周期。
连接管理
连接查询
消息发送
工具调用
连接统计 (get_stats)
数据结构
多节点连接模型
ConnectionManager 使用嵌套字典管理连接,支持每个用户拥有多个节点:- Extension / Desktop:每个用户可连接多个节点(多设备),通过
node_id区分 - Web:每个用户可有多个 Web 客户端(多标签页),使用 Set 存储