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

# Temporal Workflow

[Temporal](https://temporal.io/) 是一個持久執行平台，可協調長時間執行且具容錯能力的 Workflow。`@mastra/temporal` 套件讓你能使用標準 Mastra API 編寫 Workflow，並在 Temporal 叢集上執行。

> **警告:** `@mastra/temporal` 仍處於實驗階段，尚未準備好用於正式環境。API 可能在不同版本間變更。請參閱[套件 README](https://github.com/mastra-ai/mastra/tree/main/workflows/temporal) 瞭解目前狀態。

## Temporal 如何與 Mastra 搭配運作

使用 `createWorkflow()` 和 `createStep()` 編寫的 Mastra Workflow 會對應至 Temporal 的 Workflow 與 Activity 模型。Temporal Worker 的 `MastraPlugin` 會在封裝時編譯 Mastra 進入點檔案：

- 每個 `createStep()` 處理常式都會擷取為 Temporal Activity。
- 每個 `createWorkflow()` 都會重寫為叫用這些 Activity 的 Temporal Workflow。
- 外掛程式會自動向 Worker 註冊產生的 Activity 與 Workflow。

透過 `mastra.getWorkflow(...).createRun().start(...)` 開始執行時，Mastra Client 會將控制權交給 Temporal。接著由 Temporal 在 Worker 上驅動持久執行、重試和狀態保存。

## 設定

安裝必要套件：

**npm**:

```bash
npm install @mastra/temporal@latest @temporalio/client @temporalio/worker @temporalio/envconfig
```

**pnpm**:

```bash
pnpm add @mastra/temporal@latest @temporalio/client @temporalio/worker @temporalio/envconfig
```

**Yarn**:

```bash
yarn add @mastra/temporal@latest @temporalio/client @temporalio/worker @temporalio/envconfig
```

**Bun**:

```bash
bun add @mastra/temporal@latest @temporalio/client @temporalio/worker @temporalio/envconfig
```

你也需要能存取 Temporal 叢集。本機開發時，可以使用 Docker 執行叢集（請參閱[在本機執行](#running-locally)）。

## 建置由 Temporal 支援的 Workflow

本指南將逐步說明如何使用 Temporal 與 Mastra 建立 Workflow，並以遞增數值的計數器應用程式示範。

### 初始化 Temporal

初始化 Temporal 整合以取得與 Mastra 相容的 Workflow 輔助函式。`createWorkflow()` 和 `createStep()` 函式會繫結至 Temporal Client 與工作佇列。

```ts
import { init } from '@mastra/temporal'
import { Client, Connection } from '@temporalio/client'
import { loadClientConnectConfig } from '@temporalio/envconfig'

const config = loadClientConnectConfig()
const connection = await Connection.connect(config.connectionOptions)
const client = new Client({ connection })

export const { createWorkflow, createStep } = init({
  client,
  taskQueue: 'mastra',
})
```

`loadClientConnectConfig()` 會讀取標準 Temporal 環境變數，例如 `TEMPORAL_ADDRESS`、`TEMPORAL_NAMESPACE` 和 mTLS 設定。完整清單請參閱 [Temporal envconfig 文件](https://docs.temporal.io/develop/typescript/temporal-clients)。

### 建立步驟

定義組成 Workflow 的各個步驟。每個步驟都會成為 Temporal Activity。

```ts
import { z } from 'zod'
import { createWorkflow, createStep } from '../temporal'

const incrementStep = createStep({
  id: 'increment',
  inputSchema: z.object({
    value: z.number(),
  }),
  outputSchema: z.object({
    value: z.number(),
  }),
  execute: async ({ inputData }) => {
    return { value: inputData.value + 1 }
  },
})
```

### 建立 Workflow

將步驟組合成 Workflow。Workflow 的 `id` 必須是靜態字串常值，建置階段轉換器才能推導其 Temporal 匯出名稱。

```ts
const workflow = createWorkflow({
  id: 'increment-workflow',
  steps: [incrementStep],
  inputSchema: z.object({
    value: z.number(),
  }),
  outputSchema: z.object({
    value: z.number(),
  }),
}).then(incrementStep)

workflow.commit()

export { workflow as incrementWorkflow }
```

### 設定 Mastra 執行個體

向 Mastra 註冊 Workflow。執行作業由 Temporal Worker 驅動。

```ts
import { Mastra } from '@mastra/core'
import { PinoLogger } from '@mastra/loggers'
import { incrementWorkflow } from './workflows'

export const mastra = new Mastra({
  workflows: { incrementWorkflow },
  logger: new PinoLogger({ name: 'Mastra', level: 'info' }),
})
```

## 執行 Worker

Worker 是長時間執行的 Node.js 處理程序，會輪詢 Temporal 工作佇列。安裝 `MastraPlugin`，並將其 `src` 選項指向註冊 Workflow 的 Mastra 進入點檔案。

```ts
import { MastraPlugin } from '@mastra/temporal/worker'
import { NativeConnection, Worker } from '@temporalio/worker'

const connection = await NativeConnection.connect({
  address: 'localhost:7233',
})

const mastraPlugin = new MastraPlugin()

await mastraPlugin.prebuild({
  entryFile: import.meta.resolve('./index.ts'),
})

const worker = await Worker.create({
  connection,
  namespace: 'default',
  taskQueue: 'mastra',
  plugins: [mastraPlugin],
})

await worker.run()
```

`MastraPlugin` 會將進入點檔案重寫為僅包含 Workflow 的套件，並將步驟處理常式連接為 Temporal Activity。你不需要手動將 `activities` 或 `workflowsPath` 傳給 `Worker.create()`。

## 執行 Workflow

### 在本機執行

1. 啟動本機 Temporal 伺服器。最簡單的選項是使用 `temporalio/auto-setup` Docker 映像檔：

   ```bash
   docker run --rm -p 7233:7233 -p 8080:8080 temporalio/auto-setup:latest
   ```

2. 在 <http://localhost:8080> 開啟 Temporal UI，查看命名空間、Workflow 和 Activity。

3. 在新的終端機中執行下列指令以啟動 Worker：

   ```bash
   npx tsx src/mastra/worker.ts
   ```

4. 從指令碼或任何匯入 Mastra 執行個體的處理程序觸發 Workflow 執行：

   ```ts
   import { mastra } from '../src/mastra'

   const run = await mastra.getWorkflow('incrementWorkflow').createRun()
   const result = await run.start({ inputData: { value: 5 } })

   console.log(result)
   ```

5. 在 Temporal UI 的 **Workflows** 下監控執行作業，查看逐步 Activity 進度和重試歷程。

### 在正式環境中執行

正式環境請使用 [Temporal Cloud](https://temporal.io/cloud) 或自行託管的 Temporal 叢集。透過 `@temporalio/envconfig` 讀取的環境變數設定 Client 與 Worker 連線：

```bash
TEMPORAL_ADDRESS=your-namespace.tmprl.cloud:7233
TEMPORAL_NAMESPACE=your-namespace
TEMPORAL_API_KEY=your-api-key
```

如需 mTLS 和 API 金鑰選項，請參閱 [Temporal Cloud 連線文件](https://docs.temporal.io/cloud/get-started)。

> **警告:** Temporal Worker 必須以長時間執行的處理程序運作。請勿將其部署至 AWS Lambda 或 Vercel 函式等執行時間受限的無伺服器平台。請使用容器、虛擬機器，或 Fly.io、Railway、Kubernetes 等適合 Worker 的平台。

## 設定選項

### `taskQueue`

必要。識別 Worker 輪詢的 Temporal 工作佇列。必須將相同的值傳給 `init()`（Client 用它開始執行）和 `Worker.create()`（Worker 用它接收工作）。

### `startToCloseTimeout`

選用。設定單一 Activity（步驟）可執行的最長時間；超過後 Temporal 會取消該 Activity 並套用重試原則。預設為 `1 minute`。

```ts
export const { createWorkflow, createStep } = init({
  client,
  taskQueue: 'mastra',
  startToCloseTimeout: '5 minutes',
})
```

## 限制與注意事項

- Workflow ID 必須是靜態字串常值。建置階段轉換器會讀取常值，以推導 Temporal Workflow 匯出名稱。
- Activity 會由 `createStep()` 處理常式自動產生。請勿在 `Worker.create({ activities })` 中傳入。

## 相關內容

- [Workflow 執行器](https://mastra.zisheng.pro/zh-TW/docs/deployment/workflow-runners)
- [Workflow 概觀](https://mastra.zisheng.pro/zh-TW/docs/workflows/overview)
- [Temporal 文件](https://docs.temporal.io/)