AI SDK Codemods 实战指南用自动化代码转换无缝完成 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/aiAI SDK 在版本演进中会废弃、移除或重命名一批 API逐个文件手工修改既耗时又容易出错。ai-sdk/codemod是 AI SDK 官方提供的自动化代码转换codemod工具包它基于 jscodeshift 对代码库进行程序化转换帮助开发者在 v3→v4、v4→v5、v5→v6 甚至 v6→v7 的升级路径上一次完成大量机械性改动。读完本文你将掌握upgrade、v4/v5/v6等 CLI 命令的完整用法与全部全局选项理解 Codemod 的底层执行原理与测试机制并能安全地在真实项目中应用这些转换。什么是 AI SDK CodemodsCodemods代码变换是一类在代码库上以编程方式运行的转换脚本给定输入源码经过 AST抽象语法树级别的分析改写输出目标版本的新代码。AI SDK 在跨版本升级时会产生大量无脑但繁琐的改动——重命名导出、移除废弃 API、调整函数签名、改写 provider 配置属性——这些场景正是 Codemod 的用武之地。在 AI SDK 仓库中Codemod 工具位于 packages/codemod每个 Codemod 是独立的转换模块按目标版本分目录组织src/codemods/v4/v3 → v4 迁移src/codemods/v5/v4 → v5 迁移src/codemods/v6/v5 → v6 迁移src/codemods/v7/v6 → v7 迁移从源码结构看仓库已包含 v7 转换模块从 package.json 可以看到该包的 CLI 二进制入口为dist/bin/codemod.js运行时要求Node.js 22底层依赖jscodeshiftAST 转换引擎、commander命令行解析、cli-progress进度条与debug日志输出。快速开始一键升级运行全部 Codemods推荐在项目根目录执行npx ai-sdk/codemod upgrade该命令会自动检测并转换项目中所有适用的代码模式。从源码看upgrade.ts 中的bundle数组集中声明了全部 Codemod 清单upgrade函数会按顺序逐个执行v4 → v5 → v6 → v7并通过cli-progress渲染实时进度条转换完成后统一汇报错误。按版本运行npx ai-sdk/codemod v4 # 仅应用 v3 → v4 迁移 npx ai-sdk/codemod v5 # 仅应用 v4 → v5 迁移 npx ai-sdk/codemod v6 # 仅应用 v5 → v6 迁移 npx ai-sdk/codemod upgrade # 应用全部版本化运行的优势在于可控例如你正从 v5 升级到 v6只需执行npx ai-sdk/codemod v6避免提前应用 v7 的改动。upgrade.ts内部通过bundle.filter(codemod codemod.startsWith(v4/))等逻辑将总清单拆分为各版本子集分别交由upgradeV4/upgradeV5/upgradeV6/upgradeV7执行。运行单个 Codemodnpx ai-sdk/codemod codemod-name pathpath可以是单个文件、目录或整个项目.# 转换单个文件 npx ai-sdk/codemod v4/remove-experimental-ai-fn-exports src/app/api/chat/route.ts # 转换一个目录 npx ai-sdk/codemod v4/replace-baseurl src/lib/ # 转换整个项目 npx ai-sdk/codemod v5/rename-format-stream-part .CLI 命令与全局选项CLI 基于commander实现入口源码位于 src/bin/codemod.ts。完整用法npx ai-sdk/codemodbeta command [options]可用命令命令说明upgrade应用全部 Codemodsv4 v5 v6实际执行时也包含 v7v4应用 v4 Codemodsv3 → v4 迁移v5应用 v5 Codemodsv4 → v5 迁移v6应用 v6 Codemodsv5 → v6 迁移codemod-name path应用指定的单个 Codemod全局选项选项简写说明--dry-d预览模式不实际修改文件--print-p将转换后的代码输出到 stdout--verbose显示详细的转换日志--jscodeshift options-j将选项直接透传给底层 jscodeshift选项组合示例# 预览全部变更而不应用 npx ai-sdk/codemodbeta --dry upgrade # 仅预览 v4 变更 npx ai-sdk/codemodbeta --dry v4 # 仅预览 v5 变更 npx ai-sdk/codemodbeta --dry v5 # 仅预览 v6 变更 npx ai-sdk/codemodbeta --dry v6 # 对指定 Codemod 输出详细日志 npx ai-sdk/codemodbeta --verbose v4/remove-experimental-ai-fn-exports src/ # 打印指定 Codemod 的转换结果 npx ai-sdk/codemodbeta --print v4/replace-baseurl src/config.ts--dry与--print都是安全的只读用法--dry只计算差异不落盘--print把改写结果打印到终端非常适合在真正升级前审查 Codemod 的行为是否符合预期。可用 Codemods 完整清单v4 Codemodsv3 → v4 迁移Codemod说明v4/remove-ai-stream-methods-from-stream-text-result从 stream text 结果对象中移除 AI stream 相关方法v4/remove-anthropic-facade移除 Anthropic facadev4/remove-await-streamobject移除 streamObject 前的 awaitv4/remove-await-streamtext移除 streamText 前的 awaitv4/remove-deprecated-provider-registry-exports移除废弃的 provider registry 导出v4/remove-experimental-ai-fn-exports移除 experimental AI 函数导出v4/remove-experimental-message-types移除 experimental 消息类型v4/remove-experimental-streamdata移除 experimental streamdatav4/remove-experimental-tool移除 experimental toolv4/remove-experimental-useassistant移除 experimental useAssistantv4/remove-google-facade移除 Google facadev4/remove-isxxxerror移除 isXxxError 类错误判断函数v4/remove-metadata-with-headers移除带 headers 的 metadatav4/remove-mistral-facade移除 Mistral facadev4/remove-openai-facade移除 OpenAI facadev4/rename-format-stream-part重命名 formatStreamPartv4/rename-parse-stream-part重命名 parseStreamPartv4/replace-baseurl将 baseUrl 替换为 baseURLv4/replace-continuation-steps替换 continuationStepsv4/replace-langchain-toaistream将 LangChain 的 ToAIStream 替换为 AI SDK 实现v4/replace-nanoid替换 nanoid 使用v4/replace-roundtrips-with-maxsteps将 roundtrips 替换为 maxStepsv4/replace-token-usage-types替换 token usage 类型v4/rewrite-framework-imports重写框架导入Solid / Svelte / Vue 等v5 Codemodsv4 → v5 迁移Codemod说明v5/flatten-streamtext-file-properties扁平化 streamText 的 file 属性v5/import-LanguageModelV2-from-provider-package从 provider 包导入 LanguageModelV2v5/migrate-to-data-stream-protocol-v2迁移到 Data Stream Protocol v2v5/move-image-model-maxImagesPerCall迁移 image model 的 maxImagesPerCallv5/move-langchain-adapter迁移 LangChain adapterv5/move-maxsteps-to-stopwhen将 maxSteps 迁移为 stopWhenv5/move-provider-options迁移 provider optionsv5/move-react-to-ai-sdk将 React 相关代码迁移到 AI SDKv5/move-ui-utils-to-ai将 UI 工具迁移到 ai 包v5/remove-experimental-wrap-language-model移除 experimental wrapLanguageModelv5/remove-get-ui-text移除 getUiTextv5/remove-openai-compatibility移除 OpenAI 兼容层v5/remove-sendExtraMessageFields移除 sendExtraMessageFieldsv5/rename-IDGenerator-to-IdGenerator将 IDGenerator 重命名为 IdGeneratorv5/rename-addtoolresult-to-addtooloutput将 addToolResult 重命名为 addToolOutputv5/rename-converttocoremessages-to-converttomodelmessages将 convertToCoreMessages 重命名为 convertToModelMessagesv5/rename-core-message-to-model-message将 CoreMessage 重命名为 ModelMessagev5/rename-datastream-methods-to-uimessage将 data stream 方法重命名为 UIMessagev5/rename-datastream-transform-stream重命名 data stream transform streamv5/rename-languagemodelv1providermetadata重命名 LanguageModelV1ProviderMetadatav5/rename-max-tokens-to-max-output-tokens将 maxTokens 重命名为 maxOutputTokensv5/rename-message-to-ui-message将 Message 重命名为 UIMessagev5/rename-mime-type-to-media-type将 mimeType 重命名为 mediaTypev5/rename-pipedatastreamtoresponse-to-pipeuimessagestreamtoresponse将 pipeDataStreamToResponse 重命名为 pipeUIMessageStreamToResponsev5/rename-reasoning-properties重命名 reasoning 相关属性v5/rename-reasoning-to-reasoningText将 reasoning 重命名为 reasoningTextv5/rename-request-options重命名 request optionsv5/rename-todatastreamresponse-to-touimessagestreamresponse将 toDataStreamResponse 重命名为 toUIMessageStreamResponsev5/rename-tool-parameters-to-inputschema将 tool 的 parameters 重命名为 inputSchemav5/replace-bedrock-snake-case替换 Bedrock 的 snake_case 命名v5/replace-content-with-parts将 content 替换为 partsv5/replace-datastream-to-uimessagestream将 DataStream 替换为 UIMessageStreamv5/replace-experimental-provider-metadata替换 experimental provider metadatav5/replace-fal-snake-case替换 fal 的 snake_case 命名v5/replace-image-type-with-file-type将 ImagePart 类型替换为 FilePart 类型v5/replace-llamaindex-adapter替换 LlamaIndex adapterv5/replace-oncompletion-with-onfinal将 onCompletion 替换为 onFinalv5/replace-provider-metadata-with-provider-options将 provider metadata 替换为 provider optionsv5/replace-rawresponse-with-response将 rawResponse 替换为 responsev5/replace-redacted-reasoning-type替换 redacted reasoning 类型v5/replace-simulate-streaming替换 simulateStreamingv5/replace-textdelta-with-text将 textDelta 替换为 textv5/replace-usage-token-properties替换 usage token 属性v5/replace-usechat-api-with-transport将 useChat 的 API 参数替换为 transportv5/replace-usechat-input-with-state将 useChat 的 input 替换为 statev5/replace-zod-import-with-v3将 zod import 替换为 v3 版本v5/require-createIdGenerator-size-argument要求 createIdGenerator 提供 size 参数v5/restructure-file-stream-parts重构 file stream parts 结构v5/restructure-source-stream-parts重构 source stream parts 结构v5/rsc-package处理 RSC 包相关的迁移v6 Codemodsv5 → v6 迁移Codemod说明v6/add-await-converttomodelmessages为 convertToModelMessages 添加 awaitv6/rename-converttocoremessages-to-converttomodelmessages将 convertToCoreMessages 重命名为 convertToModelMessagesv6/rename-core-message-to-model-message将 CoreMessage 重命名为 ModelMessagev6/rename-mock-v2-to-v3将 mock v2 重命名为 v3v6/rename-text-embedding-to-embedding将 textEmbedding 重命名为 embeddingv6/rename-tool-call-options-to-tool-execution-options将 toolCallOptions 重命名为 toolExecutionOptionsv6/rename-vertex-provider-metadata-key重命名 Vertex provider 的 metadata keyv6/wrap-tomodeloutput-parameter包装 toModelOutput 参数值得注意部分 v5 迁移如v5/rename-converttocoremessages-to-converttomodelmessages、v5/rename-core-message-to-model-message与 v6 存在同名项这说明同一 API 重命名可能在多个版本中延续执行upgrade时会按版本顺序依次处理。源码级原理剖析Codemod 是如何运行的从 CLI 到 jscodeshift 的调用链完整调用链为src/bin/codemod.tscommander 解析→src/lib/upgrade.ts版本批量调度→src/lib/transform.ts构建并执行 jscodeshift 命令。transform.ts 中的buildCommand展示了每个 Codemod 最终生成的底层命令jscodeshift -t codemod路径 目标路径 \ --parser tsx \ --ignore-pattern**/node_modules/** \ --ignore-pattern**/.*/** \ --ignore-pattern**/dist/** \ --ignore-pattern**/build/** \ --ignore-pattern**/*.min.js \ --ignore-pattern**/*.bundle.js其中的关键设计--parser tsx同时兼容.ts、.tsx、.js、.jsx文件这是 README 中支持这四类文件的源码依据默认忽略清单node_modules/、所有以.开头的隐藏目录覆盖.next/等框架构建目录、dist/、build/、压缩产物*.min.js、*.bundle.js从源码注释可知忽略.*/是为了避开框架构建目录及所有本应隐藏的目录选项透传--dry、--print、--verbose会被附加到 jscodeshift 命令后--jscodeshift选项则允许用户把任意参数直接传给 jscodeshift 引擎。错误与未实现机制transform.ts通过正则解析 jscodeshift 的 stdout 输出parseErrors匹配ERR (.) Transformation error结合SyntaxError提取转换失败的文件与原因parseNotImplementedErrors匹配Not Implemented (.): (.)对应那些能识别但无法自动完成的改动。这两类问题会被汇总到upgrade.ts的allErrors与notImplementedErrors中。对于未实现的迁移CLI 会提示你在代码库中搜索FIXME(ai-sdk-upgrade-v5):注释并按注释中的说明手动完成升级——这是 Codemod 在识别模式但无法安全改写时的兜底策略。Codemod 的统一封装createTransformer所有 Codemod 模块都通过 create-transformer.ts 封装为 jscodeshift 兼容的 transformer。它向每个 Codemod 注入统一上下文jjscodeshift APIroot源码的 AST 根集合hasChangesCodemod 只要对 AST 做过改动就必须置为true否则 jscodeshift 不会输出新源码messagesCodemod 可向其中追加消息最终通过api.report上报给用户。只有当hasChanges true时封装器才会以单引号风格root.toSource({ quote: single })输出转换结果从而保证没改动就不重写文件。两个典型 Codemod 实战拆解案例一v4/replace-baseurl精准定向的 AST 改写以 v4 的 replace-baseurl.ts 为例它要做的是把 provider 工厂函数中的baseUrl属性改名为baseURL。难点在于不能把项目里所有baseUrl都改名。因此该 Codemod 维护了一个PROVIDER_CREATORS白名单createAnthropic、createAzure、createCohere、createGoogle、createGoogleGenerativeAI、createGroq、createMistral、createOpenAI并通过isWithinProviderCall沿 AST 向上遍历父节点仅当属性位于白名单 provider 工厂的调用参数内时才执行改名。测试夹具 replace-baseurl.input.ts 与 replace-baseurl.output.ts 验证了这一点// 输入provider 工厂内的 baseUrl 会被改写 const anthropic createAnthropic({ baseUrl: https://api.anthropic.com }); // 输入普通对象 / 普通函数参数中的 baseUrl 保持不变 const config { baseUrl: https://example.com };// 输出仅 provider 调用内被改写为 baseURL const anthropic createAnthropic({ baseURL: https://api.anthropic.com }); const config { baseUrl: https://example.com }; // 未被改动对应的单元测试 replace-baseurl.test.ts 通过testTransform(transformer, replace-baseurl)对比输入/输出夹具确保转换行为精确可控。这正是复杂或非常规代码模式可能需要手动处理的源码级解释Codemod 依靠白名单与 AST 上下文判断天然无法覆盖所有边界情况。案例二v5/move-maxsteps-to-stopwhen带 FIXME 注释的半自动迁移v5 的 move-maxsteps-to-stopwhen.ts 展示了更复杂的迁移逻辑对generateText/streamText调用将maxSteps属性改写为stopWhen: stepCountIs(原值)并自动向ai包的 import 声明中追加stepCountIs若尚未导入对useChat调用由于maxSteps在 v5 中被整体移除Codemod不会自动改写而是调用addUseChatComment注入Not Implemented消息并在原属性处插入FIXME(ai-sdk-upgrade-v5):注释提示开发者改到服务端使用stopWhen条件控制多步工具执行它还处理了第一个参数是变量引用的情况会回溯VariableDeclarator与AssignmentExpression找到对象字面量定义处再进行改写。这个案例说明Codemod 不是万能替换器对于无法安全自动化的改动它会通过 FIXME 注释把人工任务显式标记出来这正是文档中一些复杂模式可能需要手动修复这一最佳实践的工程化落地。最佳实践运行 Codemod 之前备份代码先把所有改动提交到版本控制系统确保随时可回滚先处理明显的废弃警告升级前修复代码中现有的 deprecation warning减少干扰项更新依赖确保项目依赖已升级到目标 AI SDK 版本再运行对应版本的 Codemod。建议先以--dry预览全量差异确认转换范围符合预期后再正式执行。运行 Codemod 之后审查改动检查 diff理解每个文件被转换了什么、为什么被转换测试应用运行你的测试套件与应用确认行为未发生回归处理边界情况搜索并处理FIXME(ai-sdk-upgrade-v5):注释以及 Codemod 无法识别的复杂模式运行类型检查修复剩余的 TypeScript 类型错误类型检查是发现遗漏迁移的最佳手段。故障排查如果某个 Codemod 没有转换某些代码检查文件扩展名Codemod 只作用于.ts、.tsx、.js、.jsx文件且默认跳过node_modules、隐藏目录、dist/build产物审查代码模式复杂或非常规的写法可能超出 Codemod 的识别范围需要手动更新改为运行单个 Codemod针对未生效的迁移单独执行npx ai-sdk/codemod codemod-name path配合--verbose观察详细日志查阅迁移文档部分改动可能没有对应的自动化 Codemod需按官方迁移指南手动处理。贡献指南为仓库新增 Codemod如果你在升级中发现缺失的迁移场景可以按以下流程为仓库贡献新 Codemod对应 packages/codemod 目录在src/codemods/下创建 Codemod 实现按版本放入v4/、v5/、v6/等子目录在src/test/__testfixtures__/添加测试夹具codemod-name.input.ts与codemod-name.output.ts成对出现在src/test/创建对应的测试文件在src/lib/upgrade.ts的bundle数组中登记新 Codemod使其进入upgrade全量流程。仓库还提供了脚手架与 README 自动生成脚本见 package.json 的scaffold与generate-readme脚本可辅助初始化新 Codemod。运行测试cd packages/codemod # 运行全部测试 pnpm test # 运行指定 Codemod 的测试 pnpm test codemod-name # 开发模式监听运行 pnpm test:watch测试基于 Vitest每个 Codemod 的测试通过testTransform工具加载__testfixtures__中的输入/输出夹具对进行断言仓库中还包含大量非 AI 代码不应被误改的夹具如replace-nanoid-not-ai.input.ts、remove-experimental-tool-not-ai.input.ts用于保证 Codemod 不会越界改写与 AI SDK 无关的代码。版本兼容性AI SDK 版本应使用的 Codemod 方案AI SDK 6.0本包的全部 CodemodsAI SDK 5.0v4 v5 CodemodsAI SDK 4.x使用ai-sdk/codemod1.xAI SDK 3.x需要手动迁移需要说明的是从当前仓库源码看upgrade的 bundle 与 CLI 已经包含 v7 系列 Codemod如v7/rename-system-to-instructions、v7/rename-on-finish-to-on-end、v7/replace-image-message-part-with-file等并支持npx ai-sdk/codemod v7命令README 文档中的兼容性表格仍以 v6 为最新正式说明。实际使用时请以你所安装的ai-sdk/codemod版本为准建议结合官方迁移指南确认当前版本的完整 Codemod 清单。小结ai-sdk/codemod把 AI SDK 跨版本升级中最繁琐、最容易遗漏的机械性改动抽象成了可复用的自动化转换upgrade一键全量执行v4/v5/v6按版本精确控制codemod-name path支持定点修复--dry/--print提供了零风险的预览通道。理解其 jscodeshift 执行链、AST 上下文判断与 FIXME 注释兜底机制后你可以在升级 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），仅供参考