qmd

QMD - 查询 Markdown 文档

搜索如何工作

QMD 搜索本地 Markdown 集合：笔记、文档、Wiki、转录稿和项目知识库。在答案可能已在索引的本地文件中时，优先于网络搜索使用。

工作流程始终是：

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

当用户需要事实、决策、引用或细节时，不要仅凭片段回答。片段只是线索。

典型循环：

qmd search "merchant reality support interviews" -n 5
# 线索: #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: 并精心设计词汇和语义术语（参见选择正确的搜索模式）。

在报告检索结果时，简洁的注释就足够了；除非必要，不要粘贴整个文件：

已检索：
- #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: 查找关于将指标作为工具的概念笔记，避免让 OKR 取代判断。\nlex: cockpit instruments OKR Goodhart metrics judgment\nvec: data informed not metric driven product judgment\nhyde: 一篇概念笔记指出，指标就像驾驶舱仪表一样有用，但领导者应保持数据知情而非指标驱动，因为 OKR 和仪表盘可能会 Goodhart 产品判断。'

结构化查询字段（你编写每个字段——不要将此委托给扩展模型）：

• intent: 说明你试图找到什么 以及要避免什么。始终提供此字段。它引导排序远离相近但错误的概念。
• lex: 你期望在来源中出现的精确术语、别名、标题、代码符号和罕见词汇。这是你自己的关键词扩展。
• vec: 用自然语言、类似来源的措辞来转述想法。
• hyde: 描述能够满足请求的文档或答案。

你不需要每次都使用全部四个字段，但几乎总是应该至少编写 intent: 加上 lex:/vec: 中的一个。裸的 qmd query "the user's sentence" 会丢弃只有你拥有的上下文，并依赖内置扩展器来重建它——请优先使用结构化形式。

如果你确实没有什么可扩展的（单个罕见标记、逐字短语），那是 qmd search 的任务，而不是裸的 qmd query：

qmd query --format json --explain $'intent: ...\nlex: ...\nvec: ...'  # 检查排序

如果 qmd query 很慢或模型/GPU 设置失败，则回退到使用更好的词汇术语的 qmd search。

检索来源

搜索结果包含类似 #abc123 的文档 ID 和 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。

输出带有行号并携带文档 ID——两者都要引用

get 和 multi-get 默认带有行号，并且始终打印文档的 #docid 和 qmd:// 路径。因此 get 输出看起来像：

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

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

在你的回答中引用文档 ID 和确切行号，并使用这些数字请求下一个切片。仅当你需要逐字复制原始内容时（例如重现代码块），才传递 --no-line-numbers。

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

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

1: # Metrics as instruments

--full-path 在 qmd search 和 qmd query 上同样有效：结果路径变为文件在磁盘上的路径——当文件在 $PWD 内时，使用 ./ 前缀的相对路径，否则使用绝对真实路径——并且每个结果的 #docid 被丢弃，因为路径就是标识符。开头的 ./ 是有意为之，这样输出明确是文件系统路径，不会被误认为是裸的集合相对字符串。默认的搜索/查询输出仍然使用 qmd:// URI；仅当你特别需要可以将路径交给非 QMD 工具时，才选择 --full-path。

使用 :from:count 后缀读取行范围——永远不要通过 sed/head/tail 管道传输

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

最紧凑的形式是在路径或文档 ID 上直接使用 :from:count 后缀——优先使用它：

qmd get "#abc123:120:40"                  # 从第 120 行开始的 40 行
qmd get qmd://concepts/note.md:200:60     # 第 200-259 行
qmd get "#abc123:120"                      # 从第 120 行到文件末尾
qmd get "#abc123" --from 120 -l 40         # 等效，使用标志

后缀和标志：

• <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 以搜索所有内容。

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. 负空间： 足够的意图以避免相近但错误的概念。

示例：

# 近似标题查找
qmd search '"arm the rebels" merchants tools big companies' -c concepts

# 语义概念查找
qmd query $'intent: 查找客户接近性概念，而不是通用的客户愉悦。\nlex: support pseudonymous merchant customer interviews\nvec: founder stays close to merchant reality through support and product use'

# 来源查找
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。输出已经带有行号；管道传输会破坏文档 ID 解析、头部和虚拟路径。
• 不要依赖查询扩展。 自己编写 intent:/lex:/vec:/hyde:。裸的 qmd query "user sentence" 会丢弃只有你拥有的上下文。你扩展查询；模型只是排序。
• 不要过度使用语义搜索。 如果你知道确切的标题或术语，BM25 更快且通常更好。
• 不要随意修改索引。 qmd collection add、qmd update 和 qmd embed 会更改本地状态，并且可能代价高昂。
• 模型支持的命令可能对环境敏感。 如果 qmd query、qmd vsearch 或重排序因本地模型/GPU 不可用而失败，请使用 qmd search 和更强的词汇/结构化术语。
• 模糊的用户措辞需要意图。 添加 intent:，而不是希望查询扩展猜对领域。
• 集合名称很重要。 在 concepts 中搜索合成的 Wiki 页面，在 sources 中搜索转录稿/原始来源页面，在文档集合中搜索代码或项目文档。