QMD - Quick Markdown Search

核心用法

qmd 是一款专为 Markdown 笔记和文档设计的本地搜索引擎，采用混合检索架构。用户通过 qmd collection add 添加笔记目录，执行 qmd embed 完成向量化索引后，即可使用三种搜索模式：

• `qmd search`（默认）：基于 BM25 的关键词搜索，响应极快，适合日常使用
• `qmd vsearch`：语义相似度搜索，依赖本地 LLM 进行查询扩展，冷启动较慢
• `qmd query`：混合搜索 + LLM 重排序，质量最高但速度最慢，容易超时

支持指定集合(-c)、调整结果数量(-n)、JSON 输出(--json)等灵活选项，并提供 qmd get/multi-get 进行文档检索。

显著优点

1. 完全本地化：数据不出设备，使用本地 GGUF 模型，隐私性极强
2. 速度分层设计：BM25 搜索几乎瞬时响应，语义搜索按需启用
3. 内容智能分块：自动按语义段落切分，无需严格 Markdown 结构
4. 增量更新友好：qmd update 快速同步变更，qmd embed 按需刷新向量
5. 输出格式丰富：支持纯文本、JSON、文件路径等多种机器可读格式

潜在缺点与局限性

• 冷启动成本高：语义搜索需加载本地模型（如 Qwen3-1.7B），首次运行可能耗时约 1 分钟
• 非代码搜索工具：不适用于源代码仓库检索，专注 Markdown 内容
• 依赖 Bun 运行时：需安装 Bun >= 1.0.0，对 Node.js 用户增加环境负担
• macOS 额外依赖：需单独安装 SQLite 扩展
• 维护 overhead：需配置 cron 或定时任务保持索引新鲜，否则搜索结果可能过时

适合人群

• 本地优先的笔记用户（Obsidian、Logseq、Bear 等导出 Markdown 的用户）
• 需要离线搜索的知识库管理者
• 对数据隐私敏感、不愿使用云端笔记搜索的用户
• 已使用 Bun 生态的开发者

常规风险

• 模型下载：首次自动下载 GGUF 模型，需确保网络可访问 Hugging Face 等源
• 索引体积：大型笔记库的向量化索引可能占用显著磁盘空间
• 路径配置：需确保 $HOME/.bun/bin 在 PATH 中，否则命令不可用
• 性能预期管理：用户可能误将 vsearch/query 作为默认，导致体验卡顿

核心用法

qmd-markdown-search 是一个为本地 Markdown 文件集合（笔记、文档、知识库）提供高性能搜索引擎的 Agent Skill。它封装了 qmd (Quick Markdown Search) 命令行工具的使用指引，帮助用户在本地环境中快速搭建可搜索的笔记系统。Skill 提供了三种搜索模式：基于 BM25 的快速关键词搜索（默认推荐）、基于向量相似度的语义搜索，以及结合了 LLM 重排序的混合搜索，全面覆盖从精确匹配到模糊联想的需求。

显著优点

• 极致本地化与隐私保护：所有索引和搜索操作均在用户本机完成，无需网络连接，不向任何外部服务传输数据，完全符合 GDPR/CCPA 等隐私法规，是处理敏感笔记和内部文档的理想方案。
• 高性能快速检索：默认的 BM25 关键词搜索几乎瞬时返回结果，即使面对大规模 Markdown 集合也能保持流畅的交互体验，极大提升了知识库的可用性。
• 强大的上游工具信誉：底层依赖的 qmd 工具由 Shopify CEO Tobias Lütke (GitHub ID 347) 开发，其 GitHub 仓库已获 24,000+ 星，采用 MIT 开源许可，社区采纳度极高，代码质量和长期维护均有保障。
• 智能内容分块：不依赖严格的 Markdown 标题结构，而是基于内容进行智能分块，能有效处理“不规整”的笔记格式，确保搜索的全面性和准确性。
• 灵活的检索模式：用户可根据需求在速度（BM25）和语义深度（向量搜索）之间灵活选择，应对不同场景的搜索挑战。

潜在缺点或局限性

• 语义搜索可能耗时：vsearch 模式因需调用本地语言模型 (如 Qwen3-1.7B) 进行查询扩展，在冷启动环境下首次搜索可能耗时约 1 分钟，影响即时体验。
• 专为 Markdown 设计：该工具明确适用于 **/*.md 文件集合，不适合用作代码库搜索工具。对于包含大量源文件的开发仓库，需要配合专用的代码搜索工具使用。
• 环境依赖：安装依赖 Bun 运行时环境，在 macOS 上还需通过 Homebrew 安装 SQLite 以支持特定扩展，对非 macOS 或未配置相关环境的用户存在一定门槛。
• 上游工具较新：尽管社区活跃，qmd 仓库创建时间相对较短，其长期稳定性和兼容性仍在持续验证中。

适合的目标群体

• Obsidian, Logseq 等笔记软件用户：希望在其已有的 Markdown 知识库上建立快速、可靠的本地搜索引擎。
• 研究人员与学者：管理大量文献笔记、实验记录，需要快速在海量 Markdown 文档中定位关键信息。
• 隐私敏感型专业人士：如律师、医生、高管等，处理内部文件时要求绝对的数据本地化和隐私控制。
• 个人知识管理爱好者：习惯于用 Markdown 维护日记、读书笔记和技术文档，希望提升检索效率。

使用该技能可能存在的常规风险

• 本地模型性能开销：语义搜索功能依赖下载至 ~/.cache/qmd/models/ 的本地 GGUF 模型，会占用磁盘空间并在运行时消耗 CPU/内存资源，低配置机器可能出现卡顿。
• 索引维护成本：虽然增量更新 (qmd update) 很快，但若频繁依赖向量搜索，每晚重建嵌入 (qmd embed) 可能成为一个耗时任务，需合理规划执行时间。
• 上游依赖变更风险：Skill 的安装指令指向 qmd 主分支最新代码，若无版本锁定，上游的重大更新或 API 变更可能导致与 Agent 配置不兼容。建议用户关注上游发布版并考虑使用 Git Tag 进行版本固定。