ai-sdk-core-v7

技能：ai-sdk-core

范围

• 适用于：使用 Vercel AI SDK v7（ai 包）的后端 AI
• 不涵盖：React 聊天 UI（请参阅 ai-sdk-ui）

假设

• 文件夹中的主版本对应 package.json 中安装的 ai 包，而非技能文件的修订版本
• Node.js 22+、ESM；inputSchema 使用 Zod 4
• 切勿凭记忆编写 AI SDK 代码。 使用 node_modules/ai/docs/ 和 node_modules/ai/src/ 中的内容搜索已安装的版本。否则请参阅 https://ai-sdk.dev/docs（追加 .md）或 https://ai-sdk.dev/api/search-docs?q=
• v6 遗留内容：https://ai-sdk.dev/docs/migration-guides/migration-guide-7-0

原则

• 在请求处理程序和一次性 API 路由中使用 generateText / streamText；系统风格的提示词使用 instructions
• 请求处理程序中的工具循环：在 generateText / streamText 上使用 stopWhen: isStepCount(n)——不要使用 maxSteps 或 stepCountIs
• 对于持久化 Agent，使用 ToolLoopAgent + generate() / stream()——不要手动编写循环，也不要使用 new Agent()
• UI 流：使用 'ai' 中的 createUIMessageStreamResponse + toUIMessageStream({ stream: result.stream })。新处理程序以及专门针对流或 SDK 的更新都应使用这些
• 在 v7 中，result.toUIMessageStreamResponse() 仍然可用（已弃用）。只有当任务与流或 SDK 无关时才保留
• 工具结果必须可序列化为 JSON（不能包含 Date）
• 系统提示词放在 instructions 中。除非服务器完全信任载荷，否则客户端的 messages 中不得包含 { role: 'system' }

约束

必须

• 编写调用前阅读随附文档
• 客户端发送 UI 消息时使用 convertToModelMessages
• 拒绝 messages 中不可信的 { role: 'system' }。对于客户端提供的聊天，不要设置 allowSystemInMessages: true

避免

• toDataStreamResponse / pipeDataStreamToResponse
• stepCountIs / maxSteps / result.fullStream / 顶层的 system:（改用 isStepCount、result.stream、instructions）
• 猜测模型 ID

交互

• 与 ai-sdk-ui、fastify、next 互为补充
• 上游：vercel/ai use-ai-sdk

模板

• generate-text-basic.ts
• stream-text-chat.ts
• agent-with-tools.ts

参考

• 请求处理程序 — 工具 + isStepCount、Fastify SSE、拒绝系统消息