Cherry Studio v2 数据迁移系统深度解析:从 Redux/Dexie 到 SQLite 的一次性升级引擎
Cherry Studio v2 数据迁移系统深度解析:从 Redux/Dexie 到 SQLite 的一次性升级引擎
本文深入解析 Cherry Studio 开源仓库中 v1 → v2 数据迁移系统的设计与实现。这套位于 src/main/data/migration/v2 的一次性迁移引擎,负责把 v1 时代基于 Dexie(IndexedDB)与 Redux Persist 的本地存储,安全、可验证地搬入 v2 的 SQLite 新架构,并配套了版本升级门控、路径安全约定、Migrator 插件契约与 IPC 迁移向导。读完本文,你将掌握迁移引擎的整体架构、版本门控规则、MigrationPaths 路径安全红线、Migrator 三阶段契约(prepare/execute/validate)、外键处理策略,以及如何在 Cherry Studio 中正确新增一个领域 Migrator。
迁移系统概览:为什么需要一次"一次性"迁移
Cherry Studio v2.0.0 引入了全新的数据架构:旧版本(v1)将业务数据分散存放在浏览器级存储中——Dexie(IndexedDB) 承载表格型数据、Redux Persist 承载应用状态切片、localStorage 承载少量键值,同时还有独立的 agents.db、~/.cherrystudio/config/config.json 与 Claude Agent SDK 的 .claude 目录。v2 将这些数据统一收敛进单文件 SQLite 数据库({userData}/Data/cherrystudio.sqlite,经由 migrations/sqlite-drizzle 的 Drizzle 迁移脚本建表)。
数据迁移系统正是完成这次"存储范式切换"的桥梁。按 v2-migration-guide.md 的定位,这套模块"拥有编排、数据访问辅助、Migrator 插件与渲染进程迁移窗口使用的 IPC 入口",其模块说明位于 src/main/data/migration/v2/README.md。整个系统的目录结构如下:
src/main/data/migration/v2/
├── core/ # MigrationEngine, MigrationContext, MigrationPaths
├── migrators/ # Domain-specific migrators
│ └── mappings/ # Mapping definitions
├── migrationDiagnosticBundle.ts # Migration diagnostic ZIP builder
├── utils/ # ReduxStateReader, DexieFileReader, JSONStreamReader, LegacyHomeConfigReader
├── window/ # IPC handlers, window manager
└── index.ts # Public exports
其中 core/ 承担引擎与共享上下文,migrators/ 是各业务领域的迁移器及字段映射定义,utils/ 提供各类遗留数据源读取器,window/ 承载迁移窗口管理与 IPC,migrationDiagnosticBundle.ts 负责生成迁移诊断 ZIP 包。主进程与渲染进程共享的类型定义统一放在 src/shared/data/migration/v2/types.ts(迁移阶段、进度、结果、状态、IPC 通道等)。
版本升级门控:强制线性升级路径
迁移窗口创建之前,系统会先用 core/versionPolicy.ts 校验升级路径,捕获那些绕过自动更新器版本过滤的手动安装场景。
必选升级路径为:
v1.old → v1.last (≥1.9.12) → v2.0.x → v2.1+
为什么要求线性路径
v2.0.0 引入一次性数据迁移,且每个 v2.0.x 补丁都完整保留该迁移并叠加修复。若允许从任意 v1 版本直接升级,迁移代码就需要面对 O(n²) 的源数据格式组合;强制所有用户先升到最终 v1 版本,迁移代码只需处理单一源数据格式,测试矩阵随之收敛。
门控如何工作
- VersionService 自 v1.7 起内嵌,每次版本变化的启动都会向
{userData}/version.log写入一条记录; - v2 首次启动时,门控通过
MigrationPaths.versionLogFile(解析后的路径,已考虑 v1 自定义目录)读取version.log; - 若上一版本过旧、缺失,或用户跳过了 v2.0.x 迁移线,门控弹出错误对话框并退出。
versionPolicy.ts 中的核心判定函数 checkUpgradePathCompatibility 实现了三条阻塞规则,与 v2-migration-guide.md 中的规则表一一对应:
| 规则 | 触发条件 | 原因 | 用户动作 |
|---|---|---|---|
no_version_log |
存在遗留数据但缺少 version.log |
用户从未运行过内嵌 VersionService(v1.7 起)的 v1 版本 | 安装 v1.last 并至少运行一次 |
v1_too_old |
previousVersion < 1.9.12 |
数据尚未处于最终 v1 形态 | 先升级到 v1.last |
v2_gateway_skipped |
previousVersion < 2.0.0 且 coerce 后的当前版本 ≥ 2.1.0 |
跳过了 v2.0.x 迁移线 | 先安装最新 v2.0.x 版本 |
预发布版本的特殊处理
v2.0.0 的预发布(alpha/beta/rc)按 semver 排序视为 2.0.0 之前:
- v1.last → v2.0.0-alpha 被允许(门控对
currentVersion做 semver coerce,coerce('2.0.0-alpha')得到2.0.0,因此gte('2.0.0', '2.1.0')为 false,不会误拦截安装预发布版本的 v1 用户); - 预发布 → 预发布升级可行,因为首次成功运行后迁移状态已为
completed; - 完整 v2.0.x 系列是已验证的直接迁移目标;v2.1.0 及以后在迁移兼容性被显式验证前继续处于阻塞状态。
从源码看,previousVersion 不参与 coerce(semver.lt(previousVersion, V1_REQUIRED_VERSION) 直接比较原始值),version.log 每行格式为 version|os|environment|packaged|mode|timestamp,readPreviousVersion 自文件尾部向前扫描,返回与当前版本不同的最近版本;损坏行会被静默跳过并告警。
与自动更新器的关系
自动更新器(AppUpdaterService)会把已安装版本与客户端元数据上报给托管发布服务(见 docs/contrib/app-upgrade.md),由服务端选择 OTA 目标并强制升级网关。迁移门控则是独立的安全网,专门拦截手动下载安装的用户——两套系统各自强制兼容升级路径,但互不依赖。
路径安全红线:一律使用 MigrationPaths
⚠️ 警告:不使用预定义路径可能导致用户数据丢失。
v1 用户可能通过 ~/.cherrystudio/config/config.json 配置了自定义 userData 目录。如果迁移代码直接调用 app.getPath('userData') 或 new Store(),在 v2 首次启动时会读到 Electron 默认路径而非用户真实数据目录,导致迁移被静默跳过或迁移空数据,让用户数据"看起来丢失了"。
因此 core/MigrationPaths.ts 定义了全部迁移关键路径的只读常量对象 MigrationPaths,迁移代码必须使用其中的路径字段,严禁直接调用 app.getPath() 或自行 path.join() 拼接路径:
| 正确 ✅ | 错误 ❌ |
|---|---|
ctx.paths.userData |
app.getPath('userData') |
ctx.paths.databaseFile |
path.join(app.getPath('userData'), 'Data', 'cherrystudio.sqlite') |
ctx.paths.legacyClaudeConfigDir |
path.join(ctx.paths.userData, '.claude') |
ctx.paths.legacyClaudeProjectsDir |
path.join(ctx.paths.userData, '.claude', 'projects') |
ctx.paths.claudeConfigDir |
path.join(ctx.paths.userData, 'Data', 'Agents', '.claude') |
ctx.paths.claudeProjectsDir |
path.join(ctx.paths.userData, 'Data', 'Agents', '.claude', 'projects') |
ctx.paths.knowledgeBaseDir |
path.join(app.getPath('userData'), 'Data', 'KnowledgeBase') |
ctx.paths.legacyConfigFile |
path.join(os.homedir(), '.cherrystudio', 'config', 'config.json') |
new Store({ cwd: ctx.paths.userData }) |
new Store() |
MigrationPaths 在迁移门控入口由 resolveMigrationPaths() 一次性解析(包含 v1 遗留 userData 目录检测),随后通过 MigrationContext.paths 传递给所有 Migrator。如果需要新路径,应将其加入 MigrationPaths 接口,而非在代码里内联拼接。它被 Object.freeze() 冻结,所有字段均为只读。
旧数据目录的探测与选择逻辑
resolveMigrationPaths() 的核心流程(源码 MigrationPaths.ts):
- 以 preboot 阶段
resolveUserDataLocation()设置好的当前app.getPath('userData')为起点; - 读取
~/.cherrystudio/config/config.json中的遗留appDataPath(兼容旧版字符串形态与新版{ executablePath, dataPath }[]数组形态); - 若发现有效自定义路径且与当前路径不同,调用
app.setPath('userData', ...)重定向,并预写 boot-config.json,保证下次启动无需回退即可解析;同时通过pinUserDataPath()以严格持久化(写失败即抛错)写入app.user_data_path,避免静默失败导致重启回到旧目录; - 若自定义路径不可达(外置盘未挂载、权限变化),回退默认路径,并通过
inaccessibleLegacyPath回报给调用方提醒用户; - 由最终 userData 预计算全部派生路径,冻结后返回。
选择逻辑由纯函数 selectLegacyUserData 完成(按命中顺序):A0 当前目录已有非空 sqlite 则保留;A1 存在精确的 exe→dir 映射则直接采纳(权威、不做模糊猜测);B1 存在"可用 ∧ 含 v1 数据 ∧ 版本合格"的目录则重定向到最近使用的一个并提示;B2 候选存在但版本被阻塞仍重定向(交给版本门控拦截);B3 无候选但存在不可达目录则弹窗询问;B4 无任何可恢复数据则走默认流程。legacyDataConfirmed 是最终解析目录的纯属性(存在 version.log、Chromium 存储或非空 config.json 即确认含 v1 数据),引擎在 needsMigration() 中读取它,避免把含真实 v1 数据的目录误判为"全新安装"而永久锁定为 completed。
唯一窄例外:应用日志输出
迁移诊断需要读取应用自身日志输出(而非 v1/v2 迁移源数据)。这一改动记录了一个窄例外:日志必须通过 application.getPath('app.logs') 解析,且不得加入 MigrationPaths。除此之外,不放松任何更宽泛的迁移文件系统访问规则。
核心编排引擎 MigrationEngine
core/MigrationEngine.ts 是迁移的总指挥:按序协调所有 Migrator、向 UI 上报进度,并以 app_state.key = 'migration_v2_status' 作为唯一持久迁移标记。其运行生命周期如下:
- 初始化:
initialize(paths, legacyDataConfirmed)创建裸数据库连接(MigrationDbService),不依赖应用生命周期系统; - 需求判定:
needsMigration()优先读持久化状态——completed则跳过;无状态时以legacyDataConfirmed || hasLegacyData()区分"全新安装"与"带旧数据升级",全新安装直接markCompleted(false); - 执行前清表:
verifyAndClearNewTables()检查并清空MIGRATION_TARGET_TABLES中列出的新架构表(顺序敏感:子表先于父表清理,例如user_model先于user_provider、message先于topic、assistant_mcp_server/assistant_knowledge_base联结表先于assistant,agent_task/agent_task_run_log已废弃、改为迁移到 JobManager); - 逐 Migrator 三阶段执行:prepare → execute → validate,每个阶段失败即中止;
- 最终校验:全库
PRAGMA foreign_key_check兜底; - 状态落库:成功
markCompleted(true),失败markFailed(error);失败尝试与成功/失败路径都会清理注册的 staging 导出目录,避免遗留大型 Redux/Dexie 快照。
进度计算采用 Migrator 等权模型:100 / migrators.length * 已完成数 + 当前 Migrator 进度占比,每个 Migrator 的状态(pending/running/completed)都会随 MigrationProgress 推送给迁移窗口。引擎对外暴露单例 migrationEngine,并注册了 registerMigrationOriginReader(() => migrationEngine.isMigratedFromV1()) 供其他模块查询是否经历过 v1→v2 迁移。
跳过迁移:干净的"放弃旧数据"
skipMigration() 是迁移失败/用户放弃时的重要路径:先把 v1 派生的启动键 app.disable_hardware_acceleration 重置为默认值(保证跳过后再也不复现迁移弹窗),再在单个事务内清空全部迁移目标表并写入 status=completed, migratedFromV1=false,让下次启动以全新默认 v2 状态引导(seeders 会重建默认数据)。v1 源数据与已拷贝文件原样保留在磁盘上。
Migrator 契约:prepare / execute / validate
所有领域 Migrator 继承 migrators/BaseMigrator.ts,实现四个元数据字段与三个阶段方法:
| 要素 | 说明 |
|---|---|
id / name / description / order |
标识、UI 显示名、描述与执行顺序(order 小者先执行) |
prepare(ctx) |
干跑检查、统计计数与暂存数据,返回 PrepareResult |
execute(ctx) |
执行插入/更新,自行管理事务,通过 reportProgress 上报进度,末尾对自有表做 assertOwnedForeignKeys 自检,返回 ExecuteResult |
validate(ctx) |
校验数量与完整性,返回含 sourceCount / targetCount / skippedCount 统计及 errors 的 ValidateResult |
引擎按 order 排序后依次执行。当前注册的执行顺序为(见 migrators/migratorRegistry.ts):BootConfigMigrator → PreferencesMigrator → NoteMigrator → MiniAppMigrator → McpServerMigrator → ProviderModelMigrator → AssistantMigrator → FileMigrator → AgentsMigrator → KnowledgeMigrator → KnowledgeVectorMigrator → ChatMigrator → AiUsageRecordMigrator → PaintingMigrator → TranslateMigrator → PromptMigrator,共 16 个。
关键约定:
- 所有日志通过
loggerService携带 Migrator 专属上下文输出; - 数据访问一律走
MigrationContext.sources(ElectronStoreReader、ReduxStateReader、DexieFileReader、DexieSettingsReader、LocalStorageReader、KnowledgeVectorSourceReader、LegacyHomeConfigReader),不直接触碰原始文件; - Migrator 间用
ctx.sharedData(Map)传递跨域引用(如 assistant → chat 的 ID 映射),避免重复读取源; - 大型 Dexie 导出用
JsonStreamReader流式读取并批量插入,防止内存尖峰; - 数量校验是强制的:
targetCount < sourceCount - skippedCount或ValidateResult.errors非空即判定失败; - 迁移保持幂等:引擎开跑前已清空目标表,但每个 Migrator 仍需容忍同次运行内的重试;
- 保留 v1 源以兼容降级:
AgentsMigrator把遗留 Agent 文件复制进 v2 布局,但永不删除agents.db或遗留短 ID 工作区; BootConfigMigrator是文件目标例外:它把早期启动设置写入bootConfigService,其余 Migrator 填充 SQLite 或基于知识库的索引产物。
AssistantMigrator 还负责 v1 助手标签分组迁移:在同一事务中插入 group(entityType='assistant') 行并把生成的 ID 回填到 assistant.groupId。各 Migrator 的专属迁移细节(源格式、恢复规则、变换逻辑)记录在 migrators/README-<name>.md 系列文档中,注册表是执行集合的权威来源。
迁移上下文与数据源读取器
core/MigrationContext.ts 构建传递给每个 Migrator 的共享上下文:sources(上述全部读取器)、db(当前 SQLite 连接)、paths、sharedData、logger。上下文创建时会预加载 Dexie settings 表与 localStorage 导出文件到内存,便于同步访问。utils/ 下的读取器各有分工:ReduxStateReader.ts 提供按分类 Redux Persist 导出文件的点路径安全访问;DexieFileReader.ts 读取导出的 Dexie JSON 表(支持大表流式);JsonStreamReader.ts 提供批处理、计数与采样;LegacyHomeConfigReader.ts 同步读取 v1 配置文件并归一化 appDataPath 字段,仅供 BootConfigMigrator 的 'configfile' 源使用。
外键处理策略:整体关闭 + 双层校验
迁移期间引擎将 foreign_keys 保持为 OFF:core/MigrationDbService.ts 在 applyMigrations 之后、连接就绪前设置一次 sqlite.pragma('foreign_keys = OFF')。由于 better-sqlite3 在整个进程内保持单一持久连接,该 pragma 对整个迁移持续生效,无需按事务重放——这允许批量插入携带尚未解析的引用(如自引用的 message.parentId,或由后续 Migrator 解决的跨域引用)。Migrator 严禁自行切换 FK 开关。
完整性通过两层验证:
- Migrator 自检:每个 Migrator 在
execute()末尾调用this.assertOwnedForeignKeys(ctx.db, [...]),对其自有且引用已完全解析的表执行定向PRAGMA foreign_key_check("<table>"),尽早暴露归因清晰的失败。注意自检范围必须排除由后续 Migrator 解决的跨域延迟引用与共享多态表——例如assistant_knowledge_base.knowledgeBaseId由AssistantMigrator写入、但要等KnowledgeMigrator重映射/裁剪后才有效,因此该表由KnowledgeMigrator自检。专用的文件关联表(如chat_message_file_ref)由同时拥有源行与引用行的 Migrator 自检。 - 引擎兜底:全部 Migrator 完成后,
MigrationEngine.verifyForeignKeys()对全库执行一次PRAGMA foreign_key_check,任一违规即抛错中止(样本展示前 5 条table(rowid)→parent)。
MigrationDbService 同时负责数据库文件完整性保障(删除 0 字节 sqlite 与孤儿 -wal/-shm 辅助文件)、WAL 模式与 synchronous=NORMAL 配置,并校验 Drizzle 迁移目录存在(打包缺失时会明确报错)。正常运行时由 DbService 自己的连接(foreign_keys = ON)接管,迁移连接在结束时关闭,约束恢复隐式完成。
Order-Key 盖章机制
遗留 Redux/Dexie → SQLite 的可排序资源 Migrator 必须为插入的每一行生成 order_key。utils/orderKey.ts 提供两个纯函数,只接收已扁平化的数组、返回附带 orderKey 的新数组,全程不触碰数据库:
| 辅助函数 | 形态 | 适用场景 |
|---|---|---|
assignOrderKeysInSequence(rows) |
每行一个单调递增的 orderKey |
全表排序(如 mcp_server、user_provider、miniapp) |
assignOrderKeysByScope(rows, getScope) |
按作用域键分组,各组独立编号 | 分区表(如 user_model.providerId、group.entityType) |
模式——先扁平化、后盖章:保持 transform* 函数纯净(不带 index 参数、不收 sortOrder),把遗留源扁平化为数组后再盖章:
import { assignOrderKeysByScope, assignOrderKeysInSequence } from '@data/migration/v2/utils/orderKey'
// 之前——每个 transform 带 index 并输出 sortOrder
const rows = legacyServers.map((src, i) => transformMcpServer(src, i).row)
// 之后——transform 保持纯净;扁平化后统一盖章
const rows = legacyServers.map((src) => transformMcpServerV2(src).row)
const stamped = assignOrderKeysInSequence(rows)
tx.insert(mcpServerTable).values(stamped).run()
// 分区示例——每个 providerId 成为独立编号空间
const stamped = assignOrderKeysByScope(userModels, (m) => m.providerId)
导入红线:Migrator 代码严禁直接引入 fractional-indexing,必须经由 src/main/data/services/utils/orderKey.ts 导出的 generateOrderKeySequence(Migrator 辅助函数、迁移脚本、Drizzle 自定义迁移回调统一从这里再导入),保证第三方库边界可审计、字符集或实现可在一处切换。迁移窗口之外的运行时对应物(insertWithOrderKey / insertManyWithOrderKey / applyMoves / resetOrder)参见 data-ordering-guide.md 的「Server-Side Service Helpers」章节。
Renderer 导出与 IPC 集成
window/MigrationIpcHandler.ts 为迁移 UI 暴露 IPC 通道,负责管理导出暂存目录、校验写入、启动引擎并把进度流式回传。核心通道定义在 src/shared/data/migration/v2/types.ts 的 MigrationIpcChannels 常量中。
Renderer 导出内存约束
迁移渲染进程通过有界的 IPC 分块写入选定的 Redux Persist 切片与 Dexie 记录:Redux 以"分类目录"方式交给主进程,localStorage 导出仅限迁移映射实际拥有的键(共享常量 MIGRATION_LOCAL_STORAGE_KEYS = ['onboarding-completed'])。禁止恢复整态解析,也不得把 persist:cherry-studio 纳入通用 localStorage 导出——否则迁移开始前就会遗留同一份旧状态的重复拷贝。
导出路径归主进程所有:migration:prepare-export 通道在每次尝试前清空注册的暂存目录并返回这些路径;migration:write-export-file 通道校验发送者(validateSender)、导出目录白名单(path.resolve 精确比对)、表名白名单(/^[A-Za-z0-9_-]+$/)与写入模式(overwrite/append)。文件写入、迁移启动与清理代码绝不接受未经校验的渲染进程自选路径——assertStartMigrationPayload 还会在启动时逐项比对三个导出路径与主进程预注册路径。
完整的 IPC 通道面
- 状态查询:
migration:check-needed、migration:get-progress、migration:get-last-error; - 流程控制:
migration:start、migration:prepare-export、migration:start-migration、migration:retry、migration:cancel、migration:restart、migration:skip-migration、渲染进程 OOM 诊断面包屑migration:report-export-stage、本地失败镜像migration:report-error; - 文件传输(Renderer → Main):
migration:write-export-file、migration:save-diagnostic-bundle、migration:show-diagnostic-bundle-in-folder、按语言选择区域 v1 下载页的migration:open-download-page; - 窗口控制:
migration:minimize、migration:close-window、流内关闭确认migration:confirm-close/migration:confirm-quit/migration:cancel-close; - 进度广播(Main → Renderer):
migration:progress、migration:export-progress。
写入安全与并发防护
主进程对迁移写操作做了严格的并发与退出保护:inFlightMigration 防止迁移/跳过并发执行(并发抛 'Migration is already in progress.');requestQuit() 在迁移写入进行中把退出推迟到 allSettled 完成,杜绝"写一半被终止";阶段在引擎开始破坏性清表前就从不受保护的 introduction 切换到受保护的 migration 阶段,避免窗口关闭绕过退出保护。SkipMigration 会先确保暂存目录清理成功,再持久化 status=completed,防止下次启动绕过迁移流程后永远无法重试清理。
迁移完成后,MigrationWindowManager(window/MigrationWindowManager.ts)创建无边框迁移窗口并管理其生命周期,生产环境下完成后执行重启指令。
迁移诊断包
只有渲染进程的错误/版本不兼容页面可以请求诊断包(无原生 preboot 入口;migration:save-diagnostic-bundle 会校验当前阶段必须是 error 或 version_incompatible)。诊断包包含最小系统信息 + 单个日志日期的稳定快照:优先使用失败面板挂载时的本地日期,否则选择最近的合格日期,绝不混用日期。若无法形成完整快照,则仅发布元数据,且只有目标可被证明安全时才会在 UI 中披露该结果;若无法确立目标或源身份,保存失败且不会覆盖现有文件。元数据排除失败堆栈、路径与运行/进程字段。日志可能敏感,不得公开分享或向 Cherry Studio 支持渠道之外传播。
新增 Migrator 的完整清单
结合 v2-migration-guide.md 与 README 的快速参考,新增一个领域 Migrator 的步骤为:
- 在
migrators/下继承BaseMigrator; - 实现
prepare、execute、validate三阶段,显式计数、批量插入与完整性检查; - 需要时在
migrators/mappings/下添加映射定义; - 通过
reportProgress接入进度上报,让 UI 展示每个 Migrator 的进度; - 将 Migrator 以正确的
order注册进 migrators/migratorRegistry.ts 的getAllMigrators()列表; - 新目标表出现后,将其加入
MigrationEngine.verifyAndClearNewTables(即MIGRATION_TARGET_TABLES,注意子表先于父表); execute()末尾通过this.assertOwnedForeignKeys(ctx.db, [...])自检自有表外键,排除跨域延迟引用与共享多态表;不要自行切换PRAGMA foreign_keys;- 全程使用
ctx.paths获取文件系统路径——严禁直接调用app.getPath(); - 文档化不易察觉的不变量与变换理由(不叙述实现细节);源格式、恢复或变换规则无法从通用契约推断时,创建
migrators/README-<MigratorName>.md。
关键契约速记:prepare(ctx) 干跑检查并返回计数;execute(ctx) 执行插入并上报进度;validate(ctx) 校验数量与完整性。
总结
Cherry Studio 的 v2 数据迁移系统是一个工程化程度很高的"一次性"升级基础设施:MigrationPaths 用路径安全红线杜绝自定义 userData 场景下的数据丢失;versionPolicy 用线性升级门控把源数据格式收敛为单一形态;MigrationEngine + BaseMigrator 插件契约把 16 个领域的迁移拆分为可独立测试的 prepare/execute/validate 三阶段;整体 FK OFF + 双层校验既保证了批量插入性能又守住了引用完整性;有界 IPC 分块与主进程路径白名单让渲染进程导出在安全边界内完成。对于任何需要理解或扩展 Cherry Studio 数据层升级流程的开发者,src/main/data/migration/v2/README.md、v2-migration-guide.md 与 core/、migrators/、utils/、window/ 下的源码及其 __tests__(如 MigrationEngine.test.ts、MigrationPaths.test.ts、versionPolicy.test.ts、orderKey.test.ts、MigrationIpcHandler.test.ts)构成了完整的学习与验证路径。