运行、调试与追踪
一次运行不只有「成功」或「失败」。Workrun 会在运行工作区保留工作流快照、状态变化、节点事件、模型与工具活动、Python 日志和运行诊断。用它回答一个具体问题:这次运行在哪一步、基于什么输入、以什么结果停下,以及下一步该改什么?
不要从最终回答倒推原因。先建立证据链,再改 Prompt、代码、Schema、权限或模型配置。
Deeplink 触发的运行
Section titled “Deeplink 触发的运行”通过外部链接执行的 App 与 Workflow 会在运行历史中标记为 外部链接。新运行先在对应列表页确认;App 确认后在列表页输出抽屉中展示日志,Workflow 确认后在详情页输出抽屉中展示执行过程。执行结束后保持当前页面,可以随后通过历史查看保存的输出。
带相同 requestId 的原请求会打开已有运行,不会自动重新执行。链接格式、输入和去重规则见通过 Deeplink 打开与运行。
失败后,先用这五步收窄范围
Section titled “失败后,先用这五步收窄范围”- 在运行历史中打开这一次运行,确认工作流版本、运行输入与开始时间;不要和另一版工作流或另一条对话混在一起。
- 看节点时间线,找到最后一个不是「已完成」的节点。它是排查起点,不一定是根因。
- 查看该节点前后事件,确认上游是否真的发布了它需要的状态,以及它是否有读取权限。
- 按节点类型查看证据:Agent 看模型消息与工具活动;Process App 看 stdout、stderr 与结构化结果;条件节点看字段值与走出的分支。
- 确认外部副作用后再恢复或重试。修复后用同一组输入重新运行,并把可复现的问题加入评测集。
这套顺序把「发生了什么」和「该怎么修」分开:先确定事实,再选择改动位置。

在单个工作流中,运行历史同时展示一段时间内的健康度和每次执行的状态、耗时与 Token。先从这里选择需要调查的那一次,再点击「查看输出」进入运行工作区。
先看运行状态,决定是否应该操作
Section titled “先看运行状态,决定是否应该操作”| 状态 | 它表示什么 | 下一步 |
|---|---|---|
queued / running |
已排队或仍在执行。 | 等待新事件;若长期没有新事件,再检查当前模型或工具的超时。 |
waiting_for_input |
正在等待人工审核、提问回答或工具确认。 | 在运行面板完成该操作;不要把它当作失败重新运行。 |
completed |
本次执行已结束。 | 核对最终状态与诊断;结果异常时,从产生错误值的节点向上追溯。 |
failed |
某个节点或运行时步骤未完成。 | 查看错误及补偿、取消记录;修复后“重新运行”,创建新任务。 |
cancelled |
用户已停止运行。 | 核实外部结果;需要再次执行时创建新任务。 |
interrupted |
执行中断或恢复前检查未通过。 | 在输出面板查看原因并尝试恢复;不再跟进时选择“不再跟进”。 |
等待输入是可恢复的暂停;失败或已停止的任务使用“重新运行”创建新任务。只有应用退出或崩溃造成的中断可以恢复原任务。

全局「运行历史」会汇总当前工作区内工作流与 App 的本地执行记录。遇到不确定运行来自哪里、或需要查找被中断和失败的 App 运行时,先用名称、目标类型、模式和状态筛选,再打开对应输出。
运行中心与重启恢复
Section titled “运行中心与重启恢复”运行中心展示当前工作区内需要跟进的运行,包括排队中、执行中、等待输入,以及尚未选择“不再跟进”的中断任务。同一工作流的不同运行分别显示;打开对应运行后,在节点输出卡片处理问题、人工审核或工具授权,也可以先检查其他节点的输出。

图中运行正在等待问题回答。点击该运行可回到对应输出,在消息中的问题卡片提交回答;也可以先查看已有节点结果,稍后再处理。
| 退出应用时的情况 | 重启后的处理 |
|---|---|
| 等待输入,且待处理请求仍存在 | 保留等待状态和请求,从原卡片继续处理。 |
| 已排队,且保存的执行信息完整 | 保留队列;调度前检查所需依赖与恢复检查点。 |
| 正在执行、缺少有效请求的等待,或保存信息不完整 | 显示已中断并保留原因,不直接创建新运行。 |
| 已完成、失败或已停止 | 保留原状态和运行历史。 |
评测执行不使用普通任务的待处理交互恢复流程。独立 App 执行也不支持从中断处恢复;先核实原执行结果,再决定是否重新运行。
在工作流输出面板选择尝试恢复,会检查并继续同一运行。恢复失败会显示原因并保留原记录,修复后可重试;远程任务正在自动确认状态时,先等待其结果。选择不再跟进会将中断任务移出运行中心并停止恢复调度,历史仍然保留;它不会取消远程任务或执行补偿。已完成、失败或已停止的运行可以使用重新运行创建新任务。
运行工作区:每种证据回答什么
Section titled “运行工作区:每种证据回答什么”| 证据 | 先问的问题 | 常见结论 |
|---|---|---|
| 节点时间线与事件 | 卡在哪个节点?完成、等待、失败的顺序是什么? | 问题属于 Agent、App、工具、条件或人工操作哪一层。 |
| 运行输入与上游状态 | 键、类型和值对吗?上游发布了所需字段吗? | 缺少必填值、键名不一致,或下游没有读取授权。 |
| 模型消息与结构化输出 | Agent 实际看到了什么?输出符合契约吗? | Prompt、模型、Schema 或状态边界需要调整。 |
| 工具活动 | 参数、审批、调用上限与返回结构正确吗? | 工具描述、状态绑定、权限或服务需要修复。 |
| Process App stdout / stderr | Python 在哪里失败?返回了预期 JSON 吗? | 依赖、环境、业务逻辑或 App 数据契约有问题。 |
| 最终状态 | 哪些字段真正交付给输出和下游? | 值没有发布、被覆盖,或敏感数据可见范围需要重新设计。 |
| 运行诊断 | 哪个节点、模型或工具消耗时间、Token 或调用次数? | 限制工具调用、缩短上下文、换模型或定位性能瓶颈。 |
运行记录会保存这次目标的快照、最终状态和事件序列。先固定这份证据,再修改当前草稿;否则很难确认修改是否解决了同一个问题。

先查看全局状态,确认工作流输出与下游依赖的键是否存在;再展开节点状态,追溯具体值由哪个节点产生。图中的消息与工单编号仅为演示数据,真实运行应依照状态访问和脱敏规则处理敏感字段。
按节点类型排查
Section titled “按节点类型排查”Agent:先看输入,再看决定
Section titled “Agent:先看输入,再看决定”依次确认:
- Agent 使用了已配置的模型,模型消息中确实有它需要的输入;
- 指令明确了工具的使用条件、输出格式和不能做的事;
- 结构化输出符合 Schema,且后续节点所需字段已发布;
- 结果不稳定时,用相同输入多跑几次,再决定改 Prompt、模型还是验收规则。
不要只因最终自然语言看起来合理就结束排查。条件和下游节点应依赖稳定的结构化字段,而不是从一段回复里猜测值。
Tool App、MCP 与远程工具:检查调用边界
Section titled “Tool App、MCP 与远程工具:检查调用边界”工具没有被调用时,确认它已在该 Agent 的工具列表中启用,且名称、描述和 Agent 指令说明了调用条件。调用失败时按顺序检查:
- 参数是否来自正确的已授权状态键;只有参数名与状态键不同时才需要状态绑定;
- 是否正在等待人工确认,或已达到调用上限、单次超时;
- 返回值是否符合声明的 Schema,而不只看服务端是否返回 HTTP 成功;
- 对 Tool App,再检查它自己的 stdout 和 stderr。
对发送、写入、删除等副作用工具,先在外部系统确认操作是否已经发生,再决定是否重试。
Process App:把日志和返回值分开看
Section titled “Process App:把日志和返回值分开看”Process App 的 stdout 和 stderr 用于调试;process.result({...}) 才是交给工作流的结构化结果。分别确认:代码是否执行、依赖与环境是否可用、返回对象是否符合 App 契约、下游所需输出键是否已在节点中发布。
如果 App 独立运行正常、进入工作流后失败,优先检查工作流状态输入、读取授权和已发布输出键,而不是立刻修改 Python 代码。详见使用 Python App。
条件、状态与人工节点:检查可见数据,不要猜路由
Section titled “条件、状态与人工节点:检查可见数据,不要猜路由”条件节点应读取明确发布的稳定字段。分支不对时,检查产生该字段的节点输出、它是否已发布、条件表达式读取的键,以及实际命中的出口。人工审核或提问暂停时,运行会保留检查点;完成操作后从原处继续,已完成节点不会重新执行。
完整的状态边界、脱敏和检查点模型见工作流与状态。
Remote Agent:本地停止与远程结束分别查看
Section titled “Remote Agent:本地停止与远程结束分别查看”workflow 失败或用户停止后,Workrun 对有 taskId、且本地状态尚未结束的远程调用发起一次尽力 CancelTask,无需运行时确认。对应节点 message 显示请求和返回状态,不覆盖原失败原因。已知终态的任务跳过取消;没有 taskId 的提交保持结果未知,不会自动重新提交。
取消请求失败或超时显示“取消结果未确认”。取消处理不预先查询、不自动轮询、不重试、不在启动时续接,失败或已停止的任务不提供“继续原任务”,后续使用“重新运行”。应用退出造成的中断仍走原恢复路径。远程取消不承诺撤销业务,详见 Remote Agent 与 A2A 任务处理。
运行输出在对应节点 message 中展示 App 自动补偿和远程取消结果。
App 补偿后,修复并重新运行
Section titled “App 补偿后,修复并重新运行”workflow 失败时,配置了补偿入口的成功 App 调用会自动清理,包括 Agent 内部成功的 Tool App 调用。先查看对应节点 message 的补偿状态,并核实未完成或结果未知的资源。补偿启动后,不再从检查点继续使用已清理的结果;修复后点击“重新运行”,创建新任务执行一轮新的业务,原运行保留失败与补偿证据。
停止执行不触发自动补偿,正常完成也不会清理。配置教程与异常处理见App 失败补偿。
从检查点恢复前,先确认副作用
Section titled “从检查点恢复前,先确认副作用”只有应用退出或崩溃造成的中断任务可以从检查点恢复。恢复前会检查操作日志,复用已保存结果;结果未知的操作先对账,不会盲目重发。缺少恢复契约的步骤可能阻止恢复。
workflow 失败后,先查看失败原因、App 自动补偿及远程取消消息,并核实外部资源状态。失败或已停止的任务只能使用“重新运行”创建新的业务执行,不会从原检查点继续;新运行也不会自动撤销上一次残留的副作用。
用运行诊断找到慢和贵的地方
Section titled “用运行诊断找到慢和贵的地方”
诊断会把同一节点下的工作流节点事件、模型调用和工具调用分开列出。例如可对比 Agent 的模型用量与 lookup_order 的工具耗时,判断瓶颈在模型、工具还是 Process App。
「运行诊断」会汇总工作流节点、工具调用和模型调用的耗时与状态;当 Provider 返回用量时,还会显示输入、输出和总 Token,以及估算成本。用它判断:模型调用是否变慢、工具是否持续超时、调用次数是否过多,以及 Token 增长来自上下文、输出还是推理。
单次异常先回到事件和输入;重复模式再用评测集或版本对比验证。有关批量回归验证与发布质量门,参见评估与质量门。
将 Trace 接入现有观测系统
Section titled “将 Trace 接入现有观测系统”运行工作区始终是单次执行的第一手证据。需要把 Workrun 与其他服务联查时,可在 设置 → 日志 中填写 OTLP/gRPC collector endpoint;保存新地址后需要重启应用才会生效。
配置前请确认 collector 地址与网络策略只允许预期接收方、Trace 不包含不应离开设备的敏感内容或凭据,并先在隔离环境用非敏感运行验证连接、字段和保留策略。
OTLP 是诊断导出,不替代本地运行记录、状态边界或逐次结果检查。
使用 Langfuse
Section titled “使用 Langfuse”可独立部署 infra/langfuse 的 Langfuse 与 Collector,也可使用已有 OTLP 后端,详见部署指南。桌面端连接 OTLP/gRPC Collector,而非直接填写 Langfuse UI URL:同机默认 http://127.0.0.1:4317。Collector 保管项目认证,转发至 Langfuse 的 /api/public/otel;远程桌面应使用可达且受保护的 collector 地址。
导出覆盖对话、工作流、节点、模型 generation 与工具 observation,并关联 session/run/node/call ID。metadata 可能包含当前账号身份;输入输出正文默认关闭,可在 设置 → 日志 → 导出对话和工作流正文 单独开启,重启后生效。关闭正文不等于停止 metadata 导出。配套配置丢弃 metrics,不需要启用 Langfuse AI Gateway,也不需要同时配置 LiteLLM Langfuse callback。
Langfuse 用于排查模型、工具和编排耗时,不代替本地检查点或运行记录;当前 Server 也没有额外接入 NestJS 分布式 Trace。
文件结果与本地存储
Section titled “文件结果与本地存储”文件输出在历史中保存为 artifact 引用,实际文件保存在本机当前工作区的 artifacts 目录。可在结果中导出文件、预览图片和视频,或打开 PDF。查看文件依赖对应的本地快照;只保留运行记录而丢失 artifacts 文件,无法恢复文件内容。
Personal 和 Team 的运行历史、聊天会话与待处理审批按工作区隔离,切换模式后只显示当前空间的数据,切回后仍可查看原空间的记录。Team 模式下的运行历史和 artifacts 也保存在本机,不会随工作流发布到团队服务器,换设备或其他成员登录后不会自动获得这些运行结果。备份或迁移时需要同时保留运行数据库和对应工作区的 artifacts 文件。