用途：在本地 Markdown 知识库（如 Obsidian vault）中做语义搜索，匹配含义而非仅关键词，可跨语言检索（例如俄语查询命中英文笔记）。
主要能力与模式：hybrid（query，默认，质量最佳，首次运行会下载重排/扩展模型）；vector（vsearch，快速概念查找）；BM25（search，精确关键词/文件名，即时且无需模型）；grep（-m grep，对 .md 文件做字面固定字符串 ripgrep，绕过索引，适合专有名词、音译、精确短语与缺失检查）；find（融合语义与字面结果）。
使用方式：优先使用封装脚本 ~/.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"；qmd-search.sh -m vsearch -n 8 "behavioral health from photos"；qmd-search.sh -m grep -n 20 "Зигги"；qmd-search.sh -m find "Зигги собака"。命中后可直接读取文件，或用 qmd get "<path>:<line>" -l <N> 取片段。
索引与维护：若 qmd status 显示未索引，执行 qmd collection add ~/Brains/brain --name brain、qmd context add qmd://brain "..."、qmd embed（重复至 0 pending）、qmd cleanup；大量编辑后 qmd update && qmd embed。
MCP：qmd mcp（stdio）暴露 query、get、multi_get、status，注册示例 {"mcpServers":{"qmd":{"command":"qmd","args":["mcp"]}}}；需要 BM25-only、vector-only、grep、find、--snippet、--min-score 时用封装脚本。
限制与注意：同一时间只运行一个 embed，嵌入期间不要搜索，否则结果为空或异常；嵌入长期不到 0 pending 时检查磁盘空间（df -h）；向量分数通常约 0.4–0.6，应看排名而非绝对值；双语/专有名词场景不要仅凭一次英文语义查询就断定不存在，应尝试原生拼写与词干并做字面 grep，失败时列出尝试过的词。质量评估可用 evals/fixture.example.json 与 scripts/run-evals.sh 运行 qmd bench，基线见 evals/BASELINE.md。完整命令、查询语法（lex:/vec:/hyde:）与恢复步骤见 references/cli-reference.md。