## 项目概述

QMD（Query Markup Documents）是一个完全本地运行的迷你命令行搜索引擎，专为个人文档、知识库、会议记录等场景设计。它结合了 BM25 全文检索、向量语义搜索和 LLM 重排序，所有模型均通过 node-llama-cpp 在本地运行，无需外部 API 或服务器。项目使用 TypeScript 编写，遵循 MIT 许可证，支持 Node.js 和 Bun 运行时。QMD 不仅提供 CLI 工具，还提供 SDK 和 MCP（Model Context Protocol）服务器，方便集成到 AI 代理工作流中。

## 核心功能

- **混合搜索**：结合 BM25 全文检索、向量语义搜索和 LLM 重排序，提供高质量搜索结果。
- **本地运行**：所有模型（嵌入、重排序、查询扩展）均通过 GGUF 模型在本地运行，数据隐私安全。
- **集合管理**：支持多个文档集合，每个集合可配置路径、文件模式、忽略规则和更新命令。
- **上下文增强**：通过为路径添加描述性上下文，提升搜索相关性，并返回上下文信息。
- **MCP 服务器**：提供 MCP 协议支持，可无缝集成到 Claude Desktop、Claude Code 等 AI 工具中。
- **SDK 支持**：提供完整的 TypeScript SDK，方便在自定义应用中集成搜索和索引功能。
- **多种输出格式**：支持 CLI、JSON、CSV、Markdown、XML 和文件列表等输出格式，便于脚本和代理处理。
- **智能分块**：采用基于 Markdown 结构的智能分块算法，保持语义单元完整，并支持 AST 感知分块（针对代码文件）。
- **查询扩展**：通过本地 LLM 自动生成查询变体，提升召回率。
- **基准测试**：内置 `qmd bench` 命令，可评估不同搜索后端的质量。

## 适用与不适用场景

**适用场景：**

- 个人笔记、日记、会议记录的本地搜索。
- 团队内部文档、知识库的快速检索。
- 需要离线、隐私安全的搜索解决方案。
- 与 AI 代理集成，提供上下文检索能力。
- 代码库的语义搜索（支持 AST 感知分块）。

**不适用场景：**

- 大规模企业级搜索（需要分布式索引和水平扩展）。
- 非 Markdown 格式的文档（如 PDF、Word 等，需先转换）。
- 需要实时索引更新的场景（索引需手动或定时更新）。
- 对搜索延迟要求极高的场景（LLM 重排序可能较慢）。

## 技术架构与依赖

QMD 采用混合搜索架构，核心组件包括：

- **SQLite FTS5**：用于 BM25 全文检索。
- **sqlite-vec**：用于向量相似度搜索。
- **node-llama-cpp**：加载 GGUF 模型，执行嵌入、重排序和查询扩展。
- **tree-sitter**：用于代码文件的 AST 感知分块（可选）。

默认模型（自动下载）：

- `embeddinggemma-300M-Q8_0`：向量嵌入模型（约 300MB）。
- `qwen3-reranker-0.6b-q8_0`：重排序模型（约 640MB）。
- `qmd-query-expansion-1.7B-q4_k_m`：查询扩展模型（约 1.1GB）。

系统要求：Node.js >= 22 或 Bun >= 1.0.0，macOS 需要 Homebrew SQLite。

## 安装与快速开始

**全局安装：**

```sh
npm install -g @tobilu/qmd
# 或
bun install -g @tobilu/qmd
```

**快速开始：**

```sh
# 创建集合
qmd collection add ~/notes --name notes
qmd collection add ~/Documents/meetings --name meetings

# 添加上下文（可选但推荐）
qmd context add qmd://notes "个人笔记和想法"

# 生成嵌入
qmd embed

# 搜索
qmd search "项目时间线"           # 关键词搜索
qmd vsearch "如何部署"             # 语义搜索
qmd query "季度规划流程"          # 混合搜索 + 重排序
```

## 典型使用方法

**CLI 搜索：**

```sh
# 搜索特定集合
qmd search "API" -c notes

# 输出 JSON 供代理使用
qmd search "authentication" --json -n 10

# 获取文档内容
qmd get "docs/api-reference.md" --full
```

**MCP 集成（Claude Desktop）：**

在 `claude_desktop_config.json` 中添加：

```json
{
  "mcpServers": {
    "qmd": {
      "command": "qmd",
      "args": ["mcp"]
    }
  }
}
```

**SDK 使用：**

```typescript
import { createStore } from '@tobilu/qmd'

const store = await createStore({
  dbPath: './my-index.sqlite',
  config: {
    collections: {
      docs: { path: '/path/to/docs', pattern: '**/*.md' },
    },
  },
})

const results = await store.search({ query: "authentication flow" })
console.log(results.map(r => `${r.title} (${Math.round(r.score * 100)}%)`))

await store.close()
```

## 配置与部署要点

**配置文件位置：** `~/.config/qmd/index.yml`（可通过 `XDG_CONFIG_HOME` 或 `QMD_CONFIG_DIR` 覆盖）。

**主要配置项：**

- `global_context`：全局上下文描述。
- `editor_uri`：终端超链接模板。
- `models`：覆盖默认 GGUF 模型。
- `collections`：定义每个集合的路径、模式、忽略规则、更新命令等。

**环境变量：**

- `QMD_EMBED_MODEL`：自定义嵌入模型。
- `QMD_LLAMA_GPU`：强制 GPU 后端（metal/vulkan/cuda）。
- `QMD_FORCE_CPU`：强制 CPU 模式。
- `QMD_SQLITE_BUSY_TIMEOUT`：SQLite 忙等待超时。

**部署要点：**

- 首次使用会自动下载模型，需网络连接。
- 更改嵌入模型后需重新嵌入（`qmd embed -f`）。
- 支持 HTTP 传输的 MCP 服务器，可常驻后台，减少模型加载延迟。

## 限制、风险与许可证

**限制：**

- 仅支持 Markdown 文件（可通过自定义模式扩展）。
- 索引更新需手动或通过 `update` 命令触发。
- 模型下载依赖 HuggingFace，首次使用需网络。
- 大型语料库的嵌入和重排序可能耗时较长。

**风险：**

- 本地模型可能不如云端模型准确，尤其是非英语语料。
- 并发写入可能导致 SQLite 锁冲突（已通过 busy_timeout 缓解）。
- 依赖第三方库（node-llama-cpp、tree-sitter 等），存在兼容性风险。

**许可证：** MIT

## 官方链接

- GitHub 仓库：https://github.com/tobi/qmd
- npm 包：@tobilu/qmd
- 最新版本：v2.5.3（2026-05-29 发布）

## 信息来源和分析时间

- 信息来源：GitHub 仓库 README、CHANGELOG、docs/SYNTAX.md。
- 分析时间：2026-06-25。