QMD CLI

核心用法

QMD 是一款面向本地 Markdown 知识库的检索工具，提供三种搜索模式满足不同场景需求：

• `qmd search`：基于 BM25 算法的关键词搜索，速度快，适合精确匹配已知术语
• `qmd vsearch`：向量语义搜索，理解概念和同义词，适合模糊查询
• `qmd query`：混合搜索 + LLM 重排序，质量最佳但速度最慢，适合复杂问题

支持集合管理（collection add）、文档检索（get/multi-get）、以及 MCP 服务器模式集成。所有命令建议配合 --json 使用以获得结构化输出。

显著优点

1. 多模式检索策略：从快速关键词到深度语义理解，灵活覆盖不同查询意图
2. 本地优先架构：数据完全本地处理，无需云端依赖，隐私可控
3. MCP 原生支持：可作为 Model Context Protocol 服务器运行，便于与 AI 工具链集成
4. 精确文档定位：支持按路径、ID、行号范围精准获取内容片段

潜在局限

• 冷启动延迟：向量搜索（vsearch/query）首次初始化约需 1 分钟
• Bun 运行时依赖：要求使用 Bun 而非 Node.js 安装运行
• 仅支持 Markdown：非结构化或二进制文档需预处理转换
• 无分布式能力：单机索引，不适合团队协作的大规模知识库场景

适合人群

• 个人开发者、技术写作者管理本地技术笔记
• 需要为 AI 助手提供 RAG（检索增强生成）上下文的知识工作者
• 偏好本地优先、注重数据隐私的终端用户

常规风险

• 索引同步风险：qmd update 需手动执行，文件变更后可能返回过时结果
• 路径注入可能：multi-get 支持 glob 模式，需确保集合路径边界受控
• LLM 重排序成本：query 模式若频繁调用可能产生 API 费用（如配置外部 LLM）
• 无权限管控：无内置访问控制，多用户环境需谨慎配置文件系统权限

核心用法

QMD 是一个面向本地 Markdown 知识库的搜索与检索工具，通过 MCP 协议暴露给 AI 助手使用。它封装了 qmd CLI 的功能，提供三种搜索模式：

1. search（BM25 关键词搜索）：基于传统倒排索引，速度快，适合精确关键词匹配和已知术语查询
2. vsearch（向量语义搜索）：利用嵌入向量捕捉语义相似性，支持同义词和概念关联查询
3. query（混合搜索 + LLM 重排序）：结合关键词与语义搜索，并通过大模型重排序结果，质量最优但速度最慢

基础工作流：先通过 collection add 建立索引集合，运行 embed 生成向量嵌入（语义搜索必需），然后使用 --json 标志获取结构化输出以便程序处理。支持单文档获取（get）和批量获取（multi-get），以及通过 update 增量维护索引。

显著优点

• 多模态搜索策略：三种模式覆盖从快速查找到深度理解的不同场景，用户可按需选择
• 本地优先架构：所有索引和数据处理在本地完成，无云端依赖，隐私性强
• MCP 原生集成：作为 MCP 服务器运行，可直接被 Claude 等 AI 助手调用，实现知识库对话式访问
• 灵活的结果控制：支持按集合过滤、分数阈值、结果数量限制、完整内容返回等精细调节
• 增量维护：update 命令仅处理变更文件，避免全量重建索引的开销

潜在缺点与局限性

• 外部依赖必需：Skill 本身仅为文档包装器，必须额外安装 qmd CLI（bun install -g），增加了环境配置复杂度
• 冷启动延迟：向量搜索（vsearch/query）有约 1 分钟初始化延迟，不适合高频交互场景
• Bun 运行时绑定：依赖 Bun 而非 Node.js，对未使用 Bun 的用户增加工具链负担
• Markdown 格式限定：仅支持 Markdown 文件，无法直接处理 PDF、Word 等其他常见文档格式
• 无内置同步机制：缺乏跨设备索引同步功能，多机器使用需手动迁移索引

适合人群

• 拥有大量本地 Markdown 笔记的知识工作者（开发者、研究员、作家）
• 需要为 AI 助手配置私有知识库的极客用户
• 对数据隐私敏感、拒绝云笔记服务的用户
• 已使用 Bun 生态的技术从业者

常规风险

• 供应链风险：qmd CLI 来自个人开发者（tobi），虽项目公开透明，但长期维护和审计频率不及企业级项目
• 文件系统权限：qmd 需要读取用户指定的知识库目录，建议遵循最小权限原则，避免授予整个 home 目录访问权
• 索引占用空间：向量嵌入会显著增加磁盘占用，大规模知识库需预留充足存储
• 版本兼容性：qmd CLI 更新可能引入 breaking changes，需关注上游 release notes