iii-channels

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Channels

通道

Comparable to: Unix pipes, gRPC streaming, WebSocket data streams

类似技术：Unix管道、gRPC流式传输、WebSocket数据流

Key Concepts

核心概念

Use the concepts below when they fit the task. Not every worker needs channels.

A Channel is a WebSocket-backed binary stream between two endpoints (writer and reader)
```
createChannel()
```
returns a writer/reader pair plus serializable refs that can be passed to other workers
StreamChannelRef is a serializable reference (channel_id, access_key, direction) that can be included in function payloads
Writers send binary data (chunked into 64KB frames) and text messages
Readers consume binary chunks via
```
readAll()
```
or receive text messages via callbacks
Consumers must construct a reader from a serializable
```
StreamChannelRef
```
(e.g.,
```
ChannelReader::new(...)
```
) rather than using the producer-side reader object returned by
```
createChannel()
```
Channels work cross-worker and cross-language — a Python writer can stream to a Rust reader

当任务匹配时使用以下概念，并非所有Worker都需要通道。

Channel 是基于WebSocket的、连接两个端点（writer和reader）的二进制流
```
createChannel()
```
返回writer/reader对，以及可序列化的引用，这些引用可传递给其他Worker
StreamChannelRef 是可序列化的引用（包含channel_id、access_key、direction），可包含在函数负载中
Writer发送二进制数据（分割为64KB帧）和文本消息
Reader通过
```
readAll()
```
消费二进制块，或通过回调接收文本消息
消费者必须从可序列化的
```
StreamChannelRef
```
构造reader（例如
```
ChannelReader::new(...)
```
），而非使用
```
createChannel()
```
返回的生产者端reader对象
通道支持跨Worker、跨语言使用——Python writer可向Rust reader流式传输数据

Architecture

架构

A function creates a channel via

createChannel()

, receiving a writer and reader pair. The writer ref or reader ref is passed to another function (potentially in a different worker/language) via a trigger payload. The engine brokers the WebSocket connection between the two endpoints. Binary data flows directly between workers through the engine's channel endpoint.

函数通过

createChannel()

创建通道，获取writer和reader对。writer引用或reader引用通过触发负载传递给另一个函数（可能位于不同的Worker或语言环境中）。引擎负责代理两个端点之间的WebSocket连接。二进制数据通过引擎的通道端点在Worker之间直接传输。

iii Primitives Used

使用的iii原语

Primitive	Purpose
`createChannel(bufferSize?)`	Create a channel, returns writer + reader pair
`ChannelWriter.write(data)`	Send binary data (chunked into 64KB frames)
`ChannelWriter.sendMessage(msg)`	Send a text message through the channel
`ChannelWriter.close()`	Close the writer end
`ChannelReader.readAll()`	Read entire stream into a single buffer
`ChannelReader.onMessage(callback)`	Register callback for text messages
`StreamChannelRef`	Serializable reference to pass between workers

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

Reference Implementation

参考实现

TypeScript: ../references/channels.js
Python: ../references/channels.py
Rust: ../references/channels.rs

Each reference shows the same patterns (channel creation, binary streaming, text messages, cross-function handoff) in its respective language.

TypeScript: ../references/channels.js
Python: ../references/channels.py
Rust: ../references/channels.rs

每个示例都展示了相同的模式（通道创建、二进制流传输、文本消息、跨函数传递），对应各自的语言。

Common Patterns

常见模式

Code using this pattern commonly includes, when relevant:

```
const channel = await iii.createChannel()
```
— create a channel pair (producer access)

channel.writer.stream.write(buffer)

channel.writer.write(data)

— send binary data

channel.writer.sendMessage(JSON.stringify({ type: 'metadata', ... }))

— send text metadata

```
channel.writer.close()
```
— signal end of stream
Pass
```
channel.readerRef
```
or
```
channel.writerRef
```
in trigger payloads for cross-worker streaming
Consumer must reconstruct the reader from the ref: e.g.,
```
new ChannelReader(iii.address, readerRef)
```
```
const data = await reader.readAll()
```
— read entire stream (consumer behavior)
```
reader.onMessage(msg => { ... })
```
— handle text messages (consumer behavior)

使用此模式的代码通常包含以下相关内容：

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流式传输
消费者必须从引用重建reader：例如
```
new ChannelReader(iii.address, readerRef)
```
```
const data = await reader.readAll()
```
— 读取整个流（消费者行为）
```
reader.onMessage(msg => { ... })
```
— 处理文本消息（消费者行为）

Adapting This Pattern

模式适配

Use the adaptations below when they apply to the task.

Use channels for large data transfers that shouldn't be serialized into JSON payloads
Pass
```
readerRef
```
to a processing function and
```
writerRef
```
to a producing function for pipeline patterns
Use text messages for metadata/signaling alongside binary data streams
Set
```
bufferSize
```
when the reader may be slower than the writer to apply backpressure
Channels work cross-language — a TypeScript producer can stream to a Rust consumer

当任务符合以下情况时使用相应的适配方式：

对于不应序列化为JSON负载的大型数据传输，使用通道
为管道模式，将
```
readerRef
```
传递给处理函数，将
```
writerRef
```
传递给生产函数
结合二进制数据流，使用文本消息传递元数据/信号
当reader速度慢于writer时，设置
```
bufferSize
```
以实现背压
通道支持跨语言使用——TypeScript生产者可向Rust消费者流式传输数据

Pattern Boundaries

模式边界

For key-value state persistence, prefer
```
iii-state-management
```
.
For stream CRUD (named streams with groups/keys), prefer
```
iii-realtime-streams
```
.
For pub/sub messaging, prefer triggers with
```
subscribe
```
type.
Stay with
```
iii-channels
```
when the primary problem is binary data streaming between workers.

对于键值状态持久化，优先使用
```
iii-state-management
```
。
对于流CRUD（带分组/键的命名流），优先使用
```
iii-realtime-streams
```
。
对于发布/订阅消息，优先使用
```
subscribe
```
类型的触发器。
当核心需求是Worker间二进制流传输时，使用
```
iii-channels
```
。

When to Use

使用场景

Use this skill when the task is primarily about
```
iii-channels
```
in the iii engine.
Triggers when the request directly asks for this pattern or an equivalent implementation.

当任务主要涉及iii引擎中的
```
iii-channels
```
时，使用此技能。
当请求直接要求此模式或等效实现时触发。

Boundaries

边界限制

Never use this skill as a generic fallback for unrelated tasks.
You must not apply this skill when a more specific iii skill is a better fit.
Always verify environment and safety constraints before applying examples from this skill.

切勿将此技能作为无关任务的通用 fallback。
当更特定的iii技能更合适时，不得应用此技能。
在应用此技能的示例之前，务必验证环境和安全约束。