Skip to content

RemoteTool Socket.IO 协议

RemoteTool 使用 /remote-tool namespace，让外部 Provider 注册工具，并由 Celery worker 中的 Robot 调用这些工具。

参与方

  • Robot 是业务实例，持有 Drive 并决定何时调用工具。
  • Celery worker 是 Robot 的运行宿主，维护 Socket.IO 连接并把远程工具同步到 Robot Drive。
  • Provider 是外部工具实现方，负责注册、撤销和执行工具。
  • Socket.IO Server 保存注册关系，并在 Robot 与 Provider 之间转发请求。
Provider -- register/revoke --> Socket.IO Server
                                   |
                                   +-- remote_tools_changed --> Celery worker / Robot Drive

Robot -- RemoteTool call --> Celery worker --> Socket.IO Server --> Provider
Robot <-- ToolReturn ------- Celery worker <-- acknowledgement --- Provider

当前信任模型

当前部署采用单 Robot 所有者的可信连接模型：

  • 所有成功通过 Socket.IO 认证并连接 /remote-tool 的客户端都视为可信。
  • robot 与 provider 是协议职责，不是服务端授权角色。
  • 服务端暂不限制不同客户端可调用的事件，也不阻止可信客户端查询或调用其他 Provider 的工具。
  • providerId 当前绑定注册连接的 Socket.IO SID，断线时对应注册会被清理。

这个模型只适用于连接者属于同一可信边界的部署。如果未来允许互不信任的第三方接入， 需要增加服务端身份、事件权限和 Provider 资源隔离；不能仅依赖客户端遵守事件约定。

事件方向

事件 常规发起方 处理方 用途
register Provider Server 注册工具定义
revoke Provider Server 撤销当前连接注册的工具
get_all_registered_tools Celery worker Server 将注册目录同步到 Robot Drive
remote_tools_changed Server Celery worker 通知 Robot Drive 增量更新
remote_tool_invoke Celery worker Server / Provider 调用目标 Provider 的工具

并发约束

“只有一个 Robot 实例”不等同于“只有一个工具调用线程”。生产 Robot Celery 使用单进程 线程池，当前配置为 --pool=threads --concurrency=4，多个会话可能同时驱动同一个 Robot。

所有 RemoteTool 共享 Celery worker 的同步 python-socketio Client，而 Client.call() 本身 不是线程安全的。与现有 SMCPTool 的同步客户端约束一致，当前不支持同一 Robot 并发执行远程 工具调用，Robot 执行链必须保证这类调用为 single-flight。

若后续需要并发处理多个可能调用 RemoteTool 的 Robot 任务，应先在共享 Socket.IO transport 上增加统一串行化机制，而不是给每个 RemoteTool 实例分别加锁。