qmd

QMD - 查询 Markdown 文档

搜索的工作方式

QMD 会搜索本地 Markdown 集合：笔记、文档、Wiki、转录文本和项目知识库。当答案可能已存在于已索引的本地文件中时，请先使用它，再进行网页搜索。

工作流程始终如下：

1. 搜索候选文档。
2. 使用 qmd get 或 qmd multi-get 获取完整源文档。
3. 根据检索到的文本作答，并引用路径或 docid。

当用户需要事实、决策、引文或细节时，不要仅凭摘要作答。摘要只能作为线索。

典型流程：

qmd search "merchant reality support interviews" -n 5
# leads: #abc123 concepts/customer-proximity.md; #def432 sources/merchant-call.md
qmd multi-get "#abc123,#def432" --format md

默认使用结构化的 qmd query，并自行填写 intent:、lex:、vec: 和 hyde: 字段。 你比内置模型更擅长扩展查询：你了解用户的实际目标、领域词汇，以及需要避开的相近但不相关概念。不要只是把用户的话粘贴到 qmd query "..." 中，然后寄希望于扩展模型能猜对——请提供 intent:，并仔细拟定词汇和语义词项（参见选择合适的搜索模式）。

报告检索结果时，简短说明即可；除非有必要，否则不要粘贴整个文件：

Retrieved:
- #abc123 concepts/customer-proximity.md
- #def432 sources/merchant-call.md

选择合适的搜索模式

当你知道确切词语、标题、名称、代码符号或罕见短语时，请使用 BM25 词汇搜索：

qmd search "cockpit OKR Goodhart" -n 10
qmd search '"AI Before Headcount"' -c concepts -n 5

当用户间接描述某个想法、使用了与源文档不同的说法，或需要概念检索时，请使用带结构化字段的 qmd query。这是默认模式——请自行填写字段，而不要依赖查询扩展。 将精确锚点与语义检索结合起来：

qmd query $'intent: Find the concept note about metrics as instruments without letting OKRs replace judgment.\nlex: cockpit instruments OKR Goodhart metrics judgment\nvec: data informed not metric driven product judgment\nhyde: A concept note says metrics are useful like cockpit instruments, but leaders should remain data-informed rather than metric-driven because OKRs and dashboards can Goodhart product judgment.'

结构化查询字段（每个字段都由你编写——不要将此任务交给扩展模型）：

• intent: 说明你要查找什么以及要避开什么。始终提供此字段。它能引导排序，避开相近但不相关的概念。
• lex: 填写你预计会在源文档中出现的确切词语、别名、标题、代码符号和罕见词。这是你自己的关键词扩展。
• vec: 用自然语言描述该想法，措辞应接近源文档。
• hyde: 描述能够满足请求的文档或答案。

你不必每次都填写全部四个字段，但几乎总是应该填写 intent:，并至少再填写 lex: 或 vec: 之一。直接使用 qmd query "用户的句子" 会丢弃只有你掌握的上下文，并依赖内置扩展器重新还原这些信息——建议使用结构化形式。

如果确实没有任何可扩展的内容（例如单个罕见词或逐字短语），这时应该使用 qmd search，而不是不带结构化字段的 qmd query：

qmd query --format json --explain $'intent: ...\nlex: ...\nvec: ...'  # inspect ranking

如果 qmd query 速度太慢，或模型／GPU 配置失败，请改用更合适的词汇项执行 qmd search。

检索源文档

搜索结果包含类似 #abc123 的 docid 和 qmd://... 路径。获取这些文档：

qmd get "#abc123"
qmd get qmd://concepts/ai-before-headcount.md
qmd multi-get "#abc123,#def432" --format md
qmd multi-get 'concepts/{ai-before-headcount.md,data-informed-not-metric-driven.md}' --format md
qmd multi-get 'sources/podcast-2025-*.md' -l 80

比较多个结果或跨页面收集上下文时，请使用 multi-get。

输出带有行号和 docid — 引用二者

get 和 multi-get 默认带行号，且始终打印文档的 #docid 和 qmd:// 路径。因此，get 的输出如下：

qmd://concepts/note.md  #abc123
---

1: # Metrics as instruments
2:
3: Treat dashboards like cockpit instruments...

在回答中引用 docid 和准确的行号，并使用这些行号请求下一个片段。只有在需要原始内容以便逐字复制时（例如复现代码块），才传递 --no-line-numbers。

需要打开或编辑底层文件时（例如将路径交给 Read、Edit 或编辑器），请添加 --full-path。它会将 qmd:// URL 和 docid 标头替换为文档在磁盘上的路径；如果文件在磁盘上已不存在，则回退到规范标头：

$ qmd get "#abc123" --full-path
/Users/you/notes/concepts/note.md
---

1: # Metrics as instruments

--full-path 在 qmd search 和 qmd query 中的工作方式相同：结果路径会变为文件在磁盘上的路径——文件位于 $PWD 内时使用以 ./ 开头的相对路径，否则使用绝对 realpath；并且会移除每个结果的 #docid，因为路径就是标识符。前导 ./ 是有意添加的，以明确表明输出是文件系统路径，不会被误认为是仅相对于集合的字符串。默认的 search/query 输出仍使用 qmd:// URI；只有在确实需要将路径交给非 QMD 工具时，才启用 --full-path。

使用 :from:count 后缀读取行范围 — 切勿通过 sed/head/tail 管道读取

qmd get 会自行切片文件。使用后缀或标志；不要调用 sed -n、head、tail 或 awk 来提取行范围。管道会破坏 docid 解析、虚拟路径查找、行号和标头，而且速度更慢，也更容易出错。

最简洁的形式是在路径或 docid 后直接添加 :from:count 后缀——优先使用这种形式：

qmd get "#abc123:120:40"                  # 40 lines starting at line 120
qmd get qmd://concepts/note.md:200:60     # lines 200–259
qmd get "#abc123:120"                      # from line 120 to end of file
qmd get "#abc123" --from 120 -l 40         # equivalent, using flags

后缀和标志：

• <path>:<from>:<count> — 从第 <from> 行开始，读取 <count> 行。最适合读取搜索命中附近的内容。
• <path>:<from> — 从第 <from> 行开始，读取到文件末尾。
• --from <line> / -l <lines> — 对应的标志。显式标志会覆盖后缀，因此 ... :5:2 -l 1 会读取 1 行。
• --no-line-numbers — 去掉 N: 前缀（默认显示行号）。

错误：qmd get "#abc123" | sed -n '120,160p' 正确：qmd get "#abc123:120:40"

搜索结果的每个命中项都包含 :line 锚点 — 直接将其传给 qmd get path:line:<n>，即可读取匹配内容附近的范围（输出中的行号将从 line 开始）。

查看已建立索引的内容

qmd collection list
qmd ls
qmd status

宽泛搜索偏离目标语料库时，添加集合筛选条件：

qmd search "headcount autonomous agents" -c concepts -n 10
qmd query "merchant support product reality" -c concepts -c sources -n 10

省略 -c 可搜索所有内容。

按元数据筛选

文档可以在 qmd.metadata frontmatter 块中包含带类型的元数据（字符串、数字、布尔值或一维数组）。search、vsearch 和 query 接受使用递归 JSON AST 的 --filter；每个返回的结果都符合筛选条件：

qmd search "authentication" --filter '{"key":"status","operator":"eq","value":"published"}'
qmd query "dependency injection" --filter '{"operator":"and","operands":[{"key":"topics","operator":"all","value":["typescript"]},{"key":"status","operator":"nin","value":["draft","archived"]}]}'

节点由 operator 区分：组 and/or 接受 operands，not 接受一个 operand，条件则接受带有 eq/ne/gt/gte/lt/lte（比较）、in/nin/all（成员关系）或 exists（是否存在）运算符的 key 和 value。匹配会严格按类型和精确值进行；缺失的键不符合 ne/nin（要包含这些键，请在 or 组中添加 exists: false 分支）。MCP query 工具接受相同的 AST，形式为 filter 对象。JSON 输出包含每个结果的 metadata。

MCP 工具：query

使用 MCP 服务时，优先使用结构化搜索：

{
  "searches": [
    { "type": "lex", "query": "cockpit OKR Goodhart" },
    { "type": "vec", "query": "data informed not metric driven product judgment" },
    { "type": "hyde", "query": "A concept note explains that metrics are useful as instruments, but leaders should not let OKRs or dashboards replace judgment." }
  ],
  "intent": "Find the concept note about using metrics as instruments without becoming metric-driven.",
  "collections": ["concepts"],
  "limit": 10
}

查询类型：

• lex — BM25 关键词搜索。最适合精确术语、名称、标题和代码。
• vec — 向量语义搜索。最适合自然语言概念。
• hyde — 使用假设性答案／文档片段进行的向量搜索。

查询技巧

优质的 QMD 搜索会结合以下三点：

1. 标题／别名锚点： 精确的页面标题、命名实体、短语。
2. 语义改述： 人们会如何描述这个想法。
3. 排除相近概念： 提供足够的意图信息，避免匹配到相近但错误的概念。

示例：

# Exact-ish title lookup
qmd search '"arm the rebels" merchants tools big companies' -c concepts

# Semantic concept lookup
qmd query $'intent: Find the customer proximity concept, not generic customer delight.\nlex: support pseudonymous merchant customer interviews\nvec: founder stays close to merchant reality through support and product use'

# Source lookup
qmd search "six-week cadence WhatsApp merchant relationships Shawn Ryan" -c sources -n 10

设置和维护

仅在用户要求设置或维护时才修改索引。搜索和检索是安全的；修改集合或索引不应作为随手执行的第一步。

npm install -g @tobilu/qmd
qmd collection add ~/notes --name notes
qmd update
qmd embed

健康检查和诊断：

qmd doctor
qmd status
qmd pull

qmd doctor 会检查配置、模型缓存、设备/GPU 设置、向量指纹以及常见的环境变量覆盖。如果依赖模型的命令失败，请先运行此命令，再更改配置。

MCP 设置

Claude Code、Claude Desktop、OpenClaw 和 HTTP 服务配置请参阅 references/mcp-setup.md。

注意事项

• 不要只看片段就下结论。 在作出判断前先获取文档。
• 不要用 sed/head/tail 切分文件。 使用 path:from:count 后缀（例如 qmd get "#abc123:120:40"）或 --from/-l。输出已带行号；通过管道传递会破坏 docid 解析、标题和虚拟路径。
• 不要过度依赖查询扩展。 自己编写 intent:/lex:/vec:/hyde:。直接使用 qmd query "user sentence" 会丢弃只有你掌握的上下文。由你扩展查询；模型只负责排序。
• 不要过度使用语义搜索。 如果你知道确切的标题或术语，BM25 更快，效果通常也更好。
• 不要随意修改索引。 qmd collection add、qmd update 和 qmd embed 会更改本地状态，而且可能耗费大量资源。
• 依赖模型的命令可能受环境影响。 如果 qmd query、qmd vsearch 或重排序因本地模型/GPU 不可用而失败，请使用 qmd search，并采用更具体的词法或结构化搜索词。
• 用户表述含糊时，需要明确意图。 添加 intent:，不要寄希望于查询扩展能猜对领域。
• 集合名称很重要。 搜索合成的 Wiki 页面时使用 concepts；搜索转录稿/原始来源页面时使用 sources；搜索代码或项目文档时使用文档集合。