dagflow/README.md

Workflow Engine 使用说明书

版本：v1.1（sqlor 持久化 + 子流程 input/output mapping）

本文档用于说明当前 Workflow Engine 的设计目标、核心概念、数据模型、DSL 用法、执行语义以及使用示例。不涉及未来规划能力。

---

1. 引擎定位与设计原则

1.1 引擎是什么

这是一个：

• DAG（有向无环图）流程引擎内核
• 支持 条件转移 / 并发 / 子流程
• 支持 Definition / Instance 分离
• 支持 数据库持久化与恢复

它不是：

• 简单任务编排脚本
• BPMN UI 工具
• 强绑定某种业务或 skill 的框架

---

1.2 核心设计原则

1. 流程定义不可变，实例可变
2. 所有运行状态必须可持久化
3. 流程控制与业务执行解耦
4. 子流程是边界，而不是函数调用
5. 数据流必须显式声明（input / output mapping）

---

2. 核心概念说明

2.1 FlowDefinition（流程定义）

• 描述“流程长什么样”
• 由 YAML DSL 表达
• 可被多个流程实例复用

包含内容：

• 起始节点（start）
• 节点集合（nodes）
• 边集合（edges）

---

2.2 FlowInstance（流程实例）

• 流程的一次真实运行

• 持有自己的：

  • ctx（上下文）
  • active_nodes（当前活跃节点）
  • status（running / finished）

所有流转都发生在实例中，而不是定义中。

---

2.3 Node 类型

类型	说明
task	普通执行节点（业务 / skill）
decision	条件判断节点
join	并发汇合节点
subflow	子流程节点
end	结束节点

---

3. 数据模型（数据库表）

3.1 flow_definition

用于存储流程定义（DSL）。

关键字段：

• id：定义 ID
• name / version：业务标识
• dsl：YAML 内容

---

3.2 flow_instance

用于存储流程运行状态。

关键字段：

• id：实例 ID
• flow_def_id：关联定义
• ctx：JSON 上下文
• active_nodes：当前节点集合
• status：running / finished

---

3.3 node_execution

用于记录节点执行历史（审计 / 回放）。

关键字段：

• instance_id
• node_id
• input_ctx / output_ctx
• status

---

3.4 subflow_instance

用于描述父子流程关系。

关键字段：

• parent_instance_id
• parent_node_id
• child_instance_id
• status

这是“子流程存在性”的核心表。

---

4. YAML DSL 说明

4.1 基本结构

id: order_flow_v1
start: start

nodes:
  start:
    type: task

  end:
    type: end

edges:
  - from: start
    to: end

---

4.2 条件转移

edges:
  - from: decision
    to: approved
    when: ctx.ok == true

  - from: decision
    to: rejected
    when: ctx.ok == false

条件表达式在运行时基于 ctx 求值。

---

4.3 并发（Fork / Join）

Fork（隐式）

edges:
  - from: fetch
    to: validate
  - from: fetch
    to: enrich

Join

nodes:
  join:
    type: join
    wait_for:
      - validate
      - enrich

join 节点只有在所有依赖节点完成后才会继续。

---

5. 子流程（SubFlow）说明

5.1 子流程的定义方式

nodes:
  payment:
    type: subflow
    flow: payment_flow_v1

    input:
      order_id: ctx.order.id
      amount: ctx.order.total

    output:
      pay_status: ctx.payment.status
      pay_id: ctx.payment.id

---

5.2 子流程的执行语义

1. 父流程第一次到达 subflow 节点：

   • 创建子流程实例
   • 根据 input mapping 构建子 ctx
   • 父流程阻塞在该节点

2. 子流程运行中：

   • 父流程不推进

3. 子流程完成：

   • 根据 output mapping 合并 ctx
   • 父流程继续流转

---

5.3 input / output mapping 原则

• 子流程只能看到显式声明的输入
• 父流程只接收显式声明的输出
• ctx 不做隐式全量共享

这样可以保证：

• 数据边界清晰
• 子流程可复用
• 行为可审计

---

6. 执行模型

6.1 推进方式

引擎通过反复调用：

engine.step(instance_id)

来推进流程。

• 每次 step 只推进“可推进的节点”
• 阻塞节点（join / subflow）会被保留在 active_nodes 中

---

6.2 结束判定

当：

• active_nodes 中全部为 end 节点

则流程实例状态被置为：

status = finished

---

7. 当前能力边界说明

已支持

• DAG 流程
• 条件转移
• 并发 / join
• 子流程（含 input/output mapping）
• 持久化 / 可恢复

明确未支持（但结构允许）

• 失败补偿
• 超时 / 重试
• 表达式安全沙箱
• 人工任务

---

8. 总结

当前这套 Workflow Engine 是一个：

结构清晰、语义明确、可扩展的流程引擎内核

它适合作为：

• skills / agents 编排底座
• 业务流程控制层
• 长任务调度引擎

在不引入新能力的前提下，本说明书描述的即为当前版本的完整行为定义。