编排工作流

工作流编辑器使用可视化画布：左侧节点面板负责添加节点，中央画布负责连接流程，右侧抽屉负责配置选中节点。工作流支持手动触发、Webhook 触发和定时触发。

工作流构建器界面

布局

• 节点面板（左侧）：按类别组织的可用节点类型
  • 模型：LLM、媒体生成
  • 逻辑：条件、问题分类器、决策、迭代、循环、暂停
  • 转换：代码、模板、文件转 URL、变量聚合、变量赋值、参数提取
  • 扩展：子工作流、Agent、工具、知识库检索、回答
• 画布（中央）：工作流设计区域，支持添加、连接和排列节点
• 属性面板（右侧）：节点配置、设置和变量
• 工具栏（顶部）：保存工作流、测试（调试）工作流、缩放控制

构建工作流的步骤

1. 添加开始节点：每个工作流以开始节点（用户输入或触发器）开始，定义输入参数
2. 添加处理节点：添加节点处理数据，参见下方节点类型
3. 连接节点：点击源节点的输出端口，拖动到目标节点的输入端口
4. 配置节点：在属性面板中配置每个节点的设置
5. 添加回答节点：使用回答节点定义工作流返回的最终输出；它是构建器中的输出节点，不是另一个名为“结束”的运行时终止节点
6. 测试工作流：点击测试（调试）按钮，输入测试数据，运行并查看结果
7. 保存并发布：点击保存保存为草稿，点击发布激活工作流

变量与数据流

• 输入变量：在开始节点定义，从用户或触发器收集
• 节点变量：节点输出，在后续节点中引用

在提示词或条件里使用变量选择器插入引用，不要手写不存在的名称；编辑器只列出当前可用的变量。

错误处理

构建器中没有 try-catch / 重试界面。节点失败后的流程取决于执行逻辑和工作流结构；错误会记录在运行与节点执行中供检查。HTTP 请求默认最多重试 3 次，但构建器没有单独的重试配置项。

工作流模板

内置工作流模板：

• 简单问答机器人：使用 LLM 的基本问答机器人
• RAG 知识机器人：带检索增强的知识库问答
• 意图路由器：基于检测到的意图路由对话
• 代码审查助手：多视角自动代码审查

模板会实例化到新工作流中；实例化时请在编辑器中检查并配置模型、知识库及其他节点引用，不要假设模板里的变量名固定不变。

键盘快捷键

• Space + Drag：平移画布
• Ctrl/Cmd + Scroll：缩放
• Ctrl/Cmd + 0：重置缩放

创建与保存草稿

1. 前往应用 > 创建应用 > 工作流。
2. 在工作流设置填写名称、描述、可见性和所属团队。
3. 选择开始节点：用户输入适合表单交互，触发器适合 API 或 Webhook 调用。
4. 从节点面板拖拽节点到画布，或点击添加节点。
5. 拖动源句柄到目标句柄创建连线。开始节点不能删除。
6. 选择保存。编辑器会记录最近保存时间和未保存状态。

定义变量

开始节点使用工作流级变量。变量类型包括文本、段落、下拉选项、数字、布尔、数组、对象、文件、图片、多文件和多图片。每个变量可设置必填、默认值、标签和描述。

引用变量时使用编辑器选择器，不要手写不存在的名称。当前定义格式支持原生对象和数组传递。

节点类型

节点面板按四个分类组织，下表按同一分类列出每个节点：

模型节点

逻辑节点

转换节点

扩展节点

配置节点

按任务配置节点参数：

LLM 节点

• 模型：选择已配置的模型（如 GPT-4 Turbo、Claude 等）
• 提示词：使用 {{variable}} 语法引用上游变量
• 温度：通常以 0-2 配置，具体可用范围取决于所选模型；控制输出的随机性
• 最大令牌数：限制模型输出的长度
• Top P：通常以 0-1 配置，具体可用范围取决于所选模型；核采样参数
• 输出变量：定义存储模型输出的变量名

输出变量： 响应内容、思考过程、Token 用量，以及配置的输出变量。

媒体生成节点

• 媒体类型：图片或视频
• 提示词：支持引用上游变量
• 宽度/高度：（图片）
• 持续时间/宽高比：（视频）

条件分支节点

• 条件表达式：使用 Jinja2 语法，如 {{analysis_result.urgency}} == "high"
• True 分支：条件为真时连接的下游节点
• False 分支：条件为假时连接的下游节点

问题分类器节点

将用户输入分类到多个意图/类别之一并相应路由。它把分类写进提示词让对话模型生成 JSON，再从文本里解析类别；需要概率、置信度和“不会答错格式”时改用下面的决策节点。

决策节点

决策节点调用决策模型（非生成式）对一份状态做一次类型化判断，再按判断结果走对应分支。模型不产出散文，只返回选项/等级的概率分布和置信度，因此路由结果不需要从模型输出里解析，也不会因为多写一句话而走错分支。

问题类型决定分支句柄与输出：

分支句柄与重命名

• “选择一个选项”/“按有序等级评分”的每个选项或等级就是画布上的一个输出句柄，句柄名等于选项/等级文本；兜底句柄名默认为 default。
• 改动选项文本时，只要选项个数不变，编辑器会按位置重映射已有连线；如果改动了个数，残留连线会指向“已过期的输出句柄”，检查清单会报错，必须重新连到当前句柄。
• 不需要连接每个分支，但被连接的分支必须有下游节点；低置信度答案会改走兜底分支，兜底分支没有下游时流程在该节点结束。

兜底分支与置信度阈值

• 阈值只在返回置信度严格小于阈值时生效；等于阈值仍走模型选中的分支。
• 阈值只影响路由，不影响输出：判断结果始终是模型选中的选项/等级，实际分支才是真正走的那条。
• 不设置阈值时，只有“没有解析出分支”才会走兜底；“是 / 否判断”永远不走兜底（它一定返回是或否）。
• 决策节点默认最多重试 2 次（首次失败后等待 1 秒起、指数退避）；重试与阈值无关，阈值只处理“答了但不确定”的情况。

输出变量

下游可以用节点变量记录判断结果，用置信度或概率分布决定是否再套一层人工复核。

失败路径

示例：工单分诊

调试决策分支

• 检查清单会逐项报：未选择模型、输入状态为空、判断说明为空、选项/等级数量不足或超限、选项为空或重名、连线使用已过期句柄。
• 运行追踪里看实际分支（实际走的哪条分支）和置信度（是否被阈值改道）。如果总是落到兜底分支，先看概率分布是“两个选项概率接近”还是“模型没理解判断说明”——前者调阈值，后者改判断说明或输入状态。
• 决策节点是一次调用、一个结果，没有中间步骤：调试只能整轮运行，不存在断点或单步执行。

迭代/循环节点

• 集合：要遍历的数组变量
• 项目变量：当前项目的变量名
• 输出变量：结果数组的变量名

暂停节点

暂停执行，直到团队成员提供请求的变量或提交审批决定。暂停可配置为变量模式或审批模式；等待的运行在处理请求后恢复。

• 模式：变量（收集表单字段）或审批（等待通过/拒绝），默认变量
• 标题：审批或填写页显示的名称；留空时用节点名称
• 说明模板：支持 {{变量}} 插值，保存前解析；解析不到的引用显示为空字符串，不会向审批人暴露原始占位符
• 输入变量（变量模式）：需要收集的字段，每项含名称、类型、必填与说明
• 审批人（审批模式）：从团队成员中选择。不选时默认由工作流创建者和团队管理员处理；选了之后只有名单内的成员能提交，超级管理员可越过
• 审批策略：默认关闭——任一人提交即决定结果；开启需要全员通过后，每位审批人都要各自提交，全部通过才恢复运行，任一人拒绝立即失败，同一人重复提交会被拒绝

变量模式的输出就是提交的字段本身；审批模式输出决定（通过/拒绝）、是否通过、审批意见和提交人，拒绝会让运行以“审批被拒绝”失败。等待中的请求与运行轨迹都在运行抽屉里显示，详见工作流节点。

代码执行节点

• 语言：Python 或 JavaScript
• 代码：自定义执行逻辑
• 超时：代码执行器当前固定为 30 秒；不是可在构建器中自由设置的 1-300 秒范围
• 输入变量：传递给代码的变量
• 输出变量：代码执行返回的变量

模板节点

使用变量渲染模板字符串（如 {{variable}} 替换）。

文件转 URL 节点

将文件（如沙箱产物）转换为可下载的站点地址。

变量赋值节点

为变量赋值。

变量聚合节点

聚合值（如将循环迭代结果收集到数组中）。

参数提取节点

使用模型、正则表达式或 JSON 路径从文本中提取结构化参数。

• 提取方法：模型 / 正则 / JSON 路径
• 源变量：要提取的文本
• 参数：需要提取的字段列表

HTTP 请求节点

• 方法：GET / POST / PUT / PATCH / DELETE
• URL：目标端点地址
• 请求头：自定义 HTTP 头
• 请求体：JSON 格式的请求负载
• 超时：默认 30 秒
• 输出变量：存储响应数据

工具节点

• 工具：选择已配置的工具（内置 / 自定义 / MCP / Skill）
• 参数映射：每个参数一条映射，来源可以是上游变量或常量；常量要声明类型，否则 "10" 会以字符串传给工具
• 类型转换：整数、浮点、布尔、数组、对象分别按对应格式解析；非法值会让节点报参数无效
• 网页搜索引擎：选中内置网页搜索时出现引擎下拉，默认项用站点默认，其余只列已启用引擎；执行时重新校验，引擎被禁用即失败
• 输出变量：存储工具执行结果，另有状态与耗时

可用内置工具： 时间与日期、数学计算、单位换算、网页搜索、网页抓取、订阅源读取、文档转换，以及沙箱文件工具。生图与生视频用媒体生成节点；交互式提问由 Agent 能力开关提供，它们都不在工具目录里。

知识库检索节点

• 知识库：选择目标知识库
• 查询模板：使用 {{variable}} 引用查询内容
• 返回结果数：默认 5；具体上限取决于接口与配置
• 相似度阈值：默认 0.0，即最低相似度分数
• 检索方式：向量 / 全文 / 混合

子工作流节点

运行另一个工作流作为子步骤并捕获其输出。

Agent 节点

使用消息和可选上下文调用 AI Agent。

回答节点

从工作流返回最终答案/输出。

触发配置

工作流支持三种触发方式：

手动触发

无需额外配置。发布后，具有权限的用户可以在界面中手动触发工作流。

Webhook 触发

将触发类型设为 Webhook 后，系统自动生成一个触发地址和一个触发令牌。把地址提供给调用方，调用方在请求头中携带 clou_ API 密钥发起 POST，请求体直接是工作流的输入变量（原始 JSON 或 {"inputs": {...}} 格式）。

定时触发

将触发类型设为 定时任务 后，界面支持按间隔、每天、每周、每月或自定义表达式配置。执行频率会换算成一条标准表达式（分 时 日 月 周，如 0 9 * * 1-5 表示工作日上午 9 点）。

草稿与发布

工作流有三种状态：

草稿

• 正在编辑中的工作流
• 不能被触发执行
• 仅对编辑者可见
• 可随时保存修改

已发布

• 可运行的工作流
• 可以通过界面、API 或 Webhook 触发
• 对所有有权限的用户可见
• 修改前需先取消发布

已归档

• 已停用的工作流
• 不在正常列表中显示
• 配置信息保留

发布前检查

选择检查清单，解决以下问题后再调试运行和发布：

验证通过后，使用调试运行测试工作流，确认输出符合预期后再发布。

运行工作流

访问工作流

1. 导航到应用（/app/apps）。
2. 打开工作流标签页。
3. 选择工作流卡片打开 /app/apps/workflow/{id}。
4. 选择运行开始手动执行。

工作流列表

列表显示：

手动执行

1. 打开工作流
2. 点击运行按钮
3. 如果工作流有输入变量：
   • 填写必填输入
   • 查看可选输入
   • 点击开始
4. 实时观看执行过程
5. 完成后查看结果

输入变量

工作流可能需要输入：

• 文本：自由格式文本输入
• 数字：数值
• 下拉选项：下拉选项
• 布尔：是/否复选框

观看执行

实时进度：

• ⏸️ 待定：尚未开始
• ⏳ 运行中：正在执行
• ⏳ 等待中：暂停等待外部输入或审批
• ✅ 成功：成功完成
• ❌ 失败：执行失败
• ⏭️ 已跳过：已跳过（条件性）

执行详情： 点击节点查看详细信息，包括状态、持续时间、输入和输出。

流式输出： LLM 节点实时流式输出；执行视图在运行时显示部分内容。

执行结果

成功： 显示执行持续时间、执行的节点数和状态。

失败： 显示失败节点和错误信息。

常见错误：

• 输入格式无效
• API 调用失败
• 超时
• 资源未找到
• 权限被拒绝

停止执行

1. 点击停止执行按钮
2. 确认停止操作
3. 工作流在当前节点停止

工作流变量

输入变量： 启动工作流时提供。

输出变量： 执行期间由回答节点和其他节点输出生成。

查看执行记录

执行历史

1. 选择工作流
2. 点击执行历史标签页
3. 查看运行列表：运行编号、状态、开始时间、持续时间、触发来源、输入与输出

执行详情

点击单个运行查看详细信息：

• 运行信息：运行编号、工作流名称、状态、开始时间、完成时间、持续时间、触发方式
• 节点执行时间线：每个节点的开始时间、完成时间和耗时
• 节点级详情：每个节点的输入、输出、状态与错误
• 实时事件：运行中可查看节点状态更新与 LLM 输出

工作流日志

工作流执行历史可从工作流的日志视图（/app/apps/workflow/{id}/logs）访问。打开应用 > 工作流，选择工作流，然后从工作流菜单中选择日志。

运行详情字段：

状态徽章：

查看节点执行详情

查看逐节点执行：

1. 打开运行的节点执行
2. 每个节点显示其状态、持续时间、输入、输出和错误（如有）

实时流式

运行中会实时推送事件，包括节点状态更新和 LLM 文本输出；界面据此逐步展示执行过程。

筛选历史

执行统计

摘要指标（每个工作流或系统范围）：

• 总运行次数
• 成功率
• 失败运行次数
• 平均持续时间

删除历史

1. 在历史中找到执行
2. 点击 "..." 菜单
3. 选择 "删除"
4. 确认删除
5. 执行被移除

Webhook 管理

创建或重新生成触发令牌

1. 编辑工作流
2. 将触发类型设为 Webhook
3. 保存 - 系统自动生成触发令牌与地址
4. 在访问 API页重新生成令牌；旧地址立即失效

测试 Webhook

在访问 API页复制触发地址，用任意 HTTP 客户端向其发起 POST，并在请求头中携带 clou_ API 密钥；请求体直接填写工作流输入字段。触发成功后，这次运行会出现在执行历史中。

Webhook 日志

故障排除

工作流执行失败

1. 在执行历史中打开失败的运行
2. 检查节点执行详情和错误信息
3. 常见错误：
   • 节点超时：增加超时时间或优化节点
   • 输入无效：验证输入变量格式
   • API 错误：检查 API 凭证和连接性
   • LLM 错误：验证模型可用性和 API 密钥
   • 工具错误：检查工具配置
4. 修正后重新触发

Webhook 未触发

1. 确认工作流触发类型为 Webhook
2. 确认使用的是访问 API页显示的当前触发地址
3. 确认请求头中包含有效的 clou_ API 密钥
4. 确认工作流已发布（未发布的工作流会拒绝 Webhook 触发）

定时任务未执行

1. 确认工作流已发布且触发类型为定时任务
2. 确认已填写有效的表达式
3. 联系部署维护者确认调度任务已启用，并按部署文档对齐界面保存的表达式

执行时间过长

1. 优化节点：减少 LLM 最大令牌数、使用更快的模型、优化工具调用
2. 缩小串行链：同一层的独立节点也是逐个执行，画布上没有并行节点；把可批量化的重复工作收敛进迭代节点，并缩小迭代输入规模
3. 设置节点超时：设置合理的超时时间并优雅处理
4. 监控性能：通过运行历史查看执行时长统计

工作流无法启动

1. 检查工作流是否已发布
2. 确认有执行权限
3. 确保提供所有必填输入
4. 刷新页面重试

执行卡住

1. 检查节点是否正在等待外部响应或审批
2. 确认外部端点可访问
3. 停止并重新启动执行
4. 联系管理员

无法查看历史

1. 刷新页面
2. 检查是否有权限
3. 确认工作流已执行
4. 检查日期范围筛选
5. 联系管理员

缺少执行记录

1. 检查筛选（可能隐藏结果）
2. 确认日期范围
3. 确认执行是否被删除

无法启动新运行

1. 确认有执行工作流的权限
2. 确认工作流已发布
3. 从工作流页面开始新执行

最佳实践

工作流设计

• 保持工作流简单聚焦，避免过度复杂
• 使用描述性节点名称，包含动作动词，具体明确
• 添加错误处理逻辑
• 激活前充分测试
• 记录工作流用途
• 使用变量实现可复用性，避免硬编码值
• 添加日志便于调试
• 设置合理的超时时间

性能优化

• 减少串行步骤：画布上没有并行节点，同一层的独立节点也是逐个执行；合并节点比拆分后“等它并行”更有效
• 控制迭代规模：迭代节点超过上限会截断输入，先筛掉不需要处理的数据项
• 缓存重复操作
• 优化 LLM 提示词
• 选择合适的模型
• 设置合理的超时时间
• 监控执行时间
• 优化工具调用

输入与监控

输入：

• 提供所有必填输入
• 使用正确的数据类型
• 先用样本数据测试

监控：

• 关注执行进度
• 检查节点输出
• 行为异常时停止

错误处理：

• 仔细阅读错误信息
• 检查输入值
• 审查节点配置
• 使用修正后的输入重试

安全

• Webhook 触发需携带 API 密钥；调用方式见 工作流 API
• 被泄露时重新生成触发令牌
• 启用审计日志
• 监控异常活动

退出与丢失更改

返回应用列表或关闭页面前，如果存在未保存更改，编辑器会显示确认对话框。选择不保存离开会丢弃当前草稿更改。