---
myst:
  html_meta:
    "moi:status": "paper-verified"
---

# 运行与调试

工作流发布后，每次运行都会产生工作流作业。本页说明如何从工作流作业定位失败，并列出常见的失败成因与处理方式。排查建立在[工作流](workflow.md)页的前提之上：调度引擎按定义执行、不校验任务语义，因此失败既可能来自定义，也可能来自某个算子的执行。

## 从工作流作业入手

一次运行按输入文件扇出为多条工作流作业，每个文件一条。每条记录包含各算子的执行状态、输入、输出与日志。

排查从第一个失败算子的工作流作业开始：

1. 定位状态为失败的算子。
2. 查看该算子的**输入**：是否取到了预期的值，字段是否符合该算子的约定。
3. 查看该算子的**日志**：执行问题的原因通常记录在此。
4. 若该算子的输入已经不对，问题多在其上游或定义，而非该算子本身。

## 先分两类问题

定位失败前，先判断问题属于哪一类——两类的修复位置不同。

| 类别 | 表现 | 修复位置 |
|---|---|---|
| 定义问题 | 算子选择、执行顺序或参数绑定错误；引擎照定义原样执行 | 修改工作流定义 |
| 执行问题 | 定义正确，某算子对合法输入处理失败 | 查看该算子工作流作业中的日志 |

一份能保存、能启动的工作流，不代表定义正确。定义问题不会在保存或启动时报错，只在运行中显现。

## 常见失败与成因

| 现象 | 成因 | 处理 |
|---|---|---|
| 算子持续等待，不报错也不结束 | 算子引用的算子未在工作区注册（名称拼写、版本不符，或该算子当前无可用实例） | 以 `GET /workspaces/:id/workitems` 核对算子名称与可用性 |
| 算子报输入缺失或取值为空 | 下游模板引用的键，上游未用 `save` 写入；或上下游键名不一致 | 核对上游 `save` 的键名与下游 `input` 模板引用的名称 |
| 画布显示与实际执行不一致 | 局部编辑改动了其他算子的绑定 | 发布前用“预览 DSL”核对整份定义 |
| 子工作流合并失败 | 不支持跨工作流引用或合并，工作流之间不共享状态、无数据通道 | 在同一份工作流定义内声明子网 |
| 需要文件内容的算子取不到正文 | 工作流数据只传文件引用，不传文件正文；读取正文的算子已禁用 | 由算子凭文件引用自行读取正文 |
| SQL 算子执行失败 | SQL 算子的输入仅为 SQL 语句本身，不接受自然语言 | 检查 SQL 语句本身；详见 [SQL 编辑器](sql-editor.md) |

```{note}
算子引用未注册的算子时，运行不会报错，该算子持续等待。这类失败在工作流作业中表现为算子长期停留在等待状态，而非报错退出——排查时优先核对算子名称是否与工作区实时清单一致。
```

```{tip}
在画布上完成局部编辑后，发布前用“预览 DSL”通读整份定义。画布是定义的一种编辑入口，局部操作可能改动其他算子的绑定；以 DSL 为准核对，可在运行前发现定义问题。
```

## 参见

- [工作流](workflow.md)
- [工作流算子](workflow-nodes.md)
- [SQL 编辑器](sql-editor.md)