ai-sdk

ai-sdk skill 概览

这个 ai-sdk skill 能帮你做什么

ai-sdk skill 是一份面向开发者的实用指南，适合使用 Vercel AI SDK 构建应用时参考。尤其当你需要基于当前版本、避免过时写法的帮助，而不是泛泛的 LLM 建议时，它会更有价值。它真正擅长的是：帮你选对 API 形态、核实现代语法、避开旧模式，在应用里接入 chat、streaming、tools、structured generation、embeddings 或 agents。

哪些人适合安装这个 ai-sdk skill

最适合的读者包括：

• 正在评估 ai-sdk for Full-Stack Development 的全栈开发者
• 需要把旧版 AI SDK 代码迁移到新 API 的团队
• 正在使用 generateText、streamText、tools、ToolLoopAgent 或 useChat 的开发者
• 想比较 OpenAI、Anthropic、Google 以及 gateway 接入方式差异的人
• 不想像普通“帮我写 AI 代码”提示那样走太多弯路的构建者

为什么这个 skill 比通用提示词更有用

它最重要的差异在于：这个 skill 会明确提醒你，模型对 AI SDK 的内部知识往往已经过时。它不会让你盲信“记忆”，而是把你引导到本地 package 文档、源码检查，以及 API 变更、gateway 用法、devtools、类型安全 agent 模式等针对性资料上。正因为这样，这个 ai-sdk skill 在安装决策和实际落地时，比普通提示式问答更可靠。

采用前最值得先确认的事

用户通常最先关心的是：

• 是否应该先只安装 ai
• 后续如何按需选择 provider package，而不是一开始装太多
• 哪些 API 最近发生了变化
• 网上找到的 useChat 示例现在是否还有效
• tool loop 和 streamed runs 该怎么排查
• 这个 SDK 更适合 server routes、React UI，还是两者都适合

如果这些正是你卡住的点，这页内容能帮你省下不少时间。

如何使用 ai-sdk skill

从最小化的 ai-sdk 安装路径开始

先走最小安装步骤：

pnpm add ai

仓库之所以这样建议，是有意为之：先只安装核心 ai package。不要一开始就加上 @ai-sdk/openai、@ai-sdk/react 或其他 provider/client package，除非你的实际场景已经明确需要它们。这样能减少错误预设，也能让实现过程更贴近当前文档。

如果你是要把这个 GitHub skill 本身接入到 agent workflow，请使用：

npx skills add vercel/ai --skill ai-sdk

先在本地核对文档，再去要代码

这个 skill 最关键的使用方式不是“凭记忆直接问”，而是：

1. 确认 node_modules/ai/docs/ 存在。
2. 搜索 node_modules/ai/docs/ 和 node_modules/ai/src/。
3. 只有在这之后，再回退到 ai-sdk.dev 或仓库中的参考资料。

这是这份 ai-sdk guide 里最重要的实操习惯，因为 AI SDK 的 API 变化很快，很多公开示例都已经落后。

先读这些文件

如果你想快速建立整体认知，建议按这个顺序看：

1. skills/use-ai-sdk/SKILL.md
2. skills/use-ai-sdk/references/common-errors.md
3. skills/use-ai-sdk/references/ai-gateway.md
4. skills/use-ai-sdk/references/devtools.md
5. skills/use-ai-sdk/references/type-safe-agents.md

为什么这个顺序更有效：

• SKILL.md 提供触发条件和整体工作流
• common-errors.md 能让你尽早避开 API 改名陷阱
• ai-gateway.md 有助于你更快跑通一个可用模型
• devtools.md 适合代码跑起来后继续提升调试效率
• type-safe-agents.md 则在 UI 和 agent 类型需要保持一致时尤其重要

写代码前先搞清当前 API 漂移

采用 AI SDK 时，一个常见障碍就是直接复制旧示例。参考资料里点出了几项会明显影响 ai-sdk usage 的变化：

• maxTokens → maxOutputTokens
• maxSteps → stopWhen: stepCountIs(n)
• tool parameters → inputSchema
• 一些旧的 object-generation 模式已经变了
• useChat 变化很大，复用前必须先核实

如果你第一次向这个 skill 提问时就带上当前 package 版本和遗留代码，得到的迁移建议会明显更准确。

需要尽快跑通时，优先考虑 AI Gateway

对很多团队来说，最快出第一个可用结果的路径，是先走 gateway-backed setup。这个 skill 里包含了 Vercel AI Gateway 的实用参考，模型可以像下面这样用字符串选择：

import { generateText } from 'ai';

const { text } = await generateText({
  model: 'anthropic/claude-sonnet-4.5',
  prompt: 'What is love?',
});

如果你的决策重点不是 provider SDK 的接线细节，而是先快速验证产品行为，这种方式会特别有帮助。

不过在硬编码任何 model ID 之前，先拉取当前模型列表。参考资料已经明确提醒：不要凭记忆相信模型名称。

向 ai-sdk skill 提供什么输入最有用

给这个 skill 足够的上下文，它才能帮你选对 package 组合和 API 模式。一个高质量请求通常会包含：

• 运行时：Next.js、Node.js、Vercel、edge/serverless 等
• 目标：chat UI、agent、RAG、structured extraction、tool calling
• 当前 package 版本
• 是否需要 streaming
• provider 偏好，或是否使用 gateway
• 前端需求，比如 React hooks 还是仅服务端使用
• 任何失败代码和准确报错文本

弱输入：

• "Help me use AI SDK"

强输入：

• "I have a Next.js app router project on AI SDK 6, need streaming chat with tool calling, want to start with gateway, and my old useChat code no longer works. Show the minimal server route and UI shape."

第二种问法能让这个 skill 更快定位到正确文档和当前 API 名称。

把模糊目标改写成更好的 ai-sdk prompt

一个好用的结构通常是：

• 应用上下文
• 期望的用户体验
• 当前实现状态
• 约束条件
• 期望输出格式

示例：

I'm building a customer-support assistant in Next.js. I need ai-sdk usage for streamed responses, one weather tool, and a React chat UI. Keep packages minimal, prefer gateway first, and explain any AI SDK 6 changes from older examples. Return the file list, install commands, and the smallest working path.

这比直接问“帮我做一个 agent”效果更好，因为它给了这个 skill 足够的结构信息，避免产出过于泛化的脚手架代码。

针对常见任务，选择合适的 ai-sdk workflow

不同任务，使用这个 skill 的方式也应不同：

• 首次安装：让它给出最小 package 集合和一个单次可运行请求
• 迁移旧代码：贴出旧代码，要求标出 API 改名和行为变化
• tool calling：明确询问 tool schema 形态和 stop conditions
• 前端 chat：直接要求当前版本的 useChat 用法
• 调试问题：询问如何用 DevTools 检查 runs，以及 traces 存在哪里

在这种按任务拆分的提问方式下，ai-sdk skill 比单纯浏览仓库更能体现价值。

代码能跑但行为不对时，尽早用 DevTools

如果代码已经能编译，但模型行为和预期不一致，那么 DevTools 参考资料非常值得看。它会记录 SDK 调用、步骤和 tool 交互，并写入：

.devtools/generations.json

这对以下问题尤其有帮助：

• 隐蔽的 tool-call loop
• 结构化输出格式错误
• prompt 和 tool 不匹配
• 难以理解的 streaming 行为
• agent run 过程中的 token 和 step 检查

从安装决策角度看，这一点很重要，因为它能显著降低初次接入后的调试成本。

涉及 UI 渲染时，优先采用类型安全的 agent 模式

如果你在做 agent 驱动的 UI，那么 type-safe agent 参考资料说明，这个 skill 不只是适合玩具示例。它展示了一种模式：agent 定义可以导出推断出来的 UIMessage 类型，从而让 useChat 的渲染更稳妥。

这一点尤其适用于 ai-sdk for Full-Stack Development，因为后端 agent 配置与前端消息渲染需要始终保持一致。

这些场景并不适合这个 skill

如果你的主要需求是以下内容，就不建议选这个 skill：

• 与 ai package 无关的 provider 专属 SDK 文档
• 不涉及实现落地的通用 prompt engineering 建议
• 以 Python 为主的 AI 应用指导
• 与框架无关的 LLM 理论

这个 skill 最适合的问题，是在 JavaScript/TypeScript 技术栈里实现或排查 AI SDK。

ai-sdk skill 常见问题

这个 ai-sdk skill 适合新手吗？

适合，但前提是你已经熟悉基础 JavaScript 或 TypeScript。它对新手友好的地方在于能收窄第一步，但默认你会编辑项目文件、安装 package，并能理解常见框架约定。

这个 ai-sdk skill 能替代读文档吗？

不能。它更适合作为一个“路由层”，告诉你该先看哪里、哪些现代模式值得信赖。它的核心价值是减少走错路，而不是取代源码文档。

在 ai-sdk install 前，最大的提醒是什么？

不要相信旧示例，也不要相信模型对 AI SDK 语法的“记忆”。仓库反复强调：先检查已安装文档和源码。这不是顺带一提的小心事项，而是正确完成 ai-sdk install 和后续实现的核心前提。

我应该一开始就把所有 provider package 都装上吗？

通常不应该。先从 ai 开始，再根据实际场景补充 provider 或 client package。这样能让依赖选择更有针对性，也能避免把过时假设带进你的初始化方案里。

这个 skill 主要是给 chat 应用用的吗？

不是。chat 只是最常见的场景之一，这个 skill 同样适用于 structured generation、tool calling、agents、embeddings、基于 gateway 的模型访问，以及 streamed server responses。

它和直接让 LLM 写 AI SDK 代码有什么区别？

通用提示很可能会“很自信地”生成已经过时的 API。这个 skill 更好的地方在于，它强制你采用一套核验式 workflow：本地文档、当前参考资料、已知迁移陷阱，以及有针对性的文件阅读。这样能提升可信度，也减少返工。

它对 React 和 useChat 有帮助吗？

有，但要带着警惕看：useChat 变化很大。对于旧代码片段要保持怀疑，在复制 UI 示例前，先借助这个 skill 核实当前版本的实际写法。

什么情况下不该使用这个 ai-sdk guide？

如果你的问题主要是厂商计费、模型评测策略，或非 JS 平台集成，那就可以跳过。只有当你的阻碍点是当前 AI SDK 的实现细节时，它才最有用。

如何把 ai-sdk skill 用得更好

提供带版本的信息，而不只是目标

想更快拿到有效结果，最简单的做法就是带上准确版本，尤其是 ai 以及相关 package 的版本。很多失败案例都来自只说“我要 AI SDK 代码”，却不说明自己是在用新版本还是在迁移旧代码。

先要最小可运行片段，再逐步加复杂度

比起“帮我搭一个完整 agent app”，更好的顺序是：

• “先给我最小 generateText 示例”
• “再加一个 tool”
• “然后把它改成 stream”
• “最后接上 useChat”

这种增量式 workflow 会让这份 ai-sdk guide 更有效，因为每一步都能先对照当前文档确认，再继续叠加复杂度。

报错信息要原样贴出

如果出现问题，请附上准确报错和相关代码片段。之所以有 common-errors.md 这份参考，就是因为很多问题都来自“差一点点就对了”的 API 名称。一个精确报错，通常就足以判断你到底是在看旧文档、导入了错误 package，还是用了过时选项。

明确说明你要 gateway 还是直连 provider

很多歧义只要提前说清这一点就会消失：

• "Use Vercel AI Gateway first"
• "Use direct OpenAI provider package"
• "Keep provider choice abstract for now"

这会直接影响安装命令、模型选择和示例结构。

把 runtime 和 framework 边界说清楚

想获得更强的 ai-sdk usage 帮助，建议明确说明：

• 仅服务端，还是客户端 + 服务端
• 是 Next.js App Router，还是其他框架
• edge 还是 Node runtime
• TypeScript 严格程度
• tools 调用的是内部 API 还是外部服务

这些细节都会改变“正确代码”应该长什么样。

常见失败模式要重点留意

最容易拉低结果质量的，通常是：

• 依赖过时的 useChat 示例
• 复制已废弃的选项名
• 硬编码旧的 model ID
• 过早安装过多 package
• 在没有定义 tools 和 stop conditions 的情况下就要求 agent 代码
• 只用 console logs 调试，而不是看 run traces

避开这些问题后，ai-sdk skill 的可靠性会高很多。

让这个 skill 比较两种实现路径

一个很有效的提升方式，是让它帮你做方案判断，而不只是写代码。例如：

Compare ai-sdk usage for (A) gateway-first quick setup and (B) direct provider setup in my Next.js app. Recommend one based on fast prototyping, future portability, and minimal package count.

这种问法给出的采用建议，通常会比“把文档展示给我”更有决策价值。

在第一次回答后，带着证据继续迭代

拿到第一轮输出后，想进一步提高质量，可以补充以下任意一种信息：

• 当前文件树
• 已安装 package 列表
• 准确的失败请求
• 捕获到的 .devtools/generations.json 片段
• 来自 node_modules/ai/docs/ 的本地文档片段

这种基于证据的迭代，是把 ai-sdk skill 从通用指导推进到可直接落地实现的最佳方式。