> Discover all available pages from the documentation index: https://mastra.zisheng.pro/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/reference/workflows/workflow) 标志决定是否验证 Workflow 输入。该布尔值的默认值现已改为 `true`。如果需要旧行为，或 Workflow Schema 无需验证，请设置 `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()` 方法现在返回一个 Schema，其中所有分支输出字段都是可选的。这与运行时行为一致：每个分支仅在条件为真时执行，因此任何分支的输出都可能为 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>` 的 `ToolStream`，并提供 `.write()` 和 `.custom()` 方法：
>
> ```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/reference/streaming/workflows/stream)、[`Run.resumeStream()`](https://mastra.zisheng.pro/reference/streaming/workflows/resumeStream) 和 [`Run.observeStream()`](https://mastra.zisheng.pro/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。