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

# Workflow

舊版 Workflow 功能已移除。

## 已變更

### `getWorkflows` 改為 `listWorkflows`

`mastra.getWorkflows()` 方法已重新命名為 `mastra.listWorkflows()`。這項變更與整個 API 使用的命名慣例一致：回傳多筆資料的 getter 方法會使用 `list` 前綴。

遷移時，請將所有 `mastra.getWorkflows()` 呼叫替換成 `mastra.listWorkflows()`。

```diff
- const workflows = mastra.getWorkflows();
+ const workflows = mastra.listWorkflows();
```

> **Codemod:** 你可以使用 Mastra 的 codemod CLI 自動更新匯入：
>
> ```bash
> npx @mastra/codemod@latest v1/mastra-plural-apis .
> ```

### 步驟內容中的 `RuntimeContext` 改為 `RequestContext`

Workflow 步驟執行內容中的參數名稱已從 `runtimeContext` 變更為 `requestContext`。這項變更與為提升清晰度而進行的全域重新命名一致。

遷移時，請在步驟執行函式中將 `runtimeContext` 參照更新為 `requestContext`。

```diff
createStep({
-   execute: async ({ runtimeContext } ) => {
-     const userTier = context.runtimeContext.get('userTier');
+   execute: async ({ requestContext } ) => {
+     const userTier = requestContext.get('userTier');
      return { result: userTier };
    },
  });
```

> **Codemod:** 你可以使用 Mastra 的 codemod CLI 自動更新匯入：
>
> ```bash
> npx @mastra/codemod@latest v1/runtime-context .
> ```

### `createRunAsync` 改為 `createRun`

`createRunAsync()` 方法已重新命名為 `createRun()`。由於所有 run 建立作業都是非同步，這項變更移除多餘的「Async」後綴，簡化 API。

遷移時，請將方法呼叫從 `createRunAsync` 重新命名為 `createRun`。

```diff
- await workflow.createRunAsync({ input: { ... } });
+ await workflow.createRun({ input: { ... } });
```

> **Codemod:** 你可以使用 Mastra 的 codemod CLI 自動更新程式碼：
>
> ```bash
> npx @mastra/codemod@latest v1/workflow-create-run-async .
> ```

### `runCount` 改為 `retryCount`（已棄用）

Workflow 步驟執行中的 `runCount` 參數已棄用，請改用 `retryCount`。新名稱表示此值為重試次數。舊的 `runCount` 仍可運作，但會顯示棄用警告。

遷移時，請在步驟執行函式中將 `runCount` 重新命名為 `retryCount`。

```diff
createStep({
    execute: async (inputData, context) => {
-     console.log(`Step run ${context.runCount} times`);
+     console.log(`Step retry count: ${context.retryCount}`);
    },
  });
```

> **Codemod:** 你可以使用 Mastra 的 codemod CLI 自動更新程式碼：
>
> ```bash
> npx @mastra/codemod@latest v1/workflow-run-count .
> ```

### `getInitData` 傳回 unknown

execute 函式中的 `getInitData` 函式現在傳回 unknown，而非 any。你必須自行指定型別。 遷移時，請將 `getInitData()` 變更為 `getInitData<any>()`。

```diff
createStep({
    execute: async ({ getInitData }) => {
-     const initData = getInitData();
-     if (initData.key === 'value') {}
+     const initData = getInitData<any>();
+     if (initData.key === 'value') {}
    },
  });
```

> **Codemod:** 你可以使用 Mastra 的 codemod CLI 自動更新程式碼：
>
> ```bash
> npx @mastra/codemod@latest v1/workflow-get-init-data .
> ```

### `getWorkflowRuns` 改為 `listWorkflowRuns`

`getWorkflowRuns()` 方法已重新命名為 `listWorkflowRuns()`。這項變更符合 `list*` 方法傳回集合的慣例。

遷移時，請將方法呼叫從 `getWorkflowRuns` 重新命名為 `listWorkflowRuns`。

```diff
- const runs = await workflow.getWorkflowRuns({ fromDate, toDate });
+ const runs = await workflow.listWorkflowRuns({ fromDate, toDate });
```

> **Codemod:** 你可以使用 Mastra 的 codemod CLI 自動更新程式碼：
>
> ```bash
> npx @mastra/codemod@latest v1/workflow-list-runs .
> ```

### 預設驗證輸入

先前預設不會驗證輸入。[`validateInputs`](https://mastra.zisheng.pro/zh-TW/reference/workflows/workflow) 旗標決定是否驗證 Workflow 輸入，此布林值現已改為 `true`。如果想保留舊有行為，或有不需驗證結構描述的 Workflow，請設定 `validateInputs: false`。

```diff
createWorkflow({
+  options: {
+    validateInputs: false
+  }
})
```

### 步驟 `suspendPayload` 驗證

對於已定義 `suspendSchema` 的步驟，現在會驗證步驟的 `suspendPayload`。此驗證也會使用 `validateInputs` 旗標，決定是否驗證 `suspendPayload`。

```diff
createStep({
    id: "suspend-resume-step",
    // ... other step properties
    suspendSchema: z.object({
      reason: z.string(),
      otherReason: z.string()
    }),
    execute: async ({ suspend, resumeData}) => {
      if (!resumeData) {
-       return suspend({ reason: "Suspension reason" }); // Missing otherReason
+       return suspend({ reason: "Suspension reason", otherReason: "Other reason" });
      }
    },
  });
```

### 分支結果欄位現在是選填

`.branch()` 方法現在傳回所有分支輸出欄位皆為選填的結構描述。這反映執行階段行為：每個分支只會在條件為 truthy 時執行，因此任何分支的輸出都可能是 undefined。

遷移時，請更新所有使用分支輸出的程式碼，以處理選填值。

```diff
const workflow = createWorkflow({...})
    .branch([
      [condition1, stepA],  // outputSchema: { result: z.string() }
      [condition2, stepB],  // outputSchema: { data: z.number() }
    ])
-   // Previously: stepA.result typed as string, stepB.data typed as number
+   // Now: stepA.result typed as string | undefined, stepB.data typed as number | undefined
    .then(nextStep);
```

如果程式碼依賴非選填型別，請新增執行階段檢查，或在存取分支輸出時提供預設值。

### `Run.start()` 與 `Run.timeTravel()` 中的 `writableStream` 改為 `outputWriter`

`Run.start()` 與 `Run.timeTravel()` 中的 `writableStream` 參數已由 `outputWriter` 取代。現在不再傳入 `WritableStream`，而是傳入直接接收每個 Workflow 事件區塊的非同步回呼函式。

這項變更簡化了 API：不需建立 `WritableStream` 包裝函式，直接在回呼中處理區塊即可。

\*\*範例：\*\*將 Workflow 事件串流至 HTTP 回應（SSE）：

```diff
const run = await workflow.createRun();

- const stream = new WritableStream({
-   write(chunk) {
-     response.write(`data: ${JSON.stringify(chunk)}\n\n`);
-   }
- });
- await run.start({ inputData, writableStream: stream });

+ await run.start({
+   inputData,
+   outputWriter: async (chunk) => {
+     response.write(`data: ${JSON.stringify(chunk)}\n\n`);
+   },
+ });
```

> **備註:** 這項變更不影響傳給步驟 `execute` 函式的 `writer` 參數。它仍是擴充 `WritableStream<unknown>` 並提供 `.write()` 與 `.custom()` 方法的 `ToolStream`：
>
> ```ts
> createStep({
>   id: 'my-step',
>   execute: async ({ writer }) => {
>     // This API is unchanged
>     await writer.write({ data: 'some output' })
>     await writer.custom({ type: 'custom-event', payload: {} })
>   },
> })
> ```

### `setState()` 現在是非同步，且會驗證傳入資料

`setState()` 函式現在是非同步。傳入的資料現在會根據步驟中定義的 `stateSchema` 驗證。狀態資料驗證也會使用 `validateInputs` 旗標，決定是否驗證狀態資料。此外，呼叫 `setState()` 時，現在只需傳入要更新的狀態資料，不需再展開先前的狀態 `(...state)`。

遷移時，請將 `setState()` 函式更新為非同步。

```diff
- setState({ ...state, sharedCounter: state.sharedCounter + 1 });
+ await setState({ sharedCounter: state.sharedCounter + 1 });
+ // await setState({ ...state, sharedCounter: state.sharedCounter + 1 });
+ // this also works, as the previous state spread remains supported
```

## 已移除

### `streamVNext`、`resumeStreamVNext` 與 `observeStreamVNext` 方法

實驗性的 `streamVNext()`、`resumeStreamVNext()` 與 `observeStreamVNext()` 方法已移除。這些方法現在是標準實作，並使用更新後的事件結構與傳回型別。

遷移時，請改用標準的 `stream()`、`resumeStream()` 與 `observeStream()` 方法。請將事件型別檢查更新為使用 Workflow 前綴名稱，並直接存取串流屬性。

詳情請參閱 [`Run.stream()`](https://mastra.zisheng.pro/zh-TW/reference/streaming/workflows/stream)、[`Run.resumeStream()`](https://mastra.zisheng.pro/zh-TW/reference/streaming/workflows/resumeStream) 與 [`Run.observeStream()`](https://mastra.zisheng.pro/zh-TW/reference/streaming/workflows/observeStream)。

> **Codemod:** 你可以使用 Mastra 的 codemod CLI 自動更新程式碼：
>
> ```bash
> npx @mastra/codemod@latest v1/workflow-stream-vnext .
> ```

### 步驟條件函式參數中不提供 `suspend()` 與 `setState()`

步驟條件函式參數中不提供 `suspend()` 與 `setState()` 函式。

遷移時，請改在步驟 execute 函式中使用 `suspend()` 函式。

```diff
.dowhile(step, async ({ suspend, state, setState }) => {
- setState({...state, updatedState: "updated state"})
- await suspend({ reason: "Suspension reason" });
+ // Use the suspend/setState in the step execute function instead
});
```

`dountil` 與 `branch` 條件函式參數也是如此。

### 舊版 Workflow 匯出項目

`@mastra/core` 已移除 `./workflows/legacy` 匯出路徑。不再支援舊版 Workflow。

遷移時，請使用新的 Workflow API。舊版 Workflow 沒有直接遷移路徑。

```diff
- import { LegacyWorkflow } from '@mastra/core/workflows/legacy';
+ // Legacy workflows are no longer supported
+ // Migrate to the new workflow API
```

### `WorkflowRunOutput` 的 `pipeThrough` 與 `pipeTo` 方法

`WorkflowRunOutput` 上的 `pipeThrough()` 與 `pipeTo()` 方法已棄用。這些方法仍可運作，但會顯示主控台警告。

遷移時，請使用 `fullStream` 屬性，而非直接在 run 輸出上呼叫方法。

```diff
const run = await workflow.createRun({ input: { ... } });
- await run.pipeTo(writableStream);
- const transformed = run.pipeThrough(transformStream);
+ await run.fullStream.pipeTo(writableStream);
+ const transformed = run.fullStream.pipeThrough(transformStream);
```

### Watch 事件 API

舊版 watch 事件已移除，並整合至 v2 事件 API。不再提供 `watch()` 方法與相關 watch 端點。

遷移時，請使用 Workflow 事件 API 或串流，而非 watch 事件。

```diff
- const workflow = mastraClient.getWorkflow('my-workflow');
- const run = await workflow.createRun();
- await run.watch((event) => {
-   console.log('Step completed:', event);
- });

+ const workflow = mastraClient.getWorkflow('my-workflow');
+ const run = await workflow.createRun();
+ const stream = await run.stream({ inputData: { ... } });
+ for await (const chunk of stream) {
+   console.log('Step completed:', chunk);
+ }
```

### `waitForEvent` API

Workflow 已移除 `waitForEvent` API。請改用暫停／恢復 API。

遷移時，請使用暫停／恢復 API，等待 Workflow 執行到達特定階段。

```diff
- workflow.waitForEvent('step-complete', step1).commit();
+ workflow.then(step1).commit();
+ // Use suspend/resume API instead, in step1 execute function
createStep({
- execute: async (inputData, context) => {
-  // ... execution logic
- }
+ execute: async (inputData, context) => {
+   if (!context.resumeData) {
+     return context.suspend({})
+   }
+ }
});
+
+ // after workflow is suspended, you can resume it
+ const result = await run.start({ inputData: { ... } });
+ if (result.status === 'suspended') {
+   const resumedResult = await run.resume({
+     resumeData: {
+       event: 'step-complete',
+     },
+     step: 'step1',
+   });
+ }
```

### `sendEvent` API

Workflow 已移除 `sendEvent` API。請改用暫停／恢復 API。