iii-channels

用途

iii-channels 用于在 iii 引擎的 worker 之间建立二进制流式传输通道。当任务的核心问题是「在 worker 之间流式传输二进制数据」时，应使用本技能。它适合构建数据管道、文件传输、流式响应，以及任何需要传输二进制数据、而不希望将其序列化进 JSON 负载的模式。

官方将其类比为 Unix 管道、gRPC 流式传输、WebSocket 数据流。

主要能力

通道（Channel）：一个由 WebSocket 支撑的、连接两个端点（写入端与读取端）的二进制流。
createChannel()：返回一对 writer/reader，以及可序列化的引用（refs），可传递给其他 worker。
StreamChannelRef：可序列化引用，包含 channel_id、access_key、direction，可放入函数负载中传递。
写入端：发送二进制数据（按 64KB 分帧）以及文本消息。
读取端：通过 readAll() 消费二进制分块，或通过回调接收文本消息。
跨 worker、跨语言：一个 Python 写入端可以向 Rust 读取端流式发送数据。

架构

一个函数通过 createChannel() 创建通道，获得 writer 与 reader 对。writer ref 或 reader ref 通过触发负载传递给另一个函数（可能位于不同 worker 或不同语言）。引擎在两个端点之间代理 WebSocket 连接。二进制数据经由引擎的通道端点直接在 worker 之间流动。

使用方式

iii 原语：

createChannel(bufferSize?)：创建通道，返回 writer + reader 对。
ChannelWriter.write(data)：发送二进制数据（按 64KB 分帧）。
ChannelWriter.sendMessage(msg)：通过通道发送文本消息。
ChannelWriter.close()：关闭写入端。
ChannelReader.readAll()：将整个流读入单个缓冲区。
ChannelReader.onMessage(callback)：为文本消息注册回调。
StreamChannelRef：在 worker 之间传递的可序列化引用。

参考实现（按语言）：TypeScript 见 ../references/channels.js，Python 见 ../references/channels.py，Rust 见 ../references/channels.rs。每个参考实现展示相同的模式（通道创建、二进制流式传输、文本消息、跨函数交接）。

常见代码模式包括：

const channel = await iii.createChannel() —— 创建通道对（生产者侧访问）。
channel.writer.stream.write(buffer) / channel.writer.write(data) —— 发送二进制数据。
channel.writer.sendMessage(JSON.stringify({ type: 'metadata', ... })) —— 发送文本元数据。
channel.writer.close() —— 表示流结束。
在触发负载中传递 channel.readerRef 或 channel.writerRef，实现跨 worker 流式传输。
消费方必须从 ref 重建 reader，例如 new ChannelReader(iii.address, readerRef)。
const data = await reader.readAll() —— 读取整个流（消费方行为）。
reader.onMessage(msg => { ... }) —— 处理文本消息（消费方行为）。

注意：消费方必须从可序列化的 StreamChannelRef 构造 reader（例如 ChannelReader::new(...)），而不能使用 createChannel() 返回的生产者侧 reader 对象。

适用场景与适配

用于不应被序列化进 JSON 负载的大数据传输。
管道模式：将 readerRef 传给处理函数，将 writerRef 传给生产函数。
在二进制数据流之外，用文本消息传递元数据或信令。
当读取端可能慢于写入端时，设置 bufferSize 以施加背压。
跨语言：TypeScript 生产者可以向 Rust 消费者流式发送数据。

限制与边界

并非每个 worker 都需要通道，仅在概念契合任务时使用。
键值状态持久化应优先使用 iii-state-management。
流 CRUD（带 groups/keys 的命名流）应优先使用 iii-realtime-streams。
发布/订阅消息应优先使用 subscribe 类型的触发器。
仅当主要问题是 worker 之间的二进制数据流式传输时，才使用 iii-channels。
不得将本技能作为无关任务的通用兜底方案。
当有更具体的 iii 技能更合适时，不得应用本技能。
应用本技能中的示例前，务必先验证环境与安全约束。

技能介绍

用途

主要能力

架构

使用方式

适用场景与适配

限制与边界