人工智能大模型AI 应用交互助手本地部署【免费下载链接】cherry-studio Cherry Studio 是一款支持多个 LLM 提供商的桌面客户端项目地址https://gitcode.com/CherryHQ/cherry-studio点击查看免费下载导读Cherry Studio 提供全局版global与中国版cn两种应用版本二者共享同一份本地用户数据但每个版本只暴露其官方支持的 Provider 与模型。本篇基于仓库中的 breaking change 文档v2-refactor-temp/docs/breaking-changes/2026-09-02-edition-provider-availability.md并结合源码实现完整讲解版本如何被识别、Provider 与模型的可用性如何按版本过滤、切换版本后数据为何不丢失、用户遇到不可用模型时应如何处理以及发布管理人员需要关注的风险点。变更概述Provider 可用性跟随应用版本自 2026-09-02PR #19776起Cherry Studio 引入了Provider 可用性跟随应用版本的破坏性变更breaking change核心行为如下全局版与中国版共享本地用户数据两份版本共用同一份 SQLite 本地数据库Provider、模型、助手、会话等数据落盘位置一致。每个版本只暴露其支持的 Provider 与模型当前版本不支持的 Provider/模型记录在读取与使用层面会被视为不可用不再出现在运行时可见的数据集合中。不可用记录仍然保留这些记录不会被删除、不会被迁移、不会被覆写依旧完整存储在本地数据库中当用户切换回支持这些记录的其他版本后记录会重新变为可用。这一变更的本质是可用性判定发生在读取/使用的边界上而非存储的边界上——数据层永不丢失过滤只发生在运行时暴露层。版本Edition机制在仓库中的实现AppEdition 类型版本类型在 src/shared/types/appEdition.ts 中定义只有两个合法取值import type { ProviderEdition } from cherrystudio/provider-registry export const APP_EDITIONS [global, cn] as const satisfies readonly ProviderEdition[] export type AppEdition (typeof APP_EDITIONS)[number]注意这里AppEdition直接约束自 provider-registry 包的ProviderEdition类型说明应用版本与Provider 注册表中的版本声明共用同一套枚举语义保证两侧判定一致。版本解析与缓存版本的实际解析逻辑位于 src/main/utils/appEdition.tsconst APPLICATION_IDS { global: com.kangfenmao.CherryStudio, cn: com.cherryai.cherrystudio.cn } as const satisfies RecordAppEdition, string解析顺序为开发环境覆盖若应用未打包!app.isPackaged且设置了环境变量CHERRY_EDITION则以其为准parseAppEdition会做小写 trim 并校验打包环境读取元数据读取应用根目录package.json中的cherryEdition字段未定义时默认回退为global非法值非global/cn会直接抛出Unsupported application edition错误。解析结果通过getAppEdition()惰性缓存cachedAppEdition ?? resolveAppEdition()进程内只解析一次getApplicationId()则根据版本返回对应的应用标识CN 版使用独立的com.cherryai.cherrystudio.cn这保证了两版本可共存安装但共享用户数据目录的边界设计。Provider 注册表中的版本声明Provider 是否在某个版本可用由 provider-registry 包中的静态元数据availableInEditions声明。其 Schema 定义在 packages/provider-registry/src/schemas/provider.tsexport const ProviderEditionSchema z.enum([global, cn]) export type ProviderEdition z.infertypeof ProviderEditionSchema // ... availableInEditions: looseArray(ProviderEditionSchema, { min: 1 }).optional(),availableInEditions为可选字段缺省时语义上是对所有版本可用。仓库内实际声明示例packages/provider-registry/src/providers 目录双版本可用deepseek[global, cn]、dashscope、doubao、moonshot、minimax、new-api、modelscope、baichuan、baidu-cloud、cherryin、lmstudio、gpustack等仅全局版anthropic、gemini、grok、mistral、cerebras、fireworks、huggingface、azure-openai、aws-bedrock、copilot等。也就是说切换中国版后某些 Provider 不可见并非运行时临时屏蔽而是注册表数据中本来就只声明了global。Provider 可用性判定的核心逻辑ProviderService可用性判定的入口在 src/main/data/services/ProviderService.ts核心函数function isProviderAvailableInCurrentEdition(provider: PickProvider, availableInEditions): boolean { const availableInEditions provider.availableInEditions return isMigratedFromV1() || !availableInEditions || availableInEditions.includes(getAppEdition()) }判定规则任一成立即可用v1 迁移来源豁免isMigratedFromV1()为真用户数据来自 v1 迁移时全部放行——避免老用户升级后被瞬间隐藏全部 Provider无版本声明注册表未声明availableInEditionsundefined/空视为全版本可用显式包含当前版本availableInEditions数组包含当前getAppEdition()。再向上封装为getAvailableProviderMetadata退役retiredProvider 先行排除function getAvailableProviderMetadata(row: ProviderIdentity): ProviderDisplayMetadata | null { if (isRetiredProvider(row.providerId, row.presetProviderId)) return null const metadata getDataService(ProviderRegistryService).getProviderDisplayMetadata(...) return isProviderAvailableInCurrentEdition(metadata) ? metadata : null }并导出isProviderIdentityAvailable(row)它只依赖身份列 静态注册表 构建期版本 v1 来源标记即可判定便于在其他事务中调用而不需要新开数据库连接。读取路径列表与详情都做版本过滤list(query)遍历userProviderTable全部行逐行调用getAvailableProviderMetadata不可用行直接跳过不进运行时返回结果getByProviderId(providerId)先assertProviderAvailable(row, providerId)断言当前版本不可用时抛出DataApiErrorFactory.notFound(Provider, providerId)即对调用方表现为该 Provider 不存在。写入路径显式拒绝创建create(dto)在落库前会校验注册表元数据if (!isProviderAvailableInCurrentEdition(presetMetadata)) { throw DataApiErrorFactory.invalidOperation( create provider ${dto.providerId}, provider is unavailable in the current application edition ) }即当前版本不支持时新建 Provider 会被直接拒绝错误信息明确为在当前应用版本中不可用避免用户在当前版本下配置一个永远无法使用的 Provider。运行时断言供其他服务调用ProviderService 还暴露了三个运行时检查接口供上游Agent、Assistant、消息发送等使用listAvailableProviderIds(providerIds?)批量返回当前版本可用的 Provider ID 集合isAvailableByProviderId(providerId)单项可用性检查assertAvailable(providerId)不可用时抛 not-found 断言。这些方法保证了Provider 可用性在请求发送链路上被统一执行而不是只在前端 UI 层面做隐藏。模型层同样按版本过滤ModelService模型与 Provider 是强关联的每个user_model行都通过外键挂在某个 Provider 之下ON DELETE CASCADE。src/main/data/services/ModelService.ts 在查询时通过内连接把 Provider 的身份列一并取出function selectWithProviderIdentity(tx: PickDbType, select) { return tx .select({ model: userModelTable, providerId: userProviderTable.providerId, presetProviderId: userProviderTable.presetProviderId }) .from(userModelTable) .innerJoin(userProviderTable, eq(userProviderTable.providerId, userModelTable.providerId)) }然后在模型读取处复用 Provider 的判定findByIdTx(tx, id): Model | null { const [row] selectWithProviderIdentity(tx).where(eq(userModelTable.id, id)).limit(1).all() return row isProviderIdentityAvailable(row) ? this.enrichRowsFromRegistry([row.model])[0] : null } existsByIdTx(tx, id): boolean { const [row] selectWithProviderIdentity(tx).where(eq(userModelTable.id, id)).limit(1).all() return row ! undefined isProviderIdentityAvailable(row) }由于模型查询采用innerJoin而 Provider 行不会被删除因此不会因 join 丢失行当前版本不可用完全由isProviderIdentityAvailable在读取边界上拦截。从源码注释可见这一设计意图Providers unavailable in the current edition are treated as missing before the row is enriched——在当前版本中不可用的 Provider 下的模型在富化enrich之前就被当作缺失处理。这正是文档中assistants and agents bound to an unavailable provider or model cannot send requests的底层原因当用户把 Assistant/Agent 绑定到某个模型后若切换版本导致该模型变为不可用请求发送链路在解析模型时即失败直到用户重新选择模型。数据保留语义为什么切换回原版本数据原样归来这是本次变更最关键的破坏性行为也是用户最关心的点。从源码结构可以确认其数据层语义没有任何删除操作ProviderService/ModelService中所有 edition 过滤都发生在查询/读取边界没有任何delete、update语句针对不可用记录存储与展示解耦userProviderTable、userModelTable中的行、API Key、端配置endpointConfigs、Auth 配置authConfig、默认模型设置等全部保留切换回来即恢复由于过滤条件availableInEditions.includes(getAppEdition())是纯函数判定当getAppEdition()切回支持该 Provider 的版本时同一行数据立即重新满足条件恢复可用。因此文档中的承诺——No provider, model, assistant, or conversation data is deleted——在实现层面是成立的数据是看不见而非被删除。对用户的实际影响与操作建议影响场景从全局版切换到中国版时所有availableInEditions仅含global的 Provider如 Anthropic、Gemini、Grok、Mistral 等及其下模型将变为不可用绑定在这些模型上的 Assistant、Agent 无法再发起请求请求发送在模型解析阶段即失败会话历史、消息内容、Provider 配置数据均不受影响仍然完整保留。用户的应对方式文档明确给出两条路径在当前版本内重新选择为受影响的 Assistant/Agent 重新选择一个当前版本支持的 Provider 与模型例如切换至 DeepSeek、通义千问 DashScope、豆包 Doubao、Moonshot 等双版本 Provider 的模型切回原版本如果现有配置对中国版不可用且无法替换切换回支持该配置的全局版即可恢复全部可用性无需重新配置任何数据。给发布管理人员的提示文档的 release notes 指引值得特别留意留在全局版的用户完全不受影响不必在发布说明中制造恐慌切换至中国版的用户需要明确提示需要重新选择模型这是本次变更唯一需要用户主动操作的事项应在发布公告中单独强调。测试覆盖版本行为的自动化验证仓库为这一行为提供了专门的测试文件src/main/data/services/tests/ProviderService.edition.test.ts通过vi.mock分别控制getAppEdition()如固定为cn与isMigratedFromV1()并 mock 注册表仅提供availableInEditions: [global]的global-onlyProvider验证中国版下已持久化的 global-only Provider 在所有运行时读取与变更路径上均不可用src/main/data/services/tests/ModelService.edition.test.ts对应模型层的版本过滤验证。从测试结构可以推断版本判定是可 mock、可独立验证的纯逻辑便于后续新增 Provider 时快速补充版本声明与回归用例。此外 packages/provider-registry/src/tests/catalog-source-sync.test.ts 中还有对注册表目录数据的校验如断言cherryin声明了cn、默认 Provider 声明了global保证静态数据与双版本策略一致。小结Provider 可用性跟随应用版本是 Cherry Studio 在双版本global / cn产品策略下的关键边界设计共享一份数据按版本差异化暴露能力。本文梳理了从版本解析CHERRY_EDITION/cherryEdition→ 注册表声明availableInEditions→ 读取过滤isProviderAvailableInCurrentEdition→ 写入拦截create抛错→ 模型层复用判定的完整调用链。对开发者而言新增 Provider 时应正确声明availableInEditions对用户而言切换版本前应确认自己的模型绑定是否在该版本可用切换后若发现模型消失只需重新选择模型或切回原版本即可数据始终安全。赞分享人工智能大模型AI 应用交互助手本地部署【免费下载链接】cherry-studio Cherry Studio 是一款支持多个 LLM 提供商的桌面客户端项目地址https://gitcode.com/CherryHQ/cherry-studio点击查看免费下载相关推荐WrenAI wren-core-base 版本演进全解析MDL 语义层共享 Manifest 类型与布局版本机制WrenAI wren core base 版本演进全解析MDL 语义层共享 Manifest 类型与布局版本机制 本篇文章以 WrenAI 仓库中 core后端人工智能AI Agent数据分析Machine Learning Yearning 中文版数据可用性对模型性能的影响分析Machine Learning Yearning 中文版数据可用性对模型性能的影响分析 你是否曾遇到过这样的困境明明投入了大量资源收集数据模型性能却停滞文档教程SchemaSpy多数据库支持深度测评MySQL、PostgreSQL、Oracle对比分析SchemaSpy多数据库支持深度测评MySQL、PostgreSQL、Oracle对比分析 SchemaSpy作为一款专业的数据库文档生成工具其强大的多数创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考