migrate-ai-sdk-v6-to-v7

AI SDK 6 到 7 迁移指南

以 AI SDK 仓库中的 content/docs/08-migration-guides/23-migration-guide-7-0.mdx 作为权威来源。本技能是工作清单；如需确切示例或行为不明确时，请阅读该指南。

迁移工作流程

1. 确保用户在编辑前有干净的备份或已提交的基线。
2. 检查 package.json 和锁文件，以识别已安装的 ai、@ai-sdk/*、提供商、UI、MCP 和遥测包。
3. 将 AI SDK 包升级到最新版本，并且仅当项目使用 OpenTelemetry spans 时添加 @ai-sdk/otel。
4. 更新运行时和模块假设：Node.js 必须为 >=22，且 AI SDK 包仅支持 ESM。将 require() 导入替换为 ESM 导入，并在需要时添加 "type": "module" 或使用 .mjs。
5. 搜索下面的 v6 模式，仅迁移存在的代码，然后运行类型检查和针对性测试。

优先进行保持行为的更改。当 v7 改变语义时，决定应用程序是想要新的全步骤行为还是以前的仅最终步骤行为。

核心 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 现在会延续到后续步骤。如果代码依赖于仅一步的覆盖，请显式地从 initialInstructions、initialMessages 和 responseMessages 重建。

生命周期回调

• experimental_onStart -> onStart。
• experimental_onStepStart -> onStepStart。
• onFinish -> onEnd。
• onStepFinish -> onStepEnd。
• 对于 embed、embedMany 和 rerank，experimental_onFinish -> onEnd。
• 回调事件字段使用 instructions 而不是 system。

使用情况、遥测和包含选项

• 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。更新跟踪通道订阅者以匹配相同的事件类型名称。
• experimental_include -> include。
• includeRawChunks -> include.rawChunks。
• 请求和响应主体默认排除。如果代码读取 request.body 或 response.body，请使用 include.requestBody 选择加入，对于 generateText，使用 include.responseBody。

流式、消息和工具

• StreamTextResult.fullStream -> stream。
• streamText 的 onChunk 现在接收所有流部分，包括生命周期、边界、完成、中止和错误部分。在假设文本/工具/原始内容之前，请根据 chunk.type 进行判断。
• step.response.messages 不再跨先前步骤累积。使用 result.responseMessages 获取完整的响应消息历史，或展平 result.steps。
• 工具执行回调：experimental_onToolCallStart -> onToolExecutionStart，experimental_onToolCallFinish -> onToolExecutionEnd。
• 工具回调 experimental_context -> context。
• 将共享运行时数据与工具特定数据分开：使用顶层 runtimeContext 存储编排状态，为每个工具声明 contextSchema，并通过 toolsContext 传递每个工具的值。
• 将 needsApproval 从 tool() / dynamicTool() 移到每次调用或代理的 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? } 已弃用；使用 { type: 'file', mediaType: 'image' | 'image/*', data }。
• 在穷举开关、渲染器、序列化器和验证器中添加对新的 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，等待 result.finalStep。
• 将相同的结果形状规则应用于 onEnd 事件。

流响应辅助函数

streamText 结果辅助方法已弃用。将结果方法替换为顶层无状态辅助函数：

• 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，包括用于响应式聊天输入的 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 入口点不变。

验证

编辑后运行项目类型检查，然后运行最小的相关测试套件。如果迁移涉及流式、聊天 UI、工具执行、遥测和多步骤流程，也进行冒烟测试。如果仍然存在类型错误，请在迁移指南中搜索确切移除或重命名的符号，然后再发明解决方法。