qmd-search

qmd 搜索

使用 qmd 对本地 Markdown 知识库进行语义搜索。五种模式——BM25 关键词、向量相似度、混合搜索（扩展 + 重排）、原生文字脚本字面 grep，以及融合式 find——全部在设备本地运行。相较于 Obsidian 内置搜索，主要优势在于它能匹配含义，找到与查询词毫无重合的笔记，并支持跨语言搜索（例如，俄语查询可以检索到英文笔记）。

各模式的适用场景

• 混合搜索（query）——默认模式。适用于真实问题或模糊意图（“如何避免过度设计”）。质量最佳；首次运行时会下载重排和扩展模型（首次较慢）。
• 向量搜索（vsearch）——快速查找概念（“关于具身计算的笔记”）。
• BM25（search）——查找确切关键词、名称或文件名。即时完成，无需模型。
• grep（-m grep）——对 .md 文件进行字面固定字符串 ripgrep 搜索。适用于审查专有名词、转写、确切短语、俄语词干/词形变化和确认内容是否不存在。绕过索引；仅匹配你输入的确切文字脚本/拼写。

双语／专有名称规则（请勿跳过）

这个知识库是双语的（英语／俄语）。嵌入模型处理概念的能力不错，但处理专有名词／特定实体的能力较弱；BM25 也只会匹配你输入的文字脚本。因此：

切勿仅凭一次英文语义查询就断定“知识库里没有”。 对于名称、人物、宠物、地点、外语词汇或双语主题：

1. 先进行语义搜索（query / vsearch）。
2. 生成可能的原生文字脚本拼写／词干并尝试搜索，例如 Ziggy → Зигги/Зиги、dog/pet → собак, пёс, щенок, питомц, животн。使用词干（собак 可匹配 собака/собаку/собаки），不要只用主格形式。
3. 在断定内容不存在之前，进行一次字面搜索：qmd-search.sh -m grep -n 20 "Зигги"。
4. 利用字面搜索结果区分相近名称（例如宠物 Зигги 与弗洛伊德的 Зигмунд）。
5. 如果所有方法都无效，请说“我用这些查询没有找到：……”，并列出尝试过的词语——不要说“知识库里没有”。检查是否不存在时，将 -n 提高到约 20。

主要用法——包装脚本

请使用捆绑的包装脚本；它会抑制 qmd 的 stderr 旋转提示，按 score path 格式化结果（解析 qmd 的 JSON，因此文件名中的逗号也能安全处理），并尽可能避免在 qmd embed 正在运行时执行搜索（此时搜索会返回空结果；可使用 --force 强制运行）：

~/.claude/skills/qmd-search/scripts/qmd-search.sh [-m query|search|vsearch|grep|find] [-n N] [-c COLLECTION] [--snippet] [--min-score X] [--json] [--full] <query...>

示例：

qmd-search.sh "what helps with anxiety"                 # hybrid (default)
qmd-search.sh -m vsearch -n 8 "behavioral health from photos"
qmd-search.sh -m search sensorium                       # BM25 keyword
qmd-search.sh -m grep -n 20 "Зигги"                     # literal native-spelling / absence check
qmd-search.sh -m find "Зигги собака"                    # fused: semantic + literal in one call
qmd-search.sh --snippet "agent orchestration"           # rows + matching snippets
qmd-search.sh --min-score 0.5 "quarterly planning"      # drop low-relevance hits
qmd-search.sh --json "agent orchestration"              # structured output for further processing

获得结果后，直接读取排名靠前的文件（它们是普通的知识库路径），或使用 qmd get "<path>:<line>" -l <N> 获取片段。

设置／索引（仅当 qmd status 显示知识库尚未编入索引时）

qmd collection add ~/Brains/brain --name brain        # index the vault
qmd context add qmd://brain "short description of the vault"
qmd embed                                              # build vectors; re-run until status shows 0 pending
qmd cleanup                                            # compact the index

大量编辑后刷新：qmd update && qmd embed。随时可使用 qmd status 检查状态。

操作规则（请勿跳过）

• 一次只运行一个嵌入任务，且嵌入期间绝不搜索——两者都会导致结果为空或无效。包装脚本会保护搜索；手动调用 qmd 时，请先检查 qmd status。
• 如果嵌入任务始终无法将待处理项降至 0，请检查磁盘空间（df -h）——磁盘空间已满会导致写入静默失败。参见 references/cli-reference.md →“操作注意事项”。
• 向量分数通常不高（约 0.4–0.6）；应根据排名而非绝对分值进行判断。

MCP（原生工具）与 CLI 包装脚本

qmd 提供 MCP 服务（qmd mcp，stdio），可使用 query、get、multi_get、status 工具。如果它已在宿主中注册（例如 .mcp.json），混合搜索时优先使用原生 query 工具——它会返回结构化结果，不会出现旋转提示、JSON 解析或退出码方面的问题。注册方式：

{ "mcpServers": { "qmd": { "command": "qmd", "args": ["mcp"] } } }

需要 MCP 未涵盖的功能时，请使用包装脚本（scripts/qmd-search.sh）：仅 BM25（search）、仅向量（vsearch）、字面／原生文字脚本**grep搜索、融合式find**模式、--snippet 或 --min-score。上述双语／专有名称规则同样适用于这两种方式。

质量 / 评估

evals/fixture.example.json + scripts/run-evals.sh 会运行 qmd bench，评估搜索质量（按后端统计精确率、召回率和 MRR）。基线和解读请参阅：evals/BASELINE.md。修改封装脚本、索引或嵌入模型后，请重新运行评估；与基线相比出现下降即为回归。

参考

完整的命令概览、查询语法（lex:/vec:/hyde:）、输出格式、模型和恢复步骤，请参阅 references/cli-reference.md。