Run.timeTravel()

.timeTravel() 方法會從任何指定步驟開始重新執行 Workflow，並使用已儲存的 snapshot 資料或你提供的自訂 context。你可以用它偵錯失敗的 Workflow，並以不同輸入測試個別步驟。它亦可從錯誤中復原，而毋須重新執行整個 Workflow。

使用範例

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 instance、Step 陣列（用於巢狀 Workflow）、步驟 ID 字串，或步驟 ID 字串陣列。巢狀 Workflow 步驟可使用點號標記法或陣列（例如 'nestedWorkflow.step3' 或 ['nestedWorkflow', 'step3']）

inputData?:

z.infer<TInputSchema>

目標步驟的輸入資料。必須符合該步驟的 input schema。如未提供，便會使用 Workflow snapshot 中的資料

resumeData?:

any

如果 Workflow 之前已暫停，要提供的 resume 資料

initialState?:

z.infer<TState>

為 Workflow run 設定的初始 state。用於在執行前設定 Workflow 層級的 state

context?:

TimeTravelContext<any, any, any, any>

執行 context，包含目標步驟之前各步驟的結果。每個 key 都是步驟 ID，其 StepResult object 包含 status、payload、output、startedAt、endedAt、suspendPayload 及 resumePayload

nestedStepsContext?:

Record<string, TimeTravelContext<any, any, any, any>>

巢狀 Workflow 步驟的 context。以巢狀 Workflow ID 作為 key，每項均包含該巢狀 Workflow 的步驟結果

requestContext?:

RequestContext

在 time travel 執行期間使用的 Request Context 資料

outputWriter?:

(chunk: TOutput) => Promise<void>

可選的非同步函數，用於在產生輸出 chunk 時加以處理

tracingContext?:

TracingContext

用於建立 child span 及加入 metadata 的 Tracing context。使用 Mastra 的 tracing 系統時會自動注入。

currentSpan?:

Span

用於建立 child span 及加入 metadata 的目前 span。可在執行期間用它建立自訂 child span 或更新 span attribute。

tracingOptions?:

TracingOptions

Tracing 設定的選項。

metadata?:

Record<string, any>

要加入 root trace span 的 metadata。適合用來加入使用者 ID、session ID 或 feature flag 等自訂 attribute。

requestContextKeys?:

string[]

要擷取為此 trace metadata 的其他 RequestContext key。巢狀值支援點號標記法（例如 'user.id'）。

traceId?:

string

此執行所使用的 Trace ID（1 至 32 個十六進制字元）。如有提供，此 trace 會成為指定 trace 的一部分。

parentSpanId?:

string

此執行所使用的 parent span ID（1 至 16 個十六進制字元）。如有提供，root span 會建立為此 span 的 child。

tags?:

string[]

套用至此 trace 的 tag。這些字串標籤用於分類及篩選 trace。

outputOptions?:

OutputOptions

輸出設定的選項。

includeState?:

boolean

是否在結果中包括 Workflow run state。

includeResumeLabels?:

boolean

是否在結果中包括 resume label。

傳回值

result:

Promise<WorkflowResult<TState, TInput, TOutput, TSteps>>

一個 Promise，resolve 後會傳回包含步驟輸出及狀態的 Workflow 執行結果

traceId?:

string

啟用 Tracing 時與此執行相關聯的 trace ID。可用於關聯 log 及偵錯執行流程。

spanId?:

string

啟用 Tracing 時與此執行相關聯的 root span ID。可用於 span 層級的查找及關聯。

延伸使用範例

使用自訂 context 進行 time travel

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 步驟

// 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 },
})

使用初始 state 進行 time travel

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

使用巢狀 Workflow context 進行 time travel

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 snapshot，因此必須先設定 storage
• 重新執行 Workflow 時，Workflow 會從 storage 載入現有 snapshot（如有）
• 目標步驟之前的步驟結果會根據 snapshot 或所提供的 context 重建
• 系統會使用所提供或重建的輸入資料，從指定步驟開始執行
• Workflow 會從該處繼續執行直至完成
• 即使 Workflow 尚未執行過，只要為起始步驟提供自訂 context 或輸入資料，亦可使用 time travel。

相關內容

• Time Travel
• Workflows 概覽
• Workflow.createRun()
• Snapshots
• 暫停及恢復