Squid Mesh：面向 Elixir 应用的持久化工作流运行时

Squid Mesh 是一个为 Elixir 应用设计的嵌入式持久化工作流运行时，通过声明式 DSL 支持人机协同和智能体工作流，提供重试、审批、 Saga 补偿等企业级能力。

• 原作者/维护者：dark-trench
• 来源平台：GitHub
• 原始标题：squid_mesh
• 原始链接：https://github.com/dark-trench/squid_mesh
• 发布时间：2026-05-26

在现代应用开发中，工作流编排已成为复杂业务逻辑的核心需求。从简单的任务链到涉及人工审批、条件分支、故障恢复的长流程，开发者往往面临一个两难选择：使用重量级的外部编排服务（如 Temporal、Camunda）会引入额外的运维负担和架构复杂度；而自研方案又难以保证持久性、可观测性和容错能力。

Squid Mesh 的出现正是为了解决这一痛点。它不是一个独立的服务或集群，而是一个可以嵌入到现有 Elixir/Phoenix 应用中的持久化工作流运行时，让开发者在保持现有部署架构的同时，获得企业级的工作流编排能力。

Squid Mesh 的设计遵循几个关键原则：

嵌入式而非独立部署。与许多工作流引擎不同，Squid Mesh 不运行单独的 broker 或编排集群。它直接嵌入到宿主应用的监督树中，复用现有的数据库、调度器和队列后端。这种设计显著降低了运维复杂度，同时保持了工作流的持久化保证。

声明式 DSL。工作流通过 Elixir 模块中的 DSL 定义，包括触发器、步骤、转换和补偿逻辑。这种方式既利用了 Elixir 的编译时检查优势，又保持了代码的可读性和可维护性。

职责分离。Squid Mesh 负责工作流的状态管理、步骤执行、重试策略、暂停/审批处理和恢复策略；而队列投递、工作器监督和租约管理仍由宿主应用控制。这种清晰的边界让开发者可以灵活选择底层基础设施。

Squid Mesh 构建在几个成熟的 Elixir 库之上：

• Jido：提供动作定义、执行和日志记录的基础设施
• Runic：负责工作流规划和图遍历
• Spark：支持 DSL 的创作和扩展
• Ecto：默认的持久化适配器，支持主流关系型数据库

这种分层架构不仅保证了功能的完备性，也让每个组件可以独立演进。

Squid Mesh 的 DSL 设计直观且富有表现力。以下是一个简化的示例，展示了如何定义一个包含手动触发、步骤执行、人工审批和条件分支的工作流：

defmodule MyApp.Workflows.OrderProcessing do
  use SquidMesh.Workflow

  workflow do
    trigger :new_order do
      manual()
      payload do
        field :customer_id, :string
        field :amount, :float
        field :priority, :atom, default: :normal
      end
    end

    step :validate_order, MyApp.Steps.ValidateOrder,
      input: [:customer_id, :amount],
      output: :validation_result,
      transaction: :repo

    step :check_inventory, MyApp.Steps.CheckInventory,
      input: [:validation_result],
      retry: [max_attempts: 3, backoff: [type: :exponential, min: 1000, max: 10000]]

    approval_step :manager_review,
      output: :approval_result

    step :process_payment, MyApp.Steps.ProcessPayment,
      compensate: MyApp.Steps.RefundPayment

    transition :validate_order, on: :ok, to: :check_inventory
    transition :check_inventory, on: :ok, to: :manager_review
    transition :manager_review, on: :ok, to: :process_payment
    transition :manager_review, on: :error, to: :complete
    transition :process_payment, on: :ok, to: :complete
  end
end

这个示例展示了 DSL 的核心元素：触发器定义了工作流的入口和负载结构；步骤声明了输入输出、重试策略和补偿行为；审批步骤支持人机协同；转换规则定义了执行路径。

重试与退避。每个步骤可以配置独立的重试策略，支持指数退避、固定间隔等模式。当外部服务暂时不可用或出现瞬时故障时，系统会自动重试，无需人工干预。

Saga 补偿。对于涉及多个外部系统的长事务，Squid Mesh 支持 Saga 模式。当某个步骤失败时，系统会按照相反的顺序执行已完步骤的补偿操作，确保业务一致性。

人工审批。通过 approval_step 可以定义需要人工介入的节点。工作流会在该点暂停，直到审批人通过 API 或界面提交决策。

定时触发。支持 Cron 表达式定义周期性工作流，如每日报表生成、定期数据清理等场景。

依赖驱动的执行。除了显式的转换规则，还支持基于依赖关系的执行模式。一个步骤可以声明依赖多个前置步骤，只有当所有依赖都成功完成后才会执行。

启动工作流非常简单：

{:ok, run} = SquidMesh.start_run(
  MyApp.Workflows.OrderProcessing,
  :new_order,
  %{customer_id: "cust_123", amount: 999.99}
)

系统提供了丰富的监控能力。inspect_run 可以查看工作流的完整历史，包括每个步骤的执行记录、审计事件和审批历史。explain_run 则生成面向运维人员的友好解释，说明当前状态、可能原因和后续操作建议。