bugfix

skills/workflow-builder/README.md

@@ -0,0 +1,365 @@
+# 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
+
+input_ctx和output_ctx是jinja2模版的字符串，
+
+input_ctx使用流程实例上下文（ctx）作为数据来渲染，结果作为节点执行的输入字典
+
+output_ctx使用节点执行结果的字典数据作为数据来渲染，结果update到流程的ctx中
+
+实例节点有以下节点状态：
+* pending 创建后的初始状态
+* running 执行状态
+* done 执行成功状态
+* failed 执行失败状态
+* cancelled 取消状态
+状态变化: 
+* pending 转running 如果节点没有join属性，则在下个循环直接转running， 并调用节点执行方法，记录开始执行时间
+* running zhuan done 节点执行成功，并记录完成时间
+* running 转 failed 节点执行失败， 并记录完成时间
+* pending 转 cancel 取消执行（手工或流程实例被取消）
+
+---
+
+### 3.4 subflow_instance
+
+用于描述父子流程关系。
+
+关键字段：
+
+* instance_id
+* 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
+  
+  task1:
+    title: task1 title
+	type: task
+	description: desc
+	input_ctx:["k1:g1", "k2.kk1:g2"]	# 可选， 缺省使用流程实例的全部ctx
+	output_ctx:["k1:ck1", "k2:ck2.x"]	# 可选， 缺失全部输出更新到流程实例的ctx
+  
+  subflow1:
+	title: subf
+	type: subflow
+	subflow_id: payment_flow_v2
+	input_ctx:["k1:g1", "k2.kk1:g2"]	# 可选， 缺省使用流程实例的全部ctx
+	output_ctx:["k1:ck1", "k2:ck2.x"]	# 可选， 子流程实例的ctx到本流程实例的缺失全部输出更新到流程实例的ctx
+
+  humantask1:
+  	title: conform
+	type: human
+	description: desc
+	input_ctx:["k1:g1", "k2.kk1:g2"]	# 可选， 缺省使用流程实例的全部ctx
+	output_ctx:["k1:ck1", "k2:ck2.x"]	# 可选， 缺失全部输出更新到流程实例的ctx
+
+edges:
+  - from: start
+    to: end
+	multile_on: ctx.charpter			# 
+	when: ctx.x == 'xxx' # 可选，转移条件
+```
+### 流程定义节点数据要求
+除开始节点和结束节点外，所有节点都需要有
+```
+nodes:
+  node1:
+    type: 			# task, human, subflow之一
+	title：			# 标题
+	description:	# 节点描述
+	input_ctx:		# jinja2模版字典数据字符串，用ctx渲染，用于构造给节点任务的输入字典，可选， 缺省使用流程实例的ctx
+	output_ctx:		# jinja2模版字典数据字符串，用节点执行结果字典渲染，结果结果更新ctx， 可选， 缺失全部输出更新到流程实例的ctx
+```
+
+### join节点
+当一个节点中有join属性是为join节点，join 节点只有前置节点满足join条件是才能执行
+```
+nodes:
+  end:
+    type: end
+	join:
+	  - all
+	  - some(5 or 80%)
+	  - xor
+	  - any
+```
+
+---
+
+### 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）
+
+#### 多实例节点
+根据上下文的数据如果是数组为每个数据建立一个节点实例
+```yaml
+edges:
+  - from: gen_docs
+    to: evalution_chapter
+	multiple_on: ctx.docs.chapters
+```
+
+#### Fork（隐式）
+
+```yaml
+edges:
+  - from: fetch
+    to: validate
+  - from: fetch
+    to: enrich
+```
+
+
+---
+
+## 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_ctx 构建子 ctx
+   * 父流程阻塞在该节点
+
+2. 子流程运行中：
+
+   * 父流程不推进
+
+3. 子流程完成：
+
+   * 根据 output_ctx 合并 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 编排底座
+* 业务流程控制层
+* 长任务调度引擎
+
+在不引入新能力的前提下，本说明书描述的即为**当前版本的完整行为定义**。
+

skills/workflow-builder/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: workflow-builder
+description: 根据用户输入创建工作流
+---
+# workflow-builder
+为用户输入的任务创建工作流， 生成dagflow能使用的工作流并将工作流插入到数据库中
+
+## 流程引擎
+流程引擎具体说明请看[README.md](README.md)
+## 新建流程
+用用户输入的剔除选择厂家的内容后的文本作为文生视频的输入文本来生成视频，使用方式：
+将用户输入拆解为流程引擎添加流程的json数据，然后调用以下函数
+```
+CALL：{ "function": "add_new_workflow", "params":{"name":流程名字，"dsl":YAML格式的符合上述流程规范的流程定义}
+```