编排工作流

工作流编辑器使用 React Flow 画布。左侧节点面板负责添加节点，中央画布负责连接流程，右侧抽屉负责配置选中节点。工作流支持手动触发、Webhook 触发和 Cron 定时触发（需额外部署调度任务）。

工作流构建器界面

布局

工作流编辑器由以下部分组成：

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

构建工作流的步骤

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

变量与数据流

变量作用域：

• 输入变量：在开始节点定义，从用户或触发器收集
• 节点变量：节点输出，在后续节点中引用
• 系统变量：
  • {{workflow.id}} - 工作流 ID
  • {{workflow.name}} - 工作流名称
  • {{run.id}} - 当前运行 ID

变量用法：

• 在提示词中：分析来自 {{customer_email}} 的查询：{{inquiry_text}}
• 在条件中：{{analysis.urgency}} == "high"

错误处理

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

工作流模板

内置工作流模板：

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

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

键盘快捷键

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

创建与保存草稿

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

定义变量

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

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

节点类型

编辑器提供以下节点类型，按类别组织：

节点面板按四个分类组织，下表按同一分类列出每个节点；类型标识符用于 API 交互，配置时请使用表中的准确值。

模型节点

逻辑节点

转换节点

扩展节点

配置节点

按任务配置节点参数：

LLM 节点

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

输出变量： response、reasoning、usage（加上配置的输出变量）。

媒体生成节点

• 提供商：image | video
• 提示词：{{prompt}}
• 宽度/高度：（图片）
• 持续时间/宽高比：（视频）

条件分支节点

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

问题分类器节点

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

决策节点

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

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

分支句柄与重命名

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

兜底分支与置信度阈值

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

输出变量

下游可以用 {{决策节点ID.answer}} 记录判断结果，用 {{决策节点ID.confidence}} 或 {{决策节点ID.probabilities}} 决定是否再套一层人工复核。

失败路径

示例：工单分诊

调试决策分支

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

迭代/循环节点

• 集合：{{items}}
• 项目变量：item
• 输出变量：results

暂停节点

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

• 模式：variables | approval
• 标题：审查请求
• 输入变量：需要收集或审批的变量列表

代码执行节点

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

模板节点

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

文件转 URL 节点

将文件（如沙箱工件）转换为可下载的 URL。

变量赋值节点

为变量赋值。

变量聚合节点

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

参数提取节点

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

• 提取方法：llm | regex | json_path
• 源变量：{{source}}
• 参数：[...]

HTTP 请求节点

• 方法：GET / POST / PUT / PATCH / DELETE
• URL：目标端点地址
• 请求头：自定义 HTTP 头
• 请求体：JSON 格式的请求负载
• 超时：默认 30 秒；当前未核实有 1-300 秒的代码执行超时配置范围
• 输出变量：存储响应数据

工具节点

• 工具：选择已配置的工具
• 参数映射：将上游变量映射到工具参数
• 输出变量：存储工具执行结果

可用内置工具： web_search、fetch_webpage、calculate、unit_convert、get_weather、get_current_time、format_datetime、markitdown，以及沙箱工具（bash、read、edit、write、artifact）。

知识库检索节点

• 知识库：选择目标知识库
• 查询模板：使用 {{variable}} 引用查询内容
• Top K：默认 5；具体上限取决于接口与配置，文档不将其限定为固定的 1-100 范围
• 分数阈值：默认 0.0。最低相似度分数
• 搜索模式：hybrid

子工作流节点

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

Agent 节点

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

回答节点

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

触发配置

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

手动触发

无需额外配置。发布后，具有权限的用户可以通过 UI 或 API 手动触发工作流。

Webhook 触发

将触发类型设为 Webhook 后，系统自动生成一个 webhook token。触发端点为：

POST /api/v1/workflows/webhook/{webhook_token}

请求要求：

• 认证：在 Authorization 头中提供有效的 clou_ API 密钥
• 请求体：工作流输入变量（原始 JSON 或 {"inputs": {...}} 格式）
• Webhook token：使用恒定时间比较匹配，防止时序攻击

Cron 定时触发

将触发类型设为 Cron 后，调度表达式保存在 trigger_config 中（如 0 9 * * 1-5 表示工作日上午 9 点）。界面的执行频率会换算成同一个表达式，自定义模式直接填 分 时 日 月 周。

草稿与发布

工作流有三种状态：

草稿（Draft）

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

已发布（Published）

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

已归档（Archived）

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

发布前检查

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

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

运行工作流

访问工作流

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

工作流列表

列表显示：

手动执行

步骤：

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

输入变量

工作流可能需要输入：

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

观看执行

实时进度：

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

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

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

执行结果

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

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

常见错误：

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

停止执行

执行期间：

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

工作流变量

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

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

查看执行记录

执行历史

1. 选择工作流
2. 点击执行历史标签页
3. 查看运行列表：
   • 运行 ID
   • 状态（running、success、failed 等）
   • 开始时间
   • 持续时间
   • 触发来源
   • 输入/输出

相关 API 端点：

• GET /api/v1/workflows/runs - 获取所有运行记录
• GET /api/v1/workflows/{workflow_id}/runs - 获取指定工作流的运行记录
• GET /api/v1/workflows/{workflow_id}/runs/mine - 获取当前用户的运行记录

执行详情

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

• 运行信息：运行 ID、工作流名称、状态、开始时间、完成时间、持续时间、触发方式
• 节点执行时间线：每个节点的开始时间、完成时间和耗时
• 节点级详情：GET /runs/{run_id}/nodes 获取每个节点的执行详情
• 流式事件：GET /runs/{run_id}/stream 获取节点执行的实时事件流

工作流日志

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

运行详情字段：

状态图标：

查看节点执行详情

查看逐节点执行：

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

流式传输

运行实时流式传输事件（GET /api/v1/workflows/runs/{run_id}/stream），包括节点状态更新和 LLM 令牌输出。

筛选历史

执行统计

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

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

删除历史

删除单个执行：

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

Webhook 管理

创建或重新生成 Webhook Token

1. 编辑工作流
2. 将触发类型设为 Webhook
3. 保存 - 系统自动生成 webhook_token
4. 随时通过 POST /api/v1/workflows/{workflow_id}/regenerate-webhook-token 重新生成 token

测试 Webhook

使用 curl 测试 webhook：

curl -X POST "https://your-domain.com/api/v1/workflows/webhook/TOKEN" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_email": "test@example.com",
    "inquiry_text": "测试查询",
    "priority": "low"
  }'

Webhook 日志

API 端点

工作流 API 支持程序化管理工作流生命周期：

故障排除

工作流执行失败

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

Webhook 未触发

1. 确认工作流触发类型为 webhook
2. 确认 POST 到正确的 /api/v1/workflows/webhook/{webhook_token} 端点
3. 确认 Authorization 头中包含有效的 clou_ API 密钥
4. 确认工作流已发布（未发布的工作流会拒绝 webhook 触发）

Cron 未执行

1. 确认工作流已发布且 trigger_type 为 cron
2. 确认 trigger_config 里有有效的 cron 表达式（调度任务读的是 cron 键）
3. 确认自定义部署把 app.services.workflow.tasks 加进了 Celery include，并用 Beat 定期调度 workflow.check_scheduled（例如每分钟）
4. 确认运行该任务的 Worker 消费了它实际落到的队列（默认 default）

执行时间过长

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

工作流无法启动

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

执行卡住

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

无法查看历史

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

缺少执行记录

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

无法启动新运行

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

最佳实践

工作流设计

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

性能优化

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

输入与监控

输入：

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

监控：

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

错误处理：

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

安全

• 使用 webhook 认证（API 密钥放在 Authorization 头）
• 被泄露时重新生成 webhook token
• 启用审计日志
• 监控异常活动

退出与丢失更改

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