# https://github.com/tobi/qmd 项目说明书

生成时间：2026-06-22 14:49:52 UTC

## 目录

- [QMD 项目概览与系统架构](#page-1)
- [混合搜索管线与本地 GGUF 模型集成](#page-2)
- [CLI、MCP 与 SDK 编程接口](#page-3)
- [社区关注话题、平台兼容性与可扩展性](#page-4)

<a id='page-1'></a>

## QMD 项目概览与系统架构

### 相关页面

相关主题：[混合搜索管线与本地 GGUF 模型集成](#page-2), [CLI、MCP 与 SDK 编程接口](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [package.json](https://github.com/tobi/qmd/blob/main/package.json)
- [src/mcp/server.ts](https://github.com/tobi/qmd/blob/main/src/mcp/server.ts)
- [src/cli/qmd.ts](https://github.com/tobi/qmd/blob/main/src/cli/qmd.ts)
- [src/cli/formatter.ts](https://github.com/tobi/qmd/blob/main/src/cli/formatter.ts)
- [src/bench/bench.ts](https://github.com/tobi/qmd/blob/main/src/bench/bench.ts)
- [src/bench/score.ts](https://github.com/tobi/qmd/blob/main/src/bench/score.ts)
- [src/bench/types.ts](https://github.com/tobi/qmd/blob/main/src/bench/types.ts)
- [finetune/README.md](https://github.com/tobi/qmd/blob/main/finetune/README.md)
</details>

# QMD 项目概览与系统架构

## 一、项目定位与核心能力

**QMD（Query Markup Documents）** 是由 Tobi 维护的一款 **本地优先（on-device）的 Markdown 混合检索工具**。它面向个人知识库场景，将 BM25 关键词检索、向量语义检索、可选的 LLM 重排序以及查询扩展融合到同一条管道中，让用户能够在一组 Markdown 集合（collection）之上进行精确而灵活的搜索。

根据 `package.json` 的描述，QMD 是「On-device hybrid search for markdown files with BM25, vector search, and LLM reranking」[资料来源：[package.json:3]()]，最新发布版本为 `2.5.3`[资料来源：[package.json:2]()]。运行时通过 `bin/qmd` 提供 CLI 入口，同时通过 `@modelcontextprotocol/sdk` 暴露 MCP 服务端[资料来源：[package.json:17]()]。

## 二、整体架构

QMD 的整体架构可划分为三层：底层的 **存储与索引层**、中间的 **检索与生成层**，以及上层的 **交互接口层（CLI 与 MCP）**。

```mermaid
flowchart TB
    subgraph 接口层["接口层"]
        CLI["CLI (qmd 命令)"]
        MCP["MCP Server<br/>(qmd:// 资源 + 工具)"]
    end
    subgraph 检索层["检索与生成层"]
        EXP["查询扩展 (lex/vec/hyde)"]
        LEX["BM25 (sqlite-vec + FTS)"]
        VEC["向量检索 (node-llama-cpp)"]
        RERANK["LLM Rerank"]
    end
    subgraph 存储层["存储与索引层"]
        SQLITE[("better-sqlite3<br/>+ sqlite-vec")]
        LLAMA["GGUF 模型<br/>(llama.cpp)"]
        CFG[".qmd/index.yml"]
    end
    CLI --> EXP
    MCP --> EXP
    EXP --> LEX
    EXP --> VEC
    LEX --> RERANK
    VEC --> RERANK
    LEX --> SQLITE
    VEC --> LLAMA
    CFG --> CLI
    CFG --> MCP
```

该架构的核心特点是「**一切皆可本地运行**」：向量嵌入和重排序均通过 `node-llama-cpp` 加载本地 GGUF 模型完成[资料来源：[package.json:25]()]，索引通过 `better-sqlite3` 与 `sqlite-vec` 持久化[资料来源：[package.json:24, 27]()]，配置由 `.qmd/index.yml` 控制。

## 三、核心模块与组件

### 3.1 CLI 与命令编排

`src/cli/qmd.ts` 是 CLI 的中枢，聚合了 `store`、`collections`、`formatter` 等模块的导出，负责 `qmd` 子命令的解析与执行[资料来源：[src/cli/qmd.ts]()]。它内建了 `qmd doctor` 自检逻辑，会对 `index config`、`model defaults` 等进行诊断，并提供环境变量 `QMD_EMBED_MODEL`、`QMD_GENERATE_MODEL`、`QMD_RERANK_MODEL` 的覆盖检查[资料来源：[src/cli/qmd.ts]()]。

### 3.2 MCP Server

`src/mcp/server.ts` 实现了符合 MCP 规范 `2025-06-18` 的服务端。它注册了：

- **资源（Resource）**：以 `qmd://{+path}` 为模板的 Markdown 文档资源，路径会做 `decodeURIComponent` 处理以兼容编码后的 URI[资料来源：[src/mcp/server.ts]()]。
- **工具（Tool）**：核心的 `query` 工具接收 `lex`（BM25 关键字）、`vec`（向量）、`hyde`（假设文档）三类子查询，可叠加 `intent` 字段以消歧义[资料来源：[src/mcp/server.ts]()]。

文档返回时默认带行号，并附 `qmd://` URI 和 `#docid`，方便客户端二次引用[资料来源：[src/mcp/server.ts]()]。

### 3.3 输出格式化

`src/cli/formatter.ts` 统一了 CLI 与 MCP 的输出格式，提供 `cli`、`csv`、`md`、`xml`、`files`、`json` 六种格式[资料来源：[src/cli/formatter.ts]()]。`FormatOptions` 中包含 `full`、`query`、`useColor`、`lineNumbers`、`intent` 等选项，便于在不同场景下复现搜索结果[资料来源：[src/cli/formatter.ts]()]。

### 3.4 评测与微调

`src/bench/bench.ts` 提供了跨后端的基准测试工具，可同时对比 `bm25`、`vector`、`hybrid`、`full`（含 LLM rerank）四种后端[资料来源：[src/bench/bench.ts]()]。`src/bench/score.ts` 计算 `precision@k`、`recall`、`MRR`、`F1` 等指标，并提供 `normalizePath` 与 `pathsMatch` 处理 `qmd://` URI 归一化[资料来源：[src/bench/score.ts]()]。`finetune/README.md` 则描述了基于 Qwen3-1.7B 的查询扩展模型微调流程，使用 LoRA（rank 16）并支持 SFT 与实验性 GRPO 路径[资料来源：[finetune/README.md]()]。

## 四、搜索管道与查询类型

QMD 的搜索管道围绕三类 **子查询（sub-search）** 展开，可在 MCP `query` 工具中以数组形式组合：

| 类型 | 后端 | 典型用途 | 关键参数 |
|------|------|----------|----------|
| `lex` | BM25 (FTS) | 精确关键字、含 `-negation` 排除 | 支持 `"phrase"` 短语 |
| `vec` | 向量相似度 | 语义问题、改写后查询 | 需要已建立向量索引 |
| `hyde` | HyDE 假设文档 | 未知词汇、需要「答案式」检索 | 写出一段「答案应是什么样」的文本 |

第一个子查询默认获得 **2 倍权重** 以提升头部结果的稳定性[资料来源：[src/mcp/server.ts]()]。返回时还会附带 `intent` 用于在多义词场景下引导片段提取。

## 五、社区关注点与已知局限

从社区反馈看，QMD 当前的几个热点问题集中在 **模型接入面** 与 **平台兼容性**：

1. **OpenAI 兼容后端缺失**：多个 Issue（#114、#521、#620）请求通过 LiteLLM 或 OpenAI 兼容协议接入 Embedding / Generation / Rerank，以替代强绑定的本地 `llama.cpp`[资料来源：[package.json:25]()]。
2. **Windows 兼容性**：Issue #31 报告了 Windows 11 下 Bun 运行时存在多处 Unix 假设导致的阻塞问题，反映了 `node-llama-cpp` 等原生依赖的跨平台挑战[资料来源：[package.json:optionalDependencies]()]。
3. **维护活跃度**：Issue #516 担忧项目维护节奏，最新版本 `v2.5.3` 已带来 `qmd get` 的行号范围后缀等改进[资料来源：[package.json:2]()]。

## See Also

- [QMD CLI 与命令参考](./qmd-cli-reference.md)
- [QMD MCP 服务端协议说明](./qmd-mcp-server.md)
- [QMD 混合检索与查询扩展](./qmd-hybrid-search.md)
- [QMD 评测与微调工作流](./qmd-bench-and-finetune.md)

---

<a id='page-2'></a>

## 混合搜索管线与本地 GGUF 模型集成

### 相关页面

相关主题：[QMD 项目概览与系统架构](#page-1), [社区关注话题、平台兼容性与可扩展性](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/mcp/server.ts](https://github.com/tobi/qmd/blob/main/src/mcp/server.ts)
- [src/cli/formatter.ts](https://github.com/tobi/qmd/blob/main/src/cli/formatter.ts)
- [package.json](https://github.com/tobi/qmd/blob/main/package.json)
- [src/cli/qmd.ts](https://github.com/tobi/qmd/blob/main/src/cli/qmd.ts)
- [finetune/README.md](https://github.com/tobi/qmd/blob/main/finetune/README.md)
- [src/bench/score.ts](https://github.com/tobi/qmd/blob/main/src/bench/score.ts)
- [src/bench/types.ts](https://github.com/tobi/qmd/blob/main/src/bench/types.ts)
</details>

# 混合搜索管线与本地 GGUF 模型集成

## 概述

QMD（Query Markup Documents）是一套面向本地 Markdown 知识库的混合检索管线，融合了 BM25 全文检索、向量语义检索以及基于小型语言模型的查询扩展与重排序。所有计算（推理、嵌入、生成）默认在本地通过 `node-llama-cpp` 调用 GGUF 模型完成，避免了对外部云服务的依赖。资料来源：[package.json:30-44]()

管线由三种并行的子检索构成：词法检索（`lex`）、向量检索（`vec`）与假设文档嵌入检索（`hyde`）。MCP 服务端通过统一的 `query` 工具接收一个或多个类型化的子查询，并按权重聚合结果。资料来源：[src/mcp/server.ts:1-50]()

## 管线组成

### 子检索后端

| 子查询类型 | 检索机制 | 适用场景 |
|---|---|---|
| `lex` | BM25 全文检索，支持 `"phrase"` 短语与 `-negation` 排除 | 精确关键词、术语、错误码 |
| `vec` | sqlite-vec 余弦相似度向量检索 | 语义相近、自然语言提问 |
| `hyde` | 生成假设答案文本后再做向量检索 | 答案形态已知、需要长上下文召回 |

`query` 工具接受 `searches` 数组（1–10 条），其中第一条子查询默认获得 2 倍权重，以反映用户的主要意图。资料来源：[src/mcp/server.ts:50-110]()

### 查询扩展模型

管线使用一个本地小型 LLM 将自然语言提问展开为 `lex:/vec:/hyde:` 三类结构化指令。该模型的输出格式通过 LoRA 微调固化，推荐的基座模型为 `Qwen/Qwen3-1.7B`。展开示例：

```
hyde: Authentication can be configured by setting the AUTH_SECRET environment variable.
lex: authentication configuration
vec: how to configure authentication settings
```

资料来源：[finetune/README.md:1-30]()

`lex` 行进入 BM25，`vec` 与 `hyde` 行均进入向量检索通道；CLI 在缺少 `intent:` 行时会隐式触发扩展。资料来源：[src/cli/qmd.ts:1-60]()

## 本地 GGUF 模型集成

### 运行时依赖

`node-llama-cpp` 3.18.1 直接加载 GGUF 文件以执行嵌入、生成与重排序。`sqlite-vec` 0.1.9（配合平台可选包 `sqlite-vec-{darwin,linux,windows}-*`）负责向量索引与相似度计算。资料来源：[package.json:30-44]()

### 默认模型与配置入口

CLI 暴露了若干默认值常量：`DEFAULT_EMBED_MODEL`、`DEFAULT_QUERY_MODEL`、`DEFAULT_RERANK_MODEL`，分别用于嵌入、查询扩展、重排序阶段。可通过解析函数 `resolveEmbedModel / resolveGenerateModel / resolveRerankModel / resolveModels` 覆盖模型来源与缓存路径（`DEFAULT_MODEL_CACHE_DIR`）。资料来源：[src/cli/qmd.ts:1-80]()

### 重排序

重排模型对前 K 个候选打分后重排，提高最终返回顺序的精度。MCP `query` 工具的 `minScore` 与 `limit` 参数控制阈值与返回数量。

## 输入语法与输出格式化

CLI 支持两类查询文档：单行隐式扩展，或显式 `intent:` 与 `lex:/vec:/hyde:` 多行文档。语法约束（最少/最多子查询数、引号短语、否词）由 `check-package-grammars` 在打包阶段强制校验。资料来源：[src/cli/qmd.ts:1-80]()

输出端，`formatter.ts` 支持 `cli / json / csv / md / xml / files` 六种格式，并提供行号注入（`addLineNumbers`）与短 docid（`getDocid` 取哈希前 6 位）。MCP 在读取文档时默认开启行号，便于模型做行级引用。资料来源：[src/cli/formatter.ts:1-80]()

## 评估与局限性

`src/bench/` 提供离线基准测试框架，可对同一查询在多种后端（lex / vec / hyde / hybrid）下分别计算 `precision_at_k`、`recall`、`mrr`、`f1` 与延迟，辅助调优混合权重。资料来源：[src/bench/score.ts:1-40]()、资料来源：[src/bench/types.ts:1-30]()

社区中频繁出现的诉求包括：通过 LiteLLM 接入 OpenAI / Ollama / OpenRouter / DeepInfra 等 API 提供商（参见 issue #114、#521、#620）以及修复 Windows 兼容性（参见 issue #31）。这些都反映了当前本地 GGUF-only 架构在跨平台与多模型路由上的边界。

## See Also

- [查询语法参考](https://github.com/tobi/qmd/blob/main/docs/SYNTAX.md)
- [查询扩展模型微调流程](https://github.com/tobi/qmd/blob/main/finetune/README.md)
- [MCP 服务器接口](https://github.com/tobi/qmd/blob/main/src/mcp/server.ts)

---

<a id='page-3'></a>

## CLI、MCP 与 SDK 编程接口

### 相关页面

相关主题：[QMD 项目概览与系统架构](#page-1), [混合搜索管线与本地 GGUF 模型集成](#page-2)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/mcp/server.ts](https://github.com/tobi/qmd/blob/main/src/mcp/server.ts)
- [src/cli/qmd.ts](https://github.com/tobi/qmd/blob/main/src/cli/qmd.ts)
- [src/cli/formatter.ts](https://github.com/tobi/qmd/blob/main/src/cli/formatter.ts)
- [src/index.ts](https://github.com/tobi/qmd/blob/main/src/index.ts)
- [package.json](https://github.com/tobi/qmd/blob/main/package.json)
- [bin/qmd](https://github.com/tobi/qmd/blob/main/bin/qmd)
</details>

# CLI、MCP 与 SDK 编程接口

QMD（Query Markup Documents）对外提供三种主要的使用入口：命令行（CLI）、模型上下文协议服务器（MCP Server）以及可被其他 Node/Bun 应用直接调用的 SDK 编程接口。三者在底层共享同一套 `createStore()` 与 `QMDStore` 抽象，差异主要体现在传输方式、参数表达与输出格式上。本文基于仓库源码梳理这三种接口的职责、关键能力与适用场景。

## 一、CLI 命令行入口

CLI 是面向终端用户的入口，通过 `qmd` 二进制启动，主体逻辑位于 [src/cli/qmd.ts](https://github.com/tobi/qmd/blob/main/src/cli/qmd.ts)。其支持的核心子命令包括 `query`、`get`、`multi-get`、`status` 等，覆盖搜索、读取、批量读取与索引状态查询。CLI 同时支持多行 typed-query 文法：`lex:`、`vec:`、`hyde:` 三种前缀可组合成 query document，并在 [src/cli/qmd.ts](https://github.com/tobi/qmd/blob/main/src/cli/qmd.ts) 的帮助文本中给出了完整 BNF 风格的 grammar。

输出格式方面，[src/cli/formatter.ts](https://github.com/tobi/qmd/blob/main/src/cli/formatter.ts) 暴露了 `OutputFormat` 联合类型，包含 `cli | csv | md | xml | files | json` 六种形态；`formatSearchResults()` 与 `formatDocument()` 根据 `FormatOptions` 决定是否启用彩色、行号、完整正文与领域意图高亮。`addLineNumbers()` 与 `getDocid()` 是 CLI 输出中最常复用的两个工具函数（`#abc123` 这种 6 字符短 ID 即来自 `getDocid(hash.slice(0, 6))`）。

> 社区提醒：当前 CLI 仍以本地 `node-llama-cpp` 加载 GGUF 模型为主，跨平台分发依赖 `sqlite-vec` 的可选二进制（见 [package.json](https://github.com/tobi/qmd/blob/main/package.json) 的 `optionalDependencies`），Windows 上仍存在已知兼容性障碍（参见 issue #31）。

## 二、MCP 服务器

MCP Server 面向 AI 客户端（如 Claude Desktop、Cursor 等），通过 [src/mcp/server.ts](https://github.com/tobi/qmd/blob/main/src/mcp/server.ts) 实现，遵循 MCP 规范 2025-06-18。它同时支持 stdio 与 WebStandardStreamableHTTP 两种传输，由 `process.argv` 中的 `--http` / `--stdio` 切换。

MCP 暴露的接口分为三组：

| 类别 | 名称 | 作用 |
| --- | --- | --- |
| Resource | `qmd://{+path}` | 按 URI 检索文档；自动 URL 解码并按需注入 `Context` 注释 |
| Tool | `query` | 接收 `searches: SubSearch[]`（1–10 项），支持 `lex / vec / hyde` 三种子查询 |
| Tool | `get` / `multi_get` | 按路径、`#docid` 或 glob 检索单篇/批量文档 |
| Tool | `status` | 返回 collection 列表、文档总数、是否已建立向量索引等 |

`query` 工具要求每条子查询都附带 `intent` 字段以辅助 snippet 抽取与歧义消解；MCP Server 在每次会话开始时还会输出大量提示文本，告知模型当前库规模、可用的工具与典型调用模式（见 [src/mcp/server.ts](https://github.com/tobi/qmd/blob/main/src/mcp/server.ts) 中 `lines.push` 系列）。

## 三、SDK 编程接口

对于希望将 QMD 嵌入自有应用的开发者，仓库以 `dist/index.js` 作为 npm 包入口（[package.json](https://github.com/tobi/qmd/blob/main/package.json) 中的 `main` 与 `exports."."`），由 [src/index.ts](https://github.com/tobi/qmd/blob/main/src/index.ts) 集中导出关键符号：`createStore`、`QMDStore`、`getDefaultDbPath`、`DEFAULT_MULTI_GET_MAX_BYTES`、若干 `*Query` 函数，以及 `addLineNumbers` 等格式化助手。调用方只需 `await createStore({ path })` 即可获得与 CLI/MCP 共用的存储层，再调用 `store.query(...)`、`store.get(...)`、`store.multiGet(...)` 完成搜索与读取。

需要特别注意的是 `enableProductionMode()` 行为：CLI 入口在解析参数前会自动切换到生产模式，使用 `getDefaultDbPath()`；而单元测试或 SDK 用户若传入自定义路径则不会被覆盖，避免污染真实数据（见 [src/cli/qmd.ts](https://github.com/tobi/qmd/blob/main/src/cli/qmd.ts) 的 `isMain` 守卫）。这种“显式 opt-in”模式使得同一份代码可以在脚本、测试与服务端复用。

## 四、接口对照与选择建议

```mermaid
flowchart LR
    A[调用方] --> B{使用场景}
    B -- "本地检索/批处理" --> CLI[qmd CLI<br/>src/cli/qmd.ts]
    B -- "AI 客户端/MCP" --> MCP[MCP Server<br/>src/mcp/server.ts]
    B -- "自有应用集成" --> SDK[Node SDK<br/>src/index.ts]
    CLI --> Store[(QMDStore<br/>createStore)]
    MCP --> Store
    SDK --> Store
    Store --> SQLite[(better-sqlite3 + sqlite-vec)]
    Store --> LLM[node-llama-cpp<br/>GGUF 模型]
```

- 选择 **CLI**：适合一次性检索、脚本化批处理、CI 中的回归评估（与 [src/bench/score.ts](https://github.com/tobi/qmd/blob/main/src/bench/score.ts) 的指标对齐）。
- 选择 **MCP**：让 LLM 客户端直接通过 `qmd://` URI 与工具描述访问知识库，无需额外胶水代码。
- 选择 **SDK**：当需要把 QMD 嵌入 Web 服务、桌面应用，或编写自动化集成测试时；此时可绕开 CLI 的输出格式约束，直接拿到结构化结果。

> 社区中关于 #114、#521、#620 等 issue 提出的“接入 OpenAI/Ollama/LiteLLM 兼容后端”的诉求，目前仍依赖 `node-llama-cpp` 的本地 GGUF 路径；未来若引入 `llama.cpp` 之外的 embedding/rerank 适配层，预期也会同时在 CLI、MCP 与 SDK 三处统一暴露。

## 参见

- 索引与混合检索原理：`# 混合检索引擎`（待发布）
- Collection 与配置体系：`# Collections 与多知识库`（待发布）
- 模型管理：`# GGUF 模型与 node-llama-cpp`（待发布）

---

<a id='page-4'></a>

## 社区关注话题、平台兼容性与可扩展性

### 相关页面

相关主题：[混合搜索管线与本地 GGUF 模型集成](#page-2), [CLI、MCP 与 SDK 编程接口](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/mcp/server.ts](https://github.com/tobi/qmd/blob/main/src/mcp/server.ts)
- [package.json](https://github.com/tobi/qmd/blob/main/package.json)
- [src/cli/formatter.ts](https://github.com/tobi/qmd/blob/main/src/cli/formatter.ts)
- [src/cli/qmd.ts](https://github.com/tobi/qmd/blob/main/src/cli/qmd.ts)
- [finetune/README.md](https://github.com/tobi/qmd/blob/main/finetune/README.md)
- [src/bench/score.ts](https://github.com/tobi/qmd/blob/main/src/bench/score.ts)
- [src/bench/types.ts](https://github.com/tobi/qmd/blob/main/src/bench/types.ts)
</details>

# 社区关注话题、平台兼容性与可扩展性

## 一、社区聚焦的四大核心议题

QMD（Query Markup Documents）作为一款面向 Markdown 文档的本地化混合检索工具，其 GitHub 仓库中社区讨论最集中的议题反映出当前架构的优势与瓶颈。通过分析社区高互动 Issue，主要可归纳为四类：

| 议题类别 | 代表 Issue | 现状描述 |
|---------|-----------|---------|
| 模型后端 API 化 | #114、#521、#620 | 用户希望以 OpenAI 兼容协议接入 Ollama、OpenRouter、DeepInfra、LiteLLM Proxy 等服务，覆盖嵌入、查询扩展与重排序 |
| Windows 平台兼容 | #31 | 多个 Unix 假设导致 Windows 11 环境下安装与运行失败 |
| 项目维护状态 | #516 | 大量未合并 PR（95）与未关闭 Issue（174）引发对维护活跃度的担忧 |
| 功能演进 | v2.5.3 Changelog | `qmd get` 引入 `:from:count` 行号后缀、MCP 工具按行号输出等细节优化 |

这些议题共同指向一个核心矛盾：用户希望 QMD 在保持"本地优先"理念的同时，具备更灵活的模型后端与跨平台能力。

## 二、平台兼容性现状与约束

QMD 的运行时依赖决定了其当前主要面向 Unix-like 平台：

- **核心依赖**：`better-sqlite3`（v12.10.0）、`node-llama-cpp`（v3.18.1）、`sqlite-vec`（v0.1.9）以及多个 tree-sitter 语法包（Go、Python、Rust、TypeScript）共同构成检索管线（[package.json:43-58](https://github.com/tobi/qmd/blob/main/package.json)）。
- **平台特定原生扩展**：`optionalDependencies` 仅覆盖 `darwin-arm64`、`darwin-x64`、`linux-arm64`、`linux-x64` 与 `windows-x64` 五种 sqlite-vec 预编译产物（[package.json:60-66](https://github.com/tobi/qmd/blob/main/package.json)），并未提供 Windows 上的 `node-llama-cpp` 完整 GGUF 推理链路支持，这正是社区报告 Windows 环境下 `llama.cpp` 假设触发问题的根源。
- **运行入口**：`package.json` 中的 `"bin": { "qmd": "bin/qmd" }` 表明 CLI 通过 `bin/qmd` 启动，在 Windows 上需借助 WSL 或 Git Bash 才能保证 `bin/qmd` 等脚本的 shebang 解析正确。

CLI 在多格式输出层面对平台的抽象是清晰的，例如 `formatter.ts` 通过 `formatDocument` 统一处理 JSON / Markdown / XML 输出（[src/cli/formatter.ts:67-79](https://github.com/tobi/qmd/blob/main/src/cli/formatter.ts)），但底层模型推理与路径处理仍依赖 POSIX 语义。

## 三、模型后端与可扩展性架构

QMD 的检索体系建立在"查询扩展 + 三路召回 + 重排序"的混合范式之上。`src/mcp/server.ts` 暴露的 `query` 工具定义了三种 typed sub-query（[src/mcp/server.ts](https://github.com/tobi/qmd/blob/main/src/mcp/server.ts)）：

- `lex`：BM25 关键词检索，支持 `"phrase"` 与 `-negation`；
- `vec`：语义向量检索；
- `hyde`：HyDE 假设性文档生成。

CLI 中通过 `qmd query` 的显式语法（`lex:` / `vec:` / `hyde:`）触发相应后端（[src/cli/qmd.ts](https://github.com/tobi/qmd/blob/main/src/cli/qmd.ts)），其语法由 `scripts/build.mjs` 中的 EBNF grammar 强制约束。

```mermaid
flowchart LR
    A[用户查询] --> B[查询扩展 LLM]
    B --> C[lex: BM25]
    B --> D[vec: 向量检索]
    B --> E[hyde: 假设文档]
    C --> F[结果融合]
    D --> F
    E --> F
    F --> G[重排序 LLM]
    G --> H[最终结果]
```

当前所有 LLM 能力（嵌入、查询扩展、重排序）均通过 `node-llama-cpp` 在本地加载 GGUF 模型。社区在 #114、#521、#620 中反复呼吁以 OpenAI 兼容协议将这一管线解耦为可插拔后端。`finetune/README.md` 中训练的 `Qwen3-1.7B` 查询扩展模型（[finetune/README.md:35-49](https://github.com/tobi/qmd/blob/main/finetune/README.md)）正是该管线的本地化组件，体现了 QMD"模型与系统共同演进"的设计哲学。

## 四、可观测性、基准测试与生态

为支撑扩展性迭代，QMD 内置了独立的基准测试框架：

- `src/bench/types.ts` 定义了 `BenchmarkQuery`、`BenchmarkFixture`、`BackendResult` 等结构，用于跨后端对比 precision@k、recall、MRR、F1 等指标（[src/bench/types.ts:11-30](https://github.com/tobi/qmd/blob/main/src/bench/types.ts)）。
- `src/bench/score.ts` 提供路径归一化与匹配函数 `normalizePath` 与 `pathsMatch`，处理 `qmd://collection/docs/readme.md` 等多形式路径（[src/bench/score.ts:9-25](https://github.com/tobi/qmd/blob/main/src/bench/score.ts)）。

这些基础设施为未来引入远程 API 后端的回归测试提供了基础——新后端可在同一基准下与本地 GGUF 后端进行量化对比，从而避免 Issue #516 所担忧的"维护空窗"导致性能回退。

## 五、展望与建议

综合社区反馈与代码现状，QMD 的下一阶段演进可关注以下方向：

1. **后端抽象层**：在 `node-llama-cpp` 之上引入 `ModelProvider` 接口，优先实现 OpenAI 兼容协议，对应 Issue #114、#521、#620。
2. **Windows 原生支持**：补齐 `node-llama-cpp` 在 Windows 的预编译产物，并审计 `bin/` 脚本的跨平台兼容性。
3. **维护透明化**：通过 CHANGELOG 节奏与 PR 标签化缓解 Issue #516 提出的信任问题。
4. **基准驱动迭代**：利用 `src/bench/` 体系将新后端纳入 CI，确保可扩展性不以牺牲召回质量为代价。

## See Also

- [MCP 协议与 qmd:// 资源协议](mcp-server.md)
- [查询语法与三路召回管线](query-grammar.md)
- [查询扩展模型微调流程](finetune-pipeline.md)
- [CLI 输出格式与格式化器](cli-formatter.md)
- [基准测试框架与评估指标](benchmark.md)

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：tobi/qmd

摘要：发现 14 个潜在踩坑项，其中 4 个为 high/blocking；最高优先级：安装坑 - 来源证据：qmd embed deadlocks at 0% CPU on Apple M5 Max + macOS 26.4 — Metal shader JIT compile failure in bundled llama.cpp b839…。

## 1. 安装坑 · 来源证据：qmd embed deadlocks at 0% CPU on Apple M5 Max + macOS 26.4 — Metal shader JIT compile failure in bundled llama.cpp b839…

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：qmd embed deadlocks at 0% CPU on Apple M5 Max + macOS 26.4 — Metal shader JIT compile failure in bundled llama.cpp b8390 (distinct from #673/#724)
- 对用户的影响：可能阻塞安装或首次运行。
- 证据：community_evidence:github | https://github.com/tobi/qmd/issues/735 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

## 2. 配置坑 · 来源证据：exclude: patterns in index.yml to prevent double-indexing nested collections

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：exclude: patterns in index.yml to prevent double-indexing nested collections
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/tobi/qmd/issues/645 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

## 3. 维护坑 · 来源证据：Lossy path normalization breaks QMD_EDITOR_URI for files with spaces

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Lossy path normalization breaks QMD_EDITOR_URI for files with spaces
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/tobi/qmd/issues/717 | 来源类型 github_issue 暴露的待验证使用条件。

## 4. 安全/权限坑 · 来源证据：npm install fails (macOS apple silicon, latest v26)

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：npm install fails (macOS apple silicon, latest v26)
- 对用户的影响：可能阻塞安装或首次运行。
- 证据：community_evidence:github | https://github.com/tobi/qmd/issues/699 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

## 5. 安装坑 · 来源证据：GPU selection falls back to CPU instead of Vulkan on non-NVIDIA machines

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：GPU selection falls back to CPU instead of Vulkan on non-NVIDIA machines
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/tobi/qmd/issues/739 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

## 6. 安装坑 · 来源证据：Store-open CJK FTS migration OOMs large indexes and can leave BM25 FTS empty

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Store-open CJK FTS migration OOMs large indexes and can leave BM25 FTS empty
- 对用户的影响：可能阻塞安装或首次运行。
- 证据：community_evidence:github | https://github.com/tobi/qmd/issues/736 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

## 7. 配置坑 · 可能修改宿主 AI 配置

- 严重度：medium
- 证据强度：source_linked
- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
- 证据：capability.host_targets | https://github.com/tobi/qmd | host_targets=mcp_host, claude_code, claude

## 8. 配置坑 · 来源证据：`collection add`: trailing backslash in a quoted path swallows following flags — collection is created broken (0 files,…

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：`collection add`: trailing backslash in a quoted path swallows following flags — collection is created broken (0 files, wrong name/mask) but still reports succ…
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/tobi/qmd/issues/738 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。

## 9. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://github.com/tobi/qmd | README/documentation is current enough for a first validation pass.

## 10. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://github.com/tobi/qmd | last_activity_observed missing

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://github.com/tobi/qmd | no_demo; severity=medium

## 12. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://github.com/tobi/qmd | no_demo; severity=medium

## 13. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://github.com/tobi/qmd | issue_or_pr_quality=unknown

## 14. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://github.com/tobi/qmd | release_recency=unknown

<!-- canonical_name: tobi/qmd; human_manual_source: deepwiki_human_wiki -->