qmd 是一款专为 Markdown 笔记和文档设计的本地混合搜索引擎，旨在帮助用户快速索引、检索和管理分散在本地文件系统中的知识内容。它通过一次性的索引构建，实现后续极速的内容搜索，特别适用于个人知识库、写作草稿或项目文档的整理与查找。不同于传统全文搜索工具，qmd 不仅支持关键词匹配，还集成了语义向量搜索能力，使得用户即使在模糊表达或同义词场景下也能精准定位相关文档。其设计初衷是作为代码仓库搜索工具的补充，专注于非结构化文本内容的高效组织。 该工具基于 Bun 运行时构建，依赖 SQLite 数据库进行元数据存储，并可选地利用本地 GGUF 模型实现语义理解。首次使用时需执行 `qmd embed` 命令以启用向量嵌入功能，之后即可在多种搜索模式间灵活切换。默认推荐使用 `qmd search` 命令，它采用 BM25 算法实现近乎实时的关键词检索；当关键词搜索失效时，可降级使用 `qmd vsearch` 进行语义相似度匹配（但可能因加载本地大语言模型而延迟较高）；而 `qmd query` 则提供混合搜索结果并辅以 LLM 重排序，适合对精度要求极高的查询，不过运行开销较大且易超时。 qmd 支持将任意路径下的 Markdown 文件集合定义为“收藏集”（collection），并通过通配符掩码（mask）控制索引范围。用户可通过命令行添加多个收藏集，并为每个集合设置描述性上下文信息，便于后续引用。此外，系统提供了丰富的输出格式选项，如 JSON、纯文本列表、文件路径等，方便集成到自动化流程或 AI 代理工作流中。对于持续更新的笔记库，建议配置定时任务定期调用 `qmd update` 更新索引，确保搜索结果始终反映最新状态。
核心功能特点
- 本地 Markdown 文件的混合搜索引擎，支持关键词与语义双重检索
- 一次索引、多次高速查询，默认 BM25 算法实现即时响应
- 支持多收藏集管理，可按命名空间隔离不同文档类型
- 可选向量嵌入与 LLM 重排序，提升模糊查询准确率
- 兼容 JSON 及文件路径等多种输出格式，适配自动化场景
- 轻量级架构，基于 Bun 与 SQLite，无需云端服务
适用场景
qmd 最典型的应用场景是个人数字花园或写作工作台中的笔记管理系统。例如，一位研究人员每天撰写多篇实验记录或读书笔记，这些内容散落于不同日期命名的 Markdown 文件中。通过将整个笔记目录注册为 qmd 收藏集，他可以在忘记具体文件名时，仅用自然语言提问‘上周关于神经网络优化的讨论在哪里？’，qmd 便能从语义层面召回高度相关的文档片段，即使原文未包含完整关键词。这种能力尤其适用于跨主题联想检索，比如从一篇机器学习论文草稿联想到此前未完成的代码注释或会议纪要。 另一个常见用例是技术写作团队维护的产品文档库。成员们频繁协作编写 API 指南、用户手册和技术白皮书，文档结构虽清晰但内容交叉引用密集。当新员工需要查找某接口的历史变更说明时，传统的文件系统遍历效率低下。此时，qmd 的语义搜索功能可快速定位包含‘版本差异’、‘弃用警告’等相关上下文的段落，甚至返回原始 Markdown 源码供直接编辑。结合 `–full` 参数获取全文内容，还能避免二次打开文件的操作负担。 对于开发者而言，qmd 也可用作轻量级知识图谱构建工具。若某项目涉及大量设计决策记录（ADR）、架构图说明或故障复盘报告，将其纳入 qmd 索引后，便能在调试问题时迅速回溯‘当初为何选择微服务而非单体架构’这类深层历史信息。值得注意的是，尽管 qmd 具备一定语义理解能力，但它并非通用代码搜索工具——如需扫描 Git 仓库中的函数定义或变量声明，仍应使用如 ripgrep、LSP 或 GitHub Copilot 等专用方案。因此，合理区分 qmd 与代码搜索工具的角色边界，能最大化其价值。