> Discover all available pages from the documentation index: https://mastra.zisheng.pro/llms.txt

# Workflow 状态读取器

Workflow 状态读取辅助函数用于检查 `workflow.getWorkflowRunById()` 返回的公共 `WorkflowState`。可使用这些函数恢复已暂停的 run 并检查恢复标签，还能直接读取步骤 payload 或输出，无需解析原始 workflow 快照。

## 使用示例

```typescript
import { createWorkflowStateReader } from '@mastra/core/workflows'

const state = await workflow.getWorkflowRunById('run-123')

if (state) {
  const reader = createWorkflowStateReader(state)
  const suspendedStep = reader.getSuspendedStep()
  const labels = reader.getResumeLabels()

  console.log(reader.getStatus())
  console.log(reader.getStepOutput('extract-data'))
  console.log(suspendedStep?.path)
  console.log(labels.approve)
}
```

## 函数

### `createWorkflowStateReader(state)`

创建一个读取器对象，其中的方法绑定到一个 `WorkflowState`。

```typescript
const reader = createWorkflowStateReader(state)
const suspendedStep = reader.getSuspendedStep()
```

### `getWorkflowStepOutput(state, stepId)`

返回指定步骤 ID 的输出，也支持 `parent.child` 等嵌套 workflow 点分路径。对于 `foreach` 步骤，每次迭代返回一个条目。已暂停迭代的输出条目可能为 `undefined`。

```typescript
const output = getWorkflowStepOutput(state, 'extract-data')
```

### `getWorkflowStepPayload(state, stepId)`

返回传递给步骤的 payload。对于 `foreach` 步骤，每次迭代返回一个条目。

```typescript
const payload = getWorkflowStepPayload(state, 'extract-data')
```

### `getWorkflowSuspendedStep(state)`

返回 workflow 状态中的第一个已暂停步骤。当多个步骤暂停时，顺序与 `suspendedPaths` 中存储的顺序一致。

```typescript
const suspendedStep = getWorkflowSuspendedStep(state)
```

### `getWorkflowSuspendedSteps(state)`

返回 workflow 状态中的所有已暂停步骤。每个结果都包含顶层步骤 ID、恢复路径、执行路径、暂停 payload、暂停输出和匹配的恢复标签。

```typescript
const suspendedSteps = getWorkflowSuspendedSteps(state)
```

### `getWorkflowResumeLabel(state, label)`

按名称返回恢复标签。

```typescript
const label = getWorkflowResumeLabel(state, 'approve')
```

### `getWorkflowResumeLabels(state)`

返回 workflow 状态中的所有恢复标签。

```typescript
const labels = getWorkflowResumeLabels(state)
```

## 读取器方法

`createWorkflowStateReader(state)` 返回以下方法：

**getStatus** (`() => WorkflowRunStatus`): 返回 workflow run 状态。

**getResult** (`() => WorkflowState["result"]`): 返回存在的终态 workflow 结果。

**getError** (`() => WorkflowState["error"]`): 返回存在的终态 workflow 错误。

**getStepOutput** (`(stepId: string) => any | Array<any | undefined> | undefined`): 返回指定步骤 ID 或嵌套 workflow 点分路径的输出。

**getStepPayload** (`(stepId: string) => any | Array<any | undefined> | undefined`): 返回指定步骤 ID 或嵌套 workflow 点分路径的 payload。

**getSuspendedStep** (`() => { stepId: string; path: string[]; executionPath?: number[]; step?: NonNullable<WorkflowState["steps"]>[string]; payload?: any; suspendPayload?: any; suspendOutput?: any; resumeLabels: Record<string, { stepId: string; foreachIndex?: number }> } | undefined`): 返回第一个已暂停的步骤。

**getSuspendedSteps** (`() => Array<{ stepId: string; path: string[]; executionPath?: number[]; step?: NonNullable<WorkflowState["steps"]>[string]; payload?: any; suspendPayload?: any; suspendOutput?: any; resumeLabels: Record<string, { stepId: string; foreachIndex?: number }> }>`): 返回所有已暂停的步骤。

**getResumeLabel** (`(label: string) => { stepId: string; foreachIndex?: number } | undefined`): 按名称返回恢复标签。

**getResumeLabels** (`() => Record<string, { stepId: string; foreachIndex?: number }>`): 返回所有恢复标签。

## 注意事项

仅当通过 `fields` 明确请求时，`workflow.getWorkflowRunById()` 才会返回 `requestContext` 和 `tracingContext`。

## 相关内容

- [暂停与恢复](https://mastra.zisheng.pro/docs/workflows/suspend-and-resume)
- [快照](https://mastra.zisheng.pro/docs/workflows/snapshots)
- [Workflow 类](https://mastra.zisheng.pro/reference/workflows/workflow)