# 工作流

使用 `moi-cli workflow` 在终端中查询、部署和运行工作流，读取工作流作业状态与结果，并在需要时取消工作流作业。CLI 调用 Product API，不用于调用 Genesis 模型。

## 前提条件

- 已获得 `moi-cli`。
- 已配置产品 API 服务地址、个人访问令牌和目标工作区。
- 已有工作流 ID；部署工作流时还需要经过检查的工作流 DSL。

运行以下命令查看当前版本实际提供的子命令：

```bash
moi-cli workflow --help
```

## 查看工作流

列出当前工作区中的工作流：

```bash
moi-cli -o workflow list --workspace-id "$WORKSPACE_ID"
```

读取一个工作流的详情：

```bash
moi-cli -o workflow get \
  --workspace-id "$WORKSPACE_ID" \
  --workflow-id "$WORKFLOW_ID"
```

全局 `-o` 选项输出 JSON，适合从响应中读取工作流 ID、状态和可用操作。工作区已经写入配置文件时，可以省略子命令上的 `--workspace-id`。

## 启动工作流

```bash
moi-cli -o workflow run \
  --workspace-id "$WORKSPACE_ID" \
  --workflow-id "$WORKFLOW_ID"
```

保存响应中的工作流作业 ID `workflow_run.execution_id`：

```bash
export EXECUTION_ID='<EXECUTION_ID>'
```

当前 `workflow run` 命令只接收工作区 ID 和工作流 ID，不提供运行时 `values` 参数。需要向运行表单传值时，使用 [Product API](../../api/product-api/workflows-workitems-lineage/run-query-cancel.md) 或 [Product SDK](../../sdk/product-sdk/guides/workflows-workitems-lineage.md)。

命令返回工作流作业 ID 只表示平台已接受运行请求，不表示工作流已经完成。

## 查询状态和结果

查询工作流作业详情：

```bash
moi-cli -o workflow get-run \
  --workspace-id "$WORKSPACE_ID" \
  --workflow-id "$WORKFLOW_ID" \
  --execution-id "$EXECUTION_ID"
```

获取工作流作业结果：

```bash
moi-cli -o workflow get-run-result \
  --workspace-id "$WORKSPACE_ID" \
  --workflow-id "$WORKFLOW_ID" \
  --execution-id "$EXECUTION_ID"
```

在脚本中轮询时，应限制总等待时间和轮询次数。读取到终态或达到等待上限后停止；超时后先保留工作流作业 ID 并返回当前状态，不要自动再次运行工作流。

## 取消工作流作业

取消前先运行 `get-run`，确认当前工作流作业仍允许取消：

```bash
moi-cli -o workflow cancel-run \
  --workspace-id "$WORKSPACE_ID" \
  --workflow-id "$WORKFLOW_ID" \
  --execution-id "$EXECUTION_ID"
```

取消命令返回后，再运行 `get-run` 确认服务端状态。取消工作流作业不会自动回滚算子已经写入数据库、文件系统或外部服务的结果。

## 常用子命令

| 任务 | 子命令 |
| --- | --- |
| 列出和读取工作流 | `list`、`get` |
| 部署工作流 | `deploy` |
| 暂停或恢复工作流 | `pause`、`resume` |
| 运行工作流 | `run` |
| 查询工作流作业 | `list-runs`、`list-all-runs`、`get-run`、`get-run-by-id` |
| 读取结果和算子 | `get-run-result`、`get-run-node` |
| 处理重试和算子重新运行 | `retry-run`、`get-run-node-rerun-plan`、`create-run-node-rerun` |
| 取消工作流作业或重新运行 | `cancel-run`、`cancel-run-rerun` |
| WorkItem API Service | `get-workitem-api-service`、`publish-workitem-api-service`、`invoke-workitem-api-service` |
| 产物与血缘 | `artifact-lineage-overview`、`artifact-output-blocks`、`artifact-node` |

对于使用 `--json` 或 `--json-file` 传入复杂输入的命令，请参阅相应的 [Product API 文档](../../api/product-api/workflows-workitems-lineage/index.md)。不要从其他子命令推断参数名或请求体。

## 下一步

- [使用 Product API 运行、查询与取消](../../api/product-api/workflows-workitems-lineage/run-query-cancel.md)
- [使用 Product SDK 管理工作流](../../sdk/product-sdk/guides/workflows-workitems-lineage.md)
- [重新运行算子](../../api/product-api/workflows-workitems-lineage/rerun-nodes.md)