用途:iii-bridge 通过 iii-sdk 把当前 iii 引擎连接到另一个 iii 实例,让两侧函数可以跨边界互相调用。它向配置的 url 建立一条出站 WebSocket,用 service_id 向远端注册,并在引擎生命周期内保持连接;桥接即在这条长连接上做请求/响应,没有 trigger 类型。
主要能力:以配置驱动为主,核心是两个列表字段 forward: 和 expose:,用于在两侧绑定稳定的函数 id。配置完成后,调用方用常规 iii.trigger({ function_id, payload }) 调用这些稳定 id 即可跨桥,无需桥接专用调用形式。另注册 bridge.invoke 与 bridge.invoke_async 两个函数,作为远端函数 id 在运行时动态变化时的临时逃生口。
使用方式:bridge.invoke 调用远端 function_id 并等待返回值(直接返回,无信封),支持可选 timeout_ms(默认 30000)。bridge.invoke_async 把远端调用交给 WebSocket 发送队列后立即返回,忽略 timeout_ms,不返回远端响应。两者参数均为 { function_id, data?, timeout_ms? }。配置项包括:url(远端 iii 实例的 WebSocket 地址,默认 ${III_URL:ws://0.0.0.0:49134});service_id / service_name(向远端注册的标识与可读名称);expose: [{ local_function, remote_function? }](本引擎允许远端调用的函数,remote_function 为远端调用路径,默认取 local_function,初始化时注册到远端);forward: [{ local_function, remote_function, timeout_ms? }](把本地别名代理到远端函数的出站映射,worker 在本引擎注册 local_function,timeout_ms 覆盖单次调用期限,默认 30000)。
适用场景:两个 iii 引擎需要通过稳定长连接互调函数;希望远端函数以本地 id 出现(forward:),使调用点感知不到桥接;希望把特定本地函数暴露给远端引擎(expose:);远端函数 id 动态或仅做连通性探测时,使用 bridge.invoke 系列。
限制:优先使用 forward:/expose: 别名而非 bridge.invoke,逃生口仅用于动态 id 和一次性调用。bridge.invoke_async 为发后即忘,忽略 timeout_ms、不返回值,远端后续拒绝只记录日志、不会反馈给调用方。forward 别名与暴露 id 由运维按部署在 iii-config.yaml 中接线,不跨部署稳定,其文档随 worker 配置而非此处。失败返回 FunctionResult::Failure 及稳定错误码(deserialization_error 或 bridge_error);异步成功仅表示消息已入队,不代表远端已执行。