寻找一篇笔记

↑ ↓ 移动 · Esc 关闭查看全部文章
技术 已归档

QMD 常用命令

整理 QMD 本地 Markdown 知识库最常用的初始化、索引、检索、原文读取和 MCP 命令,并说明 lexical、vector、HyDE 和 rerank 分别什么时候用。

这篇文章已归档,保留原链接供历史查阅。

作者:黄撑 更新于 2026-09-22
本文目录 14 节 · 展开收起

QMD 解决的是一个很具体的问题:Markdown 文档越来越多以后,怎么让人和 Agent 快速找到真正需要的那几篇?

我现在仍然把 Markdown 和 Git 当成知识库本体。QMD 不负责取代原文,而是在旁边增加全文检索、向量检索、混合检索和 MCP 接口。

QMD · QUICK MARKDOWN SEARCHMarkdown 继续做人能读的知识库,QMD 负责让机器更快找到它

原文仍然可以直接编辑、Git diff 和审查;索引只是可重建的检索层。

01 · SOURCEMarkdown正式知识原文
→
02 · INDEXQMDBM25 · Vector · Rerank
→
03 · CONSUMER人 / AgentCLI · MCP

这篇只整理日常最常用的命令,以及我实际使用后留下来的检索顺序。命令以 QMD 2.8.x 的 CLI 行为为基线;版本变化后,以本机 qmd —help 为准。

先理解三个东西

一个项目级 QMD 知识库可以长这样:

knowledge-base/
├── .qmd/
│   ├── index.yml
│   └── index.sqlite
├── docs/
├── api-docs/
├── skills/
└── reference-projects/

这里其实有三层:

原文层Markdown

真正应该长期维护和 Git 同步的知识。QMD 可以删掉重建,原文不能丢。

检索层.qmd / index.sqlite

全文索引、向量和检索状态。它是运行时产物,可以重新生成。

分区层Collection

把 docs、API、Skill、参考项目等不同身份的资料分开索引和过滤。

我通常把 .qmd/index.yml 提交进 Git,而把 .qmd/index.sqlite 放进 .gitignore。这样索引规则跟着仓库走,但不同电脑各自生成运行时数据库。

初始化与维护

第一次给项目接入 QMD:

qmd init

日常真正高频的是下面三条:

qmd update
qmd embed
qmd status
1
qmd update重新扫描文档

Markdown 新增、删除、修改后,先更新全文索引。

→
2
qmd embed刷新向量

需要语义检索时,为新增或变化内容生成 embedding。

→
3
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

已知准确词: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 对配置文件中的敏感信息进行加密保存"
LEX词已经知道

尽量命中准确文本。适合技术词、代码符号、文件名、报错。

VEC意思知道,词不知道

按语义相似度找内容,适合自然语言问题和概念检索。

HyDE先描述“答案可能长什么样”

用假设答案帮助召回与问题相关、但措辞差距更大的资料。

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 输出

对于精确函数名、文件名和错误字符串,这种方式通常足够,而且明显更轻。

有准确技术词search / lex

先走便宜、稳定的精确检索。

→
只能描述意思vsearch / vec

再进入语义检索。

→
仍然不稳定query / hyde / rerank

最后再扩大召回和排序成本。

找到候选后,要继续读原文

搜索最容易犯的错误,是看到 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 jsonJSON 输出交给程序或 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”。

相反,检索顺序应该从最便宜、最贴近当前项目的信息开始。

01
CURRENT PROJECT当前项目有没有可靠的相同用法?

有就直接沿用,不重复查知识库。

↓
02
NAVIGATION知识库索引页能否直接定位?

目录、llms.txt 或已知正式页面能定位,就直接读原文。

↓
03
QMD FALLBACK精确词先 lexical,找不到再语义

先小范围召回,必要时再使用 vec / hyde / rerank。

↓
04
FULL SOURCEget / multi-get 读取正式原文

确认上下文、限制和边界后,再开始实现。

这条顺序的核心不是“少调用工具”,而是避免把非常简单的确定性问题也升级成一次昂贵的语义搜索。

最后:真正高频的命令

# 初始化
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 面前。