尧图网页设计 
Cherry Studio v2 数据迁移深度解析McpServerMigrator 如何将 MCP 服务器配置从 Redux 迁移到 SQLite【免费下载链接】cherry-studioAI productivity studio with smart chat, autonomous agents, and 300 assistants. Unified access to frontier LLMs项目地址: https://gitcode.com/GitHub_Trending/ch/cherry-studio本篇文章聚焦 Cherry Studio 桌面应用 v2 数据迁移体系中 MCPModel Context Protocol服务器配置的迁移实现。文章以 README-McpServerMigrator.md 为骨架结合 McpServerMigrator.ts、McpServerMappings.ts、mcpServer.ts 等源码与测试完整讲解数据来源、目标表结构、字段映射规则、边界条件处理、三阶段执行契约以及它在整个 v2 迁移管线中的位置与对外协作关系。读完本文你将能够理解 Cherry Studio 中 MCP 服务器配置从Redux 持久化到SQLite 关系型存储的完整迁移路径并掌握这套迁移器的设计原则与可复用模式。背景为什么要迁移 MCP 服务器配置Cherry Studio 的 v1 版本将应用状态保存在 Redux经 Redux Persist 写入 localStorage/磁盘而 v2 版本全面转向 SQLite 关系型数据库。MCPModel Context Protocol服务器是 Cherry Studio 接入外部工具能力的核心载体——用户手动配置的 stdio / SSE / streamableHttp 服务器、内置的 inMemory 服务器、它们的环境变量、启动命令、信任状态与启用状态等都是需要被完整保留的业务数据。McpServerMigrator 正是负责这一领域的数据迁移器它从 v1 的 Redux 状态切片state.mcp.servers读取全部 MCP 服务器对象经过字段变换后写入 v2 的mcp_server表。迁移的核心目标有三个数据不丢失用户配置的每一个服务器都要映射到 SQLite 表中同时生成可供下游迁移器使用的旧 ID → 新 ID 映射结构规范化v1 中松散的、未经过严格校验的字段如服务器type在迁移时被归一化以满足 v2 表结构上的 CHECK 约束依赖安全迁移器运行在AssistantMigrator之前确保助手assistant对 MCP 服务器的引用在重映射之后仍然有效。从源码结构看McpServerMigrator 位于 src/main/data/migration/v2/migrators/McpServerMigrator.ts是 v2 迁移体系中 16 个领域迁移器之一其完整注册顺序定义在 migratorRegistry.ts。数据来源与目标表来源Reduxstate.mcp.servers迁移器的prepare阶段通过ctx.sources.reduxState.get(mcp, servers)读取数据见 McpServerMigrator.ts。reduxState是 ReduxStateReader 的实例它在迁移准备阶段由渲染进程把 Redux Persist 切片导出为分类目录文件主进程按类别读取。来源路径说明Reduxstate.mcp.serversMcpServer 对象数组即 v1 用户配置的全部 MCP 服务器目标mcp_server表目标表定义于 src/main/data/db/schemas/mcpServer.ts基于 Drizzle ORM 的sqliteTable。表结构要点主键id类型为uuidPrimaryKey()UUID v4由数据库自动生成必填列nameNOT NULL、isActiveNOT NULL默认falseJSON 列args、env、headers、tags、configSample、disabledTools、disabledAutoApproveTools均以text({ mode: json })存储布尔列longRunning、shouldConfig、isActive、isTrusted以integer({ mode: boolean })存储时间戳列trustedAt、installedAt为整数时间戳毫秒级此外还通过createUpdateTimestamps自动附带createdAt/updatedAt索引mcp_server_name_idxname、mcp_server_is_active_idxisActive、mcp_server_sort_order_idxsortOrderCHECK 约束type必须是stdio、sse、streamableHttp、inMemory之一允许 NULLinstallSource必须是builtin、manual、ai_assisted、protocol、unknown之一允许 NULL。其中type与installSource的取值约束与 src/shared/data/types/mcpServer.ts 中的 Zod 枚举McpServerTypeSchema、McpServerInstallSourceSchema完全一致体现了共享类型 → 数据库约束的单一事实来源设计。字段映射从 camelCase 到 snake_case 的 1:1 变换文档明确指出所有 McpServer 字段在 Drizzle ORM 层面以 camelCase 属性名 1:1 映射底层 SQLite 列名自动使用 snake_case如baseUrl→base_url由 Drizzle 自动处理迁移代码无需手写列名转换。映射实现位于 src/main/data/migration/v2/migrators/mappings/McpServerMappings.ts核心函数为transformMcpServer(source, index)它接收一个旧的 Redux 服务器对象和序号index返回{ row, oldId }。完整的字段映射表如下源字段目标列变换规则idid不直接透传生成新的 UUID v4 作为主键旧 ID 记录在oldId中用于下游重映射namename优先使用源name缺失/空串/纯空白时回退为生成的新idtoRequiredString实现typetype可空透传但经过类型归一化见下文type 归一化descriptiondescription可空透传toNullablebaseUrl/urlbaseUrl优先取baseUrl缺失时回退到url兼容旧版 SSE 服务器commandcommand可空透传registryUrlregistryUrl可空透传argsargsJSON 数组envenvJSON 对象headersheadersJSON 对象providerprovider可空透传providerUrlproviderUrl可空透传logoUrllogoUrl可空透传tagstagsJSON 数组longRunninglongRunning可空布尔timeouttimeout可空整数dxtVersiondxtVersion可空透传dxtPathdxtPath可空透传referencereference可空透传searchKeysearchKey可空透传configSampleconfigSampleJSON 对象McpConfigSample含command、args、可选envdisabledToolsdisabledToolsJSON 数组disabledAutoApproveToolsdisabledAutoApproveToolsJSON 数组shouldConfigshouldConfig可空布尔isActiveisActive布尔缺失时默认false写入后 NOT NULLinstallSourceinstallSource可空透传isTrustedisTrusted可空布尔trustedAttrustedAt可空整数时间戳installedAtinstalledAt可空整数时间戳无sortOrder由变换函数传入的序号index赋值sortOrder: index保持源数组顺序type归一化为什么不能直接透传表结构上的 CHECK 约束把type限制在当前枚举但 v1 的 Redux 状态从未在写入后针对最新枚举重新校验——例如 v1 曾短暂允许字面量http/streamable_http且不受校验的代码路径可能混入任意字符串。若直接透传任何一个非法值都会让整批 INSERT 因 CHECK 约束失败而中止迁移。toMcpServerType函数见 McpServerMappings.ts复刻了 v1 自身的归一化逻辑非字符串 →null命中stdio/sse/streamableHttp/inMemory→ 原样保留其余包含http子串的字符串 → 统一折叠为streamableHttp其余无法识别的字符串 → 置为null而不是让整批插入失败。测试用例 McpServerMappings.test.ts 中的legacy type normalization参数化用例完整覆盖了这一规则http、streamable_http、streamable-http均映射为streamableHttp而、websocket、unknown-type映射为null。两个关键变换工具函数映射文件内定义了两个通用工具toNullableT(value)value ?? null把undefined/null统一归一为 SQLite 的NULLtoRequiredString(value, fallback)仅当值为非空字符串trim().length 0时保留否则使用回退值——这正是name 缺失时回退到新 id的实现基础。跳过与不迁移的数据跳过字段运行时派生状态字段原因V2 目标isUvInstalled、isBunInstalled由实时二进制可用性派生属于运行时缓存不持久化这两个字段表示当前环境是否安装了 uv / bun 运行时本质上是运行环境探测结果而非用户业务数据。v2 中它们会在运行时重新探测持久化反而会导致过期判断。不迁移数据可再生的缓存来源原因V2 目标Dexiemcp:provider:*:servers由 provider API 重新拉取单独 PR 处理这类数据是某类 provider 通过 API 返回的 MCP 服务器列表缓存迁移器不会将其固化而是在运行时重新获取。边界条件与防御式处理prepare阶段逐条遍历源数组并建立seenIds去重集合文档列出的边界条件在代码中均有对应实现见 McpServerMigrator.ts缺失id跳过该条并记录 warningSkipped server without valid id空id同样跳过typeof s.id ! string或空串判定重复id保留首条后续重复条目跳过Skipped duplicate server idname缺失/空串/纯空白使用生成的新 UUID 作为迁移后的name由toRequiredString保证isActive缺失默认false可选字段为undefined/null统一存储为 SQLiteNULL。全量失败策略一个值得注意的设计如果skippedCount 0且preparedResults.length 0且源数组非空prepare直接返回success: false即全部条目都被跳过时整个迁移器判定失败避免把迁移失败静默包装成迁移了 0 条。反之只要至少有一条成功准备即使部分条目被跳过迁移仍继续被跳过的条目记录在 warnings 中。这一点在 McpServerMigrator.test.ts 的should fail when all servers are skipped用例中得到了验证。源数据形状防御prepare还对源数据形状做了防御mcp.servers不是数组如字符串→ 记录 warningmcp.servers is not an array视为 0 条处理mcp类别缺失或servers键缺失 → 视为空数组正常返回itemCount: 0单条数据变换抛异常如结构异常→ 跳过该条并记录 warning不中断整体迁移。三阶段执行契约prepare / execute / validateMcpServerMigrator 继承自 BaseMigrator实现了抽象的三阶段生命周期。这是整个 v2 迁移体系的统一契约每个领域迁移器都必须提供阶段职责McpServerMigrator 的实现要点prepare(ctx)干跑校验读取源数据、逐条变换、统计计数与跳过数遍历state.mcp.servers去重、过滤、调用transformMcpServer把结果暂存到preparedResults返回itemCount与 warningsexecute(ctx)执行实际写入事务内批量 INSERT报告进度以100 条一批的方式在单个事务内分批插入发布mcpServerIdMapping到ctx.sharedDatavalidate(ctx)校验数据完整性必须包含计数校验统计表中总数与preparedResults.length比对count_mismatch抽样 3 条检查id/name必填字段返回sourceCount/targetCount/skippedCount统计批处理与进度上报execute中定义了BATCH_SIZE 100将全部行按每批 100 条切分在单个事务ctx.db.transaction内完成所有批次插入见 McpServerMigrator.ts。这样做既避免单条插入的事务开销又保证整体原子性——任一约束违反都会回滚整个迁移。迁移完成后通过reportProgress(100, ...)上报 100% 进度并携带 i18n 消息键migration.progress.migrated_mcp_servers使迁移窗口 UI 可以显示本地化进度文案。空数据集时也必须发布映射execute的一个隐蔽但关键的设计即使preparedResults为空0 个服务器也必须向ctx.sharedData发布一个空Map的mcpServerIdMapping见 McpServerMigrator.ts。注释解释了原因下游的AssistantMigrator在助手仍引用已被删除的服务器时如果发现mcpServerIdMapping完全缺失会抛出致命错误而发布空映射后它能优雅地丢弃这些悬空引用而不是让整个迁移失败。测试用例 McpServerMigrator.test.ts 的should publish an empty id mapping when there are no servers专门验证了这一行为。校验阶段的两个检查点validate除计数比对期望值 preparedResults.length外还会对表中前 3 行抽样检查每行id与name是否齐全缺失即报错。这一抽样策略以低成本覆盖了必填列被意外写入空值的回归场景。测试中的should fail when sample has missing required fields与should fail on count mismatch分别验证了两类失败路径。执行顺序与协作为什么是 order 1.5迁移器的执行顺序属性定义为order 1.5。在 migratorRegistry.ts 的getAllMigrators()中各迁移器按order升序执行MCP 服务器迁移排在PreferencesMigrator1.0之后、AssistantMigrator2.0之前BootConfigMigrator → PreferencesMigrator → NoteMigrator → MiniAppMigrator → McpServerMigrator (1.5) → ProviderModelMigrator → AssistantMigrator → …这一顺序存在明确的数据依赖理由v1 的助手assistant配置中引用了 MCP 服务器 IDAssistantMigrator需要借助mcpServerIdMapping把旧 ID 重映射为新的 UUID。只有 McpServerMigrator 先完成写入并发布映射下游才能正确解析引用。这也解释了为什么空映射也必须发布——映射的存在性本身就是一个语义信号表示MCP 领域已迁移完毕。测试体系与可验证性McpServerMigrator 拥有两层测试保障单元变换测试McpServerMappings.test.ts聚焦transformMcpServer纯函数覆盖完整字段透传、最小对象、null/undefined 归一化、isActive默认值、空白 name 回退、空数组/空对象保留、baseUrl/url回退优先级、sortOrder赋值、以及 legacytype归一化的全部分支迁移器集成测试McpServerMigrator.test.ts通过createMockContext模拟 MigrationContextRedux 源数据、事务型 DB、sharedData Map验证元数据id/name/order、prepare 的计数与跳过逻辑、execute 的批量插入与空映射发布、事务抛错时的失败返回、validate 的计数与抽样校验。值得注意的测试细节should use the generated id as the name when a server has no valid name用例验证了 name 回退不是回退到旧 ID而是回退到新生成的 UUID断言row.name不等于源 ID 列表。对迁移器编写者的启示结合 v2 迁移系统总文档 中的新建迁移器指引与 McpServerMigrator 的实现可以归纳出本迁移器体现的可复用设计模式继承BaseMigrator实现prepare/execute/validate三阶段并在reset()中清理上次运行残留状态McpServerMigrator 会重置preparedResults与skippedCount因为 MigrationEngine 会复用迁移器实例以支持重试transform 逻辑与迁移器解耦领域映射放在mappings/目录的纯函数中便于独立单元测试数据库约束前置防御在变换层完成 CHECK 约束所需的归一化而不是把非法数据抛给数据库导致整批回滚共享数据契约通过ctx.sharedData发布下游依赖的 ID 映射并保证空结果也发布契约路径安全所有文件系统访问必须使用ctx.paths预计算常量严禁在迁移代码中直接调用app.getPath()详见 v2 迁移系统总文档 的 Path Safety 章节这是防止 v1 自定义 userData 目录用户数据看似丢失的强制要求。如果需要深入了解迁移引擎调度、版本兼容性门禁要求升级路径为v1.old → v1.last (≥1.9.12) → v2.0.x → v2.1、外键检查策略等整体机制可以进一步阅读 v2-migration-guideMCP 服务器实体的完整 Zod 类型定义位于 src/shared/data/types/mcpServer.ts可作为字段语义的权威参考。【免费下载链接】cherry-studioAI productivity studio with smart chat, autonomous agents, and 300 assistants. Unified access to frontier LLMs项目地址: https://gitcode.com/GitHub_Trending/ch/cherry-studio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Cherry Studio v2 数据迁移深度解析：McpServerMigrator 如何将 MCP 服务器配置从 Redux 迁移到 SQLite
Cherry Studio v2 数据迁移深度解析McpServerMigrator 如何将 MCP 服务器配置从 Redux 迁移到 SQLite【免费下载链接】cherry-studioAI productivity studio with smart chat, autonomous agents, and 300 assistants. Unified access to frontier LLMs项目地址: https://gitcode.com/GitHub_Trending/ch/cherry-studio本篇文章聚焦 Cherry Studio 桌面应用 v2 数据迁移体系中 MCPModel Context Protocol服务器配置的迁移实现。文章以 README-McpServerMigrator.md 为骨架结合 McpServerMigrator.ts、McpServerMappings.ts、mcpServer.ts 等源码与测试完整讲解数据来源、目标表结构、字段映射规则、边界条件处理、三阶段执行契约以及它在整个 v2 迁移管线中的位置与对外协作关系。读完本文你将能够理解 Cherry Studio 中 MCP 服务器配置从Redux 持久化到SQLite 关系型存储的完整迁移路径并掌握这套迁移器的设计原则与可复用模式。背景为什么要迁移 MCP 服务器配置Cherry Studio 的 v1 版本将应用状态保存在 Redux经 Redux Persist 写入 localStorage/磁盘而 v2 版本全面转向 SQLite 关系型数据库。MCPModel Context Protocol服务器是 Cherry Studio 接入外部工具能力的核心载体——用户手动配置的 stdio / SSE / streamableHttp 服务器、内置的 inMemory 服务器、它们的环境变量、启动命令、信任状态与启用状态等都是需要被完整保留的业务数据。McpServerMigrator 正是负责这一领域的数据迁移器它从 v1 的 Redux 状态切片state.mcp.servers读取全部 MCP 服务器对象经过字段变换后写入 v2 的mcp_server表。迁移的核心目标有三个数据不丢失用户配置的每一个服务器都要映射到 SQLite 表中同时生成可供下游迁移器使用的旧 ID → 新 ID 映射结构规范化v1 中松散的、未经过严格校验的字段如服务器type在迁移时被归一化以满足 v2 表结构上的 CHECK 约束依赖安全迁移器运行在AssistantMigrator之前确保助手assistant对 MCP 服务器的引用在重映射之后仍然有效。从源码结构看McpServerMigrator 位于 src/main/data/migration/v2/migrators/McpServerMigrator.ts是 v2 迁移体系中 16 个领域迁移器之一其完整注册顺序定义在 migratorRegistry.ts。数据来源与目标表来源Reduxstate.mcp.servers迁移器的prepare阶段通过ctx.sources.reduxState.get(mcp, servers)读取数据见 McpServerMigrator.ts。reduxState是 ReduxStateReader 的实例它在迁移准备阶段由渲染进程把 Redux Persist 切片导出为分类目录文件主进程按类别读取。来源路径说明Reduxstate.mcp.serversMcpServer 对象数组即 v1 用户配置的全部 MCP 服务器目标mcp_server表目标表定义于 src/main/data/db/schemas/mcpServer.ts基于 Drizzle ORM 的sqliteTable。表结构要点主键id类型为uuidPrimaryKey()UUID v4由数据库自动生成必填列nameNOT NULL、isActiveNOT NULL默认falseJSON 列args、env、headers、tags、configSample、disabledTools、disabledAutoApproveTools均以text({ mode: json })存储布尔列longRunning、shouldConfig、isActive、isTrusted以integer({ mode: boolean })存储时间戳列trustedAt、installedAt为整数时间戳毫秒级此外还通过createUpdateTimestamps自动附带createdAt/updatedAt索引mcp_server_name_idxname、mcp_server_is_active_idxisActive、mcp_server_sort_order_idxsortOrderCHECK 约束type必须是stdio、sse、streamableHttp、inMemory之一允许 NULLinstallSource必须是builtin、manual、ai_assisted、protocol、unknown之一允许 NULL。其中type与installSource的取值约束与 src/shared/data/types/mcpServer.ts 中的 Zod 枚举McpServerTypeSchema、McpServerInstallSourceSchema完全一致体现了共享类型 → 数据库约束的单一事实来源设计。字段映射从 camelCase 到 snake_case 的 1:1 变换文档明确指出所有 McpServer 字段在 Drizzle ORM 层面以 camelCase 属性名 1:1 映射底层 SQLite 列名自动使用 snake_case如baseUrl→base_url由 Drizzle 自动处理迁移代码无需手写列名转换。映射实现位于 src/main/data/migration/v2/migrators/mappings/McpServerMappings.ts核心函数为transformMcpServer(source, index)它接收一个旧的 Redux 服务器对象和序号index返回{ row, oldId }。完整的字段映射表如下源字段目标列变换规则idid不直接透传生成新的 UUID v4 作为主键旧 ID 记录在oldId中用于下游重映射namename优先使用源name缺失/空串/纯空白时回退为生成的新idtoRequiredString实现typetype可空透传但经过类型归一化见下文type 归一化descriptiondescription可空透传toNullablebaseUrl/urlbaseUrl优先取baseUrl缺失时回退到url兼容旧版 SSE 服务器commandcommand可空透传registryUrlregistryUrl可空透传argsargsJSON 数组envenvJSON 对象headersheadersJSON 对象providerprovider可空透传providerUrlproviderUrl可空透传logoUrllogoUrl可空透传tagstagsJSON 数组longRunninglongRunning可空布尔timeouttimeout可空整数dxtVersiondxtVersion可空透传dxtPathdxtPath可空透传referencereference可空透传searchKeysearchKey可空透传configSampleconfigSampleJSON 对象McpConfigSample含command、args、可选envdisabledToolsdisabledToolsJSON 数组disabledAutoApproveToolsdisabledAutoApproveToolsJSON 数组shouldConfigshouldConfig可空布尔isActiveisActive布尔缺失时默认false写入后 NOT NULLinstallSourceinstallSource可空透传isTrustedisTrusted可空布尔trustedAttrustedAt可空整数时间戳installedAtinstalledAt可空整数时间戳无sortOrder由变换函数传入的序号index赋值sortOrder: index保持源数组顺序type归一化为什么不能直接透传表结构上的 CHECK 约束把type限制在当前枚举但 v1 的 Redux 状态从未在写入后针对最新枚举重新校验——例如 v1 曾短暂允许字面量http/streamable_http且不受校验的代码路径可能混入任意字符串。若直接透传任何一个非法值都会让整批 INSERT 因 CHECK 约束失败而中止迁移。toMcpServerType函数见 McpServerMappings.ts复刻了 v1 自身的归一化逻辑非字符串 →null命中stdio/sse/streamableHttp/inMemory→ 原样保留其余包含http子串的字符串 → 统一折叠为streamableHttp其余无法识别的字符串 → 置为null而不是让整批插入失败。测试用例 McpServerMappings.test.ts 中的legacy type normalization参数化用例完整覆盖了这一规则http、streamable_http、streamable-http均映射为streamableHttp而、websocket、unknown-type映射为null。两个关键变换工具函数映射文件内定义了两个通用工具toNullableT(value)value ?? null把undefined/null统一归一为 SQLite 的NULLtoRequiredString(value, fallback)仅当值为非空字符串trim().length 0时保留否则使用回退值——这正是name 缺失时回退到新 id的实现基础。跳过与不迁移的数据跳过字段运行时派生状态字段原因V2 目标isUvInstalled、isBunInstalled由实时二进制可用性派生属于运行时缓存不持久化这两个字段表示当前环境是否安装了 uv / bun 运行时本质上是运行环境探测结果而非用户业务数据。v2 中它们会在运行时重新探测持久化反而会导致过期判断。不迁移数据可再生的缓存来源原因V2 目标Dexiemcp:provider:*:servers由 provider API 重新拉取单独 PR 处理这类数据是某类 provider 通过 API 返回的 MCP 服务器列表缓存迁移器不会将其固化而是在运行时重新获取。边界条件与防御式处理prepare阶段逐条遍历源数组并建立seenIds去重集合文档列出的边界条件在代码中均有对应实现见 McpServerMigrator.ts缺失id跳过该条并记录 warningSkipped server without valid id空id同样跳过typeof s.id ! string或空串判定重复id保留首条后续重复条目跳过Skipped duplicate server idname缺失/空串/纯空白使用生成的新 UUID 作为迁移后的name由toRequiredString保证isActive缺失默认false可选字段为undefined/null统一存储为 SQLiteNULL。全量失败策略一个值得注意的设计如果skippedCount 0且preparedResults.length 0且源数组非空prepare直接返回success: false即全部条目都被跳过时整个迁移器判定失败避免把迁移失败静默包装成迁移了 0 条。反之只要至少有一条成功准备即使部分条目被跳过迁移仍继续被跳过的条目记录在 warnings 中。这一点在 McpServerMigrator.test.ts 的should fail when all servers are skipped用例中得到了验证。源数据形状防御prepare还对源数据形状做了防御mcp.servers不是数组如字符串→ 记录 warningmcp.servers is not an array视为 0 条处理mcp类别缺失或servers键缺失 → 视为空数组正常返回itemCount: 0单条数据变换抛异常如结构异常→ 跳过该条并记录 warning不中断整体迁移。三阶段执行契约prepare / execute / validateMcpServerMigrator 继承自 BaseMigrator实现了抽象的三阶段生命周期。这是整个 v2 迁移体系的统一契约每个领域迁移器都必须提供阶段职责McpServerMigrator 的实现要点prepare(ctx)干跑校验读取源数据、逐条变换、统计计数与跳过数遍历state.mcp.servers去重、过滤、调用transformMcpServer把结果暂存到preparedResults返回itemCount与 warningsexecute(ctx)执行实际写入事务内批量 INSERT报告进度以100 条一批的方式在单个事务内分批插入发布mcpServerIdMapping到ctx.sharedDatavalidate(ctx)校验数据完整性必须包含计数校验统计表中总数与preparedResults.length比对count_mismatch抽样 3 条检查id/name必填字段返回sourceCount/targetCount/skippedCount统计批处理与进度上报execute中定义了BATCH_SIZE 100将全部行按每批 100 条切分在单个事务ctx.db.transaction内完成所有批次插入见 McpServerMigrator.ts。这样做既避免单条插入的事务开销又保证整体原子性——任一约束违反都会回滚整个迁移。迁移完成后通过reportProgress(100, ...)上报 100% 进度并携带 i18n 消息键migration.progress.migrated_mcp_servers使迁移窗口 UI 可以显示本地化进度文案。空数据集时也必须发布映射execute的一个隐蔽但关键的设计即使preparedResults为空0 个服务器也必须向ctx.sharedData发布一个空Map的mcpServerIdMapping见 McpServerMigrator.ts。注释解释了原因下游的AssistantMigrator在助手仍引用已被删除的服务器时如果发现mcpServerIdMapping完全缺失会抛出致命错误而发布空映射后它能优雅地丢弃这些悬空引用而不是让整个迁移失败。测试用例 McpServerMigrator.test.ts 的should publish an empty id mapping when there are no servers专门验证了这一行为。校验阶段的两个检查点validate除计数比对期望值 preparedResults.length外还会对表中前 3 行抽样检查每行id与name是否齐全缺失即报错。这一抽样策略以低成本覆盖了必填列被意外写入空值的回归场景。测试中的should fail when sample has missing required fields与should fail on count mismatch分别验证了两类失败路径。执行顺序与协作为什么是 order 1.5迁移器的执行顺序属性定义为order 1.5。在 migratorRegistry.ts 的getAllMigrators()中各迁移器按order升序执行MCP 服务器迁移排在PreferencesMigrator1.0之后、AssistantMigrator2.0之前BootConfigMigrator → PreferencesMigrator → NoteMigrator → MiniAppMigrator → McpServerMigrator (1.5) → ProviderModelMigrator → AssistantMigrator → …这一顺序存在明确的数据依赖理由v1 的助手assistant配置中引用了 MCP 服务器 IDAssistantMigrator需要借助mcpServerIdMapping把旧 ID 重映射为新的 UUID。只有 McpServerMigrator 先完成写入并发布映射下游才能正确解析引用。这也解释了为什么空映射也必须发布——映射的存在性本身就是一个语义信号表示MCP 领域已迁移完毕。测试体系与可验证性McpServerMigrator 拥有两层测试保障单元变换测试McpServerMappings.test.ts聚焦transformMcpServer纯函数覆盖完整字段透传、最小对象、null/undefined 归一化、isActive默认值、空白 name 回退、空数组/空对象保留、baseUrl/url回退优先级、sortOrder赋值、以及 legacytype归一化的全部分支迁移器集成测试McpServerMigrator.test.ts通过createMockContext模拟 MigrationContextRedux 源数据、事务型 DB、sharedData Map验证元数据id/name/order、prepare 的计数与跳过逻辑、execute 的批量插入与空映射发布、事务抛错时的失败返回、validate 的计数与抽样校验。值得注意的测试细节should use the generated id as the name when a server has no valid name用例验证了 name 回退不是回退到旧 ID而是回退到新生成的 UUID断言row.name不等于源 ID 列表。对迁移器编写者的启示结合 v2 迁移系统总文档 中的新建迁移器指引与 McpServerMigrator 的实现可以归纳出本迁移器体现的可复用设计模式继承BaseMigrator实现prepare/execute/validate三阶段并在reset()中清理上次运行残留状态McpServerMigrator 会重置preparedResults与skippedCount因为 MigrationEngine 会复用迁移器实例以支持重试transform 逻辑与迁移器解耦领域映射放在mappings/目录的纯函数中便于独立单元测试数据库约束前置防御在变换层完成 CHECK 约束所需的归一化而不是把非法数据抛给数据库导致整批回滚共享数据契约通过ctx.sharedData发布下游依赖的 ID 映射并保证空结果也发布契约路径安全所有文件系统访问必须使用ctx.paths预计算常量严禁在迁移代码中直接调用app.getPath()详见 v2 迁移系统总文档 的 Path Safety 章节这是防止 v1 自定义 userData 目录用户数据看似丢失的强制要求。如果需要深入了解迁移引擎调度、版本兼容性门禁要求升级路径为v1.old → v1.last (≥1.9.12) → v2.0.x → v2.1、外键检查策略等整体机制可以进一步阅读 v2-migration-guideMCP 服务器实体的完整 Zod 类型定义位于 src/shared/data/types/mcpServer.ts可作为字段语义的权威参考。【免费下载链接】cherry-studioAI productivity studio with smart chat, autonomous agents, and 300 assistants. Unified access to frontier LLMs项目地址: https://gitcode.com/GitHub_Trending/ch/cherry-studio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考