用途:在 iii 引擎中向已连接的 WebSocket 客户端推送实时更新,适合实时仪表盘、实时信息流和协作类功能。
主要能力:iii-stream 在配置的流端口(默认 3112)上提供 WebSocket 连接;客户端连接地址为 ws://host:{stream_port}/stream/{stream_name}/{group_id}。通过 stream::set、stream::get、stream::list、stream::delete 对流项目做增删改查,通过 stream::send 向某个流分组内所有已连接客户端推送事件。每个流项目由 stream_name、group_id、item_id 标识,data 为项目负载。createStream 可注册非默认流后端的自定义适配器。
使用方式:以 trigger 调用各原语,例如 trigger({ function_id: 'stream::set', payload: { stream_name, group_id, item_id, data } }) 写入项目,trigger({ function_id: 'stream::send', payload: { stream_name, group_id, data } }) 推送事件,stream::get 读取、stream::list 列出分组项目、stream::delete 删除。常见模式还包括 registerWorker(url, { workerName }) 初始化 worker。浏览器端 WebSocket 连接应使用 iii-browser-sdk,而非 Node SDK;支持通过 literals 进行流认证。iii-stream 需在 iii-config.yaml 中启用并配置端口与适配器(KvStore 或 Redis)。
适用场景:按领域命名流(如 chat-messages、dashboard-metrics、notifications),用 group_id 按用户、房间或租户分区;可与 iii-state-reactions 结合,在状态变化时推送流事件;默认适配器不满足需求(如自定义持久化或扇出逻辑)时使用 createStream。
限制:若任务只是持久化键值数据而无实时推送,应优先使用 iii-state-management;若需要服务端状态变化的响应式触发,应优先使用 iii-state-reactions。仅当主要需求是向已连接客户端推送实时更新时使用本技能,不应作为无关任务的通用回退,也不应在更具体的 iii 技能更合适时使用。应用示例前需先确认环境与安全约束。参考实现见 references/realtime-streams.js,另有 Python 与 Rust 版本;完整配置参考见 references/iii-config.yaml。