AI SDK 预发布周期Pre-Release Cycle完整指南从创建维护分支到发布下一个大版本【免费下载链接】aiThe AI Toolkit for TypeScript. From the creators of Next.js, the AI SDK is a free open-source library for building AI-powered applications and agents项目地址: https://gitcode.com/GitHub_Trending/ai/ai导读本指南基于 contributing/pre-release-cycle.md 展开完整讲解 AI SDKThe AI Toolkit for TypeScript如何围绕大版本升级Major Release组织一次预发布beta周期从创建维护分支、进入 changeset 预发布模式、为新版 Provider 规范播种 v4 规格目录到适配器与 mock 测试工具、文档站版本化部署再到周期内的日常开发约定与收尾发布。读完本文你将掌握在main分支上并行开发下一个大版本、同时为当前稳定版持续回传补丁的完整工程流程并能对照仓库源码理解每个步骤背后的真实实现。一、为什么需要预发布周期AI SDK 的每一个大版本发布都会引入一个新的Provider 规范版本provider specification version例如 V3 到 V4。演进规范正是大版本发布存在的理由它允许对 Provider 接口做出破坏性变更同时为 Provider 作者提供清晰的迁移目标。在仓库的 packages/provider/src/ 中这一点体现得极为直观以语言模型为例packages/provider/src/language-model/ 下并排存在着v2、v3、v4三个版本目录每个目录内的类型都通过specificationVersion字面量标明版本例如 embedding-model-v3.ts 中readonly specificationVersion: v3而 embedding-model-v4.ts 中则是v4。预发布周期解决的核心问题是双轨并行main分支发布 beta 版本例如ai7.0.0-beta.1一个维护分支例如release-v6.0接收回传backport的补丁并发布稳定版本。这样既能让破坏性变更在main上持续推进又不阻塞当前稳定版用户的紧急修复。二、启动一个预发布周期1. 创建维护分支从当前mainHEAD 创建一个分支让当前稳定版本可以继续接收补丁git checkout main git pull origin main git checkout -b release-vcurrent-major.0 # e.g. release-v6.0 git push origin release-vcurrent-major.0仓库中的发布工作流 已经配置在release-v*分支上运行branches: [main, release-v*]因此无需修改任何工作流文件维护分支上的合并会自动触发稳定版发布。2. 在维护分支上设置 npm dist-tag在新建的维护分支上更新根目录package.json中的ci:release脚本使其以版本专属的 npm dist-tag 发布。这一步防止维护版本抢占 npm 上的latest标签- ci:release: turbo clean turbo build changeset publish, ci:release: turbo clean turbo build changeset publish --tag ai-vcurrent-major,例如对于release-v6.0分支使用--tag ai-v6。直接将该改动提交并推送到维护分支。仓库现状佐证当前根 package.json 中的脚本为ci:release: turbo clean npm run build:packages changeset publish并没有--tag后缀——这正是维护分支上追加版本专属 tag需要改动的行同时ci:version脚本changeset version node .github/scripts/cleanup-examples-changesets.mjs pnpm install --no-frozen-lockfile会在版本 PR 合并时统一执行版本号提升与依赖重装。3. 在main上进入预发布模式切回main进入 changeset 的预发布模式git checkout main pnpm changeset pre enter beta该命令会修改.changeset/pre.json。其中initialVersions字段应当只包含来自packages/*/package.json的包需要移除其他任何条目例如example/*、tools/*或嵌套的测试包。提交并推送该改动或开一个 PR。4. 创建一个大版本 changeset创建一个将每个已发布包提升到下一个大版本的 changesetpnpm changeset选择packages/*/package.json中的所有包跳过example/*、tools/*以及任何不在packages/下的条目——它们是私有的、不会被发布并为每个包选择major。写一个类似这样的摘要Start v7 pre-release提交生成的.changeset/*.md文件。5. 播种新的规范版本spec version每个大版本都会引入一个新的 Provider 规范版本例如 V3 → V4。必须为packages/provider/src/下每一个包含版本化子目录的规范目录创建新版本目录。可以用下面的命令找到它们ls -d packages/provider/src/*/v3截至本文写作时这些目录为embedding-model、embedding-model-middleware、image-model、image-model-middleware、language-model、language-model-middleware、provider、reranking-model、shared、speech-model、transcription-model、video-model。仓库现状佐证在当前仓库执行上述命令实际返回了 12 个v3目录与文档列出的清单完全一致packages/provider/src/embedding-model/v3、packages/provider/src/language-model/v3、packages/provider/src/provider/v3、packages/provider/src/shared/v3等。同时language-model目录下已存在v4印证了 V3→V4 迁移在仓库中已经落地。对于每个目录将当前规范目录例如v3/复制为新的版本目录例如v4/。将所有文件从旧版本重命名为新版本例如language-model-v3.ts→language-model-v4.ts。在每个文件内部将所有旧版本字样替换为新版本例如类型名、import 路径中的V3→V4、v3→v4以及specificationVersion字面量。在父级index.ts中于 v3 导出之前添加export * from ./v4/index;。更新交叉引用如果providerv4 规范导入了其他模型类型确保它从新的 v4 路径导入而不是 v3。通过在packages/provider中运行pnpm build验证——所有新类型都应出现在构建出的.d.ts输出中。6. 创建 mock 测试工具为packages/ai/src/test/中的每一个 mock 文件创建 V4 对应版本例如mock-language-model-v3.ts→mock-language-model-v4.ts。更新packages/ai/test/index.ts以导出新的 V4 mocks。仓库现状佐证在 packages/ai/src/test/ 中可以看到完整的 V2/V3/V4 mock 矩阵例如mock-language-model-v2.ts、mock-language-model-v3.ts、mock-language-model-v4.ts以及mock-provider-v2.ts、mock-provider-v3.ts、mock-provider-v4.ts等说明 V3→V4 迁移中三版本并存、测试各自覆盖的模式在仓库中已经真实落地。7. 更新packages/ai以支持新规范版本核心的packages/ai包需要适配函数、更新的公共 API 以及测试更新来在旧版本之外同时支持新的规范版本。适配函数Adapter Functions在packages/ai/src/model/中为每种模型类型创建 V4 适配文件。这些适配器使用Proxy通过覆盖specificationVersion将 V3 模型转换为 V4as-language-model-v4.tsas-embedding-model-v4.tsas-image-model-v4.tsas-speech-model-v4.tsas-transcription-model-v4.tsas-reranking-model-v4.tsas-video-model-v4.tsas-provider-v4.ts通过包装所有模型工厂方法将 V3 Provider 转换为 V4每个适配器都会检查specificationVersion如果已经是 V4 则原样返回模型否则将其包装在Proxy中。以 as-language-model-v4.ts 为例源码清晰地展示了这一模式export function asLanguageModelV4( model: LanguageModelV2 | LanguageModelV3 | LanguageModelV4, ): LanguageModelV4 { if (model.specificationVersion v4) { return model; } // first convert v2 to v3, then proxy v3 as v4: const v3Model model.specificationVersion v2 ? asLanguageModelV3(model) : model; return new Proxy(v3Model, { get(target, prop: keyof LanguageModelV3) { if (prop specificationVersion) return v4; return target[prop]; }, }) as unknown as LanguageModelV4; }可以看到V4 直接透传identityV2 先经asLanguageModelV3升到 V3再通过 Proxy 伪装为 V4Proxy 的get拦截器只在读取specificationVersion时返回v4其余属性与方法一律透传因此模型行为完全保留。而 as-provider-v4.ts 展示了 Provider 级别的转换先确保得到 V3 Provider必要时调用asProviderV3再返回一个全新的对象其中specificationVersion: v4并且每个模型工厂方法languageModel、embeddingModel、imageModel、transcriptionModel、speechModel、rerankingModel都通过对应的 V4 适配器包装对于 Provider 未提供的可选模型类型如transcriptionModel、speechModel、rerankingModel会保留undefined语义。每个适配器还应有对应的测试文件例如as-language-model-v4.test.ts验证以下行为V4 输入原样返回用.toBe()做身份校验V3 输入被代理且specificationVersion变为v4V2 输入如适用先转为 V3 再转为 V4属性和方法在通过 Proxy 后保持完好。公共 API 更新更新以下文件使其公共边界接受V2 | V3 | V4模型并在内部用适配器转换为 V4packages/ai/src/middleware/wrap-language-model.ts —— 接受LanguageModelV2 | V3 | V4packages/ai/src/middleware/wrap-image-model.ts—— 接受ImageModelV2 | V3 | V4packages/ai/src/middleware/wrap-embedding-model.ts—— 接受EmbeddingModelV3 | V4V2 是通用类型、不包含保留 V3 以向后兼容packages/ai/src/registry/custom-provider.ts—— 所有模型 map 中接受 V2/V3/V4 模型packages/ai/src/registry/provider-registry.ts—— 接受ProviderV2 | V3 | V4用asProviderV4转换packages/ai/src/types/language-model-middleware.ts—— 放宽为同时接受 V3 和 V4 中间件从 wrap-language-model.ts 的源码可以看到这一演进的落地形态其wrapLanguageModel的入参类型为LanguageModelV2 | LanguageModelV3 | LanguageModelV4函数体第一行即调用asLanguageModelV4(inputModel)统一转成 V4随后所有内部逻辑LanguageModelV4CallOptions、LanguageModelV4GenerateResult、LanguageModelV4StreamResult都基于 V4 类型展开返回的包装对象也显式声明specificationVersion: v4。测试更新为每个 V4 适配器创建测试文件例如as-language-model-v4.test.ts验证身份透传、V3→V4 转换和 V2→V4 转换。更新resolve-model.test.ts用独立的测试块分别测试 V3→V4 转换使用 V3 mocks和 V4 透传使用 V4 mocks。更新其他测试文件在代码现在返回 V4 模型的地方改用 V4 mocks例如custom-provider.test.ts、provider-registry.test.ts、中间件测试。任何对返回模型做引用相等性.toBe()校验的测试都应使用 V4 mocks。在packages/ai中运行pnpm test并在工作区根目录运行pnpm type-check:full对应根 package.json 中的tsc --build tsconfig.with-examples.json来验证。8. 配置文档站点ai-sdk.dev文档站点托管在ai-studio仓库中通过一个指向本仓库的 Git submodule 引用本仓库。在预发布周期内站点需要同时为稳定版和 beta 版文档提供版本化分支与 Vercel 部署。在vercel/ai仓库中更新.github/workflows/update-sdk-submodule-v6.yml使其跟踪release-v6.0分支而非main。创建.github/workflows/update-sdk-submodule-v7.yml—— 该工作流拉取main、在ai-studio中检出sdk/v7分支并推送到origin sdk/v7。在ai-studio仓库中创建sdk/v7分支默认分支暂时保持sdk/v6这样生产站点继续提供稳定版文档。在 Vercel 中创建一个连接到sdk/v7分支的 v7 预览部署例如v7.ai-sdk.dev。9. 合并到main打开一个包含第 3-7 步全部改动的 PR。合并后第一个 beta 版本例如ai7.0.0-beta.1将自动发布。三、预发布周期内的日常开发日常开发约定所有功能 PR 继续指向main。每个 PR 仍然需要 changeset默认使用patch。当Version PackagesPR 被合并时beta 版本自动发布。新增一个包在main处于预发布模式时引入新包将其package.json中的初始version设为纯0.0.0——绝不要设成0.0.0-canary.0或任何-tag.N后缀。预发布后缀会使版本成为 premajor而 semver 会把对 premajor 的major/minor/patch提升视为仅仅去掉后缀于是包会卡在0.0.0-canary.N而无法前进例如一个majorchangeset 本应产生1.0.0-canary.0。详见 add-new-provider.md → When in pre-release mode。将修复回传到稳定版要把main上的修复回传到维护分支给已合并的 PR 添加backport标签即可。这会自动创建一个指向维护分支的新 PR。仓库现状佐证这一行为由 .github/workflows/backport.yml 实现。工作流同时监听pull_request的labeled与closed事件labeled捕获合并后补打标签的场景closed捕获合并时已带标签的场景两者都以事件载荷中的 PR 号为准避免竞态。它会自动解析目标维护分支main的 PR 回传到最新release-v*分支release-vN的 PR 回传到更早一个执行git cherry-pick -m 1并通过 GitHub GraphQLcreateCommitOnBranch创建签名提交与 backport PR。注意两点限制来自 fork 的 PR 需要用workflow_dispatch手动触发修改.github/workflows/的 PR 因GITHUB_TOKEN缺少workflows权限无法自动回传。发布稳定补丁合并进维护分支的补丁会触发发布工作流并发布稳定补丁版本。四、结束预发布周期当新大版本准备好发布稳定版时1. 退出预发布模式git checkout main pnpm changeset pre exit这会移除.changeset/pre.json。提交并推送或开一个 PR。仓库现状佐证当前仓库根目录的 .changeset/ 下只有README.md、config.json与几个常规 changeset 文件如gentle-images-shine.md并无pre.json——说明仓库当前并不处于预发布模式这正是进入/退出模式由pre.json存在与否决定的旁证。2. 发布稳定版退出预发布模式的 PR 合并后下一个Version PackagesPR 将产生稳定版本例如ai7.0.0。合并它即可发布。3. 切换文档站点在ai-studio仓库中将默认分支从sdk/v6改为sdk/v7使生产站点提供新大版本的文档。同步更新 Vercel 生产部署。4. 归档维护分支维护分支例如release-v6.0可以保留以应对紧急补丁但不再接收常规回传。五、小结一份可复用的预发布检查清单阶段关键动作验证方式启动创建release-vmajor.0分支并推送分支上 CI 自动运行启动维护分支ci:release追加--tag ai-vmajor检查 npm dist-tag 未被覆盖启动pnpm changeset pre enter beta并清理pre.json的initialVersions检查pre.json内容启动创建全包majorchangeset检查生成的.changeset/*.md启动为全部 12 个规范目录播种 v4、重命名文件、替换版本字样、更新index.ts导出与交叉引用packages/provider中pnpm build通过启动创建 V4 mock 并导出pnpm test通过启动创建 8 个 V4 适配器及测试更新公共 API 边界与相关测试pnpm testpnpm type-check:full通过启动文档站点版本化分支与 Vercel 部署预览域名可访问 beta 文档周期内功能 PR 均指向main默认patchchangesetVersion Packages PR 自动发布 beta周期内新包初始版本用纯0.0.0避免 premajor 卡版本周期内已合并 PR 加backport标签backport PR 自动创建结束pnpm changeset pre exit删除pre.jsonVersion Packages 产生稳定版本结束文档站默认分支切换到sdk/vnew-major生产站点提供新版文档这套流程的底层设计意图清晰规范版本化spec versioning是 AI SDK 大版本演进的锚点——从packages/provider/src/*/vN的目录结构到packages/ai/src/model/中以Proxy实现的版本适配器再到packages/ai/src/test/中 V2/V3/V4 三套并行的 mock 矩阵整条链路保证了 Provider 作者可以渐进迁移而核心packages/ai的公共 API 能同时在旧版本与新版本之上稳定运行。理解并复现这个周期是任何希望在 AI SDK 生态中跟进或贡献大版本演进的关键能力。【免费下载链接】aiThe AI Toolkit for TypeScript. From the creators of Next.js, the AI SDK is a free open-source library for building AI-powered applications and agents项目地址: https://gitcode.com/GitHub_Trending/ai/ai创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考