develop-ai-functions-example：Vercel AI SDK 的示例工厂

Vercel AI SDK 的 npm 周下载量已经跑到三百多万次了。支持 20 多个模型提供商，13 种核心函数，从 generateText 到 rerank、从 transcribe 到 ToolLoopAgent。但如果你是那个负责维护这些示例代码的人，场面就没那么好看了。

每接入一个新 provider，你要给 10 多个函数写示例。每加一个新 feature，你至少要覆盖一个 provider。还得保证命名一致、结构统一、工具函数复用。不出三个月，examples 目录就能长成谁都不敢碰的野草。

develop-ai-functions-example 这个 Skill，本质上是 Vercel 把”写 AI SDK 示例”这件事工程化了。它规定了四件事：

• 文件怎么命名
• 模板怎么套
• 工具怎么复用
• 什么时候该写新示例

不是教你写代码，是教你不要每次从头写。

说白了，这篇文章想讲清楚一件事：一个仓库大到一定程度之后，”怎么写示例”本身变成了一个需要 Skill 来管理的问题。Vercel 怎么解决的，哪些设计值得抄，哪些地方还有改进空间，咱们拆开看看。

环境准备

这个 Skill 不在 npm 上，它是 Vercel AI SDK 仓库 vercel/ai 里的一个子模块。安装方式就是直接通过 Smithery 或 npx skills add 把它挂到你的编码 Agent 里。

npx skills add https://github.com/vercel/ai --skill develop-ai-functions-example

前置条件很轻：Node.js 22 以上，pnpm（Vercel AI SDK 仓库用 pnpm 管理 monorepo），然后 clone 仓库。不需要额外的账号注册或 API Key 配置，示例脚本跑起来需要的是各个模型 provider 的 Key，那是你自己的事。

跑通第一关只需要一条命令：进到 examples/ai-functions 目录，用 pnpm tsx 跑一个最简单的示例。

pnpm tsx src/generate-text/openai.ts

如果环境变量里配了 OPENAI_API_KEY，终端会打印出模型回复的文本和 token 用量。没配 Key 的话会报错，但这至少验证了 Skill 本身、模板路径、工具链都是通的。不少人卡在这一步就是因为没意识到 .env 文件必须手动创建，Skill 只会加载它，不会帮你生成。

示例编写流程

这个 Skill 的核心价值不在”教你怎么调用 generateText”，AI SDK 的官方文档已经写得很清楚了。它的价值在于定义了一套写示例的标准操作流程。

打开 examples/ai-functions/src 目录，你会看到按 AI SDK 函数分类的子目录：

• generate-text/：非流式文本生成
• stream-text/：流式文本生成
• generate-object/：结构化输出
• agent/：智能体工作流
• embed/ 和 embed-many/：嵌入向量
• transcribe/：音频转录
• rerank/：文档重排序

剩下的几个分类同样重要：

• generate-image/：图像生成
• generate-speech/：文本转语音
• stream-object/：流式结构化输出
• middleware/：自定义中间件
• telemetry/：OpenTelemetry 集成
• complex/：多组件组合示例

一共 13 个分类。每个子目录里是按 {provider}-{feature}.ts 命名的示例文件。

命名规范本身就是一条隐形的质量门槛。openai.ts 是基础用法，openai-tool-call.ts 是特定功能，amazon-bedrock-anthropic.ts 是带子 provider 的，google-vertex-anthropic-cache-control.ts 是子 provider 加特定功能。一眼就能看出这个文件在测什么 provider 的什么能力，不用打开看。

每个示例统一用 run() 包装函数启动，这个函数来自 lib/run.ts，自动加载 .env 并处理错误日志。你不需要在每个示例里重复写 try-catch 和环境变量加载，省掉了大量样板代码。

写完示例后，一条 pnpm tsx 命令就能跑起来。如果你在开发一个新的 provider 集成，通常需要在 generateText、streamText 和 generateObject 上各写一个基础示例，确保这三个最核心的 API 都能正常工作。如果是修 bug，一个能复现问题的最小示例就够了。

实际在维护大型 monorepo 的人会立刻理解这套流程的价值。示例不是一次性的，是会持续演进的。某天有人改了 AI SDK 的工具调用接口，所有用到 tool 的示例都可能需要更新。没有统一的命名规范和模板结构，这个更新成本是 O(n) 的散点排查，有了之后变成按文件名就能定位到需要改的文件。

关键设计

从设计角度看，这个 Skill 最聪明的一个决策，是把”写示例”从”写代码”降维成”套模板”。

它提供了四套核心模板：

• 基本文本生成（generateText）
• 流式文本生成（streamText）
• 工具调用（generateText + tool()）
• 结构化输出（generateObject + Zod schema）

每套模板的结构几乎固定，一个标准流程是这样：

• 导入 provider SDK 和 AI SDK 核心函数
• 用 run() 包裹异步逻辑
• 调用目标函数
• 打印结果

你只需要替换 provider 名称、模型 ID、prompt 和 schema。

另一个值得一提的设计是 tools/ 目录。它把 weatherTool 这类常用工具定义抽出来复用，而不是让每个示例文件里重复定义同一个工具。tools 目录和 lib/ 目录的共享工具函数（print.ts、print-full-stream.ts、save-raw-chunks.ts）一起，构成了一个微型但完整的”示例基础设施层”。

不过也有可以改进的地方。目前的模板只覆盖了四个最常用的函数，agent、embed、generateImage 这些类别的示例更多的是”靠约定”而非”靠模板”。如果后续能把这些也模板化，整个 examples 目录的一致性会更上一层楼。另一个小遗憾是缺少示例质量的自动化检查，比如模板版本与 AI SDK 版本的对齐校验。

使用场景

最典型的场景是接入新 provider。你刚写完 @ai-sdk/newprovider 这个包，想在 PR 里证明它能正常工作。按 Skill 的指引，你需要在 generateText、streamText、generateObject 三个核心函数上各写一个示例，放到对应子目录，按 {provider}.ts 命名。三步走完，审阅者一眼就能确认你的集成是可工作的。

第二个高频场景是新增功能演示。AI SDK 版本迭代很快，v4 到 v5 到 v6，每次大版本都有新的 API 加入。每加一个新功能，你需要一个能展示典型用法的示例，让其他开发者一眼看懂”这个 API 是这么用的”。Skill 里为 generateObject、streamObject 这类”新功能”都预留了对应的示例目录和模板。

第三个场景相对冷门但价值很高：生成测试 fixture。Skill 文档里提到的 save-raw-chunks.ts 工具可以让你把一次真实的 API 调用结果保存下来，作为后续单元测试的 mock 数据。在 provider 集成测试里，这个功能能省掉大量手写 mock 的工作，尤其是流式响应的 mock，手写起来极其繁琐。

局限性也很明显。这个 Skill 是强绑定 Vercel AI SDK 仓库结构的，它假定你的项目目录是 examples/ai-functions/src/。如果你在维护自己的 AI SDK（比如某个 provider 的独立 SDK），需要手动适配目录结构和模板路径。它不是开箱即用的通用方案，更像是一份”最佳实践参考指南”。

洞察与反思

说实话，看完这个 Skill 的 SKILL.md 之后，最让人意外的是它定义问题的方式。多数人想到”写代码示例”，第一反应是”写清楚就行”。但 Vercel 把问题定义成了”如何让示例代码在 20 多个 provider 乘以 13 种函数的矩阵下保持一致性”。问题定义对了，解决方案自然就有了：模板化、命名约定、工具复用。

这映射了一个更底层的规律。工具链工程化的本质不是做更多事，是把重复的事标准化。GitHub 的 CODEOWNERS、ESLint 的 shareable config、Terraform 的 module registry，都是一个逻辑。develop-ai-functions-example 把这个逻辑用到了 AI SDK 的示例管理上，而且做得相当务实。

不过它有一个潜在的隐患。模板越完善、越容易上手，写示例的人就越可能不过脑子直接套。如果某天 AI SDK 的 API 改了，但模板还没来得及更新，所有基于旧模板生成的示例都会产生一致性的错误。一致性在好的时候是效率加速器，在坏的时候是错误放大器。

换个角度来看，这个 Skill 本身也是 Vercel AI SDK 生态成熟度的一个信号。一个 SDK 能专门抽出一个 Skill 来管理示例编写流程，说明它的函数数量和 provider 数量已经到了”手动管理不可能”的拐点。回头看三年前的 OpenAI Node SDK，examples 目录里就十来个文件，根本不需要这么一套东西。复杂度催生了工程化，工程化反过来又撑起了更大的规模。

总结

回过头来看，develop-ai-functions-example 这个 Skill 解决的不是”怎么写 AI SDK 代码”的问题，是”怎么在 20 多个 provider 乘以 13 种函数的矩阵下，让 5 个开发者写出来的 200 个示例看起来像同一个人写的”。

它的核心手段就三个：模板降低写示例的认知成本，命名约定让文件名本身成为索引，工具复用省掉样板代码。这三样东西单独拿出来都不新鲜，但组合在一起，在 Vercel AI SDK 这个体量的项目里，价值就体现出来了。

如果你在维护一个 API 数量持续膨胀的 SDK，或者一个 provider 数量不断增长的集成项目，花半天时间写一套类似的”示例模板加命名规范加工具复用”方案，半年后你会感谢现在的自己。如果你只是想参考现成的方案，把 develop-ai-functions-example 的 SKILL.md 从头到尾读一遍就够了。它本身就是最好的设计文档。