Cherry Studio v2 知识库数据源变更解析Sitemap 类型移除与 URL 迁移方案【免费下载链接】cherry-studio Cherry Studio 是一款支持多个 LLM 提供商的桌面客户端项目地址: https://gitcode.com/CherryHQ/cherry-studioSitemap站点地图曾是 Cherry Studio 知识库中独立的网页数据源类型用户可以通过它一次导入一个网站的全部页面。在 v2 架构重构中这一能力被移除知识库不再提供 Sitemap/Website 入口存量 v1 数据中的 sitemap 条目在迁移时统一降级为普通 URL 条目。本文基于仓库中的变更公告与迁移器源码完整梳理这次移除的来龙去脉、对用户的实际影响、v1 → v2 的迁移映射细节以及向量数据的处理方式帮助受影响的用户和二次开发者理解并平稳过渡。变更总览Sitemap 不再是独立数据源类型本次变更记录于 2026-06-04-remove-knowledge-sitemap.md其性质为移除removed、影响等级为 notice提示级随 PR #15682 引入。核心结论只有一句话知识库不再提供 Sitemap 作为独立的数据源类型存量 v1 的 sitemap 条目在迁移时被转换为普通 URL 条目。这意味着 v2 版本中知识库的数据源类型集合不再包含 sitemap。从 v2 运行时数据模型可以印证这一点shared/data/types/knowledge.ts 中KnowledgeItemDataSchema是file、url、note、directory四类数据模式的联合不存在任何 sitemap 数据模式。V2 的UrlItemDataSchemasrc/shared/data/types/knowledge.ts定义了 URL 条目所需的最小载荷const UrlItemDataSchema KnowledgeItemSharedSchema.extend({ url: z.string().trim().min(1).describe(URL to read and index.), // 首次索引/刷新时由 main 进程惰性写入用户新增时省略 relativePath: KnowledgeRelativePathSchema.optional().describe( Knowledge-base-relative path for the captured URL snapshot markdown, written on first index. ) })作为对比v1 时代的数据类型定义仍保留在渲染进程类型中renderer/types/knowledge.ts 的KnowledgeItemType依然列出了file | url | note | sitemap | directory | memory | video且存在独立的KnowledgeSitemapItem类型src/renderer/types/knowledge.ts。这些是迁移器读取 v1 导出数据时使用的旧版类型并不代表 v2 仍支持该类型——迁移器的输入类型同样保留了 sitemapLegacyKnowledgeItemType file | url | note | sitemap | directory | memory | videoKnowledgeMappings.ts。为什么这次移除会影响你的知识库对用户而言最直接的变化发生在知识库界面的数据源选择处UI 不再显示 Sitemap/Website 入口新建或向知识库添加数据时不再有Sitemap站点地图这一选项只能选择文件、文件夹、URL、笔记等类型。存量 sitemap 数据不会丢失已存在的 v1 sitemap 数据源在升级迁移后会以 URL 数据源的形式继续出现在知识库中条目内容即原来的 sitemap 地址原样保留。没有自动替代方案v2 中不存在sitemap 自动展开为多个网页的等价能力。如果之前依赖 sitemap 批量导入某个站点的所有页面需要改为逐条添加网页 URL。仓库中残留的旧版本地化文案可以作为 v1 UI 曾提供该入口的佐证例如 el-gr.json 中仍保留着use files, folders, URLs or sitemaps的描述这是 v1 添加数据源对话框的翻译残留。用户应对指南用 URL 数据源替代 Sitemap官方建议非常明确仅此一条路径单个网页的导入直接使用 URL 数据源粘贴具体的网页地址即可整站批量导入v2 没有自动的 sitemap 展开机制作为替代需要自行逐页添加 URL或将网页内容整理后以其他支持的类型如本地文件、笔记导入迁移后的数据升级到 v2 后原有的 sitemap 条目会以 URL 条目的形态出现在知识库中无需手动重建只需留意其行为已从站点地图变为单条 URL 记录。迁移实现细节v1 sitemap 如何映射为 url 条目这一节是整次迁移的核心。负责知识库迁移的组件是KnowledgeMigratorsrc/main/data/migration/v2/migrators/KnowledgeMigrator.ts它把 v1 时代存放在 Redux Dexie 导出中的知识库数据迁移进 v2 的 SQLite 结构。sitemap 条目的类型转换发生在映射层 KnowledgeMappings.ts 的transformKnowledgeItem中} else if (item.type sitemap) { const content typeof item.content string ? item.content.trim() : if (content ) { return { ok: false, reason: invalid_sitemap } } type url data { source: content, url: content } }映射规则可以总结为以下几点类型与数据载荷的等价转换目标类型sitemap→url。迁移后的条目type为urlgroupId为nullv1 导出是扁平结构不携带分组信息。数据载荷v1 的item.contentsitemap 地址字符串被同时写入 v2 的data.source与data.url。source是所有知识条目共有的面向用户的来源标识url是 URL 条目特有的待索引地址二者取值相同保证旧数据在新 schema 下可被正常读取和索引。前后端一致性v2 运行时没有 sitemap schema因此迁移后写入的只能是UrlItemDataSchema可解析的数据这一转换是让旧数据活下来的必要条件。内容去空格与无效条目降级迁移器会对content做trim()处理消除首尾空白后再写入确保满足 v2 schema 中trim().min(1)的约束若去空格后内容为空例如原 sitemap 条目只有空白字符则该条目被判定为无效返回invalid_sitemap失败原因在迁移结果中按跳过处理并记录一条警告Skipped sitemap item with invalid content (itemId...)见 KnowledgeMigrator.ts 的formatItemWarning。处理状态的归一化迁移器不信任 v1 的processingStatus字段而是根据uniqueId推断条目状态uniqueId非空视为completed否则为idleKnowledgeMappings.ts。因此一个曾经成功索引过的 sitemap 条目迁移后对应的 URL 条目会以completed状态呈现error为null。字段映射速查KnowledgeMigrator的迁移说明文档 README-KnowledgeMigrator.md 给出了knowledge_item的完整字段映射其中与 sitemap 直接相关的两行是源字段v1 条目目标字段v2knowledge_item说明typetype支持的目标类型为 file/url/note/directorylegacy sitemap 映射为 urlcontent Dexie 查找data按类型执行特定转换sitemap 的字符串内容直接作为 url 数据写入向量数据的迁移sitemap 向量随条目转为 URL 向量知识库条目的价值在于其已建立的向量索引。KnowledgeMigrator本身不复制向量行只负责准备好 base 与 item 记录真正的向量迁移由KnowledgeVectorMigrator完成二者的协作通过sharedData中的 ID 重映射KNOWLEDGE_ITEM_ID_REMAP_SHARED_DATA_KEY等衔接。针对 sitemap 的向量处理规则在 README-KnowledgeMigrator.md 中有明确说明Legacy vector rows that map back to a legacysitemapitem are migrated as URL vectors because the item now maps to target typeurl.也就是说由于 sitemap 条目本身被转换成了 url 条目与之关联的旧向量行也会作为URL 向量继续迁移而不是被丢弃。这一点在向量迁移器的测试 KnowledgeVectorMigrator.test.ts 中有专门的用例 migrates legacy sitemap vectors when their item migrated as url 加以验证。需要对比的是目录directory类型的处理v1 的目录条目在迁移中会展开为容器 每文件子条目以重新归属向量而根目录级向量会被跳过README-KnowledgeMigrator.md。sitemap 则没有这种展开逻辑——它本身就是单条记录直接平移为 URL 条目即可完整保留其向量。迁移验证与测试保障本次迁移行为有完整的测试覆盖可直接作为行为契约阅读KnowledgeMigrator.test.ts 中针对 sitemap 的三组用例migrates legacy sitemap items as url items验证type: sitemap的条目迁移后得到type: url、data: { source, url }、status: completed、error: null、groupId: nulltrims whitespace around legacy sitemap content before migrating验证content首尾空白会被去除后再写入source/urlkeeps invalid legacy sitemap items skippable验证空白内容返回invalid_sitemap失败原因条目被跳过。KnowledgeVectorMigrator.test.ts 中的向量迁移用例确保 sitemap 的旧向量能正确归属到迁移后的 URL 条目上。在迁移结果的validate阶段迁移器还会进行计数校验sourceCount/targetCount/skippedCount与孤儿条目检查保证没有knowledge_item行游离于knowledge_base之外KnowledgeMigrator.ts。与其它被处理类型的边界了解 sitemap 的迁移路径后还需要知道它和被跳过类型的区别以免混淆sitemap → url有效内容被保留作为 URL 条目迁移含向量directory → directory作为容器/来源声明迁移容器级向量跳过嵌入文件向量重新归属到合成子条目video、memory → 跳过这两类 v1 条目在迁移中被整体丢弃README-KnowledgeMigrator.md属于比 sitemap 更彻底的移除。相关源码与文档索引如果你想深入本次变更的完整实现建议按以下顺序阅读变更公告2026-06-04-remove-knowledge-sitemap.md迁移器主实现KnowledgeMigrator.ts类型转换入口在transformKnowledgeItem调用处类型映射KnowledgeMappings.tssitemap → url 的核心逻辑迁移设计文档README-KnowledgeMigrator.md数据来源、字段映射、被跳过数据清单测试用例KnowledgeMigrator.test.ts、KnowledgeVectorMigrator.test.tsv2 数据模型shared/data/types/knowledge.tsKnowledgeItemDataSchema联合类型确认 v2 无 sitemap schemav1 渲染层类型仅用于理解旧数据renderer/types/knowledge.ts总结Sitemap 在 Cherry Studio v2 中作为数据源类型被移除但这不是数据灾难——存量条目会以 URL 条目的身份平滑迁移向量索引也随之一并保留。唯一需要接受的现实是v2 不再提供基于站点地图的整站批量导入能力网页数据需要以单条 URL 的方式逐条添加。【免费下载链接】cherry-studio Cherry Studio 是一款支持多个 LLM 提供商的桌面客户端项目地址: https://gitcode.com/CherryHQ/cherry-studio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Cherry Studio v2 知识库数据源变更解析：Sitemap 类型移除与 URL 迁移方案
Cherry Studio v2 知识库数据源变更解析Sitemap 类型移除与 URL 迁移方案【免费下载链接】cherry-studio Cherry Studio 是一款支持多个 LLM 提供商的桌面客户端项目地址: https://gitcode.com/CherryHQ/cherry-studioSitemap站点地图曾是 Cherry Studio 知识库中独立的网页数据源类型用户可以通过它一次导入一个网站的全部页面。在 v2 架构重构中这一能力被移除知识库不再提供 Sitemap/Website 入口存量 v1 数据中的 sitemap 条目在迁移时统一降级为普通 URL 条目。本文基于仓库中的变更公告与迁移器源码完整梳理这次移除的来龙去脉、对用户的实际影响、v1 → v2 的迁移映射细节以及向量数据的处理方式帮助受影响的用户和二次开发者理解并平稳过渡。变更总览Sitemap 不再是独立数据源类型本次变更记录于 2026-06-04-remove-knowledge-sitemap.md其性质为移除removed、影响等级为 notice提示级随 PR #15682 引入。核心结论只有一句话知识库不再提供 Sitemap 作为独立的数据源类型存量 v1 的 sitemap 条目在迁移时被转换为普通 URL 条目。这意味着 v2 版本中知识库的数据源类型集合不再包含 sitemap。从 v2 运行时数据模型可以印证这一点shared/data/types/knowledge.ts 中KnowledgeItemDataSchema是file、url、note、directory四类数据模式的联合不存在任何 sitemap 数据模式。V2 的UrlItemDataSchemasrc/shared/data/types/knowledge.ts定义了 URL 条目所需的最小载荷const UrlItemDataSchema KnowledgeItemSharedSchema.extend({ url: z.string().trim().min(1).describe(URL to read and index.), // 首次索引/刷新时由 main 进程惰性写入用户新增时省略 relativePath: KnowledgeRelativePathSchema.optional().describe( Knowledge-base-relative path for the captured URL snapshot markdown, written on first index. ) })作为对比v1 时代的数据类型定义仍保留在渲染进程类型中renderer/types/knowledge.ts 的KnowledgeItemType依然列出了file | url | note | sitemap | directory | memory | video且存在独立的KnowledgeSitemapItem类型src/renderer/types/knowledge.ts。这些是迁移器读取 v1 导出数据时使用的旧版类型并不代表 v2 仍支持该类型——迁移器的输入类型同样保留了 sitemapLegacyKnowledgeItemType file | url | note | sitemap | directory | memory | videoKnowledgeMappings.ts。为什么这次移除会影响你的知识库对用户而言最直接的变化发生在知识库界面的数据源选择处UI 不再显示 Sitemap/Website 入口新建或向知识库添加数据时不再有Sitemap站点地图这一选项只能选择文件、文件夹、URL、笔记等类型。存量 sitemap 数据不会丢失已存在的 v1 sitemap 数据源在升级迁移后会以 URL 数据源的形式继续出现在知识库中条目内容即原来的 sitemap 地址原样保留。没有自动替代方案v2 中不存在sitemap 自动展开为多个网页的等价能力。如果之前依赖 sitemap 批量导入某个站点的所有页面需要改为逐条添加网页 URL。仓库中残留的旧版本地化文案可以作为 v1 UI 曾提供该入口的佐证例如 el-gr.json 中仍保留着use files, folders, URLs or sitemaps的描述这是 v1 添加数据源对话框的翻译残留。用户应对指南用 URL 数据源替代 Sitemap官方建议非常明确仅此一条路径单个网页的导入直接使用 URL 数据源粘贴具体的网页地址即可整站批量导入v2 没有自动的 sitemap 展开机制作为替代需要自行逐页添加 URL或将网页内容整理后以其他支持的类型如本地文件、笔记导入迁移后的数据升级到 v2 后原有的 sitemap 条目会以 URL 条目的形态出现在知识库中无需手动重建只需留意其行为已从站点地图变为单条 URL 记录。迁移实现细节v1 sitemap 如何映射为 url 条目这一节是整次迁移的核心。负责知识库迁移的组件是KnowledgeMigratorsrc/main/data/migration/v2/migrators/KnowledgeMigrator.ts它把 v1 时代存放在 Redux Dexie 导出中的知识库数据迁移进 v2 的 SQLite 结构。sitemap 条目的类型转换发生在映射层 KnowledgeMappings.ts 的transformKnowledgeItem中} else if (item.type sitemap) { const content typeof item.content string ? item.content.trim() : if (content ) { return { ok: false, reason: invalid_sitemap } } type url data { source: content, url: content } }映射规则可以总结为以下几点类型与数据载荷的等价转换目标类型sitemap→url。迁移后的条目type为urlgroupId为nullv1 导出是扁平结构不携带分组信息。数据载荷v1 的item.contentsitemap 地址字符串被同时写入 v2 的data.source与data.url。source是所有知识条目共有的面向用户的来源标识url是 URL 条目特有的待索引地址二者取值相同保证旧数据在新 schema 下可被正常读取和索引。前后端一致性v2 运行时没有 sitemap schema因此迁移后写入的只能是UrlItemDataSchema可解析的数据这一转换是让旧数据活下来的必要条件。内容去空格与无效条目降级迁移器会对content做trim()处理消除首尾空白后再写入确保满足 v2 schema 中trim().min(1)的约束若去空格后内容为空例如原 sitemap 条目只有空白字符则该条目被判定为无效返回invalid_sitemap失败原因在迁移结果中按跳过处理并记录一条警告Skipped sitemap item with invalid content (itemId...)见 KnowledgeMigrator.ts 的formatItemWarning。处理状态的归一化迁移器不信任 v1 的processingStatus字段而是根据uniqueId推断条目状态uniqueId非空视为completed否则为idleKnowledgeMappings.ts。因此一个曾经成功索引过的 sitemap 条目迁移后对应的 URL 条目会以completed状态呈现error为null。字段映射速查KnowledgeMigrator的迁移说明文档 README-KnowledgeMigrator.md 给出了knowledge_item的完整字段映射其中与 sitemap 直接相关的两行是源字段v1 条目目标字段v2knowledge_item说明typetype支持的目标类型为 file/url/note/directorylegacy sitemap 映射为 urlcontent Dexie 查找data按类型执行特定转换sitemap 的字符串内容直接作为 url 数据写入向量数据的迁移sitemap 向量随条目转为 URL 向量知识库条目的价值在于其已建立的向量索引。KnowledgeMigrator本身不复制向量行只负责准备好 base 与 item 记录真正的向量迁移由KnowledgeVectorMigrator完成二者的协作通过sharedData中的 ID 重映射KNOWLEDGE_ITEM_ID_REMAP_SHARED_DATA_KEY等衔接。针对 sitemap 的向量处理规则在 README-KnowledgeMigrator.md 中有明确说明Legacy vector rows that map back to a legacysitemapitem are migrated as URL vectors because the item now maps to target typeurl.也就是说由于 sitemap 条目本身被转换成了 url 条目与之关联的旧向量行也会作为URL 向量继续迁移而不是被丢弃。这一点在向量迁移器的测试 KnowledgeVectorMigrator.test.ts 中有专门的用例 migrates legacy sitemap vectors when their item migrated as url 加以验证。需要对比的是目录directory类型的处理v1 的目录条目在迁移中会展开为容器 每文件子条目以重新归属向量而根目录级向量会被跳过README-KnowledgeMigrator.md。sitemap 则没有这种展开逻辑——它本身就是单条记录直接平移为 URL 条目即可完整保留其向量。迁移验证与测试保障本次迁移行为有完整的测试覆盖可直接作为行为契约阅读KnowledgeMigrator.test.ts 中针对 sitemap 的三组用例migrates legacy sitemap items as url items验证type: sitemap的条目迁移后得到type: url、data: { source, url }、status: completed、error: null、groupId: nulltrims whitespace around legacy sitemap content before migrating验证content首尾空白会被去除后再写入source/urlkeeps invalid legacy sitemap items skippable验证空白内容返回invalid_sitemap失败原因条目被跳过。KnowledgeVectorMigrator.test.ts 中的向量迁移用例确保 sitemap 的旧向量能正确归属到迁移后的 URL 条目上。在迁移结果的validate阶段迁移器还会进行计数校验sourceCount/targetCount/skippedCount与孤儿条目检查保证没有knowledge_item行游离于knowledge_base之外KnowledgeMigrator.ts。与其它被处理类型的边界了解 sitemap 的迁移路径后还需要知道它和被跳过类型的区别以免混淆sitemap → url有效内容被保留作为 URL 条目迁移含向量directory → directory作为容器/来源声明迁移容器级向量跳过嵌入文件向量重新归属到合成子条目video、memory → 跳过这两类 v1 条目在迁移中被整体丢弃README-KnowledgeMigrator.md属于比 sitemap 更彻底的移除。相关源码与文档索引如果你想深入本次变更的完整实现建议按以下顺序阅读变更公告2026-06-04-remove-knowledge-sitemap.md迁移器主实现KnowledgeMigrator.ts类型转换入口在transformKnowledgeItem调用处类型映射KnowledgeMappings.tssitemap → url 的核心逻辑迁移设计文档README-KnowledgeMigrator.md数据来源、字段映射、被跳过数据清单测试用例KnowledgeMigrator.test.ts、KnowledgeVectorMigrator.test.tsv2 数据模型shared/data/types/knowledge.tsKnowledgeItemDataSchema联合类型确认 v2 无 sitemap schemav1 渲染层类型仅用于理解旧数据renderer/types/knowledge.ts总结Sitemap 在 Cherry Studio v2 中作为数据源类型被移除但这不是数据灾难——存量条目会以 URL 条目的身份平滑迁移向量索引也随之一并保留。唯一需要接受的现实是v2 不再提供基于站点地图的整站批量导入能力网页数据需要以单条 URL 的方式逐条添加。【免费下载链接】cherry-studio Cherry Studio 是一款支持多个 LLM 提供商的桌面客户端项目地址: https://gitcode.com/CherryHQ/cherry-studio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考