知识迁移指南¶

手册 · 相关指南

本指南介绍将现有笔记从 Obsidian、Hermes 或其他基于 Markdown 的工具迁移到当前 Knowledge Center。如需在不同工作区之间移动现有 DeepTutor 数据，请参阅工作区数据迁移。

选择迁移路径¶

DeepTutor 没有专门的一键式 Hermes 导入器。请将 Hermes 笔记导出为 Markdown，并按照“导入知识库”路径操作。请先在笔记工具中检查导出结果；DeepTutor 不会转换专有格式。

准备源数据¶

1. 在连接或导入之前，对源仓库或导出内容进行完整备份。
2. 将笔记导出为 .md 或 .markdown 格式。如果笔记工具提供相关选项，请包含链接的图片和文档资源。
3. 如果应用导出 HTML 或其他格式，请在 DeepTutor 外部将其转换为 Markdown，检查样例，并确认链接和附件仍然有效。
4. 选择上表中的两条路径之一。你也可以同时使用两者：连接实时 Obsidian 仓库进行笔记工作，并在需要可检索索引时导入一份副本。

连接 Obsidian¶

当 Obsidian 仍是你的主要编辑器，并且你希望 DeepTutor 浏览并写入这些相同的笔记时，请使用此路径。

1. 在 DeepTutor 中，打开 Knowledge Center，选择 Create KB，然后选择 Link existing 和 Obsidian。
2. 输入 DeepTutor 服务器可以访问的仓库文件夹的绝对路径，例如 /Users/example/Documents/MyVault。不要输入来自另一台机器的路径。
3. 为知识库指定一个不同的名称并连接它。
4. 在 Chat 中选择该 KB。然后 Obsidian 工具将基于所选仓库运行。

DeepTutor 创建的是指针，而不是上传或索引。它识别 Markdown 笔记，跟随仓库链接和标签，并忽略 .obsidian、.trash 和 .git 内部文件。写入是增量式的：可以创建、追加笔记或为其添加 frontmatter 属性，但助手不会删除或重写现有笔记正文。删除知识库只会移除 DeepTutor 指针；仓库本身不受影响。

对于自托管容器，请挂载主机仓库，使同一路径在服务器容器内可见，然后连接服务器可见的路径。仅在主机上有效的路径是不够的。

若要对 Obsidian 笔记的副本进行语义检索，请将该副本作为独立的已索引知识库导入。保留已连接的仓库用于实时编辑，以使两种用途保持清晰。

导入 Markdown 或 Hermes 笔记¶

当你想要一份已复制并索引的语料库时，请使用此路径。源笔记保留在原始位置。

网页端¶

1. 将笔记和资源导出到本地 Markdown 文件夹。
2. 在 DeepTutor 中，打开 Knowledge Center 并选择 Create KB。
3. 选择 Create new 和检索引擎。LlamaIndex 是默认引擎；只有当其他引擎的取舍适合该语料库时才选择它。
4. 上传文件、文件夹或 .zip 压缩包。
5. 等待解析和索引完成，然后在删除任何源备份之前，确认几个代表性笔记可以被检索到。

文件夹上传 会保留其相对目录结构。.zip 压缩包会以防御性方式解压：嵌套目录会被扁平化，不支持的成员会被跳过，隐藏条目和系统条目会被跳过，扁平化后重复的 basename 会被跳过。当不同文件夹中的笔记标题重复或文件夹层级有意义时，请优先选择文件夹上传。

上传界面会显示受支持的扩展名和单文件限制。当前 Markdown 扩展名为 .md 和 .markdown；其他受支持的文本、文档、电子表格、演示文稿、EPUB、图片和源代码格式也遵循相同的上传策略。

CLI¶

从导出目录：

deeptutor kb create hermes-notes --docs-dir /path/to/hermes-export

对于单个文件或后续添加：

deeptutor kb create one-note --doc /path/to/note.md
deeptutor kb add hermes-notes --docs-dir /path/to/more-notes

CLI 会递归地从 --docs-dir 收集受支持的文件，然后将每个匹配的文件复制到 KB 的 raw/ 目录的顶层。由于重复的文件名可能覆盖先前复制的文件，当文件名重复或层级有意义时，请优先使用网页端的文件夹上传。使用 deeptutor kb list 和 deeptutor kb info hermes-notes 确认创建结果和文档数量。

验证迁移¶

• 打开一个小型、中型和深层嵌套的示例笔记，检查文本、链接和资源引用是否仍然可读。
• 对于已索引的 KB，对准确的笔记名称、短语和概念进行代表性搜索。确认引用的来源指向预期的笔记。
• 对于 Obsidian，搜索一条笔记，跟踪链接或反向链接，创建一条临时笔记，然后从 Obsidian 中删除该临时笔记。
• 在确认检索质量和资源引用之前，请保留原始备份。

实现与验证¶

• deeptutor/capabilities/obsidian/vault.py
• deeptutor/api/routers/knowledge.py
• deeptutor_cli/kb.py