Qmd

Qmd 是什么

Qmd 是本地文件搜索与索引 CLI，为 Markdown 等文档建立集合后，提供 BM25 关键词、向量语义和混合重排查询，并能按路径与行号取回原文片段。它还提供 MCP 模式，适合让代理在不上传整套知识库的前提下检索本机资料。

适用场景与选择边界

适合个人笔记、项目文档、规范和知识库的本地检索。只需要少量文件时直接搜索更简单；需要多用户权限、强事务、审计或云端协作时，Qmd 不能替代正式搜索服务。

核心能力与工作机制

collection add 用路径、名称和 mask 建集合，update 刷新索引，status 检查状态。search 执行 BM25，vsearch 执行向量检索，query 组合检索与重排；get 可按集合内路径和起始行读取指定数量的文本。

实际工作流与交付结果

先限定目录和文件掩码，避免无意索引秘密；创建集合后运行 update 与 status。用已知关键词测试 BM25，再用概念问题测试向量与混合检索；从结果路径 get 原文核验。需要代理调用时才启动 qmd mcp。

依赖、账号与权限

需要安装 qmd 二进制。向量嵌入和重排依赖 Ollama，默认地址为本机 11434，也可用 OLLAMA_URL 指定。索引默认写入用户缓存目录，因此需要读取源文件和写缓存权限。

限制、成本与安全风险

索引会复制可检索表示并长期留在缓存，敏感目录、密钥、个人资料和大文件应排除。Ollama 若指向远程地址，文档内容可能离开本机。索引不会自动等于最新内容，使用前要 update，并从原文核对答案。

上手与验收建议

从一个小目录和严格的 md 掩码试用，记录集合名与范围。建立三组测试：精确词、同义问题、应无结果的敏感查询。确认 get 返回的行与源文件一致，再扩大集合或接入 MCP。

来源、版本与许可

依据 ClawHub 1.0.0 详情与完整 SKILL.md 整理；平台未声明许可证，不能据公开可见推断开源。

常见问题

1. 支持哪几种搜索方式？

提供 BM25 关键词 search、向量 vsearch 和带重排的混合 query。建议用同一问题比较三种结果，再从原文片段判断哪种更适合当前资料。

2. 如何建立一个文档集合？

用 collection add 指定本地路径、集合名和文件 mask，然后运行 update 建索引、status 检查。mask 应尽量严格，避免把整个主目录纳入。

3. 向量搜索是否完全离线？

嵌入和重排依赖 OLLAMA_URL，默认是本机 Ollama。若修改为远程服务，内容可能经网络发送，因此应先核查地址、模型与数据政策。

4. 索引文件放在哪里？

默认位于用户目录下的 .cache/qmd。删除源文件不一定立即清除旧索引，应更新或按工具机制删除集合，并把缓存纳入磁盘与隐私管理。

5. 如何读取搜索结果原文？

使用 get 加集合内路径、行号和长度取回片段。代理生成结论前应查看原文上下文，而不是只根据分数、标题或向量命中作答。

6. MCP 模式有什么用途？

qmd mcp 把本地检索能力暴露给兼容客户端，使代理可按需查询。启动前仍要限定集合和文件权限，MCP 并不会自动解决敏感数据访问问题。

7. 索引会自动保持最新吗？

来源只给出显式 qmd update，因此不能假设后台实时同步。文件变动后应更新索引并用 status 检查，再执行依赖最新内容的查询。

8. 许可证是什么？

ClawHub 当前版本的许可证字段为空，本次条目只能标记未声明。公开下载、较高热度或作者身份都不能替代明确许可文本。