add-provider-package

add-provider-package 技能概览

add-provider-package 是一份聚焦实现层面的指南，用来在 vercel/ai 中创建新的 @ai-sdk/<provider> 包。它最适合维护者、贡献者，以及希望把某个模型提供商接入 AI SDK 的 API 平台团队，帮助你按正确的包形态、适配器分层方式和仓库约定来落地实现。

add-provider-package 真正帮你解决什么问题

它要完成的并不只是“写一点 wrapper 代码”。add-provider-package 的核心价值，是帮助你新增一个真正符合 AI SDK 内部架构的 provider package：导出符合预期的 provider 能力面，遵循仓库既有的 package 布局、测试策略和实现模式。

什么人适合用 add-provider-package

如果你属于以下情况，建议使用 add-provider-package：

• 想在 vercel/ai monorepo 中新增一个模型提供商
• 想参考官方一方包的做法，构建第三方 provider package
• 正在把外部 API 映射到 AI SDK 的抽象层，比如 language models 或 embeddings
• 不满足于泛泛的“build an adapter”建议，想要一条可执行的具体路径

尤其适合这样一种场景：你已经理解目标 provider 的 HTTP API，但还不知道怎么把它翻译成 AI SDK 里的 package 约定。

最匹配的使用场景

在以下任务里，add-provider-package skill 的效果最好：

• 创建符合预期结构的 packages/<provider> 目录
• 按 @ai-sdk/provider 接口实现 provider 类
• 复用已有 provider 的成熟模式，而不是自己重新发明一套
• 在投入实现前，先搞清楚 first-party 和 third-party 的要求差异

相比通用编码提示，它的关键差异是什么

普通提示词也许能帮你草拟 adapter 代码，但当你需要“理解仓库上下文”的指导时，add-provider-package 更有价值：比如包应该放在哪里、provider 架构如何分层、通常有哪些文件、以及在这个代码库里一个完整 provider package 应该长什么样。

采用前最重要的限制条件

这个技能的定位本来就很窄。它专门用于创建 @ai-sdk/<provider> 包，不适用于通用 API SDK 设计、无关的 wrapper，或任意插件系统。如果你的目标不在 AI SDK 的 provider 架构范围内，它会显得过于具体，甚至不太适配。

如何使用 add-provider-package 技能

add-provider-package 的安装上下文

这个技能位于 vercel/ai 仓库中的 skills/add-provider-package。在支持 Skills 的工作流里，可以通过下面的命令安装：

npx skills add vercel/ai --skill add-provider-package

如果你的环境已经会自动暴露仓库内的 skills，那么你可能只需要按名称调用这个技能即可。

先看最关键的那个文件

优先阅读 skills/add-provider-package/SKILL.md。从当前仓库快照看，这个技能的主要指导信息都集中在这里，包括：

• first-party 与 third-party package 的要求差异
• provider 的分层架构
• package 结构
• 分步骤实现指导
• 一个完整示例的参考 PR

由于这里没有额外展示出 resources/、rules/ 或辅助脚本，所以真正有用的信息，主要就在 SKILL.md，以及 monorepo 中其他现有 provider package 的实现里。

使用 add-provider-package 时你需要提供什么输入

想让技能给出真正可用的结果，就不要只说“给 X 加支持”，而要提供具体的 provider 信息。最低限度的有效输入包括：

• provider 名称和目标包名，例如 @ai-sdk/acme
• API 鉴权方式
• 支持的模型类型：chat、completion、embeddings、image 等
• 流式返回行为
• 请求与响应 schema
• 错误格式以及 rate limit 行为
• 任何 provider 特有的细节，比如 tool calling 或 JSON mode 的差异

如果没有这些信息，技能可以帮你搭结构，但无法可靠地把 adapter 真正做对。

如何把一个模糊目标改写成高质量提示

较弱的提示：

Use add-provider-package to add Acme AI to the SDK.

更强的提示：

Use add-provider-package to scaffold a new packages/acme provider for vercel/ai. Acme uses API key auth via Authorization: Bearer <key>. It supports text generation and embeddings, with SSE streaming for text. I need the package structure, main source files, likely exports, and the mapping from Acme endpoints to AI SDK model interfaces. Show the repo files I should create first and call out any ambiguous areas I must resolve from the API docs.

之所以后者更有效，是因为它给了技能足够的信息去判断应该实现哪些 provider surface，同时也能更早暴露尚未明确的集成风险。

推荐的 add-provider-package 使用流程

一个实用的 add-provider-package usage 流程通常是：

1. 先确认你做的是 first-party 还是 third-party package。
2. 阅读 SKILL.md，了解架构和预期的 package 布局。
3. 查看技能里链接的参考 PR：https://github.com/vercel/ai/pull/8136/files。
4. 对照 packages/ 中一到两个现有 provider package。
5. 在生成文件之前，先让技能把你的 provider API 映射到 AI SDK 接口。
6. 然后再让它给出 package skeleton、实现计划和测试清单。

这样做可以明显减少返工，因为很多接口不匹配的问题会在代码生成之前就暴露出来。

读完 SKILL.md 后，接下来该看哪些仓库路径

如果你要做的是实际实现决策，通常最值得继续读的是：

• skills/add-provider-package/SKILL.md
• 技能中链接的参考 PR
• monorepo 中现有 packages/<provider>/src/* 的实现
• @ai-sdk/provider 里的共享接口
• @ai-sdk/provider-utils 里的辅助模式

这个技能明确讲了分层架构，所以去读这些位置，本质上就是在用仓库当前的真实模式校验生成结果。

add-provider-package 擅长覆盖哪些内容

add-provider-package guide 最擅长帮助你处理：

• package 脚手架搭建
• 在 AI SDK 内部架构中的适配位置
• 判断哪些 provider 接口是关键的
• 理解如何把 provider 建模成 adapter，而不是做成一个定制 client
• 把已有 provider 的接入案例当成参考实现

哪些事情它不会替你决定

这个技能并不能替代你阅读上游 provider API 文档。下面这些决策，仍然需要你自己做：

• 哪些能力值得做成一等支持
• provider 特有的请求选项该怎么处理
• 具体暴露哪些模型
• 如何翻译非标准错误和流式 payload
• 不支持的能力应该直接省略，还是通过 provider-specific options 暴露出来

面向 API 开发时，add-provider-package 的实用提问方式

如果你是在用 add-provider-package for API Development，建议按“决策顺序”来要结果：

1. capability mapping
2. package/file plan
3. type/interface plan
4. request/response transformation plan
5. tests and edge cases

示例：

Use add-provider-package to plan an @ai-sdk/zen package. First, map Zen's endpoints to AI SDK interfaces. Second, propose the package file tree. Third, list the core transforms for text generation, embeddings, and streaming. Finally, list the top 10 edge cases to test.

相比一开始就要求输出整包代码，这种方式更容易得到可以真正落地的结果。

编码前最常见的卡点

最大的阻碍通常不是语法错误，而是产品与设计层面的决策还没做清楚：

• 这到底是 first-party 还是 third-party？
• 这个 provider API 是否真的能自然映射到 AI SDK 抽象？
• 流式事件是否足够稳定，适合做适配？
• 哪些模型能力已经成熟到可以公开暴露？
• 是否存在一个形态更接近、值得直接参考的现有 provider？

建议尽早使用这个技能，把这些问题在真正写 package 之前就挖出来。

add-provider-package 技能 FAQ

add-provider-package 只适合 Vercel 维护者吗？

不是。这个技能对外部贡献者和第三方包作者同样有用。原始说明里明确区分了第三方 package 与 first-party @ai-sdk/<provider> package，并提到如果要做 first-party 增加，应该先沟通讨论。

add-provider-package 适合新手吗？

如果你已经了解目标 provider 的 API，那么新手也可以使用它；但它并不是一份面向新手的 TypeScript、package 发布或 SDK 设计教程。它的最大价值，在于为需要仓库特定指导和架构匹配的人提供帮助。

它和直接让 LLM 写一个 provider wrapper 有什么不同？

普通提示可能会生成“看起来合理”的代码，但不一定符合 AI SDK 的 package 结构或接口约定。add-provider-package skill 的价值在于，它会把工作锚定到 monorepo 的 adapter 架构上，并引导你参考一个具体、可核对的实现样例。

我可以在 vercel/ai 仓库之外使用 add-provider-package 吗？

可以，把它当作一种模式参考即可。不过你的项目越接近 AI SDK 的 provider 抽象和 package 布局，输出就越容易迁移。如果你的代码库使用的是不同接口或发布约定，那就要预留额外的适配工作。

什么情况下不该用 add-provider-package？

如果你属于以下情况，就不建议使用：

• 正在构建通用型 API client
• 想在 AI SDK 体系之外接入某个 provider
• 你要找的是前端应用示例，而不是 provider package 代码
• 不打算检查现有 provider 实现，做对齐和比照

add-provider-package 会包含完整的端到端示例吗？

它提供了一个完整 provider 接入 PR 的参考入口：https://github.com/vercel/ai/pull/8136/files。这是这个技能最有价值的部分之一，因为它让你能在真实上下文里看到“一个完成的新增 provider”究竟是什么样子。

如何提升 add-provider-package 技能的使用效果

给 add-provider-package 提供能力级输入

想最快提升输出质量，最有效的方法就是把 provider 能力描述得更精确。不要只说“supports chat”，而要提供：

• endpoint 名称
• 流式协议
• tool calling 支持情况
• structured output 行为
• embeddings 的维度或请求格式
• auth 和 headers
• retry 或 rate limit 的特殊点

这样技能才能基于接口适配来推理，而不是根据营销话术去猜。

在生成代码前，先让它做差距分析

一个很强的起手式是：

Use add-provider-package to identify the gaps between this provider API and AI SDK expectations before proposing code.

很多时候，这比一上来就让它搭脚手架更有效，因为它能先暴露缺失能力、不兼容的流式格式，或那些必须通过 provider-specific options 处理的地方。

明确指出可参考的相似 provider

如果你知道 vercel/ai 里有某个 provider 的 API 形态跟目标很像，直接说明。例如：

Use add-provider-package and model this after the provider package that has the closest SSE text streaming and embeddings support.

这样可以提升一致性，也能减少凭空创造抽象的情况。

按文件逐步输出，不要一次生成一大坨

当你这样拆着要结果时，技能更容易被验证和审查：

• package tree
• src/index.ts exports
• provider factory
• model implementation files
• tests
• package metadata

相比一次性生成整个 package，这种方式更利于评审，也更可靠。

使用 add-provider-package 时要重点警惕的常见失败模式

在审查输出时，重点检查这些问题：

• 把尚未稳定支持的能力当成已支持能力直接暴露
• 对 streaming 的映射过于乐观
• provider-specific options 泄漏进通用接口
• 缺少错误归一化处理
• package 结构不符合现有仓库约定
• 代码忽略了 first-party 与 third-party 在流程上的差异

用真实 API 样例来强化提示

如果第一轮输出太抽象，就补充 provider 文档里的真实请求与响应样例。这往往是提升效果最明显的做法之一，因为 provider package 的成败，很大程度上取决于转换逻辑是否准确。

一个好的追问示例：

Here are the exact JSON request and SSE response shapes for text generation. Revise the add-provider-package plan so the model implementation and streaming parser match these payloads.

明确要求它把未决问题拆开说清楚

第一轮结果出来后，可以要求技能把内容拆分为：

• confident implementation steps
• assumptions
• open questions requiring provider docs
• likely tests

这种结构会让结果更可执行，也能减少隐藏的猜测成分。

验证 add-provider-package 输出的最佳方式

把输出当成一份“理解仓库上下文的实现计划”，然后按下面这些来源逐一校验：

• SKILL.md
• 链接的参考 PR
• 一到两个现有 provider package
• @ai-sdk/provider 接口
• 目标 provider 的官方 API 文档

这个校验闭环，是把 add-provider-package usage 从“有帮助的草稿”提升到“真正可合并或可发布的 package”的最佳方式。