核心用法
qmd是一款本地文件搜索与索引CLI工具的MCP封装，专为需要高效检索本地文档的用户设计。核心工作流程分为索引构建与智能检索两个阶段：
索引阶段：通过qmd collection add /path --name docs --mask "**/*.md"添加待索引目录，支持通配符筛选特定文件类型；执行qmd update构建索引，数据默认存储于~/.cache/qmd。索引采用混合架构，同时支持传统BM25关键词索引与向量语义索引。
检索阶段：提供三级检索能力——qmd search执行BM25关键词搜索，qmd vsearch执行向量语义搜索，qmd query执行混合检索（BM25+向量+重排序）。通过qmd get docs/path.md:10 -l 40可精确定位文档具体段落。
MCP集成：qmd mcp命令启用MCP模式，使AI Agent能够直接调用本地检索能力，实现RAG（检索增强生成）架构的完全本地化部署。
显著优点
1. 完全本地化处理：所有索引、embedding、重排序均在本地完成，引用Ollama本地服务（默认localhost:11434），数据零外泄，满足企业合规与隐私敏感场景。
2. 混合检索架构：BM25保证关键词精确匹配，向量检索捕获语义关联，重排序优化结果相关性，三重机制协同提升搜索质量。
3. 轻量无依赖：Skill本身为纯Markdown文档封装，无可执行代码，依赖外部qmd二进制工具，安装简洁。
4. 来源高度可信：上游作者Tobi Lutke为Shopify创始人，GitHub账号信誉卓著；维护者instant-picture在clawhub平台有稳定发布记录。
潜在缺点与局限性
1. 外部工具依赖：需独立安装qmd二进制与Ollama服务，配置链路较长，对非技术用户存在门槛。
2. 本地资源占用：向量索引与embedding计算消耗本地CPU/GPU资源，大规模文档集可能面临性能瓶颈。
3. 无分布式能力：纯单机架构，不支持多机协同索引或团队共享索引，企业级场景需自行扩展。
4. 索引维护成本：文档变更后需手动执行qmd update，无实时增量更新机制。
适合的目标群体
- 隐私敏感型用户：律师、医生、研究人员等需处理机密文档，无法接受云端RAG方案。
- 离线工作环境：内网开发、安全隔离网络等无法连接外部API的场景。
- 技术向知识管理者：开发者、技术写作者需管理大量Markdown/代码文档，追求精准检索。
- AI应用开发者：构建完全本地化的RAG应用，替代OpenAI/Claude等云端embedding服务。
使用风险说明
1. 索引缓存泄露风险：~/.cache/qmd存储被索引文件的内容片段，若设备共享或丢失可能导致信息泄露，建议定期清理或加密存储。
2. 敏感目录误索引：配置宽泛的--mask可能意外索引含密钥、密码的文件，需严格限定路径范围。
3. Ollama服务安全：确保本地Ollama为官方版本，避免端口暴露于公网；可通过OLLAMA_URL环境变量自定义绑定地址增强隔离。
4. 工具链版本兼容性：qmd二进制与Skill文档可能版本脱节，关注上游更新以确保功能同步。