migrate-ai-sdk-v6-to-v7

AI SDK 6 至 7 遷移指南

以 AI SDK 官方儲存庫中的 content/docs/08-migration-guides/23-migration-guide-7-0.mdx 作為權威參考來源（Source of truth）。本 Skill 為操作查核清單（Checklist）；當需要確切範例或行為不明確時，請查閱該完整指南。

遷移工作流程

1. 在編輯程式碼前，確保使用者已有乾淨的備份或已 Commit 的程式碼基準線。
2. 檢查 package.json 及 lockfile，確認已安裝的 ai、@ai-sdk/*、提供者 (provider)、UI、MCP 與遙測 (telemetry) 等套件。
3. 將 AI SDK 套件升級至最新版本；僅在專案有使用 OpenTelemetry span 時才新增 @ai-sdk/otel。
4. 更新執行階段 (runtime) 與模組假設：Node.js 版本必須 >=22，且 AI SDK 套件已改為僅支援 ESM（ESM-only）。請將 require() 匯入替換為 ESM 匯入，必要時新增 "type": "module" 或使用 .mjs 副檔名。
5. 搜尋下方列出的 v6 模式，僅遷移專案中實際存在的程式碼，隨後執行型別檢查 (typecheck) 與針對性測試。

優先採用保持既有行為的變更。當 v7 變更語意時，請評估應用程式需要的是新的「全步驟 (all-steps)」行為，還是原有的「僅最終步驟 (final-step-only)」行為。

核心 API 變更

• experimental_customProvider -> customProvider。
• experimental_generateImage -> generateImage；Experimental_GenerateImageResult -> GenerateImageResult。
• experimental_transcribe -> transcribe；Experimental_TranscriptionResult -> TranscriptionResult。
• experimental_generateSpeech -> generateSpeech；Experimental_SpeechResult -> SpeechResult。
• experimental_output 選項/結果 -> output 選項/結果。
• CallSettings -> LanguageModelCallOptions & Omit<RequestOptions, 'timeout'>；prepareCallSettings -> prepareLanguageModelCallOptions。
• stepCountIs -> isStepCount。

提示詞與步驟

• 針對 generateText、streamText、generateObject、streamObject 與 streamUI，將頂層的 system 重新命名為 instructions。
• 將 prompt 或 messages 中的 { role: 'system' } 訊息搬移至頂層的 instructions。僅在處理可信任且已持久化的訊息時才使用 allowSystemInMessages: true。
• 將 experimental_prepareStep 重新命名為 prepareStep。
• 在 prepareStep 中，將傳回的 system 重新命名為 instructions。
• 在 experimental_repairToolCall 中，使用 { instructions } 替代 { system }。
• 審查 prepareStep 行為：傳回的 instructions 與 messages 現在會延續 (carry forward) 至後續步驟。若程式碼原本依賴單一步驟獨立覆蓋的行為，請改由 initialInstructions、initialMessages 及 responseMessages 明確重構。

生命週期回呼

• experimental_onStart -> onStart。
• experimental_onStepStart -> onStepStart。
• onFinish -> onEnd。
• onStepFinish -> onStepEnd。
• 針對 embed、embedMany 與 rerank，experimental_onFinish -> onEnd。
• 回呼事件欄位改用 instructions 替代 system。

用量、遙測與 Include 選項

• usage.cachedInputTokens -> usage.inputTokenDetails.cacheReadTokens。
• usage.reasoningTokens -> usage.outputTokenDetails.reasoningTokens。
• OpenTelemetry 已移出 ai 主套件；請安裝 @ai-sdk/otel 並在應用程式啟動時呼叫 registerTelemetry(new OpenTelemetry(...))。
• 一旦註冊了整合介面，遙測預設為啟用狀態。請移除多餘的 isEnabled: true；若個別呼叫要停用，請使用 isEnabled: false。
• 將 experimental_telemetry.tracer 搬移至 OpenTelemetry 建構函式中。
• experimental_telemetry -> telemetry。
• 遙測整合回呼：onRerankFinish -> onRerankEnd、onEmbedFinish -> onEmbedEnd。同步更新使用相同事件名稱的 tracing-channel 訂閱者。
• experimental_include -> include。
• includeRawChunks -> include.rawChunks。
• 請求與回應主體 (Request/Response body) 預設已排除。若程式碼需要讀取 request.body 或 response.body，請透過 include.requestBody 啟用，針對 generateText 則使用 include.responseBody。

串流、訊息與工具

• StreamTextResult.fullStream -> stream。
• streamText 的 onChunk 現在會接收所有串流片段 (parts)，包含生命週期、邊界 (boundary)、完成 (finish)、中斷 (abort) 與錯誤 (error) 片段。在讀取 text/tool/raw 內容前，請先依 chunk.type 進行判斷防護。
• step.response.messages 不再自動累加先前步驟的訊息。請使用 result.responseMessages 取得完整的回應訊息歷史，或將 result.steps 展平 (flatten)。
• 工具執行回呼：experimental_onToolCallStart -> onToolExecutionStart、experimental_onToolCallFinish -> onToolExecutionEnd。
• 工具回呼的 experimental_context -> context。
• 拆分共享的執行階段資料與工具特定資料：使用頂層 runtimeContext 處理協同編排狀態，為每個工具宣告 contextSchema，並透過 toolsContext 傳遞工具特定的數值。
• 將 needsApproval 從 tool() / dynamicTool() 搬移至每次呼叫或 Agent 層級的 toolApproval 中。
• experimental_activeTools -> activeTools。
• ToolCallOptions -> ToolExecutionOptions。
• isToolOrDynamicToolUIPart -> isToolUIPart。

內容片段與推理

• 工具結果中的 { type: 'media' } 已移除；請改用 { type: 'file-data' }。
• 將 toModelOutput 的 image-*、file-*、file-id 及 image-file-id 變體遷移至標準格式 { type: 'file', mediaType, data: { type: 'data' | 'url' | 'reference', ... } }。
• 使用者訊息 { type: 'image', image, mediaType? } 已棄用 (deprecated)；請改用 { type: 'file', mediaType: 'image' | 'image/*', data }。
• 在完整匹配分支 (exhaustive switch)、算圖器 (renderer)、序列化器 (serializer) 與驗證器 (validator) 中，加入對新 reasoning-file 內容型別的支援。
• 採用頂層 reasoning 時，請移除 providerOptions 中重複的特定提供者推理設定，除非意圖讓特定提供者的設定優先套用。

多步驟結果結構

• result.usage 現在包含所有步驟；result.totalUsage 已棄用。若僅需最終步驟的用量，請使用 result.finalStep.usage。
• 頂層的 content、toolCalls、staticToolCalls、dynamicToolCalls、toolResults、staticToolResults、dynamicToolResults、files、sources 與 warnings 現在包含所有步驟。若要維持以往僅取得最終步驟的行為，請使用 finalStep。
• 頂層的 reasoning、reasoningText、request、response 與 providerMetadata 在取得最終步驟資料時已棄用。請使用 result.finalStep.*；若為 streamText，請 await result.finalStep。
• 同樣的結果結構規則亦套用至 onEnd 事件。

串流回應輔助函式

streamText 結果的輔助方法 (helper methods) 已棄用。請將結果方法替換為頂層的無狀態輔助函式：

• result.toUIMessageStream(...) -> toUIMessageStream({ stream: result.stream, ... })。
• result.toUIMessageStreamResponse(...) -> toUIMessageStream(...) 加 createUIMessageStreamResponse({ stream })。
• result.pipeUIMessageStreamToResponse(response, ...) -> toUIMessageStream(...) 加 pipeUIMessageStreamToResponse({ response, stream })。
• result.toTextStreamResponse() -> toTextStream({ stream: result.stream }) 加 createTextStreamResponse({ stream })。
• result.pipeTextStreamToResponse(response) -> toTextStream({ stream: result.stream }) 加 pipeTextStreamToResponse({ response, stream })。

特定套件檢查

• MCP：MCPTransportConfig.redirect 預設值現已改為 'error'。僅在確信 MCP 伺服器安全且依賴重新導向時，才設定 redirect: 'follow'。
• Vue：@ai-sdk/vue 的 Chat 類別已棄用。建議改用 useChat，包含在響應式 (reactive) 聊天輸入中使用 getter/ref 初始化。
• Anthropic 及 @ai-sdk/google-vertex/anthropic：providerMetadata.anthropic.cacheCreationInputTokens 已移除。請使用 usage.inputTokenDetails.cacheWriteTokens；原始 Anthropic 用量仍可於 finalStep.providerMetadata?.anthropic?.usage 存取。
• Google：將 GoogleGenerativeAI* 型別、類別與函式重新命名為 Google*，例如 createGoogleGenerativeAI -> createGoogle。google 入口點保持不變。

驗證

修改完成後，請先執行專案型別檢查 (typecheck)，再執行最小相關測試套件。若遷移影響到了串流、聊天 UI、工具執行、遙測或多步驟流程，也請進行冒煙測試 (smoke-test)。若仍有型別錯誤，請在自行摸索替代方案前，先至遷移指南中搜尋確切已移除或重命名的符號。