工作流调试与监控

工作流问题分为配置问题、数据流问题和运行时问题。先过检查清单，再做调试运行，最后看节点追踪和运行指标。

配置校验

检查清单在发布前逐项报告：未选择模型、工具或知识库；输入/输出变量没有来源；变量引用不存在；条件分支不完整；决策节点缺少模型、输入状态或判断说明，选项/等级数量或唯一性不合规，连线指向已过期的决策分支句柄；代码或模板为空；迭代/循环缺少开始或处理节点；没有输出节点。

清单里没有对应错误不代表配置正确——它只覆盖结构性问题，"这条分支真的走得到吗"要靠调试运行回答。

调试运行

选择调试运行并填入输入。它对应 POST /api/v1/workflows/{workflow_id}/debug：需要 workflow:run 权限和该工作流的写权限，创建一个 is_debug: true 的运行记录，并立刻返回 run_id 与 stream_url，真正的执行在后台任务里完成。

调试运行使用当前草稿，不会改动已发布版本；正式运行则加载最新已发布版本的快照。同一个按钮不会同时验证两条路径——改完草稿仍然需要重新发布才能让正式运行生效。

调试运行结束后，运行抽屉的详情显示输入、输出和错误；追踪显示每个节点的状态、输入、输出、Token、耗时和重试次数。连接 GET /api/v1/workflows/runs/{run_id}/stream 可以实时接收节点事件和 LLM 流式输出。

调试运行会回填变量类型

每次调试运行完成后，后端会根据节点执行记录推断每个输出的类型，并与草稿定义里已有的 data.inferredSchema 做并集合并：

编辑器在调试运行结束后重新拉取工作流，变量选择器因此能在一次试跑后给出字段级补全，不必手工声明结构。
以 _ 开头的内部输出（如 _iteration_state、_loop_complete）会被跳过，不进入推断结果。
只有调试运行会写回推断结果；正式运行刻意跳过，避免线上数据形态改变编辑器里的类型提示。

目前没有断点或单步调试。代码库里存在调试会话与断点的内部定义，但没有 API 路由或界面暴露它们，因此只能整轮运行、事后看追踪。要缩小定位范围，把大段逻辑拆成多个节点，或临时在中间加一个变量赋值/回答节点输出中间值。

运行状态

运行级状态：

状态	含义
`pending`	已创建，等待执行
`running`	正在执行
`waiting`	停在暂停节点，等待人工审批或补充变量
`success`	全部流程成功完成
`failed`	某节点或运行时失败
`cancelled`	用户取消
`timeout`	达到运行时限制

节点级状态多了 skipped：该节点被条件分支或循环跳过。跳过不是失败，也不会出现在运行级状态里。

监控指标

工作流监控页（/app/apps/workflow/{id}/monitor）的数据来自两个接口：

接口	内容
`GET /api/v1/workflows/{id}/stats`	总运行次数、成功次数、失败次数、超时次数、平均耗时、最后运行时间；不绑定时间窗，覆盖该工作流的全部历史
`GET /api/v1/workflows/{id}/stats/trends?period=7d\|30d`	按本地日期分桶的每日运行数、成功数、失败数和平均耗时；`period` 只识别 `30d`，其他取值按 `7d` 处理

监控页可以在 7d 与 30d 之间切换，卡片显示总运行数、成功率、平均耗时和失败数，下方是趋势图和最近运行列表。运行日志支持按状态、时间和完整运行 ID 过滤。

团队级/系统级运行统计见 GET /api/v1/workflows/runs/stats；管理员级的聚合指标（仪表盘摘要、单工作流指标、节点类型指标、运行中工作流、缓存统计与清理）挂在 /api/v1/admin/workflows/metrics/*，需要管理员权限。

排查顺序

检查输入变量是否存在且类型正确。
查看第一个失败节点，而不是只看最终错误。
对 LLM 检查模型授权、提示词和 Token；对 HTTP 检查 URL、请求头、超时与响应路径；对代码检查包版本、资源限制和产物路径。
对决策节点检查模型是否为决策类型且已授权给团队；看追踪里的 selected_handle、confidence 和 probabilities 判断是阈值问题还是判断说明问题（详见编排工作流 → 决策节点）。
对知识库检查文档是否完成处理、嵌入维度是否匹配以及检索服务可用性。
若是已发布应用，确认失败发生在已发布版本而不是草稿编辑器。