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

# Workflow state reader

Workflow state reader 輔助函式會檢查 `workflow.getWorkflowRunById()` 傳回的公開 `WorkflowState`。你可以用它們復原已暫停的 run 及檢查恢復標籤，亦可讀取 step payload 或輸出，而無需解析原始 Workflow snapshot。

## 使用範例

```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)`

建立 reader 物件，當中的方法會綁定至一個 `WorkflowState`。

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

### `getWorkflowStepOutput(state, stepId)`

傳回指定 step ID 的輸出，包括 `parent.child` 等巢狀 Workflow 點號路徑。對於 `foreach` step，每次反覆運算會傳回一個項目。已暫停的反覆運算可能有值為 `undefined` 的輸出項目。

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

### `getWorkflowStepPayload(state, stepId)`

傳回傳遞至 step 的 payload。對於 `foreach` step，每次反覆運算會傳回一個項目。

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

### `getWorkflowSuspendedStep(state)`

傳回 Workflow 狀態中第一個已暫停的 step。當有多個 step 暫停時，排序會依照它們在 `suspendedPaths` 中儲存的次序。

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

### `getWorkflowSuspendedSteps(state)`

傳回 Workflow 狀態中所有已暫停的 step。每個結果都包括頂層 step ID、恢復路徑、執行路徑、暫停 payload、暫停輸出，以及相符的恢復標籤。

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

### `getWorkflowResumeLabel(state, label)`

按名稱傳回恢復標籤。

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

### `getWorkflowResumeLabels(state)`

傳回 Workflow 狀態中的所有恢復標籤。

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

## Reader 方法

`createWorkflowStateReader(state)` 會傳回以下方法：

**getStatus** (`() => WorkflowRunStatus`): 傳回 Workflow run 狀態。

**getResult** (`() => WorkflowState["result"]`): 如有最終 Workflow 結果，則傳回該結果。

**getError** (`() => WorkflowState["error"]`): 如有最終 Workflow 錯誤，則傳回該錯誤。

**getStepOutput** (`(stepId: string) => any | Array<any | undefined> | undefined`): 傳回指定 step ID 或巢狀 Workflow 點號路徑的輸出。

**getStepPayload** (`(stepId: string) => any | Array<any | undefined> | undefined`): 傳回指定 step 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`): 傳回第一個已暫停的 step。

**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 }> }>`): 傳回所有已暫停的 step。

**getResumeLabel** (`(label: string) => { stepId: string; foreachIndex?: number } | undefined`): 按名稱傳回恢復標籤。

**getResumeLabels** (`() => Record<string, { stepId: string; foreachIndex?: number }>`): 傳回所有恢復標籤。

## 注意事項

只有在使用 `fields` 明確要求時，`workflow.getWorkflowRunById()` 才會傳回 `requestContext` 及 `tracingContext`。

## 相關內容

- [暫停及恢復](https://mastra.zisheng.pro/zh-HK/docs/workflows/suspend-and-resume)
- [Snapshots](https://mastra.zisheng.pro/zh-HK/docs/workflows/snapshots)
- [Workflow 類別](https://mastra.zisheng.pro/zh-HK/reference/workflows/workflow)