iii-workflow-orchestration

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Workflow Orchestration & Durable Execution

工作流编排与持久化执行

Comparable to: Temporal, Airflow, Inngest

同类工具：Temporal、Airflow、Inngest

Key Concepts

核心概念

Use the concepts below when they fit the task. Not every workflow needs every durability or tracking mechanism shown here.

Each pipeline step is a registered function chained via named queues with config-driven retries
Step progress is tracked in shared state and broadcast via streams
A cron trigger handles scheduled maintenance (e.g. stale order cleanup)
Queue behavior (retries, backoff, concurrency, FIFO) is defined per queue in
```
iii-config.yaml
```

当任务需要时使用以下概念。并非每个工作流都需要此处展示的所有持久化或跟踪机制。

每个管道步骤都是一个已注册的函数，通过命名队列进行链式调用，重试由配置驱动
步骤进度在共享状态中跟踪，并通过流进行广播
Cron触发器处理定时维护（如过期订单清理）
队列行为（重试、退避、并发、FIFO）在
```
iii-config.yaml
```
中按队列定义

Architecture

架构

text

HTTP (create order)
  → Enqueue(order-validate) → validate
    → Enqueue(order-payment) → charge-payment
      → Enqueue(order-ship) → ship
        → publish(order.fulfilled)

Cron (hourly) → cleanup-stale

Queue configs (iii-config.yaml):
  order-validate:  max_retries: 2
  order-payment:   max_retries: 5, type: fifo, concurrency: 2
  order-ship:      max_retries: 3

text

HTTP (创建订单)
  → Enqueue(order-validate) → 验证
    → Enqueue(order-payment) → 支付扣款
      → Enqueue(order-ship) → 发货
        → publish(order.fulfilled)

Cron (每小时) → 清理过期订单

队列配置 (iii-config.yaml):
  order-validate:  max_retries: 2
  order-payment:   max_retries: 5, type: fifo, concurrency: 2
  order-ship:      max_retries: 3

iii Primitives Used

使用的iii原语

Primitive	Purpose
`registerWorker`	Initialize the worker and connect to iii
`registerFunction`	Define each pipeline step
`trigger({ ..., action: TriggerAction.Enqueue({ queue }) })`	Durable step chaining via named queues
`trigger({ function_id: 'state::...', payload })`	Track step progress
`trigger({ ..., action: TriggerAction.Void() })`	Fire-and-forget stream events and publish
`registerTrigger({ type: 'cron' })`	Scheduled maintenance
`registerTrigger({ type: 'http' })`	Entry point

原语	用途
`registerWorker`	初始化worker并连接到iii引擎
`registerFunction`	定义每个管道步骤
`trigger({ ..., action: TriggerAction.Enqueue({ queue }) })`	通过命名队列实现持久化步骤链式调用
`trigger({ function_id: 'state::...', payload })`	跟踪步骤进度
`trigger({ ..., action: TriggerAction.Void() })`	触发即忘的流事件并发布
`registerTrigger({ type: 'cron' })`	定时维护
`registerTrigger({ type: 'http' })`	入口点

Reference Implementation

参考实现

See ../references/workflow-orchestration.js for the full working example — an order fulfillment pipeline with validate → charge → ship steps, retry configuration, stream-based progress tracking, and hourly stale-order cleanup.

查看../references/workflow-orchestration.js获取完整的工作示例——一个包含验证→扣款→发货步骤、重试配置、基于流的进度跟踪以及每小时过期订单清理的订单履约管道。

Common Patterns

常见模式

Code using this pattern commonly includes, when relevant:

```
registerWorker(url, { workerName })
```
— worker initialization

trigger({ function_id, payload, action: TriggerAction.Enqueue({ queue }) })

— durable step chaining via named queues

trigger({ function_id: 'state::update', payload: { scope, key, ops } })

— step progress tracking

Named queues with a comment referencing
```
iii-config.yaml
```
for retry/concurrency settings
```
const logger = new Logger()
```
— structured logging per step
Each step as its own
```
registerFunction
```
with a single responsibility

trigger({ function_id: 'publish', payload, action: TriggerAction.Void() })

— completion broadcast

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

```
registerWorker(url, { workerName })
```
—— worker初始化

trigger({ function_id, payload, action: TriggerAction.Enqueue({ queue }) })

—— 通过命名队列实现持久化步骤链式调用

trigger({ function_id: 'state::update', payload: { scope, key, ops } })

—— 步骤进度跟踪

带有注释的命名队列，注释引用
```
iii-config.yaml
```
中的重试/并发设置
```
const logger = new Logger()
```
—— 每个步骤的结构化日志
每个步骤都是独立的
```
registerFunction
```
，单一职责

trigger({ function_id: 'publish', payload, action: TriggerAction.Void() })

—— 完成事件广播

Adapting This Pattern

适配此模式

Use the adaptations below when they apply to the task.

Each step should do one thing and enqueue the next function on success
Define separate named queues in
```
iii-config.yaml
```
when steps need different retry/concurrency settings
Capture enqueue receipts (
```
messageReceiptId
```
) for observability and DLQ correlation when needed
The
```
trackStep
```
helper pattern (state update + stream event) is reusable for any pipeline
Failed jobs exhaust retries and move to a DLQ — see the dead-letter-queues HOWTO
DLQ support for named queues is provided by the Builtin and RabbitMQ adapters (Redis is pub/sub only)
Cron expressions use 7-position numeric format:
```
0 0 * * * * *
```
(every hour)

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

每个步骤应只完成一件事，并在成功时将下一个函数加入队列
当步骤需要不同的重试/并发设置时，在
```
iii-config.yaml
```
中定义单独的命名队列
必要时捕获入队回执（
```
messageReceiptId
```
），用于可观测性和DLQ关联
```
trackStep
```
助手模式（状态更新+流事件）可复用至任何管道
失败任务耗尽重试次数后会转移到DLQ——请查看死信队列操作指南
内置适配器和RabbitMQ适配器支持命名队列的DLQ功能（Redis仅支持发布/订阅）
Cron表达式使用7位数字格式：
```
0 0 * * * * *
```
（每小时执行一次）

Engine Configuration

引擎配置

Named queues for pipeline steps are declared in iii-config.yaml under

queue_configs

with per-queue retry, concurrency, and FIFO settings. See ../references/iii-config.yaml for the full annotated config reference.

管道步骤的命名队列在iii-config.yaml的

queue_configs

下声明，包含每个队列的重试、并发和FIFO设置。查看../references/iii-config.yaml获取完整的带注释配置参考。

Pattern Boundaries

模式边界

If the task is "model HTTP endpoints as HTTP-invoked
```
registerFunction
```
functions" (including
```
{ path, id }
```
arrays iterated into registration), prefer
```
iii-http-invoked-functions
```
.
Stay with
```
iii-workflow-orchestration
```
when durable step sequencing, queue retries/backoff, and workflow progress tracking are the primary concerns.

如果任务是“将HTTP端点建模为HTTP调用的
```
registerFunction
```
函数”（包括迭代
```
{ path, id }
```
数组进行注册），请优先使用
```
iii-http-invoked-functions
```
。
当持久化步骤排序、队列重试/退避和工作流进度跟踪是主要需求时，使用
```
iii-workflow-orchestration
```
。

When to Use

使用场景

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

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

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技能更合适时，不得应用此技能。
在应用此技能中的示例之前，始终验证环境和安全约束。