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

# Run.timeTravel()

`.timeTravel()` 方法會從任一特定步驟開始重新執行 Workflow，並使用已儲存的快照資料或你提供的自訂情境。可用它偵錯失敗的 Workflow，或使用不同輸入測試個別步驟。它也能在不重新執行整個 Workflow 的情況下從錯誤中復原。

## 使用範例

```typescript
const run = await workflow.createRun()

const result = await run.timeTravel({
  step: 'step2',
  inputData: { value: 10 },
})
```

## 參數

**step** (`Step<string, any, TInputSchema, any, any, any, TEngineType> | [...Step<string, any, any, any, any, any, TEngineType>[], Step<string, any, TInputSchema, any, any, any, TEngineType>] | string | string[]`): 要從中開始執行的目標步驟。可為 Step 執行個體、Step 陣列（用於巢狀 Workflow）、步驟 ID 字串或步驟 ID 字串陣列。巢狀 Workflow 步驟請使用點號標記法或陣列（例如 'nestedWorkflow\.step3' 或 \['nestedWorkflow', 'step3']）

**inputData** (`z.infer<TInputSchema>`): 目標步驟的輸入資料，必須符合該步驟的輸入 schema。若未提供，則使用 Workflow 快照中的資料

**resumeData** (`any`): 若 Workflow 先前已暫停，要提供的繼續執行資料

**initialState** (`z.infer<TState>`): 要為 Workflow run 設定的初始狀態。用於在執行前設定 Workflow 層級狀態

**context** (`TimeTravelContext<any, any, any, any>`): 包含目標步驟之前各步驟結果的執行情境。每個 key 都是步驟 ID，其 StepResult 物件包含 status、payload、output、startedAt、endedAt、suspendPayload 與 resumePayload

**nestedStepsContext** (`Record<string, TimeTravelContext<any, any, any, any>>`): 巢狀 Workflow 步驟的情境。以巢狀 Workflow ID 作為 key，每個值都包含該巢狀 Workflow 的步驟結果

**requestContext** (`RequestContext`): time travel 執行期間要使用的 Request Context 資料

**outputWriter** (`(chunk: TOutput) => Promise<void>`): 在產生輸出區塊時處理這些區塊的選用非同步函式

**tracingContext** (`TracingContext`): 用來建立子 span 及新增中繼資料的 Tracing context。使用 Mastra 的 tracing 系統時會自動注入。

**tracingContext.currentSpan** (`Span`): 用來建立子 span 及新增中繼資料的目前 span。執行期間可用它建立自訂子 span 或更新 span 屬性。

**tracingOptions** (`TracingOptions`): Tracing 設定選項。

**tracingOptions.metadata** (`Record<string, any>`): 要新增至根 Trace span 的中繼資料。適合新增使用者 ID、工作階段 ID 或功能旗標等自訂屬性。

**tracingOptions.requestContextKeys** (`string[]`): 要擷取為此 Trace 中繼資料的其他 RequestContext key。支援以點號標記法表示巢狀值（例如 'user.id'）。

**tracingOptions.traceId** (`string`): 此執行要使用的 Trace ID（1 至 32 個十六進位字元）。若有提供，此 Trace 會成為指定 Trace 的一部分。

**tracingOptions.parentSpanId** (`string`): 此執行要使用的父 span ID（1 至 16 個十六進位字元）。若有提供，根 span 會建立為此 span 的子 span。

**tracingOptions.tags** (`string[]`): 要套用至此 Trace 的標籤。這些字串標籤可用來分類及篩選 Trace。

**outputOptions** (`OutputOptions`): 輸出設定選項。

**outputOptions.includeState** (`boolean`): 是否在結果中包含 Workflow run 狀態。

**outputOptions.includeResumeLabels** (`boolean`): 是否在結果中包含 resume label。

## 回傳值

**result** (`Promise<WorkflowResult<TState, TInput, TOutput, TSteps>>`): 會解析為 Workflow 執行結果的 promise；結果包含步驟輸出與狀態

**traceId** (`string`): 啟用 Tracing 時，與此執行相關聯的 Trace ID。可用來關聯記錄及偵錯執行流程。

**spanId** (`string`): 啟用 Tracing 時，與此執行相關聯的根 span ID。可用於 span 層級的查找與關聯。

## 延伸使用範例

### 使用自訂情境進行 time travel

```typescript
const result = await run.timeTravel({
  step: 'step2',
  context: {
    step1: {
      status: 'success',
      payload: { value: 0 },
      output: { step1Result: 2 },
      startedAt: Date.now(),
      endedAt: Date.now(),
    },
  },
})
```

### Time travel 至巢狀 Workflow 步驟

```typescript
// Using dot notation
const result = await run.timeTravel({
  step: 'nestedWorkflow.step3',
  inputData: { value: 10 },
})

// Using array of step IDs
const result = await run.timeTravel({
  step: ['nestedWorkflow', 'step3'],
  inputData: { value: 10 },
})
```

### 使用初始狀態進行 time travel

```typescript
const result = await run.timeTravel({
  step: 'step2',
  inputData: { value: 10 },
  initialState: {
    counter: 5,
    metadata: { source: 'time-travel' },
  },
})
```

### 使用巢狀 Workflow 情境進行 time travel

```typescript
const result = await run.timeTravel({
  step: 'nestedWorkflow.step3',
  context: {
    step1: {
      status: 'success',
      payload: { value: 0 },
      output: { step1Result: 2 },
      startedAt: Date.now(),
      endedAt: Date.now(),
    },
    nestedWorkflow: {
      status: 'running',
      payload: { step1Result: 2 },
      startedAt: Date.now(),
    },
  },
  nestedStepsContext: {
    nestedWorkflow: {
      step2: {
        status: 'success',
        payload: { step1Result: 2 },
        output: { step2Result: 3 },
        startedAt: Date.now(),
        endedAt: Date.now(),
      },
    },
  },
})
```

## 注意事項

- Time travel 仰賴已保存的 Workflow 快照，因此需要設定儲存空間
- 重新執行 Workflow 時，Workflow 會從儲存空間載入現有快照（若有）
- 系統會根據快照或提供的情境，重建目標步驟之前的步驟結果
- 系統會使用提供或重建的輸入資料，從指定步驟開始執行
- Workflow 會從該處繼續執行至完成
- 即使 Workflow 尚未執行過，也可以透過提供自訂情境或起始步驟的輸入資料來使用 time travel。

## 相關內容

- [Time Travel](https://mastra.zisheng.pro/zh-TW/docs/workflows/time-travel)
- [Workflows 概觀](https://mastra.zisheng.pro/zh-TW/docs/workflows/overview)
- [Workflow.createRun()](https://mastra.zisheng.pro/zh-TW/reference/workflows/workflow-methods/create-run)
- [快照](https://mastra.zisheng.pro/zh-TW/docs/workflows/snapshots)
- [暫停與繼續](https://mastra.zisheng.pro/zh-TW/docs/workflows/suspend-and-resume)