From 2a715aba7e1418972cfda24d7f86eb0110bf8ed3 Mon Sep 17 00:00:00 2001
From: yumoqing <yumoqing@icloud.com>
Date: Mon, 26 Jan 2026 21:33:35 +0800
Subject: [PATCH] bugfix

---
 README.md | 318 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 318 insertions(+)

diff --git a/README.md b/README.md
index e69de29..cb66dcd 100644
--- a/README.md
+++ b/README.md
@@ -0,0 +1,318 @@
+# 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 基本结构
+
+```yaml
+id: order_flow_v1
+start: start
+
+nodes:
+  start:
+    type: task
+
+  end:
+    type: end
+
+edges:
+  - from: start
+    to: end
+```
+
+---
+
+### 4.2 条件转移
+
+```yaml
+edges:
+  - from: decision
+    to: approved
+    when: ctx.ok == true
+
+  - from: decision
+    to: rejected
+    when: ctx.ok == false
+```
+
+条件表达式在运行时基于 ctx 求值。
+
+---
+
+### 4.3 并发（Fork / Join）
+
+#### Fork（隐式）
+
+```yaml
+edges:
+  - from: fetch
+    to: validate
+  - from: fetch
+    to: enrich
+```
+
+#### Join
+
+```yaml
+nodes:
+  join:
+    type: join
+    wait_for:
+      - validate
+      - enrich
+```
+
+join 节点只有在所有依赖节点完成后才会继续。
+
+---
+
+## 5. 子流程（SubFlow）说明
+
+### 5.1 子流程的定义方式
+
+```yaml
+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 编排底座
+* 业务流程控制层
+* 长任务调度引擎
+
+在不引入新能力的前提下，本说明书描述的即为**当前版本的完整行为定义**。
+