介绍
# QMD - Local Markdown Search
从本地索引的 Markdown 知识库中搜索和检索文档。
## 安装
```bash bun install -g https://github.com/tobi/qmd ```
## 设置
```bash # Add a collection qmd collection add ~/notes --name notes --mask "**/*.md"
# Generate embeddings (required for vsearch/query) qmd embed ```
## 使用规则
在调用 qmd 命令时，**务必使用 `--json` 标志**以获取结构化输出。
## 搜索命令
### search (BM25 关键词搜索 - 快速)
```bash qmd search "authentication flow" --json qmd search "error handling" --json -n 10 qmd search "config" --json -c notes ```
### vsearch (向量语义搜索)
```bash qmd vsearch "how does login work" --json qmd vsearch "authentication best practices" --json -n 20 ```
### query (混合搜索配合 LLM 重排序 - 最佳质量)
```bash qmd query "implementing user auth" --json qmd query "deployment process" --json --min-score 0.5 ```
### 搜索选项
| 选项 | 描述 | |--------|-------------| | `-n NUM` | 结果数量 (默认: 5，使用 --json 时为 20) | | `-c, --collection NAME` | 限制在特定集合中 | | `--min-score NUM` | 最低分数阈值 | | `--full` | 在结果中返回完整的文档内容 | | `--all` | 返回所有匹配项 |
## 检索命令
### get (单个文档)
```bash qmd get docs/guide.md --json qmd get "#a1b2c3" --json qmd get notes/meeting.md:50 -l 100 --json ```
### multi-get (多个文档)
```bash qmd multi-get "docs/*.md" --json qmd multi-get "api.md, guide.md, #abc123" --json qmd multi-get "notes/**/*.md" --json --max-bytes 20480 ```
## 维护命令
```bash qmd update # Re-index changed files qmd status # Check index health qmd collection list # List all collections ```
## 搜索模式选择
| 模式 | 速度 | 质量 | 最适用于 | |------|-------|---------|----------| | search | 快 | 良 | 精确关键词，已知术语 | | vsearch | 中等 | 较好 | 概念查询，同义词 | | query | 慢 | 最佳 | 复杂问题，不确定术语 |
**性能提示：** `vsearch` 和 `query` 在向量初始化时约有 1 分钟的冷启动延迟。交互式使用建议首选 `search`。
## MCP 服务器
qmd 可以作为 MCP 服务器运行，以便直接集成：
```bash qmd mcp ```
暴露工具：`qmd_search`、`qmd_vsearch`、`qmd_query`、`qmd_get`、`qmd_multi_get`、`qmd_status`