工作流节点参考

Clouisle 工作流引擎支持原生复杂对象、流式推理、分支路由与循环/迭代容器。工作流定义采用 schema_version: 2，图结构包含 nodes 与 edges（基于 React Flow）。

节点分类与注册目录

前端画布选择器当前提供 19 个可添加节点类型（normalCategories：模型 2 + 逻辑 6 + 数据 6 + 扩展 5）；进入迭代/循环容器后，选择器改为容器内专用目录（用 iteration_exit/loop_exit 替换 iteration/loop/pause）。后端执行器注册表另有 25 个可执行节点类型，包含 user_input、trigger、iteration_start、loop_start 等内部入口节点。画布还保留 start、iteration_exit、loop_exit、comment 等前端别名或视觉标记，它们不都对应独立执行器。下表将常规节点、运行时节点和视觉辅助标记一并列出：

---

节点详细配置参考

1. LLM 节点 (llm)

配置容器：node.data.llmConfig 或 node.data.config。

输出变量：

• response (string)：模型生成的最终回复文本（流式模式下为惰性流代理）
• reasoning (string)：模型推理思考过程（如 DeepSeek R1 的思维链）
• usage (object)：Token 计量数据，含 prompt_tokens、completion_tokens、total_tokens

---

2. 决策节点 (decision)

决策节点把一个「状态」交给决策模型（model_type: decision，当前为 TypeSafe AI）判断，并根据返回的类型化答案选择分支。与 LLM 节点不同，决策模型不生成文本，只返回类型化答案与概率分布，节点负责把答案映射为输出连线（handle）。

配置容器：node.data.decisionConfig（兼容旧定义中的 node.data.config）。

问题类型行为：

• choice：要求模型从 options 中选一个。每个选项即一个输出 handle。
• score：要求模型按 options 给出的有序等级打分；概率最高的等级决定分支，数值 score 同时作为输出。
• noul：返回 0–1 的是/否概率，>= 0.5 走 yes，否则走 no；noul 不返回 confidence。

分支 handle：

• choice/score：每个选项/等级一个 handle，外加回退 handle（默认 default）。
• noul：固定 yes 与 no，外加回退 handle。
• 重命名选项时编辑器会尽量把已有连线重映射到新 handle（remapDecisionBranchEdges）；无法映射的旧 handle 会被校验器标记为错误（decisionBranchHandleInvalid），需要手动重连。
• 早期把 yes/no 当作选项的决策节点，加载时会自动把分支连线迁移到新选项名（migrateLegacyDecisionBranchEdges）。

输出变量：

• answer (string)：选中的选项/等级，或 yes/no
• selected_handle (string)：实际激活的分支 handle（可能为回退 handle）
• usage (object)：决策模型 Token 计量
• choice + confidence + probabilities（choice 类型）
• score + confidence + probabilities（score 类型）
• noul (number)：是/否概率（noul 类型）

---

3. 媒体生成节点 (media_generation)

配置容器：node.data.mediaGenerationConfig 或 node.data.config。

输出变量：

• result：生成的媒体持久化访问 URL。生图模式下为 URL 数组，生视频模式下为单个 URL 字符串。

---

4. 条件分支节点 (condition)

配置容器：node.data.conditionConfig 或 node.data.config。

支持基于多条件组的树状逻辑判断。每个条件由 variable（变量引用）、operator（比较运算符）和 value（目标值）组成。

支持的操作符清单：

• 相等判断：equals（等于）、not_equals（不等于）
• 文本模式：contains（包含）、not_contains（不包含）、starts_with（以...开头）、ends_with（以...结尾）、regex_match（正则表达式匹配）
• 数值比较：greater_than（>）、less_than（<）、greater_or_equal（>=）、less_or_equal（<=）
• 空值与状态：is_empty（为空）、is_not_empty（非空）、is_null（为 null）、is_not_null（非 null）

---

5. HTTP 请求节点 (http_request)

配置容器：node.data.config。

输出变量：

• statusCode (int)：HTTP 响应状态码（如 200、404）
• body (any)：自动解析为 JSON 结构；若非合规 JSON 则返回原始文本
• headers (object)：响应头键值对

---

6. 知识库检索节点 (knowledge_retrieval)

配置容器：node.data.knowledgeRetrievalConfig。

输出变量：

• results (array)：切片数组，每项包含 content（正文）、score（相似度分值）、metadata（元数据）、documentId 和 chunkId
• context (string)：已自动用 \n\n---\n\n 拼接好的长文本上下文，方便直接喂给 LLM
• totalFound (int)：命中的切片总数

---

7. 代码执行节点 (code)

配置容器：node.data.codeConfig 或 node.data.config。

在沙箱安全容器中执行，默认超时 30 秒（CODE_TIMEOUT = 30）。

• Python 入口：language: "python" 时，必须声明 def main(inputs): 函数，形参 inputs 为字典，必须返回 dict。
• JavaScript 入口：language: "javascript" 时，必须声明 function main(params) 或 const main = (params) =>，必须返回 object。
• 其他 language 取值会被拒绝（unsupported_code_execution_language）。

输出变量：函数返回字典中的所有键值对将自动映射为下游可用的独立变量。

---

8. 数据处理辅助节点

模板转换 (template)

• 配置容器：node.data.templateConfig。
• template：Jinja2 风格模板字符串，如 你好 {{ user_name }}，工单 #{{ order_id }} 已更新。
• inputs：映射上游变量至模板变量名的参数映射列表。
• 输出变量：output（字符串）或自定义命名的输出变量。

变量聚合器 (variable_aggregator)

• 配置容器：node.data.variableAggregatorConfig。
• mode：聚合模式：
  • "object"：将变量作为键值对组装为 JSON 对象
  • "array"：将变量按顺序合并为数组列表
  • "concat"：使用 separator 分隔符将各字符串拼装为长文本
  • "merge"：深度或浅度合并多个对象
• 输出变量：result（默认）。

变量赋值 (variable_assignment)

• 配置容器：node.data.variableAssignmentConfig。
• assignments：赋值项列表，支持三种操作（operation）：
  • overwrite：以 variableRef 引用的变量覆盖目标对话变量
  • clear：重置目标变量为空值
  • set：设置指定的 constantValue 常量值

参数提取器 (parameter_extractor)

• 配置容器：node.data.parameterExtractorConfig。
• extractionMethod：提取策略："llm"（大模型推理）、"regex"（正则表达式）、"json_path"（JSON Path 语法）。
• 输出变量：定义的每一个提取参数都将作为独立的强类型输出变量暴露给下游。

文件转URL (file_to_url)

• 配置容器：node.data.fileToUrlConfig。
• 将节点接收到的文件或图片二进制变量转换为带有安全访问权限的永久/临时 URL，避免在大模型上下文中传递冗长的 Base64。

---

9. 流程控制与容器节点

问题分类 (question_classifier)

• 配置容器：node.data.questionClassifierConfig。
• 配置一个大模型与若干预定义的分类分支（包含 id、name、description 和 handle），节点在运行时通过提示词驱动模型判断分类，命中对应分支向下游继续执行。

迭代 (iteration)

• 配置容器：node.data.iterationConfig（兼容旧定义中的 node.data.config）。
• iteratorVariable：待遍历的变量引用；旧定义可使用 inputVariable。
• iteratorType："array"（默认）或 "object"。数组模式对标量输入会封装成单元素数组；对象模式下非对象输入不会执行迭代。
• 数组模式使用 itemVariable（默认 "item"）与 indexVariable（默认 "index"）；对象模式使用 keyVariable（默认 "key"）与 valueVariable（默认 "value"）。
• maxIterations：默认 100；正整数配置会在运行时被限制为最多 1000。

循环 (loop)

• 配置容器：node.data.loopConfig（兼容旧定义中的 node.data.config）。
• 优先使用 exitConditions（条件数组）与 exitLogicOperator（"and" 或其他值按 "or" 处理）定义退出条件；条件由 variable、operator、value 组成。
• 若未提供 exitConditions，兼容使用旧字段 conditionVariable、conditionOperator、conditionValue；若两类条件均未配置，循环会持续到迭代次数上限。
• counterVariable 默认为 "loopCount"，未设置时兼容读取旧字段 indexVariable；outputVariable 默认为 "results"。
• maxIterations 默认 100，执行器会以 min(配置值, 1000) 处理。应提供可比较的整数值；该路径未像迭代节点那样实施额外的严格类型验证。

暂停 (pause)

• 配置容器：node.data.pauseConfig。
• mode："approval"（人工审批继续）或 "variables"（等待外部补充表单字段）。
• 工作流运行至该节点时状态置为挂起，通过发布事件通知外部系统，待人工确认或填表后恢复调度。

输出节点 (answer)

• 配置容器：node.data.answerConfig。
• outputs：定义工作流最终呈现给调用方的结构化键值对（支持 string、number、boolean、array、object 等）。
• streaming：支持绑定某个流式 LLM 节点的 response 变量，向客户端实时透传文字生成。

---

校验清单（Validation Checklist）

工作流编辑器使用校验引擎在检查面板中报告已识别的错误或警告，帮助作者修正定义。该清单当前不由发布接口强制执行；保存或发布前应主动处理其提示。已实现的检查包括：

1. 图结构检查：
   • 运行时计划验证要求恰好一个 user_input 或 trigger 入口，并检测工作流图中的循环。
   • 校验器会标记缺少上游边的节点；user_input、trigger、iteration_start、loop_start 和 comment 除外。
2. 节点配置检查：
   • 依据节点类型报告诸如缺少模型、工具、知识库、提取参数、变量赋值或容器处理节点等问题。
   • condition、question_classifier、decision、code、sub_workflow、agent、media_generation、pause 与变量处理节点都有对应配置检查。
   • decision 节点会校验 stateTemplate、instructions、选项数量与唯一性，以及连线是否引用了旧的分支 handle（decisionBranchHandleInvalid）。
3. 变量与容器检查：
   • 编辑器报告当前可见上游变量中不存在的变量引用、非法或重复参数名，以及容器结构相关问题。
   • 编辑器也会报告迭代/循环容器中 pause 节点的放置问题。

运行时仍会执行各节点的配置检查与授权校验；通过或忽略检查面板中的提示不保证调用外部模型、工具或知识库时一定成功。