iii-effect-system

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

可比对象：Effect-TS

核心概念

在适合任务时使用以下概念。并非每条 effect 流水线都需要全部概念。

• 每个 effect 都是一个已注册的函数，且只负责一项职责（解析、丰富、持久化、通知）
• 通过 trigger 从一个函数调用另一个函数来组合 effect
• 整条流水线都可通过 OpenTelemetry 进行端到端追踪
• 错误会自然传播——某个 effect 失败时，链路会停止
• HTTP 触发器提供入口；effect 从此处开始串联

架构

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 原语

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

参考实现

完整可运行示例请参阅 ../references/effect-system.js：这是一个用户注册流水线，其中输入会被解析、通过外部数据进行丰富、持久化到状态中，并触发欢迎通知。

常见模式

使用此模式的代码通常会在适用时包含：

• registerWorker(url, { workerName }) — worker 初始化
• trigger({ function_id, payload }) — 同步组合（effect A 调用 effect B）
• 每个 effect 都作为独立的 registerFunction，ID 使用 fx:: 前缀
• 验证失败时抛出错误（错误会沿链路向上传播）
• trigger({ ..., action: TriggerAction.Void() }) — 对非关键副作用采用触发即弃方式
• const logger = new Logger() — 为每个 effect 进行结构化日志记录

调整此模式

在适用于任务时使用以下调整方式。

• 将模拟逻辑替换为实际工作（API 调用、数据库查询、ML 推理）
• 通过注册函数并使用 trigger 调用它们来添加新 effect
• 对于不可靠的步骤，使用 TriggerAction.Enqueue({ queue }) 代替同步 trigger
• 尽可能保持 effect 纯粹——接收输入、返回输出，不产生隐藏的副作用
• 函数 ID 应带有领域前缀（例如 fx::validate-email、fx::geocode-address）

模式边界

• 如果请求涉及需要重试和 DLQ 处理的持久化多步骤工作流，请优先使用 iii-workflow-orchestration。
• 如果任务涉及多个相互独立、需要交接工作的 Agent，请优先使用 iii-agentic-backend。
• 当主要关注点是可组合、可追踪且带有同步链式调用的函数流水线时，请使用 iii-effect-system。

适用场景

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

边界

• 切勿将此技能用作无关任务的通用兜底方案。
• 如果有更具体的 iii 技能更适合，切勿应用此技能。
• 应用此技能中的示例之前，务必先核实环境和安全约束。