Qmd

使用 qmd 在本地搜索个人知识库、笔记、文档和会议记录——qmd 是一个混合检索引擎，结合了 BM25、向量搜索和 LLM 重排序。支持 CLI 和 MCP 集成。

技能元数据


来源	可选 — 使用 `hermes skills install official/research/qmd` 安装
路径	`optional-skills/research/qmd`
版本	`1.0.0`
作者	Hermes Agent + Teknium
许可证	MIT
平台	macos, linux
标签	`Search`, `Knowledge-Base`, `RAG`, `Notes`, `MCP`, `Local-AI`
相关技能	`obsidian`, `native-mcp`, `arxiv`

参考：完整 SKILL.md

信息

以下是 Hermes 在触发此技能时加载的完整技能定义。这是技能激活时代理看到的指令。

QMD — 查询标记文档

用于个人知识库的本地、设备端搜索引擎。索引 Markdown 笔记、会议记录、文档以及任何基于文本的文件，并提供结合关键词匹配、语义理解和 LLM 驱动的重排序的混合搜索——所有功能均在本地运行，无需云依赖。

由 Tobi Lütke 创建。采用 MIT 许可证。

何时使用

用户要求搜索其笔记、文档、知识库或会议记录
用户希望在大量 Markdown/文本文件中查找内容
用户希望进行语义搜索（“查找关于 X 概念的笔记”），而不仅仅是关键词 grep
用户已设置好 qmd 集合并希望查询它们
用户要求设置本地知识库或文档搜索系统
关键词：“search my notes”、“find in my docs”、“knowledge base”、“qmd”

前置条件

Node.js >= 22（必需）

# Check version
node --version  # must be >= 22

# macOS — install or upgrade via Homebrew
brew install node@22

# Linux — use NodeSource or nvm
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs
# or with nvm:
nvm install 22 && nvm use 22

支持扩展的 SQLite（仅限 macOS）

macOS 系统自带的 SQLite 缺乏扩展加载功能。通过 Homebrew 安装：

brew install sqlite

安装 qmd

npm install -g @tobilu/qmd
# or with Bun:
bun install -g @tobilu/qmd

首次运行会自动下载 3 个本地 GGUF 模型（总共约 2GB）：

模型	用途	大小
embeddinggemma-300M-Q8_0	向量嵌入	~300MB
qwen3-reranker-0.6b-q8_0	结果重排序	~640MB
qmd-query-expansion-1.7B	查询扩展	~1.1GB

验证安装

qmd --version
qmd status

快速参考

命令	功能	速度
`qmd search "query"`	BM25 关键词搜索（无模型）	~0.2s
`qmd vsearch "query"`	语义向量搜索（1 个模型）	~3s
`qmd query "query"`	混合 + 重排序（全部 3 个模型）	预热后 ~2-3s，冷启动 ~19s
`qmd get <docid>`	检索完整文档内容	即时
`qmd multi-get "glob"`	检索多个文件	即时
`qmd collection add <path> --name <n>`	将目录添加为集合	即时
`qmd context add <path> "description"`	添加上下文元数据以改善检索效果	即时
`qmd embed`	生成/更新向量嵌入	视情况而定
`qmd status`	显示索引健康状况和集合信息	即时
`qmd mcp`	启动 MCP 服务器（stdio）	持久运行
`qmd mcp --http --daemon`	启动 MCP 服务器（HTTP，预热模型）	持久运行

设置工作流

1. 添加集合

将 qmd 指向包含文档的目录：

# Add a notes directory
qmd collection add ~/notes --name notes

# Add project docs
qmd collection add ~/projects/myproject/docs --name project-docs

# Add meeting transcripts
qmd collection add ~/meetings --name meetings

# List all collections
qmd collection list

2. 添加上下文描述

上下文元数据有助于搜索引擎理解每个集合的内容。这能显著提高检索质量：

qmd context add qmd://notes "Personal notes, ideas, and journal entries"
qmd context add qmd://project-docs "Technical documentation for the main project"
qmd context add qmd://meetings "Meeting transcripts and action items from team syncs"

3. 生成嵌入

qmd embed

这将处理所有集合中的所有文档并生成向量嵌入。在添加新文档或集合后重新运行。

4. 验证

qmd status   # shows index health, collection stats, model info

搜索模式

快速关键词搜索 (BM25)

适用于：精确术语、代码标识符、名称、已知短语。不加载模型——结果近乎即时。

qmd search "authentication middleware"
qmd search "handleError async"

语义向量搜索

适用于：自然语言问题、概念性查询。加载嵌入模型（首次查询约 3 秒）。

qmd vsearch "how does the rate limiter handle burst traffic"
qmd vsearch "ideas for improving onboarding flow"

带重排序的混合搜索（最佳质量）

适用于：对质量要求最高的重要查询。使用全部 3 个模型——查询扩展、并行 BM25+向量、重排序。

qmd query "what decisions were made about the database migration"

结构化多模式查询

在单个查询中组合不同的搜索类型以提高精度：

# BM25 for exact term + vector for concept
qmd query 

### 查询语法 (lex/BM25 模式)

| 语法 | 效果 | 示例 |
|--------|--------|---------|
| `term` | 前缀匹配 | `perf` 匹配 "performance" |
| `"phrase"` | 精确短语 | `"rate limiter"` |
| `-term` | 排除术语 | `performance -sports` |

### HyDE（假设文档嵌入）

对于复杂主题，写出你期望的答案样子：

```bash
qmd query 

### 限定集合范围 \{#query-syntax-lexbm25-mode}

```bash
qmd search "query" --collection notes
qmd query "query" --collection project-docs

输出格式

qmd search "query" --json        # JSON output (best for parsing)
qmd search "query" --limit 5     # Limit results
qmd get "#abc123"                # Get by document ID
qmd get "path/to/file.md"       # Get by file path
qmd get "file.md:50" -l 100     # Get specific line range
qmd multi-get "journals/*.md" --json  # Batch retrieve by glob

MCP 集成（推荐）

qmd 暴露一个 MCP 服务器，通过原生 MCP 客户端直接向 Hermes Agent 提供搜索工具。这是首选的集成方式——配置完成后，Agent 会自动获得 qmd 工具，无需加载此技能。

选项 A：Stdio 模式（简单）

添加到 ~/.hermes/config.yaml：

mcp_servers:
  qmd:
    command: "qmd"
    args: ["mcp"]
    timeout: 30
    connect_timeout: 45

这将注册以下工具：mcp_qmd_search、mcp_qmd_vsearch、mcp_qmd_deep_search、mcp_qmd_get、mcp_qmd_status。

权衡： 模型在首次搜索调用时加载（冷启动约 19 秒），然后在会话期间保持预热状态。对于偶尔使用来说可以接受。

选项 B：HTTP 守护进程模式（快速，重度使用推荐）

单独启动 qmd 守护进程——它会在内存中保持模型预热：

# Start daemon (persists across agent restarts)
qmd mcp --http --daemon

# Runs on http://localhost:8181 by default

然后配置 Hermes Agent 通过 HTTP 连接：

mcp_servers:
  qmd:
    url: "http://localhost:8181/mcp"
    timeout: 30

权衡： 运行时占用约 2GB RAM，但每次查询都很快（约 2-3 秒）。最适合频繁搜索的用户。

保持守护进程运行

macOS (launchd)

cat > ~/Library/LaunchAgents/com.qmd.daemon.plist << 'EOF'
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>com.qmd.daemon</string>
  <key>ProgramArguments</key>
  <array>
    <string>qmd</string>
    <string>mcp</string>
    <string>--http</string>
    <string>--daemon</string>
  </array>
  <key>RunAtLoad</key>
  <true/>
  <key>KeepAlive</key>
  <true/>
  <key>StandardOutPath</key>
  <string>/tmp/qmd-daemon.log</string>
  <key>StandardErrorPath</key>
  <string>/tmp/qmd-daemon.log</string>
</dict>
</plist>
EOF

launchctl load ~/Library/LaunchAgents/com.qmd.daemon.plist

Linux (systemd 用户服务)

mkdir -p ~/.config/systemd/user

cat > ~/.config/systemd/user/qmd-daemon.service << 'EOF'
[Unit]
Description=QMD MCP Daemon
After=network.target

[Service]
ExecStart=qmd mcp --http --daemon
Restart=on-failure
RestartSec=10
Environment=PATH=/usr/local/bin:/usr/bin:/bin

[Install]
WantedBy=default.target
EOF

systemctl --user daemon-reload
systemctl --user enable --now qmd-daemon
systemctl --user status qmd-daemon

MCP 工具参考

连接后，这些工具可作为 mcp_qmd_* 使用：

MCP 工具	映射到	描述
`mcp_qmd_search`	`qmd search`	BM25 关键词搜索
`mcp_qmd_vsearch`	`qmd vsearch`	语义向量搜索
`mcp_qmd_deep_search`	`qmd query`	混合搜索 + 重排序
`mcp_qmd_get`	`qmd get`	按 ID 或路径检索文档
`mcp_qmd_status`	`qmd status`	索引健康和统计信息

MCP 工具接受结构化 JSON 查询以进行多模式搜索：

{
  "searches": [
    {"type": "lex", "query": "authentication middleware"},
    {"type": "vec", "query": "how user login is verified"}
  ],
  "collections": ["project-docs"],
  "limit": 10
}

CLI 用法（无 MCP）

当未配置 MCP 时，直接通过终端使用 qmd：

terminal(command="qmd query 'what was decided about the API redesign' --json", timeout=30)

对于设置和管理任务，始终使用终端：

terminal(command="qmd collection add ~/Documents/notes --name notes")
terminal(command="qmd context add qmd://notes 'Personal research notes and ideas'")
terminal(command="qmd embed")
terminal(command="qmd status")

搜索管道工作原理

了解内部机制有助于选择合适的搜索模式：

查询扩展 — 一个微调过的 1.7B 模型生成 2 个替代查询。原始查询在融合中获得 2 倍权重。
并行检索 — BM25 (SQLite FTS5) 和向量搜索在所有查询变体上同时运行。
RRF 融合 — 倒数排名融合（Reciprocal Rank Fusion, k=60）合并结果。高排名奖励：第 1 名 +0.05，第 2-3 名 +0.02。
LLM 重排序 — qwen3-reranker 对前 30 个候选项进行评分（0.0-1.0）。
位置感知混合 — 排名 1-3：75% 检索 / 25% 重排序器。排名 4-10：60/40。排名 11+：40/60（对于长尾结果更信任重排序器）。

智能分块： 文档在自然断点（标题、代码块、空行）处分割，目标约为 900 个 token，重叠率为 15%。代码块绝不会在中间被分割。

最佳实践

始终添加上下文描述 — qmd context add 能显著提高检索准确性。描述每个集合包含的内容。
添加文档后重新嵌入 — 向集合添加新文件时，必须重新运行 qmd embed。
使用 qmd search 追求速度 — 当需要快速关键词查找（代码标识符、确切名称）时，BM25 是瞬时的且不需要模型。
使用 qmd query 追求质量 — 当问题是概念性的或用户需要尽可能好的结果时，使用混合搜索。
首选 MCP 集成 — 配置完成后，Agent 会获得原生工具，无需每次都加载此技能。
频繁用户使用守护进程模式 — 如果用户定期搜索其知识库，建议设置 HTTP 守护进程。
结构化搜索中的第一个查询获得 2 倍权重 — 当组合词汇搜索和向量搜索时，将最重要/最确定的查询放在第一位。

故障排除

“首次运行时下载模型”

正常现象 — qmd 在首次使用时会自动下载约 2GB 的 GGUF 模型。这是一次性操作。

冷启动延迟（约 19 秒）

当模型未加载到内存中时会发生这种情况。解决方案：

使用 HTTP 守护进程模式 (qmd mcp --http --daemon) 以保持预热
当不需要模型时使用 qmd search（仅 BM25）
MCP stdio 模式在首次搜索时加载模型，并在会话期间保持预热

macOS: “unable to load extension”

安装 Homebrew SQLite：brew install sqlite 然后确保它在系统 SQLite 之前位于 PATH 中。

“No collections found”

运行 qmd collection add <path> --name <name> 添加目录，然后运行 qmd embed 对其进行索引。

嵌入模型覆盖（CJK/多语言）

为非英语内容设置 QMD_EMBED_MODEL 环境变量：

export QMD_EMBED_MODEL="your-multilingual-model"

数据存储

索引和向量： ~/.cache/qmd/index.sqlite
模型： 首次运行时自动下载到本地缓存
无云依赖 — 所有内容均在本地运行

参考

GitHub: tobi/qmd
QMD Changeloglex: rate limiter\nvec: how does throttling work under load'

With query expansion

qmd query

查询语法 (lex/BM25 模式)

语法	效果	示例
`term`	前缀匹配	`perf` 匹配 "performance"
`"phrase"`	精确短语	`"rate limiter"`
`-term`	排除术语	`performance -sports`

HyDE（假设文档嵌入）

对于复杂主题，写出你期望的答案样子：

@@HERMES_PROTECTED_BLOCK_12@@

限定集合范围

qmd search "query" --collection notes
qmd query "query" --collection project-docs

输出格式

qmd search "query" --json        # JSON output (best for parsing)
qmd search "query" --limit 5     # Limit results
qmd get "#abc123"                # Get by document ID
qmd get "path/to/file.md"       # Get by file path
qmd get "file.md:50" -l 100     # Get specific line range
qmd multi-get "journals/*.md" --json  # Batch retrieve by glob

MCP 集成（推荐）

选项 A：Stdio 模式（简单）

添加到 ~/.hermes/config.yaml：

mcp_servers:
  qmd:
    command: "qmd"
    args: ["mcp"]
    timeout: 30
    connect_timeout: 45

这将注册以下工具：mcp_qmd_search、mcp_qmd_vsearch、mcp_qmd_deep_search、mcp_qmd_get、mcp_qmd_status。

权衡： 模型在首次搜索调用时加载（冷启动约 19 秒），然后在会话期间保持预热状态。对于偶尔使用来说可以接受。

选项 B：HTTP 守护进程模式（快速，重度使用推荐）

单独启动 qmd 守护进程——它会在内存中保持模型预热：

# Start daemon (persists across agent restarts)
qmd mcp --http --daemon

# Runs on http://localhost:8181 by default

然后配置 Hermes Agent 通过 HTTP 连接：

mcp_servers:
  qmd:
    url: "http://localhost:8181/mcp"
    timeout: 30

权衡： 运行时占用约 2GB RAM，但每次查询都很快（约 2-3 秒）。最适合频繁搜索的用户。

保持守护进程运行

macOS (launchd)

cat > ~/Library/LaunchAgents/com.qmd.daemon.plist << 'EOF'
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>com.qmd.daemon</string>
  <key>ProgramArguments</key>
  <array>
    <string>qmd</string>
    <string>mcp</string>
    <string>--http</string>
    <string>--daemon</string>
  </array>
  <key>RunAtLoad</key>
  <true/>
  <key>KeepAlive</key>
  <true/>
  <key>StandardOutPath</key>
  <string>/tmp/qmd-daemon.log</string>
  <key>StandardErrorPath</key>
  <string>/tmp/qmd-daemon.log</string>
</dict>
</plist>
EOF

launchctl load ~/Library/LaunchAgents/com.qmd.daemon.plist

Linux (systemd 用户服务)

mkdir -p ~/.config/systemd/user

cat > ~/.config/systemd/user/qmd-daemon.service << 'EOF'
[Unit]
Description=QMD MCP Daemon
After=network.target

[Service]
ExecStart=qmd mcp --http --daemon
Restart=on-failure
RestartSec=10
Environment=PATH=/usr/local/bin:/usr/bin:/bin

[Install]
WantedBy=default.target
EOF

systemctl --user daemon-reload
systemctl --user enable --now qmd-daemon
systemctl --user status qmd-daemon

MCP 工具参考

连接后，这些工具可作为 mcp_qmd_* 使用：

MCP 工具	映射到	描述
`mcp_qmd_search`	`qmd search`	BM25 关键词搜索
`mcp_qmd_vsearch`	`qmd vsearch`	语义向量搜索
`mcp_qmd_deep_search`	`qmd query`	混合搜索 + 重排序
`mcp_qmd_get`	`qmd get`	按 ID 或路径检索文档
`mcp_qmd_status`	`qmd status`	索引健康和统计信息

MCP 工具接受结构化 JSON 查询以进行多模式搜索：

{
  "searches": [
    {"type": "lex", "query": "authentication middleware"},
    {"type": "vec", "query": "how user login is verified"}
  ],
  "collections": ["project-docs"],
  "limit": 10
}

CLI 用法（无 MCP）

当未配置 MCP 时，直接通过终端使用 qmd：

terminal(command="qmd query 'what was decided about the API redesign' --json", timeout=30)

对于设置和管理任务，始终使用终端：

terminal(command="qmd collection add ~/Documents/notes --name notes")
terminal(command="qmd context add qmd://notes 'Personal research notes and ideas'")
terminal(command="qmd embed")
terminal(command="qmd status")

搜索管道工作原理

了解内部机制有助于选择合适的搜索模式：

查询扩展 — 一个微调过的 1.7B 模型生成 2 个替代查询。原始查询在融合中获得 2 倍权重。
并行检索 — BM25 (SQLite FTS5) 和向量搜索在所有查询变体上同时运行。
RRF 融合 — 倒数排名融合（Reciprocal Rank Fusion, k=60）合并结果。高排名奖励：第 1 名 +0.05，第 2-3 名 +0.02。
LLM 重排序 — qwen3-reranker 对前 30 个候选项进行评分（0.0-1.0）。
位置感知混合 — 排名 1-3：75% 检索 / 25% 重排序器。排名 4-10：60/40。排名 11+：40/60（对于长尾结果更信任重排序器）。

智能分块： 文档在自然断点（标题、代码块、空行）处分割，目标约为 900 个 token，重叠率为 15%。代码块绝不会在中间被分割。

最佳实践

始终添加上下文描述 — qmd context add 能显著提高检索准确性。描述每个集合包含的内容。
添加文档后重新嵌入 — 向集合添加新文件时，必须重新运行 qmd embed。
使用 qmd search 追求速度 — 当需要快速关键词查找（代码标识符、确切名称）时，BM25 是瞬时的且不需要模型。
使用 qmd query 追求质量 — 当问题是概念性的或用户需要尽可能好的结果时，使用混合搜索。
首选 MCP 集成 — 配置完成后，Agent 会获得原生工具，无需每次都加载此技能。
频繁用户使用守护进程模式 — 如果用户定期搜索其知识库，建议设置 HTTP 守护进程。
结构化搜索中的第一个查询获得 2 倍权重 — 当组合词汇搜索和向量搜索时，将最重要/最确定的查询放在第一位。

故障排除

“首次运行时下载模型”

正常现象 — qmd 在首次使用时会自动下载约 2GB 的 GGUF 模型。这是一次性操作。

冷启动延迟（约 19 秒）

当模型未加载到内存中时会发生这种情况。解决方案：

使用 HTTP 守护进程模式 (qmd mcp --http --daemon) 以保持预热
当不需要模型时使用 qmd search（仅 BM25）
MCP stdio 模式在首次搜索时加载模型，并在会话期间保持预热

macOS: “unable to load extension”

安装 Homebrew SQLite：brew install sqlite 然后确保它在系统 SQLite 之前位于 PATH 中。

“No collections found”

运行 qmd collection add <path> --name <name> 添加目录，然后运行 qmd embed 对其进行索引。

嵌入模型覆盖（CJK/多语言）

为非英语内容设置 QMD_EMBED_MODEL 环境变量：

export QMD_EMBED_MODEL="your-multilingual-model"

数据存储

索引和向量： ~/.cache/qmd/index.sqlite
模型： 首次运行时自动下载到本地缓存
无云依赖 — 所有内容均在本地运行

参考

GitHub: tobi/qmd
QMD Changelogexpand: database migration plan\nlex: "schema change"'

### 查询语法 (lex/BM25 模式)

| 语法 | 效果 | 示例 |
|--------|--------|---------|
| `term` | 前缀匹配 | `perf` 匹配 "performance" |
| `"phrase"` | 精确短语 | `"rate limiter"` |
| `-term` | 排除术语 | `performance -sports` |

### HyDE（假设文档嵌入）

对于复杂主题，写出你期望的答案样子：

@@HERMES_PROTECTED_BLOCK_12@@

### 限定集合范围

```bash
qmd search "query" --collection notes
qmd query "query" --collection project-docs

输出格式

qmd search "query" --json        # JSON output (best for parsing)
qmd search "query" --limit 5     # Limit results
qmd get "#abc123"                # Get by document ID
qmd get "path/to/file.md"       # Get by file path
qmd get "file.md:50" -l 100     # Get specific line range
qmd multi-get "journals/*.md" --json  # Batch retrieve by glob

MCP 集成（推荐）

选项 A：Stdio 模式（简单）

添加到 ~/.hermes/config.yaml：

mcp_servers:
  qmd:
    command: "qmd"
    args: ["mcp"]
    timeout: 30
    connect_timeout: 45

这将注册以下工具：mcp_qmd_search、mcp_qmd_vsearch、mcp_qmd_deep_search、mcp_qmd_get、mcp_qmd_status。

权衡： 模型在首次搜索调用时加载（冷启动约 19 秒），然后在会话期间保持预热状态。对于偶尔使用来说可以接受。

选项 B：HTTP 守护进程模式（快速，重度使用推荐）

单独启动 qmd 守护进程——它会在内存中保持模型预热：

# Start daemon (persists across agent restarts)
qmd mcp --http --daemon

# Runs on http://localhost:8181 by default

然后配置 Hermes Agent 通过 HTTP 连接：

mcp_servers:
  qmd:
    url: "http://localhost:8181/mcp"
    timeout: 30

权衡： 运行时占用约 2GB RAM，但每次查询都很快（约 2-3 秒）。最适合频繁搜索的用户。

保持守护进程运行

macOS (launchd)

cat > ~/Library/LaunchAgents/com.qmd.daemon.plist << 'EOF'
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>com.qmd.daemon</string>
  <key>ProgramArguments</key>
  <array>
    <string>qmd</string>
    <string>mcp</string>
    <string>--http</string>
    <string>--daemon</string>
  </array>
  <key>RunAtLoad</key>
  <true/>
  <key>KeepAlive</key>
  <true/>
  <key>StandardOutPath</key>
  <string>/tmp/qmd-daemon.log</string>
  <key>StandardErrorPath</key>
  <string>/tmp/qmd-daemon.log</string>
</dict>
</plist>
EOF

launchctl load ~/Library/LaunchAgents/com.qmd.daemon.plist

Linux (systemd 用户服务)

mkdir -p ~/.config/systemd/user

cat > ~/.config/systemd/user/qmd-daemon.service << 'EOF'
[Unit]
Description=QMD MCP Daemon
After=network.target

[Service]
ExecStart=qmd mcp --http --daemon
Restart=on-failure
RestartSec=10
Environment=PATH=/usr/local/bin:/usr/bin:/bin

[Install]
WantedBy=default.target
EOF

systemctl --user daemon-reload
systemctl --user enable --now qmd-daemon
systemctl --user status qmd-daemon

MCP 工具参考

连接后，这些工具可作为 mcp_qmd_* 使用：

MCP 工具	映射到	描述
`mcp_qmd_search`	`qmd search`	BM25 关键词搜索
`mcp_qmd_vsearch`	`qmd vsearch`	语义向量搜索
`mcp_qmd_deep_search`	`qmd query`	混合搜索 + 重排序
`mcp_qmd_get`	`qmd get`	按 ID 或路径检索文档
`mcp_qmd_status`	`qmd status`	索引健康和统计信息

MCP 工具接受结构化 JSON 查询以进行多模式搜索：

{
  "searches": [
    {"type": "lex", "query": "authentication middleware"},
    {"type": "vec", "query": "how user login is verified"}
  ],
  "collections": ["project-docs"],
  "limit": 10
}

CLI 用法（无 MCP）

当未配置 MCP 时，直接通过终端使用 qmd：

terminal(command="qmd query 'what was decided about the API redesign' --json", timeout=30)

对于设置和管理任务，始终使用终端：

terminal(command="qmd collection add ~/Documents/notes --name notes")
terminal(command="qmd context add qmd://notes 'Personal research notes and ideas'")
terminal(command="qmd embed")
terminal(command="qmd status")

搜索管道工作原理

了解内部机制有助于选择合适的搜索模式：

查询扩展 — 一个微调过的 1.7B 模型生成 2 个替代查询。原始查询在融合中获得 2 倍权重。
并行检索 — BM25 (SQLite FTS5) 和向量搜索在所有查询变体上同时运行。
RRF 融合 — 倒数排名融合（Reciprocal Rank Fusion, k=60）合并结果。高排名奖励：第 1 名 +0.05，第 2-3 名 +0.02。
LLM 重排序 — qwen3-reranker 对前 30 个候选项进行评分（0.0-1.0）。
位置感知混合 — 排名 1-3：75% 检索 / 25% 重排序器。排名 4-10：60/40。排名 11+：40/60（对于长尾结果更信任重排序器）。

智能分块： 文档在自然断点（标题、代码块、空行）处分割，目标约为 900 个 token，重叠率为 15%。代码块绝不会在中间被分割。

最佳实践

始终添加上下文描述 — qmd context add 能显著提高检索准确性。描述每个集合包含的内容。
添加文档后重新嵌入 — 向集合添加新文件时，必须重新运行 qmd embed。
使用 qmd search 追求速度 — 当需要快速关键词查找（代码标识符、确切名称）时，BM25 是瞬时的且不需要模型。
使用 qmd query 追求质量 — 当问题是概念性的或用户需要尽可能好的结果时，使用混合搜索。
首选 MCP 集成 — 配置完成后，Agent 会获得原生工具，无需每次都加载此技能。
频繁用户使用守护进程模式 — 如果用户定期搜索其知识库，建议设置 HTTP 守护进程。
结构化搜索中的第一个查询获得 2 倍权重 — 当组合词汇搜索和向量搜索时，将最重要/最确定的查询放在第一位。

故障排除

“首次运行时下载模型”

正常现象 — qmd 在首次使用时会自动下载约 2GB 的 GGUF 模型。这是一次性操作。

冷启动延迟（约 19 秒）

当模型未加载到内存中时会发生这种情况。解决方案：

使用 HTTP 守护进程模式 (qmd mcp --http --daemon) 以保持预热
当不需要模型时使用 qmd search（仅 BM25）
MCP stdio 模式在首次搜索时加载模型，并在会话期间保持预热

macOS: “unable to load extension”

安装 Homebrew SQLite：brew install sqlite 然后确保它在系统 SQLite 之前位于 PATH 中。

“No collections found”

运行 qmd collection add <path> --name <name> 添加目录，然后运行 qmd embed 对其进行索引。

嵌入模型覆盖（CJK/多语言）

为非英语内容设置 QMD_EMBED_MODEL 环境变量：

export QMD_EMBED_MODEL="your-multilingual-model"

数据存储

索引和向量： ~/.cache/qmd/index.sqlite
模型： 首次运行时自动下载到本地缓存
无云依赖 — 所有内容均在本地运行

参考

GitHub: tobi/qmd
QMD Changeloghyde: The migration plan involves three phases. First, we add the new columns without dropping the old ones. Then we backfill data. Finally we cut over and remove legacy columns.'

### 限定集合范围

```bash
qmd search "query" --collection notes
qmd query "query" --collection project-docs

输出格式

qmd search "query" --json        # JSON output (best for parsing)
qmd search "query" --limit 5     # Limit results
qmd get "#abc123"                # Get by document ID
qmd get "path/to/file.md"       # Get by file path
qmd get "file.md:50" -l 100     # Get specific line range
qmd multi-get "journals/*.md" --json  # Batch retrieve by glob

MCP 集成（推荐）

选项 A：Stdio 模式（简单）

添加到 ~/.hermes/config.yaml：

mcp_servers:
  qmd:
    command: "qmd"
    args: ["mcp"]
    timeout: 30
    connect_timeout: 45

这将注册以下工具：mcp_qmd_search、mcp_qmd_vsearch、mcp_qmd_deep_search、mcp_qmd_get、mcp_qmd_status。

权衡： 模型在首次搜索调用时加载（冷启动约 19 秒），然后在会话期间保持预热状态。对于偶尔使用来说可以接受。

选项 B：HTTP 守护进程模式（快速，重度使用推荐）

单独启动 qmd 守护进程——它会在内存中保持模型预热：

# Start daemon (persists across agent restarts)
qmd mcp --http --daemon

# Runs on http://localhost:8181 by default

然后配置 Hermes Agent 通过 HTTP 连接：

mcp_servers:
  qmd:
    url: "http://localhost:8181/mcp"
    timeout: 30

权衡： 运行时占用约 2GB RAM，但每次查询都很快（约 2-3 秒）。最适合频繁搜索的用户。

保持守护进程运行

macOS (launchd)

cat > ~/Library/LaunchAgents/com.qmd.daemon.plist << 'EOF'
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>com.qmd.daemon</string>
  <key>ProgramArguments</key>
  <array>
    <string>qmd</string>
    <string>mcp</string>
    <string>--http</string>
    <string>--daemon</string>
  </array>
  <key>RunAtLoad</key>
  <true/>
  <key>KeepAlive</key>
  <true/>
  <key>StandardOutPath</key>
  <string>/tmp/qmd-daemon.log</string>
  <key>StandardErrorPath</key>
  <string>/tmp/qmd-daemon.log</string>
</dict>
</plist>
EOF

launchctl load ~/Library/LaunchAgents/com.qmd.daemon.plist

Linux (systemd 用户服务)

mkdir -p ~/.config/systemd/user

cat > ~/.config/systemd/user/qmd-daemon.service << 'EOF'
[Unit]
Description=QMD MCP Daemon
After=network.target

[Service]
ExecStart=qmd mcp --http --daemon
Restart=on-failure
RestartSec=10
Environment=PATH=/usr/local/bin:/usr/bin:/bin

[Install]
WantedBy=default.target
EOF

systemctl --user daemon-reload
systemctl --user enable --now qmd-daemon
systemctl --user status qmd-daemon

MCP 工具参考

连接后，这些工具可作为 mcp_qmd_* 使用：

MCP 工具	映射到	描述
`mcp_qmd_search`	`qmd search`	BM25 关键词搜索
`mcp_qmd_vsearch`	`qmd vsearch`	语义向量搜索
`mcp_qmd_deep_search`	`qmd query`	混合搜索 + 重排序
`mcp_qmd_get`	`qmd get`	按 ID 或路径检索文档
`mcp_qmd_status`	`qmd status`	索引健康和统计信息

MCP 工具接受结构化 JSON 查询以进行多模式搜索：

{
  "searches": [
    {"type": "lex", "query": "authentication middleware"},
    {"type": "vec", "query": "how user login is verified"}
  ],
  "collections": ["project-docs"],
  "limit": 10
}

CLI 用法（无 MCP）

当未配置 MCP 时，直接通过终端使用 qmd：

terminal(command="qmd query 'what was decided about the API redesign' --json", timeout=30)

对于设置和管理任务，始终使用终端：

terminal(command="qmd collection add ~/Documents/notes --name notes")
terminal(command="qmd context add qmd://notes 'Personal research notes and ideas'")
terminal(command="qmd embed")
terminal(command="qmd status")

搜索管道工作原理

了解内部机制有助于选择合适的搜索模式：

查询扩展 — 一个微调过的 1.7B 模型生成 2 个替代查询。原始查询在融合中获得 2 倍权重。
并行检索 — BM25 (SQLite FTS5) 和向量搜索在所有查询变体上同时运行。
RRF 融合 — 倒数排名融合（Reciprocal Rank Fusion, k=60）合并结果。高排名奖励：第 1 名 +0.05，第 2-3 名 +0.02。
LLM 重排序 — qwen3-reranker 对前 30 个候选项进行评分（0.0-1.0）。
位置感知混合 — 排名 1-3：75% 检索 / 25% 重排序器。排名 4-10：60/40。排名 11+：40/60（对于长尾结果更信任重排序器）。

智能分块： 文档在自然断点（标题、代码块、空行）处分割，目标约为 900 个 token，重叠率为 15%。代码块绝不会在中间被分割。

最佳实践

始终添加上下文描述 — qmd context add 能显著提高检索准确性。描述每个集合包含的内容。
添加文档后重新嵌入 — 向集合添加新文件时，必须重新运行 qmd embed。
使用 qmd search 追求速度 — 当需要快速关键词查找（代码标识符、确切名称）时，BM25 是瞬时的且不需要模型。
使用 qmd query 追求质量 — 当问题是概念性的或用户需要尽可能好的结果时，使用混合搜索。
首选 MCP 集成 — 配置完成后，Agent 会获得原生工具，无需每次都加载此技能。
频繁用户使用守护进程模式 — 如果用户定期搜索其知识库，建议设置 HTTP 守护进程。
结构化搜索中的第一个查询获得 2 倍权重 — 当组合词汇搜索和向量搜索时，将最重要/最确定的查询放在第一位。

故障排除

“首次运行时下载模型”

正常现象 — qmd 在首次使用时会自动下载约 2GB 的 GGUF 模型。这是一次性操作。

冷启动延迟（约 19 秒）

当模型未加载到内存中时会发生这种情况。解决方案：

使用 HTTP 守护进程模式 (qmd mcp --http --daemon) 以保持预热
当不需要模型时使用 qmd search（仅 BM25）
MCP stdio 模式在首次搜索时加载模型，并在会话期间保持预热

macOS: “unable to load extension”

安装 Homebrew SQLite：brew install sqlite 然后确保它在系统 SQLite 之前位于 PATH 中。

“No collections found”

运行 qmd collection add <path> --name <name> 添加目录，然后运行 qmd embed 对其进行索引。

嵌入模型覆盖（CJK/多语言）

为非英语内容设置 QMD_EMBED_MODEL 环境变量：

export QMD_EMBED_MODEL="your-multilingual-model"

数据存储

索引和向量： ~/.cache/qmd/index.sqlite
模型： 首次运行时自动下载到本地缓存
无云依赖 — 所有内容均在本地运行

参考

GitHub: tobi/qmd
QMD Changeloglex: rate limiter\nvec: how does throttling work under load'

With query expansion

qmd query

查询语法 (lex/BM25 模式)

语法	效果	示例
`term`	前缀匹配	`perf` 匹配 "performance"
`"phrase"`	精确短语	`"rate limiter"`
`-term`	排除术语	`performance -sports`

HyDE（假设文档嵌入）

对于复杂主题，写出你期望的答案样子：

qmd query 

### 限定集合范围

```bash
qmd search "query" --collection notes
qmd query "query" --collection project-docs

输出格式

qmd search "query" --json        # JSON output (best for parsing)
qmd search "query" --limit 5     # Limit results
qmd get "#abc123"                # Get by document ID
qmd get "path/to/file.md"       # Get by file path
qmd get "file.md:50" -l 100     # Get specific line range
qmd multi-get "journals/*.md" --json  # Batch retrieve by glob

MCP 集成（推荐）

选项 A：Stdio 模式（简单）

添加到 ~/.hermes/config.yaml：

mcp_servers:
  qmd:
    command: "qmd"
    args: ["mcp"]
    timeout: 30
    connect_timeout: 45

这将注册以下工具：mcp_qmd_search、mcp_qmd_vsearch、mcp_qmd_deep_search、mcp_qmd_get、mcp_qmd_status。

权衡： 模型在首次搜索调用时加载（冷启动约 19 秒），然后在会话期间保持预热状态。对于偶尔使用来说可以接受。

选项 B：HTTP 守护进程模式（快速，重度使用推荐）

单独启动 qmd 守护进程——它会在内存中保持模型预热：

# Start daemon (persists across agent restarts)
qmd mcp --http --daemon

# Runs on http://localhost:8181 by default

然后配置 Hermes Agent 通过 HTTP 连接：

mcp_servers:
  qmd:
    url: "http://localhost:8181/mcp"
    timeout: 30

权衡： 运行时占用约 2GB RAM，但每次查询都很快（约 2-3 秒）。最适合频繁搜索的用户。

保持守护进程运行

macOS (launchd)

cat > ~/Library/LaunchAgents/com.qmd.daemon.plist << 'EOF'
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>com.qmd.daemon</string>
  <key>ProgramArguments</key>
  <array>
    <string>qmd</string>
    <string>mcp</string>
    <string>--http</string>
    <string>--daemon</string>
  </array>
  <key>RunAtLoad</key>
  <true/>
  <key>KeepAlive</key>
  <true/>
  <key>StandardOutPath</key>
  <string>/tmp/qmd-daemon.log</string>
  <key>StandardErrorPath</key>
  <string>/tmp/qmd-daemon.log</string>
</dict>
</plist>
EOF

launchctl load ~/Library/LaunchAgents/com.qmd.daemon.plist

Linux (systemd 用户服务)

mkdir -p ~/.config/systemd/user

cat > ~/.config/systemd/user/qmd-daemon.service << 'EOF'
[Unit]
Description=QMD MCP Daemon
After=network.target

[Service]
ExecStart=qmd mcp --http --daemon
Restart=on-failure
RestartSec=10
Environment=PATH=/usr/local/bin:/usr/bin:/bin

[Install]
WantedBy=default.target
EOF

systemctl --user daemon-reload
systemctl --user enable --now qmd-daemon
systemctl --user status qmd-daemon

MCP 工具参考

连接后，这些工具可作为 mcp_qmd_* 使用：

MCP 工具	映射到	描述
`mcp_qmd_search`	`qmd search`	BM25 关键词搜索
`mcp_qmd_vsearch`	`qmd vsearch`	语义向量搜索
`mcp_qmd_deep_search`	`qmd query`	混合搜索 + 重排序
`mcp_qmd_get`	`qmd get`	按 ID 或路径检索文档
`mcp_qmd_status`	`qmd status`	索引健康和统计信息

MCP 工具接受结构化 JSON 查询以进行多模式搜索：

{
  "searches": [
    {"type": "lex", "query": "authentication middleware"},
    {"type": "vec", "query": "how user login is verified"}
  ],
  "collections": ["project-docs"],
  "limit": 10
}

CLI 用法（无 MCP）

当未配置 MCP 时，直接通过终端使用 qmd：

terminal(command="qmd query 'what was decided about the API redesign' --json", timeout=30)

对于设置和管理任务，始终使用终端：

terminal(command="qmd collection add ~/Documents/notes --name notes")
terminal(command="qmd context add qmd://notes 'Personal research notes and ideas'")
terminal(command="qmd embed")
terminal(command="qmd status")

搜索管道工作原理

了解内部机制有助于选择合适的搜索模式：

查询扩展 — 一个微调过的 1.7B 模型生成 2 个替代查询。原始查询在融合中获得 2 倍权重。
并行检索 — BM25 (SQLite FTS5) 和向量搜索在所有查询变体上同时运行。
RRF 融合 — 倒数排名融合（Reciprocal Rank Fusion, k=60）合并结果。高排名奖励：第 1 名 +0.05，第 2-3 名 +0.02。
LLM 重排序 — qwen3-reranker 对前 30 个候选项进行评分（0.0-1.0）。
位置感知混合 — 排名 1-3：75% 检索 / 25% 重排序器。排名 4-10：60/40。排名 11+：40/60（对于长尾结果更信任重排序器）。

智能分块： 文档在自然断点（标题、代码块、空行）处分割，目标约为 900 个 token，重叠率为 15%。代码块绝不会在中间被分割。

最佳实践

始终添加上下文描述 — qmd context add 能显著提高检索准确性。描述每个集合包含的内容。
添加文档后重新嵌入 — 向集合添加新文件时，必须重新运行 qmd embed。
使用 qmd search 追求速度 — 当需要快速关键词查找（代码标识符、确切名称）时，BM25 是瞬时的且不需要模型。
使用 qmd query 追求质量 — 当问题是概念性的或用户需要尽可能好的结果时，使用混合搜索。
首选 MCP 集成 — 配置完成后，Agent 会获得原生工具，无需每次都加载此技能。
频繁用户使用守护进程模式 — 如果用户定期搜索其知识库，建议设置 HTTP 守护进程。
结构化搜索中的第一个查询获得 2 倍权重 — 当组合词汇搜索和向量搜索时，将最重要/最确定的查询放在第一位。

故障排除

“首次运行时下载模型”

正常现象 — qmd 在首次使用时会自动下载约 2GB 的 GGUF 模型。这是一次性操作。

冷启动延迟（约 19 秒）

当模型未加载到内存中时会发生这种情况。解决方案：

使用 HTTP 守护进程模式 (qmd mcp --http --daemon) 以保持预热
当不需要模型时使用 qmd search（仅 BM25）
MCP stdio 模式在首次搜索时加载模型，并在会话期间保持预热

macOS: “unable to load extension”

安装 Homebrew SQLite：brew install sqlite 然后确保它在系统 SQLite 之前位于 PATH 中。

“No collections found”

运行 qmd collection add <path> --name <name> 添加目录，然后运行 qmd embed 对其进行索引。

嵌入模型覆盖（CJK/多语言）

为非英语内容设置 QMD_EMBED_MODEL 环境变量：

export QMD_EMBED_MODEL="your-multilingual-model"

数据存储

索引和向量： ~/.cache/qmd/index.sqlite
模型： 首次运行时自动下载到本地缓存
无云依赖 — 所有内容均在本地运行

参考

GitHub: tobi/qmd
QMD Changelogexpand: database migration plan\nlex: "schema change"'

### 查询语法 (lex/BM25 模式)

| 语法 | 效果 | 示例 |
|--------|--------|---------|
| `term` | 前缀匹配 | `perf` 匹配 "performance" |
| `"phrase"` | 精确短语 | `"rate limiter"` |
| `-term` | 排除术语 | `performance -sports` |

### HyDE（假设文档嵌入）

对于复杂主题，写出你期望的答案样子：

@@HERMES_PROTECTED_BLOCK_12@@

### 限定集合范围

```bash
qmd search "query" --collection notes
qmd query "query" --collection project-docs

输出格式

qmd search "query" --json        # JSON output (best for parsing)
qmd search "query" --limit 5     # Limit results
qmd get "#abc123"                # Get by document ID
qmd get "path/to/file.md"       # Get by file path
qmd get "file.md:50" -l 100     # Get specific line range
qmd multi-get "journals/*.md" --json  # Batch retrieve by glob

MCP 集成（推荐）

选项 A：Stdio 模式（简单）

添加到 ~/.hermes/config.yaml：

mcp_servers:
  qmd:
    command: "qmd"
    args: ["mcp"]
    timeout: 30
    connect_timeout: 45

这将注册以下工具：mcp_qmd_search、mcp_qmd_vsearch、mcp_qmd_deep_search、mcp_qmd_get、mcp_qmd_status。

权衡： 模型在首次搜索调用时加载（冷启动约 19 秒），然后在会话期间保持预热状态。对于偶尔使用来说可以接受。

选项 B：HTTP 守护进程模式（快速，重度使用推荐）

单独启动 qmd 守护进程——它会在内存中保持模型预热：

# Start daemon (persists across agent restarts)
qmd mcp --http --daemon

# Runs on http://localhost:8181 by default

然后配置 Hermes Agent 通过 HTTP 连接：

mcp_servers:
  qmd:
    url: "http://localhost:8181/mcp"
    timeout: 30

权衡： 运行时占用约 2GB RAM，但每次查询都很快（约 2-3 秒）。最适合频繁搜索的用户。

保持守护进程运行

macOS (launchd)

cat > ~/Library/LaunchAgents/com.qmd.daemon.plist << 'EOF'
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>com.qmd.daemon</string>
  <key>ProgramArguments</key>
  <array>
    <string>qmd</string>
    <string>mcp</string>
    <string>--http</string>
    <string>--daemon</string>
  </array>
  <key>RunAtLoad</key>
  <true/>
  <key>KeepAlive</key>
  <true/>
  <key>StandardOutPath</key>
  <string>/tmp/qmd-daemon.log</string>
  <key>StandardErrorPath</key>
  <string>/tmp/qmd-daemon.log</string>
</dict>
</plist>
EOF

launchctl load ~/Library/LaunchAgents/com.qmd.daemon.plist

Linux (systemd 用户服务)

mkdir -p ~/.config/systemd/user

cat > ~/.config/systemd/user/qmd-daemon.service << 'EOF'
[Unit]
Description=QMD MCP Daemon
After=network.target

[Service]
ExecStart=qmd mcp --http --daemon
Restart=on-failure
RestartSec=10
Environment=PATH=/usr/local/bin:/usr/bin:/bin

[Install]
WantedBy=default.target
EOF

systemctl --user daemon-reload
systemctl --user enable --now qmd-daemon
systemctl --user status qmd-daemon

MCP 工具参考

连接后，这些工具可作为 mcp_qmd_* 使用：

MCP 工具	映射到	描述
`mcp_qmd_search`	`qmd search`	BM25 关键词搜索
`mcp_qmd_vsearch`	`qmd vsearch`	语义向量搜索
`mcp_qmd_deep_search`	`qmd query`	混合搜索 + 重排序
`mcp_qmd_get`	`qmd get`	按 ID 或路径检索文档
`mcp_qmd_status`	`qmd status`	索引健康和统计信息

MCP 工具接受结构化 JSON 查询以进行多模式搜索：

{
  "searches": [
    {"type": "lex", "query": "authentication middleware"},
    {"type": "vec", "query": "how user login is verified"}
  ],
  "collections": ["project-docs"],
  "limit": 10
}

CLI 用法（无 MCP）

当未配置 MCP 时，直接通过终端使用 qmd：

terminal(command="qmd query 'what was decided about the API redesign' --json", timeout=30)

对于设置和管理任务，始终使用终端：

terminal(command="qmd collection add ~/Documents/notes --name notes")
terminal(command="qmd context add qmd://notes 'Personal research notes and ideas'")
terminal(command="qmd embed")
terminal(command="qmd status")

搜索管道工作原理

了解内部机制有助于选择合适的搜索模式：

查询扩展 — 一个微调过的 1.7B 模型生成 2 个替代查询。原始查询在融合中获得 2 倍权重。
并行检索 — BM25 (SQLite FTS5) 和向量搜索在所有查询变体上同时运行。
RRF 融合 — 倒数排名融合（Reciprocal Rank Fusion, k=60）合并结果。高排名奖励：第 1 名 +0.05，第 2-3 名 +0.02。
LLM 重排序 — qwen3-reranker 对前 30 个候选项进行评分（0.0-1.0）。
位置感知混合 — 排名 1-3：75% 检索 / 25% 重排序器。排名 4-10：60/40。排名 11+：40/60（对于长尾结果更信任重排序器）。

智能分块： 文档在自然断点（标题、代码块、空行）处分割，目标约为 900 个 token，重叠率为 15%。代码块绝不会在中间被分割。

最佳实践

始终添加上下文描述 — qmd context add 能显著提高检索准确性。描述每个集合包含的内容。
添加文档后重新嵌入 — 向集合添加新文件时，必须重新运行 qmd embed。
使用 qmd search 追求速度 — 当需要快速关键词查找（代码标识符、确切名称）时，BM25 是瞬时的且不需要模型。
使用 qmd query 追求质量 — 当问题是概念性的或用户需要尽可能好的结果时，使用混合搜索。
首选 MCP 集成 — 配置完成后，Agent 会获得原生工具，无需每次都加载此技能。
频繁用户使用守护进程模式 — 如果用户定期搜索其知识库，建议设置 HTTP 守护进程。
结构化搜索中的第一个查询获得 2 倍权重 — 当组合词汇搜索和向量搜索时，将最重要/最确定的查询放在第一位。

故障排除

“首次运行时下载模型”

正常现象 — qmd 在首次使用时会自动下载约 2GB 的 GGUF 模型。这是一次性操作。

冷启动延迟（约 19 秒）

当模型未加载到内存中时会发生这种情况。解决方案：

使用 HTTP 守护进程模式 (qmd mcp --http --daemon) 以保持预热
当不需要模型时使用 qmd search（仅 BM25）
MCP stdio 模式在首次搜索时加载模型，并在会话期间保持预热

macOS: “unable to load extension”

安装 Homebrew SQLite：brew install sqlite 然后确保它在系统 SQLite 之前位于 PATH 中。

“No collections found”

运行 qmd collection add <path> --name <name> 添加目录，然后运行 qmd embed 对其进行索引。

嵌入模型覆盖（CJK/多语言）

为非英语内容设置 QMD_EMBED_MODEL 环境变量：

export QMD_EMBED_MODEL="your-multilingual-model"

数据存储

索引和向量： ~/.cache/qmd/index.sqlite
模型： 首次运行时自动下载到本地缓存
无云依赖 — 所有内容均在本地运行

参考

GitHub: tobi/qmd
QMD Changeloghyde: The migration plan involves three phases. First, we add the new columns without dropping the old ones. Then we backfill data. Finally we cut over and remove legacy columns.'

### 限定集合范围

```bash
qmd search "query" --collection notes
qmd query "query" --collection project-docs

输出格式

qmd search "query" --json        # JSON output (best for parsing)
qmd search "query" --limit 5     # Limit results
qmd get "#abc123"                # Get by document ID
qmd get "path/to/file.md"       # Get by file path
qmd get "file.md:50" -l 100     # Get specific line range
qmd multi-get "journals/*.md" --json  # Batch retrieve by glob

MCP 集成（推荐）

选项 A：Stdio 模式（简单）

添加到 ~/.hermes/config.yaml：

mcp_servers:
  qmd:
    command: "qmd"
    args: ["mcp"]
    timeout: 30
    connect_timeout: 45

这将注册以下工具：mcp_qmd_search、mcp_qmd_vsearch、mcp_qmd_deep_search、mcp_qmd_get、mcp_qmd_status。

权衡： 模型在首次搜索调用时加载（冷启动约 19 秒），然后在会话期间保持预热状态。对于偶尔使用来说可以接受。

选项 B：HTTP 守护进程模式（快速，重度使用推荐）

单独启动 qmd 守护进程——它会在内存中保持模型预热：

# Start daemon (persists across agent restarts)
qmd mcp --http --daemon

# Runs on http://localhost:8181 by default

然后配置 Hermes Agent 通过 HTTP 连接：

mcp_servers:
  qmd:
    url: "http://localhost:8181/mcp"
    timeout: 30

权衡： 运行时占用约 2GB RAM，但每次查询都很快（约 2-3 秒）。最适合频繁搜索的用户。

保持守护进程运行

macOS (launchd)

cat > ~/Library/LaunchAgents/com.qmd.daemon.plist << 'EOF'
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>com.qmd.daemon</string>
  <key>ProgramArguments</key>
  <array>
    <string>qmd</string>
    <string>mcp</string>
    <string>--http</string>
    <string>--daemon</string>
  </array>
  <key>RunAtLoad</key>
  <true/>
  <key>KeepAlive</key>
  <true/>
  <key>StandardOutPath</key>
  <string>/tmp/qmd-daemon.log</string>
  <key>StandardErrorPath</key>
  <string>/tmp/qmd-daemon.log</string>
</dict>
</plist>
EOF

launchctl load ~/Library/LaunchAgents/com.qmd.daemon.plist

Linux (systemd 用户服务)

mkdir -p ~/.config/systemd/user

cat > ~/.config/systemd/user/qmd-daemon.service << 'EOF'
[Unit]
Description=QMD MCP Daemon
After=network.target

[Service]
ExecStart=qmd mcp --http --daemon
Restart=on-failure
RestartSec=10
Environment=PATH=/usr/local/bin:/usr/bin:/bin

[Install]
WantedBy=default.target
EOF

systemctl --user daemon-reload
systemctl --user enable --now qmd-daemon
systemctl --user status qmd-daemon

MCP 工具参考

连接后，这些工具可作为 mcp_qmd_* 使用：

MCP 工具	映射到	描述
`mcp_qmd_search`	`qmd search`	BM25 关键词搜索
`mcp_qmd_vsearch`	`qmd vsearch`	语义向量搜索
`mcp_qmd_deep_search`	`qmd query`	混合搜索 + 重排序
`mcp_qmd_get`	`qmd get`	按 ID 或路径检索文档
`mcp_qmd_status`	`qmd status`	索引健康和统计信息

MCP 工具接受结构化 JSON 查询以进行多模式搜索：

{
  "searches": [
    {"type": "lex", "query": "authentication middleware"},
    {"type": "vec", "query": "how user login is verified"}
  ],
  "collections": ["project-docs"],
  "limit": 10
}

CLI 用法（无 MCP）

当未配置 MCP 时，直接通过终端使用 qmd：

terminal(command="qmd query 'what was decided about the API redesign' --json", timeout=30)

对于设置和管理任务，始终使用终端：

terminal(command="qmd collection add ~/Documents/notes --name notes")
terminal(command="qmd context add qmd://notes 'Personal research notes and ideas'")
terminal(command="qmd embed")
terminal(command="qmd status")

搜索管道工作原理

了解内部机制有助于选择合适的搜索模式：

查询扩展 — 一个微调过的 1.7B 模型生成 2 个替代查询。原始查询在融合中获得 2 倍权重。
并行检索 — BM25 (SQLite FTS5) 和向量搜索在所有查询变体上同时运行。
RRF 融合 — 倒数排名融合（Reciprocal Rank Fusion, k=60）合并结果。高排名奖励：第 1 名 +0.05，第 2-3 名 +0.02。
LLM 重排序 — qwen3-reranker 对前 30 个候选项进行评分（0.0-1.0）。
位置感知混合 — 排名 1-3：75% 检索 / 25% 重排序器。排名 4-10：60/40。排名 11+：40/60（对于长尾结果更信任重排序器）。

智能分块： 文档在自然断点（标题、代码块、空行）处分割，目标约为 900 个 token，重叠率为 15%。代码块绝不会在中间被分割。

最佳实践

始终添加上下文描述 — qmd context add 能显著提高检索准确性。描述每个集合包含的内容。
添加文档后重新嵌入 — 向集合添加新文件时，必须重新运行 qmd embed。
使用 qmd search 追求速度 — 当需要快速关键词查找（代码标识符、确切名称）时，BM25 是瞬时的且不需要模型。
使用 qmd query 追求质量 — 当问题是概念性的或用户需要尽可能好的结果时，使用混合搜索。
首选 MCP 集成 — 配置完成后，Agent 会获得原生工具，无需每次都加载此技能。
频繁用户使用守护进程模式 — 如果用户定期搜索其知识库，建议设置 HTTP 守护进程。
结构化搜索中的第一个查询获得 2 倍权重 — 当组合词汇搜索和向量搜索时，将最重要/最确定的查询放在第一位。

故障排除

“首次运行时下载模型”

正常现象 — qmd 在首次使用时会自动下载约 2GB 的 GGUF 模型。这是一次性操作。

冷启动延迟（约 19 秒）

当模型未加载到内存中时会发生这种情况。解决方案：

使用 HTTP 守护进程模式 (qmd mcp --http --daemon) 以保持预热
当不需要模型时使用 qmd search（仅 BM25）
MCP stdio 模式在首次搜索时加载模型，并在会话期间保持预热

macOS: “unable to load extension”

安装 Homebrew SQLite：brew install sqlite 然后确保它在系统 SQLite 之前位于 PATH 中。

“No collections found”

运行 qmd collection add <path> --name <name> 添加目录，然后运行 qmd embed 对其进行索引。

嵌入模型覆盖（CJK/多语言）

为非英语内容设置 QMD_EMBED_MODEL 环境变量：

export QMD_EMBED_MODEL="your-multilingual-model"

数据存储

索引和向量： ~/.cache/qmd/index.sqlite
模型： 首次运行时自动下载到本地缓存
无云依赖 — 所有内容均在本地运行

参考

GitHub: tobi/qmd
QMD Changelogexpand: database migration plan\nlex: "schema change"'

### 查询语法 (lex/BM25 模式)

| 语法 | 效果 | 示例 |
|--------|--------|---------|
| `term` | 前缀匹配 | `perf` 匹配 "performance" |
| `"phrase"` | 精确短语 | `"rate limiter"` |
| `-term` | 排除术语 | `performance -sports` |

### HyDE（假设文档嵌入）

对于复杂主题，写出你期望的答案样子：

```bash
qmd query 

### 限定集合范围

```bash
qmd search "query" --collection notes
qmd query "query" --collection project-docs

输出格式

qmd search "query" --json        # JSON output (best for parsing)
qmd search "query" --limit 5     # Limit results
qmd get "#abc123"                # Get by document ID
qmd get "path/to/file.md"       # Get by file path
qmd get "file.md:50" -l 100     # Get specific line range
qmd multi-get "journals/*.md" --json  # Batch retrieve by glob

MCP 集成（推荐）

选项 A：Stdio 模式（简单）

添加到 ~/.hermes/config.yaml：

mcp_servers:
  qmd:
    command: "qmd"
    args: ["mcp"]
    timeout: 30
    connect_timeout: 45

这将注册以下工具：mcp_qmd_search、mcp_qmd_vsearch、mcp_qmd_deep_search、mcp_qmd_get、mcp_qmd_status。

权衡： 模型在首次搜索调用时加载（冷启动约 19 秒），然后在会话期间保持预热状态。对于偶尔使用来说可以接受。

选项 B：HTTP 守护进程模式（快速，重度使用推荐）

单独启动 qmd 守护进程——它会在内存中保持模型预热：

# Start daemon (persists across agent restarts)
qmd mcp --http --daemon

# Runs on http://localhost:8181 by default

然后配置 Hermes Agent 通过 HTTP 连接：

mcp_servers:
  qmd:
    url: "http://localhost:8181/mcp"
    timeout: 30

权衡： 运行时占用约 2GB RAM，但每次查询都很快（约 2-3 秒）。最适合频繁搜索的用户。

保持守护进程运行

macOS (launchd)

cat > ~/Library/LaunchAgents/com.qmd.daemon.plist << 'EOF'
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>com.qmd.daemon</string>
  <key>ProgramArguments</key>
  <array>
    <string>qmd</string>
    <string>mcp</string>
    <string>--http</string>
    <string>--daemon</string>
  </array>
  <key>RunAtLoad</key>
  <true/>
  <key>KeepAlive</key>
  <true/>
  <key>StandardOutPath</key>
  <string>/tmp/qmd-daemon.log</string>
  <key>StandardErrorPath</key>
  <string>/tmp/qmd-daemon.log</string>
</dict>
</plist>
EOF

launchctl load ~/Library/LaunchAgents/com.qmd.daemon.plist

Linux (systemd 用户服务)

mkdir -p ~/.config/systemd/user

cat > ~/.config/systemd/user/qmd-daemon.service << 'EOF'
[Unit]
Description=QMD MCP Daemon
After=network.target

[Service]
ExecStart=qmd mcp --http --daemon
Restart=on-failure
RestartSec=10
Environment=PATH=/usr/local/bin:/usr/bin:/bin

[Install]
WantedBy=default.target
EOF

systemctl --user daemon-reload
systemctl --user enable --now qmd-daemon
systemctl --user status qmd-daemon

MCP 工具参考

连接后，这些工具可作为 mcp_qmd_* 使用：

MCP 工具	映射到	描述
`mcp_qmd_search`	`qmd search`	BM25 关键词搜索
`mcp_qmd_vsearch`	`qmd vsearch`	语义向量搜索
`mcp_qmd_deep_search`	`qmd query`	混合搜索 + 重排序
`mcp_qmd_get`	`qmd get`	按 ID 或路径检索文档
`mcp_qmd_status`	`qmd status`	索引健康和统计信息

MCP 工具接受结构化 JSON 查询以进行多模式搜索：

{
  "searches": [
    {"type": "lex", "query": "authentication middleware"},
    {"type": "vec", "query": "how user login is verified"}
  ],
  "collections": ["project-docs"],
  "limit": 10
}

CLI 用法（无 MCP）

当未配置 MCP 时，直接通过终端使用 qmd：

terminal(command="qmd query 'what was decided about the API redesign' --json", timeout=30)

对于设置和管理任务，始终使用终端：

terminal(command="qmd collection add ~/Documents/notes --name notes")
terminal(command="qmd context add qmd://notes 'Personal research notes and ideas'")
terminal(command="qmd embed")
terminal(command="qmd status")

搜索管道工作原理

了解内部机制有助于选择合适的搜索模式：

查询扩展 — 一个微调过的 1.7B 模型生成 2 个替代查询。原始查询在融合中获得 2 倍权重。
并行检索 — BM25 (SQLite FTS5) 和向量搜索在所有查询变体上同时运行。
RRF 融合 — 倒数排名融合（Reciprocal Rank Fusion, k=60）合并结果。高排名奖励：第 1 名 +0.05，第 2-3 名 +0.02。
LLM 重排序 — qwen3-reranker 对前 30 个候选项进行评分（0.0-1.0）。
位置感知混合 — 排名 1-3：75% 检索 / 25% 重排序器。排名 4-10：60/40。排名 11+：40/60（对于长尾结果更信任重排序器）。

智能分块： 文档在自然断点（标题、代码块、空行）处分割，目标约为 900 个 token，重叠率为 15%。代码块绝不会在中间被分割。

最佳实践

始终添加上下文描述 — qmd context add 能显著提高检索准确性。描述每个集合包含的内容。
添加文档后重新嵌入 — 向集合添加新文件时，必须重新运行 qmd embed。
使用 qmd search 追求速度 — 当需要快速关键词查找（代码标识符、确切名称）时，BM25 是瞬时的且不需要模型。
使用 qmd query 追求质量 — 当问题是概念性的或用户需要尽可能好的结果时，使用混合搜索。
首选 MCP 集成 — 配置完成后，Agent 会获得原生工具，无需每次都加载此技能。
频繁用户使用守护进程模式 — 如果用户定期搜索其知识库，建议设置 HTTP 守护进程。
结构化搜索中的第一个查询获得 2 倍权重 — 当组合词汇搜索和向量搜索时，将最重要/最确定的查询放在第一位。

故障排除

“首次运行时下载模型”

正常现象 — qmd 在首次使用时会自动下载约 2GB 的 GGUF 模型。这是一次性操作。

冷启动延迟（约 19 秒）

当模型未加载到内存中时会发生这种情况。解决方案：

使用 HTTP 守护进程模式 (qmd mcp --http --daemon) 以保持预热
当不需要模型时使用 qmd search（仅 BM25）
MCP stdio 模式在首次搜索时加载模型，并在会话期间保持预热

macOS: “unable to load extension”

安装 Homebrew SQLite：brew install sqlite 然后确保它在系统 SQLite 之前位于 PATH 中。

“No collections found”

运行 qmd collection add <path> --name <name> 添加目录，然后运行 qmd embed 对其进行索引。

嵌入模型覆盖（CJK/多语言）

为非英语内容设置 QMD_EMBED_MODEL 环境变量：

export QMD_EMBED_MODEL="your-multilingual-model"

数据存储

索引和向量： ~/.cache/qmd/index.sqlite
模型： 首次运行时自动下载到本地缓存
无云依赖 — 所有内容均在本地运行

参考

GitHub: tobi/qmd
QMD Changeloghyde: The migration plan involves three phases. First, we add the new columns without dropping the old ones. Then we backfill data. Finally we cut over and remove legacy columns.'

### 限定集合范围

```bash
qmd search "query" --collection notes
qmd query "query" --collection project-docs

输出格式

qmd search "query" --json        # JSON output (best for parsing)
qmd search "query" --limit 5     # Limit results
qmd get "#abc123"                # Get by document ID
qmd get "path/to/file.md"       # Get by file path
qmd get "file.md:50" -l 100     # Get specific line range
qmd multi-get "journals/*.md" --json  # Batch retrieve by glob

MCP 集成（推荐）

选项 A：Stdio 模式（简单）

添加到 ~/.hermes/config.yaml：

mcp_servers:
  qmd:
    command: "qmd"
    args: ["mcp"]
    timeout: 30
    connect_timeout: 45

这将注册以下工具：mcp_qmd_search、mcp_qmd_vsearch、mcp_qmd_deep_search、mcp_qmd_get、mcp_qmd_status。

权衡： 模型在首次搜索调用时加载（冷启动约 19 秒），然后在会话期间保持预热状态。对于偶尔使用来说可以接受。

选项 B：HTTP 守护进程模式（快速，重度使用推荐）

单独启动 qmd 守护进程——它会在内存中保持模型预热：

# Start daemon (persists across agent restarts)
qmd mcp --http --daemon

# Runs on http://localhost:8181 by default

然后配置 Hermes Agent 通过 HTTP 连接：

mcp_servers:
  qmd:
    url: "http://localhost:8181/mcp"
    timeout: 30

权衡： 运行时占用约 2GB RAM，但每次查询都很快（约 2-3 秒）。最适合频繁搜索的用户。

保持守护进程运行

macOS (launchd)

cat > ~/Library/LaunchAgents/com.qmd.daemon.plist << 'EOF'
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>com.qmd.daemon</string>
  <key>ProgramArguments</key>
  <array>
    <string>qmd</string>
    <string>mcp</string>
    <string>--http</string>
    <string>--daemon</string>
  </array>
  <key>RunAtLoad</key>
  <true/>
  <key>KeepAlive</key>
  <true/>
  <key>StandardOutPath</key>
  <string>/tmp/qmd-daemon.log</string>
  <key>StandardErrorPath</key>
  <string>/tmp/qmd-daemon.log</string>
</dict>
</plist>
EOF

launchctl load ~/Library/LaunchAgents/com.qmd.daemon.plist

Linux (systemd 用户服务)

mkdir -p ~/.config/systemd/user

cat > ~/.config/systemd/user/qmd-daemon.service << 'EOF'
[Unit]
Description=QMD MCP Daemon
After=network.target

[Service]
ExecStart=qmd mcp --http --daemon
Restart=on-failure
RestartSec=10
Environment=PATH=/usr/local/bin:/usr/bin:/bin

[Install]
WantedBy=default.target
EOF

systemctl --user daemon-reload
systemctl --user enable --now qmd-daemon
systemctl --user status qmd-daemon

MCP 工具参考

连接后，这些工具可作为 mcp_qmd_* 使用：

MCP 工具	映射到	描述
`mcp_qmd_search`	`qmd search`	BM25 关键词搜索
`mcp_qmd_vsearch`	`qmd vsearch`	语义向量搜索
`mcp_qmd_deep_search`	`qmd query`	混合搜索 + 重排序
`mcp_qmd_get`	`qmd get`	按 ID 或路径检索文档
`mcp_qmd_status`	`qmd status`	索引健康和统计信息

MCP 工具接受结构化 JSON 查询以进行多模式搜索：

{
  "searches": [
    {"type": "lex", "query": "authentication middleware"},
    {"type": "vec", "query": "how user login is verified"}
  ],
  "collections": ["project-docs"],
  "limit": 10
}

CLI 用法（无 MCP）

当未配置 MCP 时，直接通过终端使用 qmd：

terminal(command="qmd query 'what was decided about the API redesign' --json", timeout=30)

对于设置和管理任务，始终使用终端：

terminal(command="qmd collection add ~/Documents/notes --name notes")
terminal(command="qmd context add qmd://notes 'Personal research notes and ideas'")
terminal(command="qmd embed")
terminal(command="qmd status")

搜索管道工作原理

了解内部机制有助于选择合适的搜索模式：

查询扩展 — 一个微调过的 1.7B 模型生成 2 个替代查询。原始查询在融合中获得 2 倍权重。
并行检索 — BM25 (SQLite FTS5) 和向量搜索在所有查询变体上同时运行。
RRF 融合 — 倒数排名融合（Reciprocal Rank Fusion, k=60）合并结果。高排名奖励：第 1 名 +0.05，第 2-3 名 +0.02。
LLM 重排序 — qwen3-reranker 对前 30 个候选项进行评分（0.0-1.0）。
位置感知混合 — 排名 1-3：75% 检索 / 25% 重排序器。排名 4-10：60/40。排名 11+：40/60（对于长尾结果更信任重排序器）。

智能分块： 文档在自然断点（标题、代码块、空行）处分割，目标约为 900 个 token，重叠率为 15%。代码块绝不会在中间被分割。

最佳实践

始终添加上下文描述 — qmd context add 能显著提高检索准确性。描述每个集合包含的内容。
添加文档后重新嵌入 — 向集合添加新文件时，必须重新运行 qmd embed。
使用 qmd search 追求速度 — 当需要快速关键词查找（代码标识符、确切名称）时，BM25 是瞬时的且不需要模型。
使用 qmd query 追求质量 — 当问题是概念性的或用户需要尽可能好的结果时，使用混合搜索。
首选 MCP 集成 — 配置完成后，Agent 会获得原生工具，无需每次都加载此技能。
频繁用户使用守护进程模式 — 如果用户定期搜索其知识库，建议设置 HTTP 守护进程。
结构化搜索中的第一个查询获得 2 倍权重 — 当组合词汇搜索和向量搜索时，将最重要/最确定的查询放在第一位。

故障排除

“首次运行时下载模型”

正常现象 — qmd 在首次使用时会自动下载约 2GB 的 GGUF 模型。这是一次性操作。

冷启动延迟（约 19 秒）

当模型未加载到内存中时会发生这种情况。解决方案：

使用 HTTP 守护进程模式 (qmd mcp --http --daemon) 以保持预热
当不需要模型时使用 qmd search（仅 BM25）
MCP stdio 模式在首次搜索时加载模型，并在会话期间保持预热

macOS: “unable to load extension”

安装 Homebrew SQLite：brew install sqlite 然后确保它在系统 SQLite 之前位于 PATH 中。

“No collections found”

运行 qmd collection add <path> --name <name> 添加目录，然后运行 qmd embed 对其进行索引。

嵌入模型覆盖（CJK/多语言）

为非英语内容设置 QMD_EMBED_MODEL 环境变量：

export QMD_EMBED_MODEL="your-multilingual-model"

数据存储

索引和向量： ~/.cache/qmd/index.sqlite
模型： 首次运行时自动下载到本地缓存
无云依赖 — 所有内容均在本地运行

技能元数据​

参考：完整 SKILL.md​

QMD — 查询标记文档

何时使用​

前置条件​

Node.js >= 22（必需）​

支持扩展的 SQLite（仅限 macOS）​

安装 qmd​

验证安装​

快速参考​

设置工作流​

1. 添加集合​

2. 添加上下文描述​

3. 生成嵌入​

4. 验证​

搜索模式​

快速关键词搜索 (BM25)​

语义向量搜索​

带重排序的混合搜索（最佳质量）​

结构化多模式查询​

输出格式​

MCP 集成（推荐）​

选项 A：Stdio 模式（简单）​

选项 B：HTTP 守护进程模式（快速，重度使用推荐）​

保持守护进程运行​

macOS (launchd)​

Linux (systemd 用户服务)​

MCP 工具参考​

CLI 用法（无 MCP）​

搜索管道工作原理​

最佳实践​

故障排除​

“首次运行时下载模型”​

冷启动延迟（约 19 秒）​

macOS: “unable to load extension”​

“No collections found”​

嵌入模型覆盖（CJK/多语言）​

数据存储​

参考​

With query expansion

查询语法 (lex/BM25 模式)​

HyDE（假设文档嵌入）​

限定集合范围​

输出格式​

MCP 集成（推荐）​

选项 A：Stdio 模式（简单）​

选项 B：HTTP 守护进程模式（快速，重度使用推荐）​

保持守护进程运行​

macOS (launchd)​

Linux (systemd 用户服务)​

MCP 工具参考​

CLI 用法（无 MCP）​

搜索管道工作原理​

最佳实践​

故障排除​

“首次运行时下载模型”​

冷启动延迟（约 19 秒）​

macOS: “unable to load extension”​

“No collections found”​

嵌入模型覆盖（CJK/多语言）​

数据存储​

参考​

输出格式​

MCP 集成（推荐）​

选项 A：Stdio 模式（简单）​

选项 B：HTTP 守护进程模式（快速，重度使用推荐）​

保持守护进程运行​

macOS (launchd)​

Linux (systemd 用户服务)​

MCP 工具参考​

CLI 用法（无 MCP）​

搜索管道工作原理​

最佳实践​

故障排除​

“首次运行时下载模型”​

冷启动延迟（约 19 秒）​

macOS: “unable to load extension”​

“No collections found”​

嵌入模型覆盖（CJK/多语言）​

数据存储​

技能元数据

参考：完整 SKILL.md

何时使用

前置条件

Node.js >= 22（必需）

支持扩展的 SQLite（仅限 macOS）

安装 qmd

验证安装

快速参考

设置工作流

1. 添加集合

2. 添加上下文描述

3. 生成嵌入

4. 验证

搜索模式

快速关键词搜索 (BM25)

语义向量搜索

带重排序的混合搜索（最佳质量）

结构化多模式查询

输出格式

MCP 集成（推荐）

选项 A：Stdio 模式（简单）

选项 B：HTTP 守护进程模式（快速，重度使用推荐）

保持守护进程运行

macOS (launchd)

Linux (systemd 用户服务)

MCP 工具参考

CLI 用法（无 MCP）

搜索管道工作原理

最佳实践

故障排除

“首次运行时下载模型”

冷启动延迟（约 19 秒）

macOS: “unable to load extension”

“No collections found”

嵌入模型覆盖（CJK/多语言）

数据存储

参考

查询语法 (lex/BM25 模式)

HyDE（假设文档嵌入）

限定集合范围

输出格式

MCP 集成（推荐）

选项 A：Stdio 模式（简单）

选项 B：HTTP 守护进程模式（快速，重度使用推荐）

保持守护进程运行

macOS (launchd)

Linux (systemd 用户服务)

MCP 工具参考

CLI 用法（无 MCP）

搜索管道工作原理

最佳实践

故障排除

“首次运行时下载模型”

冷启动延迟（约 19 秒）

macOS: “unable to load extension”

“No collections found”

嵌入模型覆盖（CJK/多语言）

数据存储

参考

输出格式

MCP 集成（推荐）

选项 A：Stdio 模式（简单）

选项 B：HTTP 守护进程模式（快速，重度使用推荐）

保持守护进程运行

macOS (launchd)

Linux (systemd 用户服务)

MCP 工具参考

CLI 用法（无 MCP）

搜索管道工作原理

最佳实践

故障排除

“首次运行时下载模型”

冷启动延迟（约 19 秒）

macOS: “unable to load extension”

“No collections found”

嵌入模型覆盖（CJK/多语言）

数据存储

参考

输出格式