核心用法
qmd 是一款专为本地文档检索设计的 CLI 工具，集成 BM25 传统检索、向量语义搜索与重排序技术，适用于需要高频检索本地知识库的用户。核心功能包括：
索引管理：通过 qmd collection add /path --name docs --mask "**/*.md" 建立命名集合，支持按文件掩码过滤；qmd update 增量更新索引，索引默认存储于 ~/.cache/qmd。
多模态检索：qmd search 执行 BM25 关键词检索；qmd vsearch 启用向量语义搜索（需 Ollama 本地模型）；qmd query 自动融合两者并rerank；qmd get 可精准定位文件行号范围提取内容。
MCP 集成：qmd mcp 启动 MCP 服务，将本地搜索能力开放给兼容客户端，实现 AI 助手与本地知识库的无缝对接。
显著优点
1. 混合检索架构：BM25 保证关键词精准匹配，向量搜索捕捉语义关联，重排序优化结果相关性，显著优于单一检索方案。
2. 完全离线运行：除可选 Ollama 本地嵌入服务外无需网络，敏感文档不上云，适合企业内网与隐私敏感场景。
3. 开源可信背书：作者 Tobias Lütke 为 Shopify 联合创始人兼 CEO，GitHub 仓库获 28,000+ Stars，MIT 协议保障长期可用。
4. 轻量化设计：74 行文档型 Skill，零依赖、零代码执行风险，安装与维护成本极低。
潜在缺点与局限性
1. Ollama 依赖门槛：向量搜索与重排序需本地部署 Ollama 及嵌入模型，对非技术用户配置成本较高；仅使用 BM25 则无需此依赖。
2. 索引存储开销：大规模文档集会产生 GB 级本地索引，需关注磁盘空间；首次索引构建可能耗时较长。
3. MCP 安全边界：启用 qmd mcp 后，本地索引向 MCP 客户端开放，需确保客户端可信，避免敏感目录被意外暴露。
4. 格式支持有限：当前主要针对 Markdown 等文本文件，复杂格式（PDF、Office）需预处理转换。
适合的目标群体
- 开发者与工程师：管理技术文档、代码笔记、API 文档的个人知识库
- 研究人员与学术用户：本地化论文库、实验记录的全文检索
- 隐私敏感型企业用户：需在离线环境构建内部文档搜索系统的团队
- AI 进阶用户：希望通过 MCP 将本地知识库接入 Claude、Cursor 等 AI 工作流
使用风险提示
- 敏感数据索引：
qmd collection add应避免包含 SSH 密钥、环境变量、密码等敏感路径，索引文件虽本地存储但可能被备份工具同步 - Ollama 端点配置：
OLLAMA_URL默认指向 localhost:11434，若修改为远程端点需确保其受信任，避免嵌入数据泄露 - 性能考量：首次索引大规模目录会占用 CPU/磁盘 IO；向量检索对内存有额外要求