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/多語言）

數據存儲

參考

輸出格式