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

# Workflow state reader

Workflow state reader 輔助函式可檢查 `workflow.getWorkflowRunById()` 回傳的公開 `WorkflowState`。可用它們復原已暫停的 run，並檢查 resume label。它們也能讀取步驟 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)`

建立 reader 物件，其中的方法會繫結至一個 `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、暫停輸出及相符的 resume label。

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

### `getWorkflowResumeLabel(state, label)`

依名稱回傳 resume label。

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

### `getWorkflowResumeLabels(state)`

回傳 Workflow 狀態中的所有 resume label。

```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`): 回傳步驟 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`): 依名稱回傳 resume label。

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

## 注意事項

只有在 `workflow.getWorkflowRunById()` 透過 `fields` 明確要求時，才會回傳 `requestContext` 與 `tracingContext`。

## 相關內容

- [暫停與繼續](https://mastra.zisheng.pro/zh-TW/docs/workflows/suspend-and-resume)
- [快照](https://mastra.zisheng.pro/zh-TW/docs/workflows/snapshots)
- [Workflow 類別](https://mastra.zisheng.pro/zh-TW/reference/workflows/workflow)