人工智能大模型AI 应用交互助手本地部署【免费下载链接】cherry-studio Cherry Studio 是一款支持多个 LLM 提供商的桌面客户端项目地址https://gitcode.com/CherryHQ/cherry-studio点击查看免费下载本文基于 Cherry Studio 开源仓库中的全局重构追踪文档 v2-todo.md 展开系统梳理 v1→v2 重构中所有**跨切面Cross-Cutting**任务Redux / Dexie / ElectronStore 三套 v1 数据栈的退役、antd / styled-components 向cherrystudio/ui的收敛、14 个数据迁移器Migrator的收尾、Schema 迁移 SQL 的再生成、约 78 处deprecated站点的清理以及发布前的整目录清理流程。读完本文你将掌握这次大型重构的整体推进顺序、各任务的状态判定方法以及每项工作背后对应的源码实现位置可作为二次开发与升级维护时的索引地图。一、重构全景一份只跟踪全局任务的作战文档在 Cherry Studio 仓库中v2 重构的文档组织遵循一个明确原则全局性、跨模块的任务集中在 v2-todo.md 一处追踪模块内部的细粒度 TODO 则保留在各模块自己的文档中不在此重复。因此这份文档的定位是顶层作战地图而不是逐文件清单。文档开篇给出了两个使用前提理解它们对正确阅读本指南至关重要计数是近似值文中所有文件数、slice 数、匹配数均来自代码扫描会随开发推进漂移执行前需要重新验证状态图例✅ done已完成 todo待办 in progress进行中。文档的 Overview 总表是整份重构的目录级快照CategoryScaleStatusRemove Redux~100 files / 28 slices✅ donestore/deletedRemove Dexie~50 files mostly migrated, fallback paths pendingRemove ElectronStore~10 files awaiting migration-window closeRemove antd~145 files settings/knowledge pages already cleanRemove styled-components~112 files in progressMigrator finalization4 explicit todos 14 migrators mostly completeSchema / migration SQL regenrelease gate before release从这张表可以读出整次重构的骨架数据层三栈拆除 UI 层两库迁移 迁移器与 Schema 收尾 发布清理。下文按这四个维度逐一展开。二、数据层拆除Redux / Dexie / ElectronStore 三栈退役v2 数据层的目标非常明确移除全部三套 v1 数据栈Redux / Dexie / ElectronStore替换为 v2 的Cache / Preference / DataApi三层体系。围绕这三套栈的迁移进度与遗留策略构成了数据层拆除的全部内容。2.1 Redux~100 文件 / 28 slices— ✅ 已完成Redux 是三个数据栈中第一个被完整移除的文档记录了其拆除的完整路径全部 28 个 slice 迁移至 Cache / Preference / DataApi所有useAppSelector/useDispatch调用点重新指向 v2 的读取与写入 API各窗口入口的Provider包裹被移除src/renderer/store/目录整体删除主进程侧被 stub 的ReduxService桥接层一并删除。从文档第 5 节还能看到配套动作29 个store/*文件被列为移除待办的deprecated站点替代方向正是 DataApi Preference SQLite。也就是说 Redux 的拆除不是简单的删代码而是先完成读写路径的重定向再物理删除。2.2 Dexie~50 文件— 大部分已迁移回退路径待清理Dexie 的迁移处于大部分完成、收尾待办的状态渲染进程侧的 Dexie schema 与升级入口src/renderer/databases/已移除但迁移专用访问仍保留DexieExporter、DexieFileReader、DexieSettingsReader三类读取器仅供 v1→v2 迁移流程使用必须等到迁移窗口migration window关闭后才能删除见文档 §6。这一策略在源码中有直接印证迁移工具目录 中保留着DexieFileReader.ts、DexieSettingsReader.ts、ReduxStateReader.ts、LocalStorageReader.ts、LegacyAgentsDbReader.ts、LegacyHomeConfigReader.ts、JsonStreamReader.ts等一系列只读型遗留数据访问器——它们是迁移器读取 v1 数据的井盖迁移结束即废弃。从源码结构看v1 数据读取被统一收敛在src/main/data/migration/v2/utils/下迁移器通过它们读旧数据、通过 MigrationDbService.ts 写新库实现了旧数据只读、新数据只写的隔离降低迁移过程中破坏源数据的风险。2.3 ElectronStore~10 文件— 等待迁移窗口关闭ElectronStore 是最后退役的数据栈文档给出了明确的删除顺序入口最后删文档将src/main/services/ConfigManager.ts标注deprecated Scheduled for removal in v2.0.0内部有new Store()列为最后一个待删除入口Boot config 已先行启动配置已由BootConfigMigrator迁移至 v2PreferencesMigrator 仍依赖偏好迁移器需要通过遗留读取器读取 electron-store 的旧键属于纯迁移期代码。需要说明的是这份文档是重构推进过程中的时间快照——截至本文撰写时仓库中已无法直接检索到ConfigManager.ts文件主进程的配置读取已全面切换至 v2 preference 体系当前 MigrationEngine.ts 与 MigrationContext.ts 中仅保留对electron-store的迁移期只读访问例如读取config.json以探测遗留数据目录这正符合文档迁移专用、迁移后删除的设计。三、UI 层拆除antd / styled-components 向cherrystudio/ui收敛UI 层的目标是把两套被禁用的组件库 antd 与 styled-components 完全迁移到统一的 cherrystudio/ui基于 Tailwind Shadcn 的自研组件体系。3.1 当前进展HeroUI 已完全移除0 处 importcherrystudio/ui已在约 400 个文件中被采用settings / knowledge / library / code / notes / mini-apps 页面已基本清理干净。从源码可以直观验证这一规模src/renderer/下大量组件、页面如src/renderer/pages/settings/、src/renderer/pages/knowledge/、src/renderer/components/chat/、src/renderer/windows/migrationV2/等都已通过from cherrystudio/ui引入组件与文档描述的约 400 文件采用相互印证。3.2 迁移策略重叠优先 分区批量文档给出了两条关键战术重叠文件优先antd 与 styled-components 有约 21 个文件同时 import 两者优先处理这些文件可以一次清两笔账按区域分批迁移每个区域标注了 antd 文件数、styled 文件数与优先级AreaantdstyledPriorityNoteshome主聊天 UI~80~58high核心 UXMessages / Inputbar / Blocksshared Popups~4~4highAddAssistantPopup / AgentModal / SelectModelPopup高流量共享组件迁移后级联解锁下游agents~22~6medium可与 home 批量进行paintings各 provider 配置页~13~11medium全部为 antdstyled 重叠是很好的合并目标windows~10~16mediumquickAssistant / selection / migrationV2 / tracehistory / files / launchpad~5~8low轻量单文件钉子户3—lowSkillsSettings、ModelSelectorLegacy、ProviderLogoPicker这份优先级表的思路值得借鉴先啃高流量共享组件Popups因为它们的迁移会级联解锁依赖它们的下游页面而占文件数最多的 home 主聊天区虽然工作量大但因为处于核心 UX 路径被列为最高优先级。3.3 特殊用例MarkdownShadowDomRenderer文档特别点名了src/renderer/components/MarkdownShadowDomRenderer.tsx它曾使用 styled-components 向 Shadow DOM 注入 CSS需要专门处理而不能走常规迁移路径。从当前源码看该组件的实现已经演进为原生 Web API 方案——通过attachShadow({ mode: open })创建影子根、从document.styleSheets中抓取包含.markdown规则的样式表、将 CSS 规则文本注入 shadow 内的style节点再用createPortal把子节点渲染进影子树。这也再次印证了本文的基调文档是重构快照源码在持续前进阅读时两者需对照。四、Migrator 收尾14 个迁移器的最后 1%数据迁移是 v1→v2 的心脏。文档记录迁移器总数约为 14 个同样为扫描近似值大部分已完成仅剩 4 项显式 TODO。4.1 四个显式 TODOItemLocationTODOChatMigrator i18nChatMigrator.ts:761// TODO: i18nfallback 话题名为硬编码英文Unnamed Topic需要 i18n keyKnowledgeVectorMigrator failure handlingKnowledgeVectorMigrator.tsBase 级执行失败被当作整体迁移失败README 标记 IMPORTANT需确认设计或实现 skippable-base 模式TranslateMigrator missing testmigrators/__tests__/唯一没有配套测试的迁移器需补充TranslateMigrator.test.tsV1_REQUIRED_VERSION lock-inversionPolicy.ts:34TODO待最终 v1 版本确定后更新当时为1.9.0预期 ~1.9.x对照当前源码这 4 项的进展状态如下再次强调仓库代码已领先于文档快照ChatMigrator i18n从 ChatMigrator.test.ts 的测试用例可以看到迁移器已改为保留空的 topic nameexpect(result?.topic.name).toBe()让 UI 在渲染时调用t(chat.conversation.new)进行本地化从而不再把英文Unnamed Topic写死进数据——这与 v2 原生创建的无名话题行为保持一致中文用户不会再看到冻结的英文文案。也就是说该 TODO 的用 i18n 解决硬编码方向已通过空名 渲染时本地化落地KnowledgeVectorMigrator failure handling当前实现中已经存在每 base 非致命per-base non-fatal的处理路径——单个 base 失败时跳过该 base、将其计入skippedCount以通过引擎的targetCount sourceCount - skippedCount对账并把失败降级为 warning不再拖垮整个迁移见 KnowledgeVectorMigrator.ts 附近注释。一个锁死或损坏的 base 不再拖垮整体迁移的设计已落地TranslateMigrator missing test截至撰写时migrators 测试目录 中确实没有TranslateMigrator.test.ts仅mappings/__tests__/TranslateTransforms.test.ts覆盖了转换逻辑该 TODO 仍待办V1_REQUIRED_VERSION当前 versionPolicy.ts 中常量已更新为1.9.12且顶部 TODO 注释Update this value once the final v1 version is determined仍然保留——说明该条目处于已锁值、待终版确认状态。4.2 版本升级策略源码级补充与 V1_REQUIRED_VERSION 相关的版本策略在 versionPolicy.ts 中有完整实现它强制一条线性升级路径v1.old → v1.lastV1_REQUIRED_VERSION→ v2.0.x网关线→ v2.1核心逻辑checkUpgradePathCompatibility会拦截三类非法路径无version.log且无历史版本 → 拦截no_version_log历史版本低于V1_REQUIRED_VERSION→ 拦截v1_too_old从 v1.x 或 v2.0.0-beta 直接跳到V2_DIRECT_MIGRATION_CEILING2.1.0以上 → 拦截v2_gateway_skipped因为每个 v2.0.x 补丁都保留完整的一次性迁移可能包含某些 v1 profile 所需的修复。值得注意的细节是pre-release 的差异性处理currentVersion会通过semver.coerce()剥离 pre-release 标签2.0.0-alpha视为2.0.0防止误拦安装了预发布版的 v1 用户而previousVersion不做 coerce2.0.0-beta仍被视为未通过网关。这套语义保证了 alpha→beta→rc→2.0.0 的预发布链可以顺利升级而 v1 用户则必须经由 2.0.x 网关完成一次性迁移。4.3 有意跳过的内容发布说明必须声明文档强调以下有意为之的跳过必须在 release notes 中向用户明示Knowledgevideo/memory类条目不迁移目录子项不重建遗留 sitemap 条目以 URL 条目形式迁移分组元数据丢失groupId nullKnowledgeVectorv1 遗留向量库原地保留不迁移迁移成功后这些库以孤儿形式残留在磁盘上当前无清理触发未来可由用户确认后清理以回收磁盘NoteactiveFilePath/activeNodeId不迁移运行时重新建立MCPprovider 缓存不迁移运行时重新拉取。这些主动放弃的条目配合上面的逐项 TODO构成了迁移器收尾的完整画像不是所有数据都值得迁移明确放弃的数据需要作为产品级决策被记录和声明。4.4 迁移引擎的底层编排源码补充迁移的执行骨架在 MigrationEngine.ts 中引擎负责协调所有 migrator、管理进度、处理失败。其中MIGRATION_TARGET_TABLES常量是迁移会写入的所有表的单一事实来源约 40 张表覆盖 chat、agent、knowledge、file、preference 等全域并显式标注了clearMigrationData() 清库时的子→父顺序约束message必须先于topic清除外键引用topic必须先于assistant清除user_model必须先于user_provider清除junction 表assistant_mcp_server、assistant_knowledge_base、prompt_binding必须先于其父表清除agents 域按agent_session_message_file_ref → agent_session_message → agent_channel_task → … → agent的依赖链逆序清理。这套顺序约束保证了重试与跳过retry / skip时不会因外键约束而中断——引擎具备完整的失败重试、部分跳过能力这也是 4.2 节 KnowledgeVector per-base 跳过机制能够成立的前提。五、Schema 与迁移 SQL 收尾重构出单条干净的初始迁移文档第 4 节记录了 Schema 层面的发布门槛migrations/sqlite-drizzle/ 目录当前保存的是增量开发链文档撰写时为0000–0012meta/快照截至本文撰写时该链已延伸至0020单条干净迁移的再生成尚未发生发布前必须从最终 schema 重新生成一条干净的初始迁移以清掉中间开发状态这一要求在 CLAUDE.md 中已被强制规定工具行为陷阱drizzle-kit generate在分叉链forked chain上仍然以退出码 0 正常退出只有pnpm db:migrations:check才能标记出分叉因此开发中期的 schema 漂移是可接受的但严禁手写 patch migration。这条规范的实际含义是开发阶段允许 schema 频繁变动毕竟迁移器还在收尾但最终交付必须是一条自洽的、从零到一的干净迁移避免把开发期的中间状态泄漏给用户升级路径。六、deprecated标记清理约 78 处 / 58 文件发布前还需清理代码中残留的deprecated标记约 78 处、分布在 58 个文件中其中约 39 处明确写着Scheduled for removal in v2.0.0。文档按子系统分组给出了替代方向GroupScopeReplacement directionRedux store slices29 filesstore/*DataApi Preference SQLiteDexie / message 数据源4 filesdatabases/、DexieMessageDataSource、DbServiceDataApi主聊天/ AgentMessageDataSourceagent 会话Redux 耦合 hooks / 主进程桥6 filesuseStore/useSettings/useTagsLegacy、ReduxService等usePreference/useTagsv2ReduxService已 stub共享数据类型agent / message / provider 类型分页响应、citation 格式、遗留 provider 标志OffsetPaginationResponse、MainTextBlock.references等协议 / 消息格式LanFile*JSON 格式、web-search 访问器二进制帧、CitationMessageBlock组件 / 服务重构CodeEditor→cherrystudio/ui、FileManager不再扩展、deleteMessageFiles→safeDeleteFiles等见各标注在源码中可以看到这些标记的实际分布例如 legacyTypes.ts整文件标注deprecated v1 legacy — do not extend、FileStorage.tsdeprecated LEGACY v1 CODE — being migrated to FileManager、LegacyBackupManager.tsdeprecated LEGACY v1 CODE — removed when the v2 migration is dropped等。文档还给出了迁移相关 TODO/FIXME 的分布统计约 53 条从约 157 条中过滤而来其余为普通代码注释主工作流按规模排序Preference / Provider 设置迁移最大头约 18 条含ProviderSettings/utils/v1ProviderShim.ts的 delete after Phase 5服务架构 / 生命周期重构约 10 条Redux → SQLite/Drizzle约 9 条集中在apiServer/routes/knowledge/handlers.tsPhase-2 文件服务 stub约 8 条消息类型迁移~5、IPC handler 清理~6、DataApi 集成~3。这组数字告诉读者设置域是迁移后期最密集的战场v1ProviderShim 这类过渡 shim 被明确标注了过期时间点Phase 5 之后删除是典型的过渡代码要有明确生命周期实践。七、发布与清理从迁移窗口关闭到整目录删除文档第 6 节给出了发布期的三步收尾删除迁移专用代码DexieFileReader、DexieSettingsReader、electron-store 读取路径等仅被 v1→v2 迁移流程使用一旦迁移窗口关闭即最低支持的 v1 版本停止升级立即删除聚合 breaking changes发布负责人聚合 breaking-changes 目录中的记录将其翻译成中文用户可见的发布说明。该目录的 README 定义了严格的记录规范用户可感知的变更功能移除、默认行为改变、设置位置移动、数据迁移字段丢失、快捷键/URL scheme 变更、平台要求变化必须记录纯内部重构IPC 通道改名、服务拆分、schema 微调、类型改名不得记录拿不准时宁多勿少发布期可随时丢弃删除整个v2-refactor-temp/目录确认工具不再需要、把值得保留的文档移到正式位置、删除目录并清理.gitignore中的引用。这一步的依据是 v2-refactor-temp/README.md 中明示的 Cleanup plan——该目录不含任何生产代码只承载重构期工具与工作笔记重构落地即整体移除。八、进一步阅读重构相关的源码导航如果希望深入本次重构的实现细节以下仓库路径是最佳起点迁移核心骨架MigrationEngine.ts编排与重试、MigrationContext.ts迁移上下文含 electron-store 只读访问、MigrationPaths.ts遗留数据目录探测、versionPolicy.ts版本网关迁移器与文档migrators 目录 下的*Migrator.ts与配套README-*Migrator.md注册总表见 migratorRegistry.ts迁移测试migrators/tests与 core/tests覆盖引擎跳过、版本策略、错误处理与各迁移器行为遗留数据读取器migration/v2/utilsDexie / Redux / LocalStorage / legacy DB 等只读访问器迁移窗口 UI 与 IPCwindow/MigrationWindowManager.ts、window/MigrationIpcHandler.ts渲染端入口在 migrationV2 窗口数据迁移相关文档总入口migration/README.md 与 v2-refactor-temp/README.md。最后提醒一点阅读姿势v2-todo.md是重构进行中的状态快照其统计数字文件数、TODO 数、迁移链编号会随开发演进部分条目如 ChatMigrator 的 i18n、KnowledgeVector 的 per-base 失败处理在本文撰写时已被源码层面的新实现覆盖。将文档与当前仓库代码对照阅读才能得到最准确的实时状态。赞分享人工智能大模型AI 应用交互助手本地部署【免费下载链接】cherry-studio Cherry Studio 是一款支持多个 LLM 提供商的桌面客户端项目地址https://gitcode.com/CherryHQ/cherry-studio点击查看免费下载相关推荐Cherry Studio V2 数据与 UI 重构临时工作区v2-refactor-temp 目录定位、工具链与收尾规范Cherry Studio V2 数据与 UI 重构临时工作区v2 refactor temp 目录定位、工具链与收尾规范 本篇技术指南以 Cherry St人工智能大模型AI 应用交互助手本地部署Cherry Studio Knowledge V2 UI 重构约束指南组件结构、数据边界与协作规范Cherry Studio Knowledge V2 UI 重构约束指南组件结构、数据边界与协作规范 本文是 Cherry Studiocherry stu人工智能大模型AI 应用交互助手本地部署Cherry Studio AgentsMigrator 深度解析v1 Agent 数据到 v2 SQLite 的无损迁移与文件系统拆分Cherry Studio AgentsMigrator 深度解析v1 Agent 数据到 v2 SQLite 的无损迁移与文件系统拆分 导读 本文深入解析AI 应用大模型桌面应用本地部署RAG创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Cherry Studio v1→v2 重构作战指南：数据层与 UI 技术栈拆除、Migrator 收尾与发布清理
人工智能大模型AI 应用交互助手本地部署【免费下载链接】cherry-studio Cherry Studio 是一款支持多个 LLM 提供商的桌面客户端项目地址https://gitcode.com/CherryHQ/cherry-studio点击查看免费下载本文基于 Cherry Studio 开源仓库中的全局重构追踪文档 v2-todo.md 展开系统梳理 v1→v2 重构中所有**跨切面Cross-Cutting**任务Redux / Dexie / ElectronStore 三套 v1 数据栈的退役、antd / styled-components 向cherrystudio/ui的收敛、14 个数据迁移器Migrator的收尾、Schema 迁移 SQL 的再生成、约 78 处deprecated站点的清理以及发布前的整目录清理流程。读完本文你将掌握这次大型重构的整体推进顺序、各任务的状态判定方法以及每项工作背后对应的源码实现位置可作为二次开发与升级维护时的索引地图。一、重构全景一份只跟踪全局任务的作战文档在 Cherry Studio 仓库中v2 重构的文档组织遵循一个明确原则全局性、跨模块的任务集中在 v2-todo.md 一处追踪模块内部的细粒度 TODO 则保留在各模块自己的文档中不在此重复。因此这份文档的定位是顶层作战地图而不是逐文件清单。文档开篇给出了两个使用前提理解它们对正确阅读本指南至关重要计数是近似值文中所有文件数、slice 数、匹配数均来自代码扫描会随开发推进漂移执行前需要重新验证状态图例✅ done已完成 todo待办 in progress进行中。文档的 Overview 总表是整份重构的目录级快照CategoryScaleStatusRemove Redux~100 files / 28 slices✅ donestore/deletedRemove Dexie~50 files mostly migrated, fallback paths pendingRemove ElectronStore~10 files awaiting migration-window closeRemove antd~145 files settings/knowledge pages already cleanRemove styled-components~112 files in progressMigrator finalization4 explicit todos 14 migrators mostly completeSchema / migration SQL regenrelease gate before release从这张表可以读出整次重构的骨架数据层三栈拆除 UI 层两库迁移 迁移器与 Schema 收尾 发布清理。下文按这四个维度逐一展开。二、数据层拆除Redux / Dexie / ElectronStore 三栈退役v2 数据层的目标非常明确移除全部三套 v1 数据栈Redux / Dexie / ElectronStore替换为 v2 的Cache / Preference / DataApi三层体系。围绕这三套栈的迁移进度与遗留策略构成了数据层拆除的全部内容。2.1 Redux~100 文件 / 28 slices— ✅ 已完成Redux 是三个数据栈中第一个被完整移除的文档记录了其拆除的完整路径全部 28 个 slice 迁移至 Cache / Preference / DataApi所有useAppSelector/useDispatch调用点重新指向 v2 的读取与写入 API各窗口入口的Provider包裹被移除src/renderer/store/目录整体删除主进程侧被 stub 的ReduxService桥接层一并删除。从文档第 5 节还能看到配套动作29 个store/*文件被列为移除待办的deprecated站点替代方向正是 DataApi Preference SQLite。也就是说 Redux 的拆除不是简单的删代码而是先完成读写路径的重定向再物理删除。2.2 Dexie~50 文件— 大部分已迁移回退路径待清理Dexie 的迁移处于大部分完成、收尾待办的状态渲染进程侧的 Dexie schema 与升级入口src/renderer/databases/已移除但迁移专用访问仍保留DexieExporter、DexieFileReader、DexieSettingsReader三类读取器仅供 v1→v2 迁移流程使用必须等到迁移窗口migration window关闭后才能删除见文档 §6。这一策略在源码中有直接印证迁移工具目录 中保留着DexieFileReader.ts、DexieSettingsReader.ts、ReduxStateReader.ts、LocalStorageReader.ts、LegacyAgentsDbReader.ts、LegacyHomeConfigReader.ts、JsonStreamReader.ts等一系列只读型遗留数据访问器——它们是迁移器读取 v1 数据的井盖迁移结束即废弃。从源码结构看v1 数据读取被统一收敛在src/main/data/migration/v2/utils/下迁移器通过它们读旧数据、通过 MigrationDbService.ts 写新库实现了旧数据只读、新数据只写的隔离降低迁移过程中破坏源数据的风险。2.3 ElectronStore~10 文件— 等待迁移窗口关闭ElectronStore 是最后退役的数据栈文档给出了明确的删除顺序入口最后删文档将src/main/services/ConfigManager.ts标注deprecated Scheduled for removal in v2.0.0内部有new Store()列为最后一个待删除入口Boot config 已先行启动配置已由BootConfigMigrator迁移至 v2PreferencesMigrator 仍依赖偏好迁移器需要通过遗留读取器读取 electron-store 的旧键属于纯迁移期代码。需要说明的是这份文档是重构推进过程中的时间快照——截至本文撰写时仓库中已无法直接检索到ConfigManager.ts文件主进程的配置读取已全面切换至 v2 preference 体系当前 MigrationEngine.ts 与 MigrationContext.ts 中仅保留对electron-store的迁移期只读访问例如读取config.json以探测遗留数据目录这正符合文档迁移专用、迁移后删除的设计。三、UI 层拆除antd / styled-components 向cherrystudio/ui收敛UI 层的目标是把两套被禁用的组件库 antd 与 styled-components 完全迁移到统一的 cherrystudio/ui基于 Tailwind Shadcn 的自研组件体系。3.1 当前进展HeroUI 已完全移除0 处 importcherrystudio/ui已在约 400 个文件中被采用settings / knowledge / library / code / notes / mini-apps 页面已基本清理干净。从源码可以直观验证这一规模src/renderer/下大量组件、页面如src/renderer/pages/settings/、src/renderer/pages/knowledge/、src/renderer/components/chat/、src/renderer/windows/migrationV2/等都已通过from cherrystudio/ui引入组件与文档描述的约 400 文件采用相互印证。3.2 迁移策略重叠优先 分区批量文档给出了两条关键战术重叠文件优先antd 与 styled-components 有约 21 个文件同时 import 两者优先处理这些文件可以一次清两笔账按区域分批迁移每个区域标注了 antd 文件数、styled 文件数与优先级AreaantdstyledPriorityNoteshome主聊天 UI~80~58high核心 UXMessages / Inputbar / Blocksshared Popups~4~4highAddAssistantPopup / AgentModal / SelectModelPopup高流量共享组件迁移后级联解锁下游agents~22~6medium可与 home 批量进行paintings各 provider 配置页~13~11medium全部为 antdstyled 重叠是很好的合并目标windows~10~16mediumquickAssistant / selection / migrationV2 / tracehistory / files / launchpad~5~8low轻量单文件钉子户3—lowSkillsSettings、ModelSelectorLegacy、ProviderLogoPicker这份优先级表的思路值得借鉴先啃高流量共享组件Popups因为它们的迁移会级联解锁依赖它们的下游页面而占文件数最多的 home 主聊天区虽然工作量大但因为处于核心 UX 路径被列为最高优先级。3.3 特殊用例MarkdownShadowDomRenderer文档特别点名了src/renderer/components/MarkdownShadowDomRenderer.tsx它曾使用 styled-components 向 Shadow DOM 注入 CSS需要专门处理而不能走常规迁移路径。从当前源码看该组件的实现已经演进为原生 Web API 方案——通过attachShadow({ mode: open })创建影子根、从document.styleSheets中抓取包含.markdown规则的样式表、将 CSS 规则文本注入 shadow 内的style节点再用createPortal把子节点渲染进影子树。这也再次印证了本文的基调文档是重构快照源码在持续前进阅读时两者需对照。四、Migrator 收尾14 个迁移器的最后 1%数据迁移是 v1→v2 的心脏。文档记录迁移器总数约为 14 个同样为扫描近似值大部分已完成仅剩 4 项显式 TODO。4.1 四个显式 TODOItemLocationTODOChatMigrator i18nChatMigrator.ts:761// TODO: i18nfallback 话题名为硬编码英文Unnamed Topic需要 i18n keyKnowledgeVectorMigrator failure handlingKnowledgeVectorMigrator.tsBase 级执行失败被当作整体迁移失败README 标记 IMPORTANT需确认设计或实现 skippable-base 模式TranslateMigrator missing testmigrators/__tests__/唯一没有配套测试的迁移器需补充TranslateMigrator.test.tsV1_REQUIRED_VERSION lock-inversionPolicy.ts:34TODO待最终 v1 版本确定后更新当时为1.9.0预期 ~1.9.x对照当前源码这 4 项的进展状态如下再次强调仓库代码已领先于文档快照ChatMigrator i18n从 ChatMigrator.test.ts 的测试用例可以看到迁移器已改为保留空的 topic nameexpect(result?.topic.name).toBe()让 UI 在渲染时调用t(chat.conversation.new)进行本地化从而不再把英文Unnamed Topic写死进数据——这与 v2 原生创建的无名话题行为保持一致中文用户不会再看到冻结的英文文案。也就是说该 TODO 的用 i18n 解决硬编码方向已通过空名 渲染时本地化落地KnowledgeVectorMigrator failure handling当前实现中已经存在每 base 非致命per-base non-fatal的处理路径——单个 base 失败时跳过该 base、将其计入skippedCount以通过引擎的targetCount sourceCount - skippedCount对账并把失败降级为 warning不再拖垮整个迁移见 KnowledgeVectorMigrator.ts 附近注释。一个锁死或损坏的 base 不再拖垮整体迁移的设计已落地TranslateMigrator missing test截至撰写时migrators 测试目录 中确实没有TranslateMigrator.test.ts仅mappings/__tests__/TranslateTransforms.test.ts覆盖了转换逻辑该 TODO 仍待办V1_REQUIRED_VERSION当前 versionPolicy.ts 中常量已更新为1.9.12且顶部 TODO 注释Update this value once the final v1 version is determined仍然保留——说明该条目处于已锁值、待终版确认状态。4.2 版本升级策略源码级补充与 V1_REQUIRED_VERSION 相关的版本策略在 versionPolicy.ts 中有完整实现它强制一条线性升级路径v1.old → v1.lastV1_REQUIRED_VERSION→ v2.0.x网关线→ v2.1核心逻辑checkUpgradePathCompatibility会拦截三类非法路径无version.log且无历史版本 → 拦截no_version_log历史版本低于V1_REQUIRED_VERSION→ 拦截v1_too_old从 v1.x 或 v2.0.0-beta 直接跳到V2_DIRECT_MIGRATION_CEILING2.1.0以上 → 拦截v2_gateway_skipped因为每个 v2.0.x 补丁都保留完整的一次性迁移可能包含某些 v1 profile 所需的修复。值得注意的细节是pre-release 的差异性处理currentVersion会通过semver.coerce()剥离 pre-release 标签2.0.0-alpha视为2.0.0防止误拦安装了预发布版的 v1 用户而previousVersion不做 coerce2.0.0-beta仍被视为未通过网关。这套语义保证了 alpha→beta→rc→2.0.0 的预发布链可以顺利升级而 v1 用户则必须经由 2.0.x 网关完成一次性迁移。4.3 有意跳过的内容发布说明必须声明文档强调以下有意为之的跳过必须在 release notes 中向用户明示Knowledgevideo/memory类条目不迁移目录子项不重建遗留 sitemap 条目以 URL 条目形式迁移分组元数据丢失groupId nullKnowledgeVectorv1 遗留向量库原地保留不迁移迁移成功后这些库以孤儿形式残留在磁盘上当前无清理触发未来可由用户确认后清理以回收磁盘NoteactiveFilePath/activeNodeId不迁移运行时重新建立MCPprovider 缓存不迁移运行时重新拉取。这些主动放弃的条目配合上面的逐项 TODO构成了迁移器收尾的完整画像不是所有数据都值得迁移明确放弃的数据需要作为产品级决策被记录和声明。4.4 迁移引擎的底层编排源码补充迁移的执行骨架在 MigrationEngine.ts 中引擎负责协调所有 migrator、管理进度、处理失败。其中MIGRATION_TARGET_TABLES常量是迁移会写入的所有表的单一事实来源约 40 张表覆盖 chat、agent、knowledge、file、preference 等全域并显式标注了clearMigrationData() 清库时的子→父顺序约束message必须先于topic清除外键引用topic必须先于assistant清除user_model必须先于user_provider清除junction 表assistant_mcp_server、assistant_knowledge_base、prompt_binding必须先于其父表清除agents 域按agent_session_message_file_ref → agent_session_message → agent_channel_task → … → agent的依赖链逆序清理。这套顺序约束保证了重试与跳过retry / skip时不会因外键约束而中断——引擎具备完整的失败重试、部分跳过能力这也是 4.2 节 KnowledgeVector per-base 跳过机制能够成立的前提。五、Schema 与迁移 SQL 收尾重构出单条干净的初始迁移文档第 4 节记录了 Schema 层面的发布门槛migrations/sqlite-drizzle/ 目录当前保存的是增量开发链文档撰写时为0000–0012meta/快照截至本文撰写时该链已延伸至0020单条干净迁移的再生成尚未发生发布前必须从最终 schema 重新生成一条干净的初始迁移以清掉中间开发状态这一要求在 CLAUDE.md 中已被强制规定工具行为陷阱drizzle-kit generate在分叉链forked chain上仍然以退出码 0 正常退出只有pnpm db:migrations:check才能标记出分叉因此开发中期的 schema 漂移是可接受的但严禁手写 patch migration。这条规范的实际含义是开发阶段允许 schema 频繁变动毕竟迁移器还在收尾但最终交付必须是一条自洽的、从零到一的干净迁移避免把开发期的中间状态泄漏给用户升级路径。六、deprecated标记清理约 78 处 / 58 文件发布前还需清理代码中残留的deprecated标记约 78 处、分布在 58 个文件中其中约 39 处明确写着Scheduled for removal in v2.0.0。文档按子系统分组给出了替代方向GroupScopeReplacement directionRedux store slices29 filesstore/*DataApi Preference SQLiteDexie / message 数据源4 filesdatabases/、DexieMessageDataSource、DbServiceDataApi主聊天/ AgentMessageDataSourceagent 会话Redux 耦合 hooks / 主进程桥6 filesuseStore/useSettings/useTagsLegacy、ReduxService等usePreference/useTagsv2ReduxService已 stub共享数据类型agent / message / provider 类型分页响应、citation 格式、遗留 provider 标志OffsetPaginationResponse、MainTextBlock.references等协议 / 消息格式LanFile*JSON 格式、web-search 访问器二进制帧、CitationMessageBlock组件 / 服务重构CodeEditor→cherrystudio/ui、FileManager不再扩展、deleteMessageFiles→safeDeleteFiles等见各标注在源码中可以看到这些标记的实际分布例如 legacyTypes.ts整文件标注deprecated v1 legacy — do not extend、FileStorage.tsdeprecated LEGACY v1 CODE — being migrated to FileManager、LegacyBackupManager.tsdeprecated LEGACY v1 CODE — removed when the v2 migration is dropped等。文档还给出了迁移相关 TODO/FIXME 的分布统计约 53 条从约 157 条中过滤而来其余为普通代码注释主工作流按规模排序Preference / Provider 设置迁移最大头约 18 条含ProviderSettings/utils/v1ProviderShim.ts的 delete after Phase 5服务架构 / 生命周期重构约 10 条Redux → SQLite/Drizzle约 9 条集中在apiServer/routes/knowledge/handlers.tsPhase-2 文件服务 stub约 8 条消息类型迁移~5、IPC handler 清理~6、DataApi 集成~3。这组数字告诉读者设置域是迁移后期最密集的战场v1ProviderShim 这类过渡 shim 被明确标注了过期时间点Phase 5 之后删除是典型的过渡代码要有明确生命周期实践。七、发布与清理从迁移窗口关闭到整目录删除文档第 6 节给出了发布期的三步收尾删除迁移专用代码DexieFileReader、DexieSettingsReader、electron-store 读取路径等仅被 v1→v2 迁移流程使用一旦迁移窗口关闭即最低支持的 v1 版本停止升级立即删除聚合 breaking changes发布负责人聚合 breaking-changes 目录中的记录将其翻译成中文用户可见的发布说明。该目录的 README 定义了严格的记录规范用户可感知的变更功能移除、默认行为改变、设置位置移动、数据迁移字段丢失、快捷键/URL scheme 变更、平台要求变化必须记录纯内部重构IPC 通道改名、服务拆分、schema 微调、类型改名不得记录拿不准时宁多勿少发布期可随时丢弃删除整个v2-refactor-temp/目录确认工具不再需要、把值得保留的文档移到正式位置、删除目录并清理.gitignore中的引用。这一步的依据是 v2-refactor-temp/README.md 中明示的 Cleanup plan——该目录不含任何生产代码只承载重构期工具与工作笔记重构落地即整体移除。八、进一步阅读重构相关的源码导航如果希望深入本次重构的实现细节以下仓库路径是最佳起点迁移核心骨架MigrationEngine.ts编排与重试、MigrationContext.ts迁移上下文含 electron-store 只读访问、MigrationPaths.ts遗留数据目录探测、versionPolicy.ts版本网关迁移器与文档migrators 目录 下的*Migrator.ts与配套README-*Migrator.md注册总表见 migratorRegistry.ts迁移测试migrators/tests与 core/tests覆盖引擎跳过、版本策略、错误处理与各迁移器行为遗留数据读取器migration/v2/utilsDexie / Redux / LocalStorage / legacy DB 等只读访问器迁移窗口 UI 与 IPCwindow/MigrationWindowManager.ts、window/MigrationIpcHandler.ts渲染端入口在 migrationV2 窗口数据迁移相关文档总入口migration/README.md 与 v2-refactor-temp/README.md。最后提醒一点阅读姿势v2-todo.md是重构进行中的状态快照其统计数字文件数、TODO 数、迁移链编号会随开发演进部分条目如 ChatMigrator 的 i18n、KnowledgeVector 的 per-base 失败处理在本文撰写时已被源码层面的新实现覆盖。将文档与当前仓库代码对照阅读才能得到最准确的实时状态。赞分享人工智能大模型AI 应用交互助手本地部署【免费下载链接】cherry-studio Cherry Studio 是一款支持多个 LLM 提供商的桌面客户端项目地址https://gitcode.com/CherryHQ/cherry-studio点击查看免费下载相关推荐Cherry Studio V2 数据与 UI 重构临时工作区v2-refactor-temp 目录定位、工具链与收尾规范Cherry Studio V2 数据与 UI 重构临时工作区v2 refactor temp 目录定位、工具链与收尾规范 本篇技术指南以 Cherry St人工智能大模型AI 应用交互助手本地部署Cherry Studio Knowledge V2 UI 重构约束指南组件结构、数据边界与协作规范Cherry Studio Knowledge V2 UI 重构约束指南组件结构、数据边界与协作规范 本文是 Cherry Studiocherry stu人工智能大模型AI 应用交互助手本地部署Cherry Studio AgentsMigrator 深度解析v1 Agent 数据到 v2 SQLite 的无损迁移与文件系统拆分Cherry Studio AgentsMigrator 深度解析v1 Agent 数据到 v2 SQLite 的无损迁移与文件系统拆分 导读 本文深入解析AI 应用大模型桌面应用本地部署RAG创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考