GitShelf — GitHub 项目目录

项目概述

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。

安装与快速开始

全局安装：

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

快速开始：

# 创建集合
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 搜索：

# 搜索特定集合
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 中添加：

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

SDK 使用：

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。

项目概览