跳转到内容

工作流与状态

Workrun 的工作流不是把节点简单串起来,而是将每次运行的输入、节点结果、路由决定和人工操作放进同一份受控状态中。状态边界决定了一个节点能读什么、能将什么交给下一步,以及敏感数据如何保存和展示。

保存的工作流定义包含画布节点、连接、运行模式、输入/输出字段和节点设置。它本身不携带某次任务的客户数据、模型回复或人工决定。

当用户点击运行、提交对话消息或定时任务触发时,Workrun 会为这次执行创建一个运行实例:

工作流定义
├─ 节点、连线、指令、模型和访问规则
└─ 更多设置:运行输入、输出、模式
↓
一次运行
├─ 本次输入 → 初始状态
├─ 节点事件、状态更新、工具结果
├─ 暂停时的检查点
└─ 最终状态与运行历史

因此,「更多设置 → 运行输入」定义的是运行时表单和字段契约;实际填写的值只属于本次运行,不会写回工作流定义。新建工作流已有一个固定的 Start 节点,但 Start 不编辑输入字段。

更多设置中的运行输入:客户反馈字段的标签、键、类型、帮助文本和必填设置。

在 更多设置 中可以为工作流定义六种输入字段类型:字符串、多行文本、数字、布尔值、单文件和多文件。每个字段有面向用户的标签、机器使用的键、帮助文本和必填标记。键应保持稳定且清晰,例如 feedback、customer_id、dry_run;修改键会影响 Agent 指令、条件和后续节点对状态的引用。

模式 适用场景 输入行为
任务 单次、独立的自动化,例如分类一批反馈或执行审批流程。 运行面板展示已定义的运行输入。
对话 需要连续多轮上下文的助手或协作流程。 input 保留为消息内容;其他已定义输入仍可随对话一同提交。

工作流输出字段用于声明工作流要交付的结果。Agent 节点可额外定义输出键,或使用 JSON Schema 要求结构化模型输出。将路由或下游节点依赖的关键字段显式命名,可以减少「从一段自由文本里猜答案」的脆弱性。

在对话模式中,只有在 更多设置 → 会话状态 中明确选择的顶层全局字段才会被带到下一轮。敏感字段、保留键和嵌套路径不能作为会话状态字段。

在 更多设置 → 运行输入 中选择单文件(file)或多文件(files),运行时通过文件选择器提交。任务模式在运行表单中选取文件,对话模式可随消息提交文件字段。

Workrun 会把选中的文件复制为当前工作区内的不可变快照。State 中保存的是 ArtifactRef:包含 $type: "artifact"、ID、版本、文件名、MIME 类型和大小;单文件字段是一个引用,多文件字段是引用数组。引用不包含文件字节,也不是原始文件路径。修改原始文件不会改变已经保存的快照;当前单个文件的上限为 512 MiB。

文件引用遵循普通 State 的发布和读取权限。Process 节点通过 Python SDK 读取传入的文件并保存新文件,见 使用 Python App。需要 Agent 或 Remote Agent 实际处理文件内容时,应在节点的附件路径配置中明确选择可读取的 State 路径;只把引用写进提示词不会自动传递文件内容,模型也需要支持对应文件类型。CodeAct Agent 通过 /artifacts/manifest.json 查找获准读取的虚拟文件路径,把交付文件写到 /outputs,成功完成后 Workrun 会收集这些文件为 artifacts。

输出文件也以引用进入 State,可供获准读取的后续节点使用,或映射到工作流输出。运行结果和人工审核中的文件支持导出;图片、视频可预览,PDF 可打开查看。

每个运行的状态可以理解为三个层次:

初始输入
↓
全局状态 ───────────────→ 所有节点与路由可读取可见值
↑ 发布
节点私有命名空间 ←────── 各节点的输出默认留在这里
  1. 初始输入:由运行面板、对话或定时任务提供,作为运行的开始状态。
  2. 节点私有命名空间:一个节点的普通输出默认归属于该节点,避免它无意中覆盖其他步骤的数据。
  3. 全局状态:节点在其状态设置中把指定输出键列为「发布的输出键」后,这些值才会成为共享状态,其可见值可供所有节点、条件和工作流输出使用,无需额外配置读取节点。

这套模型的重点是最小权限:需要被下游消费的值才发布;只用于调试或节点内部处理的值留在节点命名空间中。它避免了任意节点都能悄悄改写整份上下文,也让审查者可以追溯一个全局字段由谁产生。

节点状态设置还定义访问边界:

  • 读取节点(允许读取的节点):在产生输出的节点上设置,指定哪些其他可执行节点能读取其私有输出命名空间;不限制已发布全局值的可见读取;
  • 原始读取节点:读取节点的子集,可接收该命名空间的原始值,也包括它发布到全局的值。Agent 提示词始终接收脱敏值,获授权的原始值可在工具调用时解析;
  • 敏感字段:标记节点输出中的字段或点分隔路径,例如 customer.email 或 payment.token;
  • 发布的输出键:将选定顶层输出提升到全局状态。

输入也可以在 更多设置 → 运行输入 标记为敏感,并为需要原始输入的节点单独授予原始读取权限。默认情况下,模型、工具和界面接收的是可见状态,而不是原始状态:常见 PII 和疑似密钥会被脱敏,显式敏感字段也会替换为脱敏占位值。原始状态会以加密形式保存在检查点中。

这不是把不可信代码变安全的沙箱。对本地 Python App、MCP Server 或远程服务,仍应只授予完成任务所需的数据和权限。

Agent 状态访问设置:读取节点、原始状态读取者、敏感字段和发布到全局状态的输出键。

以「客户反馈分流」为例:

运行输入
feedback, customer_id
↓
Agent:提取 category、priority、recommendation
↓ 发布 category、priority、recommendation
If/Else:读取 priority
├─ high → Human Review
└─ low / medium → End

推荐的配置方式:

  1. 在更多设置中定义 feedback 和 customer_id,只将真正需要保护的值标记为敏感;
  2. 让 Agent 用结构化输出产生 category、priority 和 recommendation;
  3. 在 Agent 的状态设置中只发布分支和最终交付所需的键;
  4. 让 If/Else 读取已发布的全局 priority,无需设置「允许读取的节点」。若其他执行节点需要读取私有输出,应在产生输出的节点上为其授权;
  5. 在人工审核节点展示必要上下文,并由审核结果决定后续路径。

这样,分支依赖的是稳定的 priority 字段,而不是 Agent 回复中某句不固定的自然语言。

Human Review 和 Ask User Question 会中断当前执行并写入本地 SQLite 检查点。检查点保存恢复所需的执行位置和状态:

节点完成 → 写入检查点
↓
Human Review / Ask User Question
↓
等待审核结果或选项
↓
从同一检查点继续后续节点

审核节点可以让审核人批准或拒绝,并可按节点配置编辑内容;提问节点将选择结果写入自己的状态键。恢复时,已经完成的节点不会重新执行。失败或已停止的任务不从检查点继续,修复后使用“重新运行”创建新任务。应用退出或崩溃造成的中断另行通过检查点和操作日志检查后恢复。

问题、人工审核和工具确认以对应节点输出中的可交互卡片展示,不阻塞查看已有输出或使用其他页面。等待交互的运行重启后仍保留请求,可以从运行中心回到原运行继续处理。执行途中中断的任务会保留并提供恢复检查;具体操作见人工审核与恢复和运行、调试与追踪。

子工作流会带着父工作流上下文执行,并会保护递归调用:Workrun 会阻止循环引用,并限制嵌套深度。Terminate 则用于显式结束整次执行,而不只是结束某一条画布路径。

保存或运行前,Workrun 会检查工作流结构,例如唯一 Start、合法连线、分支出口、子工作流引用和输入配置。运行失败时,推荐按以下顺序排查:

  1. 输入:必填运行输入是否存在,键和类型是否符合预期;
  2. 节点:Agent 是否选择了已配置 Provider 的模型,Process/App 或 MCP 工具是否可用;
  3. 状态:下游节点依赖的键是否已发布,它是否具有读取授权;
  4. 路由:条件是否读取正确的稳定字段,连线是否接到正确的出口;
  5. 运行记录:在运行面板查看发生失败、等待或工具调用的具体节点和事件。

接下来阅读构建第一个工作流了解如何把这些原则应用到 Python、条件和人工审核中。