QMD 常用命令
整理 QMD 本地 Markdown 知识库最常用的初始化、索引、检索、原文读取和 MCP 命令,并说明 lexical、vector、HyDE 和 rerank 分别什么时候用。
这篇文章已归档,保留原链接供历史查阅。
本文目录 14 节 · 展开收起
QMD 解决的是一个很具体的问题:Markdown 文档越来越多以后,怎么让人和 Agent 快速找到真正需要的那几篇?
我现在仍然把 Markdown 和 Git 当成知识库本体。QMD 不负责取代原文,而是在旁边增加全文检索、向量检索、混合检索和 MCP 接口。
原文仍然可以直接编辑、Git diff 和审查;索引只是可重建的检索层。
这篇只整理日常最常用的命令,以及我实际使用后留下来的检索顺序。命令以 QMD 2.8.x 的 CLI 行为为基线;版本变化后,以本机 qmd —help 为准。
先理解三个东西
一个项目级 QMD 知识库可以长这样:
knowledge-base/
├── .qmd/
│ ├── index.yml
│ └── index.sqlite
├── docs/
├── api-docs/
├── skills/
└── reference-projects/
这里其实有三层:
真正应该长期维护和 Git 同步的知识。QMD 可以删掉重建,原文不能丢。
全文索引、向量和检索状态。它是运行时产物,可以重新生成。
把 docs、API、Skill、参考项目等不同身份的资料分开索引和过滤。
我通常把 .qmd/index.yml 提交进 Git,而把 .qmd/index.sqlite 放进 .gitignore。这样索引规则跟着仓库走,但不同电脑各自生成运行时数据库。
初始化与维护
第一次给项目接入 QMD:
qmd init
日常真正高频的是下面三条:
qmd update
qmd embed
qmd status
qmd update重新扫描文档Markdown 新增、删除、修改后,先更新全文索引。
qmd embed刷新向量需要语义检索时,为新增或变化内容生成 embedding。
qmd status检查结果确认 Collection、文档数量、向量数量和索引状态。
知识库本身也是 Git 仓库时,可以:
qmd update --pull
只刷新某个 Collection:
qmd embed -c docs
强制重建 embedding:
qmd embed -f
长期增删大量文件后,可以先预览清理范围:
qmd cleanup --dry-run
确认后再执行:
qmd cleanup
Collection:给知识标记身份
Collection 可以理解成“这批文件属于哪一类知识”。
qmd collection add ./docs --name docs
qmd collection add ./api-docs --name api
qmd collection add ./reference-projects --name reference
查看和管理:
qmd collection list
qmd collection show docs
qmd collection rename docs knowledge
qmd collection remove reference
查看已经进入索引的文件:
qmd ls
qmd ls api
Collection 不只是为了目录整齐。对 Agent 来说,它还能表达资料身份:正式 API、稳定开发知识、专项 Skill、历史参考项目可以分别放在不同 Collection,并在规则中说明优先级。
搜索有三条路
QMD 日常最值得记住的是:
qmd search
qmd vsearch
qmd query
DPAPIBM25 全文搜索,不需要启动 LLM。函数名、文件名、错误文本特别适合。
如何保存敏感配置纯向量相似度。文档和提问用词不一致时更有价值。
关键词 + 语义 + rerank可以做查询扩展和混合检索,质量更高,但成本也更高。
已知准确词:search
qmd search "DPAPI"
qmd search "traceback.format_exc"
qmd search "selectorsV2.xml"
如果手里已经有函数名、API 名、文件名、异常文本、XPath 或独特技术词,我一般先用 search。
qmd search "DPAPI" -n 5
qmd search "DPAPI" -c api
qmd search "DPAPI" -n 5 --format json
只知道语义:vsearch
qmd vsearch "怎么把完整异常现场写进日志"
即使文档真正写的是 traceback.format_exc(),只要语义接近,向量检索仍有机会找到。
综合检索:query
qmd query "怎么处理 Python 异常日志"
单行普通文本会进入查询扩展流程。它适合“我知道问题,但不知道知识库里会怎么表述”的情况。
不过开发知识库里很多问题其实非常精确。如果已经知道 DPAPI、find_process_window 这类词,就没有必要每次都启动完整语义链路。
query 里的 lex、vec、hyde
qmd query 还可以明确指定检索类型:
qmd query "lex: DPAPI"
qmd query "vec: Windows 本地敏感配置加密"
qmd query "hyde: 使用 Windows DPAPI 对配置文件中的敏感信息进行加密保存"
尽量命中准确文本。适合技术词、代码符号、文件名、报错。
按语义相似度找内容,适合自然语言问题和概念检索。
用假设答案帮助召回与问题相关、但措辞差距更大的资料。
Linux / macOS 下可以组合多个 typed query:
qmd query $'lex: DPAPI\nvec: Windows 本地敏感配置加密'
PowerShell:
$query = @"
lex: DPAPI
vec: Windows 本地敏感配置加密
"@
qmd query $query
精确词检索时,我会关掉 rerank
QMD 的混合查询可以继续让本地模型对候选结果重新排序,这在模糊问题上很有用。
但如果只是搜一个非常准确的技术词,rerank 经常没有必要。
我日常更常用:
qmd query "lex: DPAPI" -n 5 -C 10 --no-rerank
给 Agent:
qmd query "lex: DPAPI" -n 5 -C 10 --no-rerank --format json
| 参数 | 作用 |
|---|---|
-n 5 | 最多返回 5 条结果 |
-C 10 | 最多保留 10 个候选进入后续排序 |
—no-rerank | 跳过 LLM reranker |
—format json | 用 JSON 输出 |
对于精确函数名、文件名和错误字符串,这种方式通常足够,而且明显更轻。
先走便宜、稳定的精确检索。
再进入语义检索。
最后再扩大召回和排序成本。
找到候选后,要继续读原文
搜索最容易犯的错误,是看到 snippet 里两三行内容就直接开始实现。
更稳妥的做法是:
搜索 = 定位候选
get / multi-get = 读取依据
读取一篇文档:
qmd get "docs/coding-style.md"
也可以使用搜索结果返回的 docid:
qmd get "#abc123"
只读某个范围:
qmd get "docs/coding-style.md:100:40"
表示从第 100 行开始读取 40 行。
一次读取多篇:
qmd multi-get "docs/a.md,docs/b.md"
qmd multi-get "docs/*.md" -l 100
对于 Agent,这一步尤其重要。搜索结果应该只是“候选定位器”,真正写代码或下结论之前,再读取完整正式原文。
这些参数也很常用
| 参数 | 作用 | 常见场景 |
|---|---|---|
-n <num> | 限制结果数量 | Agent 搜索避免返回太多 |
-c <name> | 限定 Collection | 已知资料属于 API / docs 等分区 |
-C <num> | 限制 rerank 候选 | 降低混合查询成本 |
—no-rerank | 跳过 LLM rerank | 精确词、本地 CPU 环境 |
—format json | JSON 输出 | 交给程序或 Agent |
—full | 返回完整文档 | 已经确认命中文档 |
—full-path | 显示磁盘路径 | 排查具体来源文件 |
—explain | 显示检索评分过程 | 调试“为什么排在这里” |
MCP:把 QMD 直接交给 Agent
QMD 可以直接启动 MCP Server:
qmd mcp
这样 Claude Code、Codex 等支持 MCP 的 Agent 就可以直接调用 QMD 的检索和读取能力。
Claude Code 项目级配置可以类似:
{
"mcpServers": {
"qmd": {
"type": "stdio",
"command": "qmd",
"args": ["mcp"]
}
}
}
Codex:
[mcp_servers.qmd]
command = "qmd"
args = ["mcp"]
cwd = "/path/to/knowledge-base"
这里要特别注意 工作目录。
如果 QMD 使用项目里的 .qmd/index.yml,Agent 却从另一个业务项目启动,直接运行 qmd mcp 可能找不到正确的项目级索引。解决办法就是让 MCP 启动命令固定进入知识库根目录,或者像 Codex 一样直接配置 cwd。
我现在实际采用的检索顺序
把 QMD 接进 Agent 后,我并没有规定“所有问题都先搜 QMD”。
相反,检索顺序应该从最便宜、最贴近当前项目的信息开始。
有就直接沿用,不重复查知识库。
目录、llms.txt 或已知正式页面能定位,就直接读原文。
先小范围召回,必要时再使用 vec / hyde / rerank。
确认上下文、限制和边界后,再开始实现。
这条顺序的核心不是“少调用工具”,而是避免把非常简单的确定性问题也升级成一次昂贵的语义搜索。
最后:真正高频的命令
# 初始化
qmd init
# 更新知识库
qmd update
qmd embed
qmd status
# 查看 Collection / 文件
qmd collection list
qmd ls
# 精确关键词
qmd search "DPAPI" -n 5
# 精确 query,跳过 rerank
qmd query "lex: DPAPI" -n 5 -C 10 --no-rerank
# 语义搜索
qmd vsearch "如何安全保存本地密码"
# 混合查询
qmd query "如何安全保存本地密码"
# 阅读正式原文
qmd get "docs/example.md"
qmd multi-get "docs/a.md,docs/b.md"
# 启动 MCP
qmd mcp
如果只把 QMD 当作“向量数据库”,反而容易把事情想复杂。
我更愿意把它理解成 Markdown 知识库旁边的一层检索基础设施:原文继续由人维护和审查,QMD 负责把合适的原文送到人和 Agent 面前。