MindArchive 如何把本地 Markdown 文件建成 AI 知识库？

把本地 Markdown 文件交给 MindArchive 管理，关键不是把文件上传到某个在线“知识库”，而是先让扩展获得一个本地文件夹的访问权限，再由它读取其中的标准 .md 文件、目录结构和 YAML 元数据。完成这一步后，文件树、全文搜索、标签与可选的 AI 增强能力会围绕同一批本地文件工作。原文件仍保存在用户选择的磁盘目录中，也可以继续由 Obsidian 等兼容工具编辑。

先理解 MindArchive 的知识库结构

MindArchive 的知识库不是封闭数据库，而是一个由普通目录和 Markdown 文件组成的文件集合。磁盘上的文件夹对应分类，.md 文件对应知识条目，标题、标签、平台、来源等信息可以写入文件顶部的 YAML frontmatter。这样的结构有两个直接好处：一是资料不会被锁在专有格式里，卸载扩展后文件仍然存在；二是可以把同一个目录同时交给其他 Markdown 工具使用。

“建成 AI 知识库”可以拆成两个层次。基础层是文件管理和全文检索，扩展会对文件名、分类路径、标题、正文和标签建立可搜索的索引。增强层才是 AI：用户自行配置模型服务后，可以让模型辅助生成标题、标签和摘要。AI 功能默认关闭，因此没有配置模型时，知识库依然可以作为本地 Markdown 管理器和全文搜索工具正常使用。

整理准备导入的 Markdown 目录

开始前，建议先把准备纳入知识库的文件放进一个专用目录。可以按项目、客户、主题或年份建立子目录，但不要为了追求复杂分类而创建过深的层级。目录名应当稳定且能表达用途，例如“产品文档”“会议记录”“开发笔记”。文件名也应尽量具有辨识度，因为全局搜索会同时匹配文件名与正文。

每个文件应使用 .md 扩展名，并采用常规 Markdown 语法。标题、段落、列表、代码块和表格都可以保留。图片如果使用相对路径，最好将图片放在知识库目录内部，并保持现有的相对位置；在移动文件夹前先检查图片引用，避免正文能检索但图片无法显示。

已有 Obsidian 仓库的用户不必复制一份资料。MindArchive 使用标准 Markdown 和 YAML frontmatter，可以直接选择 Obsidian 仓库根目录，让两边操作同一组文件。这样做之前应确认自己有可靠备份，并避免两个程序同时批量重命名或移动大量文件。普通编辑通常可以互通，但批量结构调整更适合一次只在一个工具中完成。

可选的 YAML 元数据

没有 frontmatter 的 Markdown 文件也能作为正文资料使用。需要更清晰的标签和来源信息时，可以在文件开头加入 YAML 区块。字段应保持简单、统一，不要把同一概念写成多种拼法。下面是一个便于整理的示例：

---
title: 缓存失效排查记录
tags:
  - Redis
  - 性能排查
category: 开发笔记
platform: internal
---

## 现象

接口在高并发时出现延迟波动。

## 排查过程

记录命中率、过期策略和关键日志。

示例字段用于说明组织方式，不代表所有字段都必须手写。MindArchive 的属性面板可编辑标题、标签、平台和分类，并展示创建日期、字数、AI 摘要与来源等只读信息。导入旧资料时，先保证正文可读和目录合理，再逐步补充元数据，通常比一次性修改全部文件更稳妥。

选择本地文件夹并完成授权

安装扩展后进入知识库功能，首次使用时选择前面准备好的本地文件夹。浏览器弹出目录访问权限时，需要确认选择的是知识库根目录，并允许扩展在后续访问该目录。授权对象应尽量精确，不要为了省事选择包含大量无关文件的上级目录。

选择完成后，先观察文件树是否正确显示目录和 Markdown 文件，再随机打开几篇文档，检查标题、正文、代码块、表格和图片。若文件很多，应等待初次读取和索引稳定后再进行搜索验证。此时不要急着开启 AI，先确认基础知识库能够可靠地读取、编辑和保存本地文件。

扩展的编辑器支持常见富文本操作，并会在停止输入一小段时间后自动保存。测试时可以新建一篇临时笔记，输入一句容易识别的文字，关闭后重新打开，确认内容确实写回磁盘。验证完成后删除临时笔记，或者把它保留在专门的测试目录中。

用全文搜索验证索引

知识库是否真正可用，不能只看文件树，还要验证检索。打开全局搜索，依次测试三类词：只出现在文件名中的词、只出现在正文中的词，以及 YAML 标签中的词。搜索结果会区分文件匹配和正文匹配，并高亮命中位置。选择一个结果后，应能打开对应文件并定位到相关内容。

中文资料的测试词不要全部选用常见词。可以从某篇文档中挑选一个独特的产品名、故障现象或术语，再检查返回结果是否完整。若搜索不到新加入的内容，先确认文件已经保存、扩展仍有目录权限、文件扩展名正确，然后重新打开知识库。不要仅凭一次模糊关键词搜索就判断索引失效。

开启可选的 AI 增强

基础检索正常后，再根据需要配置 AI。MindArchive 支持用户使用自己的模型服务凭据，也可以连接本地运行的 Ollama。模型凭据保存在本机；当启用某项 AI 功能时，相关内容会从浏览器发送给所选择的模型服务商，而不是发送到 MindArchive 的开发者服务器。因此，使用云端模型处理公司资料或隐私内容前，应先确认组织政策以及模型服务商的数据规则。

AI 增强包含独立开关，可以按需启用标题、标签、摘要或内容清理，而不是一次打开所有能力。更稳妥的顺序是先启用摘要，在少量非敏感文档上观察输出；确认语言、长度和准确性符合预期后，再尝试自动标签。自动生成的标签应当人工抽查，避免同义词泛滥、概念层级混乱或把文档中的偶然词汇当作主题。

AI 增强并不会替代全文索引。全文搜索适合查找确定词语和原文证据，AI 生成的标题、标签和摘要适合提高浏览与筛选效率。实际使用中，应先用搜索定位文件，再以原始 Markdown 正文为准核对结论。对重要资料，不能只阅读模型摘要就做决定。

把网页和 AI 对话归档进同一目录

除了已有 Markdown 文件，MindArchive 还可以把支持平台的 AI 对话或网页内容保存、导出为 Markdown。导出前可在编辑器中预览和修正，适合删除无关寒暄、补充上下文并统一标题。归档时建议保留能够解释内容来源的元数据，但正文里不要只留下脱离语境的结论。

侧边栏速记也可以作为资料入口。阅读网页或观看教程时先记录想法，再归档到知识库。速记适合捕捉临时信息，正式归档时仍应补上明确标题、分类和必要背景。否则文件数量增加后，即使全文搜索能找到文字，也很难判断每条记录的可信度和用途。

与 Obsidian 共用目录时的注意事项

共用仓库的核心原则是让磁盘文件成为唯一事实来源。无论在 MindArchive 还是 Obsidian 中编辑，最终都应写回同一个 Markdown 文件。修改后可在另一个工具里重新打开或刷新，确认变更可见。目录、标签和元数据可以双向使用，但不同工具对个别 Markdown 扩展语法的渲染可能不完全相同，因此重要文档宜采用通用语法。

如果仓库已通过 Git 管理，可以在大规模整理前提交一次快照。MindArchive 也提供把知识库同步到私有 GitHub 仓库的能力，但同步不能取代权限管理和备份策略。首次启用前应明确仓库是否私有、哪些附件会被纳入、是否包含密钥或个人信息。任何凭据都不应写入 Markdown 正文或 frontmatter。

常见问题与排查顺序

文件树为空或部分文件不显示

先检查选中的是否为正确根目录，再确认文件确实以 .md 结尾。浏览器权限被撤销后，需要重新选择目录并授权。若只是某个子目录缺失，检查它是否位于授权目录之外，或者文件是否刚被其他程序移动。

修改没有保存到磁盘

用一篇非关键文档进行最小测试，等待自动保存后在系统文件管理器或另一个编辑器中打开原文件。若内容未变化，检查目录是否仍可写、文件是否被设置为只读，以及是否在另一个程序中发生了覆盖。排查期间不要在重要文件上反复编辑。

搜索结果缺少新内容

确认修改已实际保存，然后关闭并重新进入知识库以触发重新读取。使用文档中的独特词语测试，排除中文分词或关键词过于宽泛造成的误判。目录规模较大时，给初次索引留出时间，再比较文件名匹配和正文匹配两类结果。

AI 标签或摘要不准确

先关闭对应开关，保留原始文件和人工标签。检查送给模型的文档是否缺少标题、上下文或正文结构，再用少量文件重试。模型生成内容只能作为辅助元数据，不能覆盖经过确认的事实，也不应在未经复核时批量应用到整个知识库。

完成后的验收清单

一个可用的本地 AI 知识库至少应通过以下验证：目录树与磁盘结构一致；随机文档能够正常打开；编辑内容可以写回原文件；文件名、正文和标签都能被搜索；AI 功能关闭时基础检索仍可工作；开启 AI 后生成内容可被人工审阅；敏感资料的处理方式符合自己的安全要求。全部通过后，再逐步扩大导入范围。

因此，最稳妥的实施路径是“整理目录、授权文件夹、验证读写、验证搜索、最后开启 AI”。这能把文件权限、索引问题和模型问题分开处理。MindArchive 提供的是围绕本地 Markdown 的管理与增强能力，真正决定知识库质量的仍是清晰的目录、稳定的元数据、可追溯的原文，以及对 AI 输出的持续复核。