Cherry Studio AI Core 2.0 演进解析AI SDK v6 迁移与 Provider 插件化架构重构【免费下载链接】cherry-studio Cherry Studio 是一款支持多个 LLM 提供商的桌面客户端项目地址: https://gitcode.com/CherryHQ/cherry-studio本篇技术指南以 Cherry Studio 仓库内 packages/aiCore/CHANGELOG.md 为主线结合 packages/aiCore 包源码完整梳理cherrystudio/ai-core从 2.0.0 到 2.0.1 的架构演进包括 AI SDK v6 迁移带来的破坏性变更、Provider Extension / Variant 类型系统重构、toolFactories 工具工厂机制以及插件化运行时的生命周期模型。读完本文你将理解该包模型层 → 运行时层的设计脉络掌握ProviderVariantTSettings, TProvider, TOutput泛型设计与azure-anthropic变体修复的底层原理并能在自己的项目中正确安装、注册与调用该统一 AI Provider 接口。版本演进总览一次破坏性重构与一次精准修复cherrystudio/ai-core即packages/aiCore是 Cherry Studio 基于 Vercel AI SDK 构建的统一 AI Provider 接口包其 package.json 声明的主版本演进记录了两个关键节点2.0.0Major Changes由 PR #12235 引入完成向 AI SDK v6 的整体迁移对 Provider 与中间件架构做了完整重写complete rewrite同时包含若干破坏性变更2.0.1Patch Changes由 PR #14087 引入集中修复azure-anthropic变体的工具工厂与类型系统问题是理解 Variant 泛型设计的最佳案例。除版本自身内容外2.0.0 还包含两项 PatchPR #13787 补充缺失的openrouter/ai-sdk-provider依赖以修复包构建PR #12783 作为基线发布Baseline release将此前未纳管的历史变更收编并正式引入基于 changesets 的发布流程。从 changelog 可见2.0.0 同时将cherrystudio/ai-sdk-provider依赖更新至 0.1.6二者属于同仓库 workspace 联动演进见 pnpm-workspace.yaml。2.0.0 核心AI SDK v6 迁移的五大变化1. 移除遗留 API 客户端与中间件管线破坏性变更2.0.0 明确标注BREAKING移除所有遗留 API clients、middleware pipeline 以及 barrel 形式的index.ts。这意味着旧版中自维护的 HTTP 客户端封装、自建的中间件链均被废弃取而代之的是直接复用 AI SDK v6 的能力。从当前源码可以印证这一转向包的主入口 packages/aiCore/src/index.ts 已不再是一份厚重的 barrel 文件而是按模块分区runtime / plugins / providers / context / errors做轻量再导出核心执行器 RuntimeExecutor 直接调用 AI SDK 的streamText、generateText、generateImage、embedMany、rerank等顶层函数不再存在自定义的网络层。2. 图像生成迁移到原生 generateImage / editImagechangelog 指出图像生成从遗留 image middleware迁移为 AI SDK 原生的generateImage/editImage。源码中 RuntimeExecutor.generateImage 正是这一迁移的落点它支持字符串模型 ID 或模型对象两种入参通过pluginEngine.executeImageWithPlugins执行并借助wrapImageModel的 v3 middleware 实现了onProviderCall观测回调记录 requestId、providerId、modelId、imageCount、usage 与耗时指标观测逻辑通过 best-effort 方式保证不干扰正常 AI 结果见 emitProviderCall。3. Embedding迁移到 embedManychangelog 记录 Embedding 从遗留客户端迁移到 AI SDK 的embedMany并移除了遗留 embedding clients。这与 AI SDK v6 的能力边界一致——源码注释明确写着AI SDK v6 只有 embedMany没有 embed见 packages/aiCore/src/core/runtime/index.ts。RuntimeExecutor.embedMany 对模型 ID 使用registry.embeddingModel(${providerId}:${modelId})解析同样支持onProviderCall观测构造函数中还针对部分 v3 provider如openrouter/ai-sdk-provider只暴露textEmbeddingModel而非embeddingModel的情况做了兼容补丁。4. 模型列表ModelListService 重构为 Strategy Registry 模式2.0.0 将ModelListService重构为Strategy Registry 模式并consolidate schema files合并 schema 文件。这是架构层面的收敛把不同 provider 的模型列取策略统一注册到注册表中避免服务类中的分支膨胀。这一思路与包内 Extension Registry 一脉相承——ExtensionRegistry 是全局单例extensionRegistry负责 provider 创建与模型解析器的集中管理。5. 命名收敛与 OpenRouter / GitHub Copilot 适配重命名index_new.ts→AiProvider.tsModelListService.ts→listModels.ts消除了过渡期命名OpenRouter 图像通过openrouter/ai-sdk-provider2.3.3 提供原生图像端点支持generateImage/editImage包依赖同步升级至^2.10.0见 package.jsonGitHub Copilot通过移除ProviderV2cast 与wrapProvider简化扩展全面拥抱 V3 模型协议——resolveModel 会强制校验模型必须是 V3否则抛出 Model must be V3 错误。2.0.1 修复深度解读ProviderVariant 的 TOutput 泛型与工具工厂2.0.1 的修复集中在 Provider Variant变体系统changelog 将其概括为三个要点为ProviderVariant增加TOutput泛型使transform的输出类型能够流向toolFactories与resolveModel为azure-anthropic变体补充 Anthropic 专属的toolFactories修复provider.tools.webSearchPreview is not a function报错修复urlContextfactory 被错误映射到webSearch工具键的问题并修正BedrockExtension的satisfies类型。TOutput 泛型的设计意图在 packages/aiCore/src/core/providers/types/index.ts 中ProviderVariant声明为export interface ProviderVariant TSettings any, TProvider extends ProviderV3 ProviderV3, TOutput extends ProviderV3 TProvider { suffix: string name: string /** 类型安全的模型解析provider.responses(modelId) / provider.chat(modelId) */ resolveModel?: (provider: TOutput, modelId: string) LanguageModel /** 替换整个 provider如 azure-anthropic简单方法切换用 resolveModel */ transform?: (baseProvider: TProvider, settings?: TSettings) TOutput | PromiseTOutput toolFactories?: ToolFactoryMapTOutput }关键点在于当transform返回的 provider 类型与输入不同即TOutput不等于TProvider时toolFactories与resolveModel必须基于TOutput而非 TProvider 做类型推导。这正是azure-anthropic场景——Azure 变体通过createAnthropic整体重建 provider输出是AnthropicProvider而不是AzureOpenAIProvider因此其webSearch、urlContext工厂必须接收 Anthropic 的 provider 实例。azure-anthropic 变体的完整实现见 packages/aiCore/src/core/providers/core/initialization.ts{ suffix: anthropic, name: Azure Anthropic, transform: async (_provider, settings) (await import(ai-sdk/anthropic)).createAnthropic({ baseURL: (settings?.baseURL ?? ) /anthropic/v1, apiKey: settings?.apiKey ?? , headers: settings?.headers, // 转发调用方注入的 fetch如代理感知的 customFetch // 避免变体重建 provider 后请求静默回退到 SDK 默认 fetch fetch: settings?.fetch }), toolFactories: { webSearch: (provider) (config: NonNullableParametersAnthropicProvider[tools][webSearch_20260209][0]) ({ tools: { webSearch: provider.tools.webSearch_20260209(config) } }), urlContext: (provider) (config: NonNullableParametersAnthropicProvider[tools][webFetch_20260209][0]) ({ tools: { urlContext: provider.tools.webFetch_20260209(config) } }) } } satisfies ProviderVariantAzureOpenAIProviderSettings, AzureOpenAIProvider, AnthropicProvider该实现揭示了修复的三个层面类型层satisfies ProviderVariantAzureOpenAIProviderSettings, AzureOpenAIProvider, AnthropicProvider显式声明 TOutput 为AnthropicProvider让toolFactories与resolveModel的参数类型自动收敛到 Anthropic 类型行为层此前azure-anthropic变体未提供自己的 toolFactoriesExtensionRegistry.getToolFactory会回退到 base extension 的工厂见 ExtensionRegistry.ts而 base Azure 工厂使用AzureOpenAIProvider[tools][webSearchPreview]在 Anthropic provider 上调用即触发webSearchPreview is not a function补充 Anthropic 工厂后webSearch_20260209与webFetch_20260209得以正确调用映射层urlContext工厂此前误映射到webSearch工具键修复后正确输出tools: { urlContext: ... }。工具工厂的解析优先级ExtensionRegistry.resolveTool 体现了工具工厂的查找策略先看 provider 自身的 toolFactoriesvariant 级别优先于 base extension失败后再沿 provider 分段逐级回退如azure-anthropic→azure→ 基础扩展最终尝试从 provider 对象上直接取方法。测试用例 ExtensionRegistry.test.ts 覆盖了 variant 级工厂、回退与 undefined 场景。此外providerToolPlugin.ts 会把工厂返回的ToolFactoryPatchtools / providerOptions合并进请求参数打通工具工厂 → 插件 → 请求链路。插件系统请求生命周期的四类钩子2.0.0 重构后的运行时以插件为第一公民。插件接口定义在 packages/aiCore/src/core/plugins/types.ts按执行语义分为四类钩子类别钩子名称执行语义First首个命中resolveModel、loadTemplate串行遍历返回第一个非空结果Sequential串行链式configureContext、transformParams、transformResult逐个执行后者接收前者的输出Parallel并行副作用onRequestStart、onRequestEnd、onErrorPromise.all并发执行互不依赖Stream流处理transformStream基于 AI SDK 流变换收集后统一传入experimental_transform插件的排序规则为pre → normal → post由enforce字段控制实现在 PluginManager.sortPlugins。请求上下文AiRequestContext携带 providerId、model、originalParams、requestId、递归深度控制默认最大 10 层防止栈溢出以及可选的 MCP tools见 types.ts并预留recursiveCall供插件内部发起递归调用。运行时侧PluginEngine 是插件与 AI SDK 调用的桥梁RuntimeExecutor.streamText/generateText会依据入参是字符串模型 ID 还是模型对象决定是否注入_internal_resolveModel插件最终把插件链产出的模型对象、转换后的参数与流变换一并交给 AI SDK见 executor.ts。从 CHANGELOG 到实践安装与接入安装与依赖边界cherrystudio/ai-core通过 pnpm workspace 管理peerDependencies 要求 AI SDK 生态的版本对齐ai ^6.0.116、ai-sdk/openai ^3.0.109、ai-sdk/google ^3.0.113内部依赖则覆盖 Anthropic、Azure、DeepSeek、OpenAI-Compatible、xAI、OpenRouter 等 provider 包见 package.json产物同时导出dist/index.cjsCommonJS与dist/index.mjsESM并声明了react-native入口Node 运行环境要求18.0.0。独立的./built-in/plugins与./provider子路径导出允许按需引入插件或 provider 能力。在 React Native 环境中使用该包时需要在metro.config.js中补充resolverMainFields [react-native, browser, main]与平台列表详见 packages/aiCore/README.md。最小可运行示例import { createExecutor, streamText } from cherrystudio/ai-core // 函数式直接流式生成 const result await streamText( openai, { apiKey: your-api-key }, { model: gpt-4, messages: [{ role: user, content: Hello! }] } ) // 实例式可复用的执行器内部自动确保 provider 已初始化 const executor await createExecutor(anthropic, { apiKey: your-key }) const res await executor.generateText({ model: claude-3-5-sonnet, messages: [{ role: user, content: Hello! }] })从源码看createExecutor会先校验extensionRegistry.has(providerId)再调用extensionRegistry.createProvider创建 provider并从 variant 声明中提取类型安全的模型解析器见 packages/aiCore/src/core/runtime/index.ts——这也解释了 changelog 中TOutput类型流向resolveModel的工程价值变体的模型解析行为随类型系统一起被约束。注册自定义 Provider对非内置 provider可通过registerProvider注册支持直接传入 creator 或动态 import 两种方式随后即可像内置 provider 一样通过AiCore.create(id, { apiKey })调用。完整的注册示例与插件示例webSearchPlugin、loggingPlugin、definePlugin 自定义插件同样见 packages/aiCore/README.md 的「扩展 Provider 注册」与「插件系统」章节。结语从 2.0.0 的 AI SDK v6 全量迁移到 2.0.1 的 Variant 泛型修复cherrystudio/ai-core的演进主线十分清晰砍掉自维护的客户端与中间件层把能力下沉到 AI SDK 原生 API同时用类型系统ProviderVariant 的 TOutput 泛型、toolFactories、satisfies 约束与插件运行时First / Sequential / Parallel / Stream 四类钩子重新织起 Cherry Studio 自己的抽象。对想要阅读或复用该包的人建议按以下顺序深入先读 packages/aiCore/CHANGELOG.md 把握演进脉络再看 packages/aiCore/src/core/runtime/executor.ts 理解执行器与插件引擎的协作最后对照 initialization.ts 与 ExtensionRegistry.ts 研读 Provider Extension 的注册、变体与工具工厂机制。【免费下载链接】cherry-studio Cherry Studio 是一款支持多个 LLM 提供商的桌面客户端项目地址: https://gitcode.com/CherryHQ/cherry-studio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考