iii-effect-system

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Effect Systems & Typed Functional Infrastructure

效应系统与类型化函数式基础设施

Comparable to: Effect-TS

类似技术：Effect-TS

Key Concepts

核心概念

Use the concepts below when they fit the task. Not every effect pipeline needs all of them.

Each effect is a registered function with a single responsibility (parse, enrich, persist, notify)
Effects compose by calling one function from another via
```
trigger
```
The entire pipeline is traceable end-to-end through OpenTelemetry
Errors propagate naturally — a failing effect stops the chain
An HTTP trigger provides the entry point; effects chain from there

当任务适配时使用以下概念，并非所有效应管道都需要全部概念。

每个效应都是一个具有单一职责的已注册函数（解析、增强、持久化、通知）
效应通过
```
trigger
```
调用另一个函数来实现组合
整个管道可通过OpenTelemetry实现端到端追踪
错误会自然传播——失败的效应会终止整个链条
HTTP触发器作为入口点，效应从这里开始链式执行

Architecture

架构

text

HTTP request
  → fx::parse-user-input (validate + normalize)
    → fx::enrich (add metadata, lookup external data)
      → fx::persist (write to state)
        → fx::notify (fire-and-forget side effect)
  ← composed result returned to caller

text

HTTP request
  → fx::parse-user-input (validate + normalize)
    → fx::enrich (add metadata, lookup external data)
      → fx::persist (write to state)
        → fx::notify (fire-and-forget side effect)
  ← composed result returned to caller

iii Primitives Used

使用的iii原语

Primitive	Purpose
`registerWorker`	Initialize the worker and connect to iii
`registerFunction`	Define each effect
`trigger({ function_id, payload })`	Compose effects synchronously
`trigger({ ..., action: TriggerAction.Void() })`	Fire-and-forget side effects
`trigger({ function_id: 'state::set/get', payload })`	Persist data between effects
`registerTrigger({ type: 'http' })`	Entry point

原语	用途
`registerWorker`	初始化worker并连接到iii引擎
`registerFunction`	定义每个效应函数
`trigger({ function_id, payload })`	同步组合效应函数
`trigger({ ..., action: TriggerAction.Void() })`	触发即发即弃的副作用
`trigger({ function_id: 'state::set/get', payload })`	在效应之间持久化数据
`registerTrigger({ type: 'http' })`	定义管道入口点

Reference Implementation

参考实现

See ../references/effect-system.js for the full working example — a user signup pipeline where input is parsed, enriched with external data, persisted to state, and a welcome notification is fired.

完整可运行示例请参见../references/effect-system.js —— 这是一个用户注册管道，其中输入会被解析、补充外部数据、持久化到状态中，并触发欢迎通知。

Common Patterns

常见模式

Code using this pattern commonly includes, when relevant:

```
registerWorker(url, { workerName })
```
— worker initialization
```
trigger({ function_id, payload })
```
— synchronous composition (effect A calls effect B)
Each effect as its own
```
registerFunction
```
with
```
fx::
```
prefix IDs
Error throwing for validation failures (errors propagate up the chain)
```
trigger({ ..., action: TriggerAction.Void() })
```
— fire-and-forget for non-critical side effects
```
const logger = new Logger()
```
— structured logging per effect

使用该模式的代码通常包含以下内容（相关时）：

```
registerWorker(url, { workerName })
```
—— worker初始化
```
trigger({ function_id, payload })
```
—— 同步组合（效应A调用效应B）
每个效应都是独立的
```
registerFunction
```
，函数ID以
```
fx::
```
为前缀
验证失败时抛出错误（错误会沿链条向上传播）
```
trigger({ ..., action: TriggerAction.Void() })
```
—— 对非关键副作用使用即发即弃模式
```
const logger = new Logger()
```
—— 为每个效应添加结构化日志

Adapting This Pattern

模式适配

Use the adaptations below when they apply to the task.

Replace simulated logic with real work (API calls, database queries, ML inference)
Add new effects by registering functions and calling them via
```
trigger
```
For unreliable steps, use
```
TriggerAction.Enqueue({ queue })
```
instead of synchronous
```
trigger
```
Keep effects pure where possible — accept input, return output, no hidden side effects
Function IDs should be domain-prefixed (e.g.
```
fx::validate-email
```
,
```
fx::geocode-address
```
)

当任务适配时，可进行以下调整：

用实际业务逻辑替换模拟逻辑（API调用、数据库查询、机器学习推理）
通过注册新函数并使用
```
trigger
```
调用的方式添加新效应
对于不可靠的步骤，使用
```
TriggerAction.Enqueue({ queue })
```
替代同步
```
trigger
```
尽可能保持效应的纯函数特性——接收输入、返回输出，无隐藏副作用
函数ID应添加领域前缀（例如
```
fx::validate-email
```
、
```
fx::geocode-address
```
）

Pattern Boundaries

模式边界

If a request is about durable multi-step workflows with retries and DLQ handling, prefer
```
iii-workflow-orchestration
```
.
If the task involves multiple independent agents handing off work, prefer
```
iii-agentic-backend
```
.
Stay with
```
iii-effect-system
```
when the primary concern is composable, traceable function pipelines with synchronous chaining.

如果需求是具备重试和死信队列（DLQ）处理的持久化多步骤工作流，优先选择
```
iii-workflow-orchestration
```
。
如果任务涉及多个独立代理交接工作，优先选择
```
iii-agentic-backend
```
。
当核心需求是构建可组合、可追踪且同步链式执行的函数管道时，使用
```
iii-effect-system
```
。

When to Use

使用场景

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

当任务主要围绕iii引擎中的
```
iii-effect-system
```
展开时，使用该技能。
当请求直接要求实现该模式或等效方案时触发。

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技能时，不得使用该技能。
在应用该技能的示例前，务必验证环境和安全约束。