QMD Plus

Enhanced QMD search with LLM-powered query expansion. Better recall and precision for multilingual knowledge bases. Use when users ask to search notes, find...

Security Scan

The skill's behavior largely matches its stated purpose (LLM-based query expansion for qmd), but the published metadata omits required tooling and the runtime instructions assume you will send prompts/responses to an LLM — a potential source of data exposure and a metadata/integration inconsistency you should review before installing.

Purpose & Capability

The skill claims to enhance qmd search (reasonable), and included scripts implement a prompt generator and a qmd wrapper. However the registry metadata lists no required binaries/env, while SKILL.md and the scripts clearly require qmd (the qmd CLI/MCP server), node (to run expand-query.js), and jq (used in the shell wrapper). This metadata omission is an incoherence that could mislead users about dependencies and privileges.

Instruction Scope

SKILL.md and scripts are scoped to: generate an LLM prompt (expand-query.js), accept an LLM JSON response or print instructions for the user, and call qmd to execute searches. The skill does NOT itself call any external LLM endpoints or send data over the network — the user (or their chosen LLM client) must send the prompt and provide the response. Important: sending the generated prompt (which contains the user query) to a cloud LLM will transmit that query outside your machine; the skill's docs imply combining context but the scripts do not automatically read local notes or secrets.

Install Mechanism

No install spec is provided (instruction-only skill with two small scripts). Nothing in the skill downloads or executes remote code during installation. The files are plain scripts that run locally — low install risk.

Credentials

No environment variables or credentials are required by the skill itself (and none are declared). But the runtime actually requires external tools (qmd, node, jq) which are not declared in the registry metadata. There's no evidence the skill asks for unrelated secrets or credentials, but the missing dependency declarations are a proportionality/documentation issue you should correct before trusting the skill.

Persistence & Privilege

The skill is not always-enabled and is user-invocable; it does not request elevated platform privileges or modify other skills. It only adds optional wrapper scripts and a prompt generator; these are local and do not persist credentials or alter global settings.

What to consider before installing

What to check before installing: 1) Dependencies: install and verify qmd (npm @tobilu/qmd), node, and jq are present — the registry metadata omitted these but SKILL.md and the scripts require them. 2) Privacy: the tool prints an LLM prompt you must send to an LLM (or provide LLM output using --response). If you use a cloud LLM, your query (and any context you add) will be transmitted off-host — avoid sending sensitive notes. Prefer an on-prem/local LLM if privacy is a concern. 3) Behavior: the scripts do not automatically read your notes or secrets; they only generate prompts and call qmd with the provided JSON response. If you expected the wrapper to gather local context for the LLM automatically, note that it does not. 4) Quick tests: run node scripts/expand-query.js 'test' to inspect the prompt only; run qmd-query-llm.sh in prompt mode to see what you would send to an LLM; only use the execute (--response) mode with responses you control. 5) Metadata correction: ask the publisher to update the skill metadata to list required binaries and any other runtime requirements. These issues look like sloppy metadata rather than malicious intent, but they affect trust and privacy — proceed only after you understand and accept the exposure risk of sending prompts to your chosen LLM.

QMD - Quick Markdown Search

Local search engine for markdown content.

Status

!qmd status 2>/dev/null || echo "Not installed: npm install -g @tobilu/qmd"

MCP: query

{
  "searches": [
    { "type": "lex", "query": "CAP theorem consistency" },
    { "type": "vec", "query": "tradeoff between consistency and availability" }
  ],
  "collections": ["docs"],
  "limit": 10
}

Query Types

Type	Method	Input
lex	BM25	Keywords — exact terms, names, code
vec	Vector	Question — natural language
hyde	Vector	Answer — hypothetical result (50-100 words)

Writing Good Queries

lex (keyword)

• 2-5 terms, no filler words
• Exact phrase: "connection pool" (quoted)
• Exclude terms: performance -sports (minus prefix)
• Code identifiers work: handleError async

vec (semantic)

• Full natural language question
• Be specific: "how does the rate limiter handle burst traffic"
• Include context: "in the payment service, how are refunds processed"

hyde (hypothetical document)

• Write 50-100 words of what the answer looks like
• Use the vocabulary you expect in the result

expand (auto-expand)

• Use a single-line query (implicit) or expand: question on its own line
• Lets the local LLM generate lex/vec/hyde variations
• Do not mix expand: with other typed lines — it's either a standalone expand query or a full query document

Intent (Disambiguation)

When a query term is ambiguous, add intent to steer results:

{
  "searches": [
    { "type": "lex", "query": "performance" }
  ],
  "intent": "web page load times and Core Web Vitals"
}

Intent affects expansion, reranking, chunk selection, and snippet extraction. It does not search on its own — it's a steering signal that disambiguates queries like "performance" (web-perf vs team health vs fitness).

Combining Types

Goal	Approach
Know exact terms	lex only
Don't know vocabulary	Use a single-line query (implicit expand:) or vec
Best recall	lex + vec
Complex topic	lex + vec + hyde
Ambiguous query	Add intent to any combination above

First query gets 2x weight in fusion — put your best guess first.

Lex Query Syntax

Syntax	Meaning	Example
term	Prefix match	perf matches "performance"
"phrase"	Exact phrase	"rate limiter"
-term	Exclude	performance -sports

Note: -term only works in lex queries, not vec/hyde.

Collection Filtering

{ "collections": ["docs"] }              // Single
{ "collections": ["docs", "notes"] }     // Multiple (OR)

Omit to search all collections.

Other MCP Tools

Tool	Use
get	Retrieve doc by path or #docid
multi_get	Retrieve multiple by glob/list
status	Collections and health

CLI

qmd query "question"              # Auto-expand + rerank
qmd query $'lex: X\nvec: Y'       # Structured
qmd query $'expand: question'     # Explicit expand
qmd query --json --explain "q"    # Show score traces (RRF + rerank blend)
qmd search "keywords"             # BM25 only (no LLM)
qmd get "#abc123"                 # By docid
qmd multi-get "journals/2026-*.md" -l 40  # Batch pull snippets by glob
qmd multi-get notes/foo.md,notes/bar.md   # Comma-separated list, preserves order

HTTP API

curl -X POST http://localhost:8181/query \
  -H "Content-Type: application/json" \
  -d '{"searches": [{"type": "lex", "query": "test"}]}'

Setup

npm install -g @tobilu/qmd
qmd collection add ~/notes --name notes
qmd embed

---

🚀 LLM 查询扩展（QMD Plus）

使用外部 LLM 生成更高质量的查询变体，替代内置的 expand 功能。

为什么用 LLM 扩展？

内置 expand	LLM 扩展
lex 扩展质量不稳定	术语更准确
hyde 固定英文	可指定语言
无法利用上下文	可结合笔记内容
模板化生成	智能语义理解

快速使用

假设 skill 安装在 ~/workspace/skills/qmd_plus/：

# 方式 1：wrapper 脚本生成提示词
~/workspace/skills/qmd_plus/scripts/qmd-query-llm.sh "汽车测试流程" -c memory-root-main -l zh

# 方式 2：wrapper 脚本执行（传入 LLM 响应）
~/workspace/skills/qmd_plus/scripts/qmd-query-llm.sh --response '{"lex":[...],"vec":[...]}' -c memory-root-main

# 方式 3：手动扩展 + 搜索
node ~/workspace/skills/qmd_plus/scripts/expand-query.js "汽车测试流程" zh
# → 复制 LLM 输出的 lex/vec → 构造 qmd query

添加到 PATH（可选）

# 在 ~/.zshrc 或 ~/.bashrc 中添加：
export PATH="$HOME/workspace/skills/qmd_plus/scripts:$PATH"

# 然后可以直接使用：
qmd-query-llm "汽车测试流程" -c memory-root-main -l zh

qmd-query-llm 命令

自动完成：LLM 扩展 → 构造查询 → 执行搜索 → 返回结果

# 生成 LLM 提示词（Mode 1）
qmd-query-llm "汽车测试流程" -c memory-root-main -l zh

# 执行搜索（Mode 2，传入 LLM JSON 响应）
qmd-query-llm --response '{"lex":["汽车测试","整车试验"],"vec":["测试流程是什么"]}' -c memory-root-main

# 显示评分详情
qmd-query-llm --response '<json>' -c memory-root-main --explain

脚本直接使用

# 生成 LLM 提示词
node expand-query.js "汽车测试流程" zh

# 输出示例：
# 你是一个专业的知识库搜索查询优化器...
# （将上述提示词发送给 LLM，获取 JSON 响应）

LLM 响应格式

{
  "lex": ["汽车测试", "整车试验", "VTS 验证"],
  "vec": ["汽车测试流程是什么样的", "整车试验包括哪些步骤"]
}

构造 qmd 查询

# 将 LLM 响应转换为 qmd query 格式
qmd query $'lex: 汽车测试\nlex: 整车试验\nvec: 汽车测试流程是什么样的' -c memory-root-main

代码示例

#!/bin/bash
# qmd-query-llm wrapper

QUERY="$1"
COLLECTION="${2:-.openclaw}"
LANG="${3:-auto}"

# Step 1: Generate LLM prompt
PROMPT=$(node scripts/expand-query.js "$QUERY" "$LANG")

# Step 2: Call LLM (implement according to your LLM provider)
RESPONSE=$(your-llm-cli "$PROMPT")

# Step 3: Parse and execute qmd query
LEX=$(echo "$RESPONSE" | jq -r '.lex[]' | sed 's/^/lex: /')
VEC=$(echo "$RESPONSE" | jq -r '.vec[]' | sed 's/^/vec: /')

qmd query "$(echo -e "$LEX\n$VEC")" -c "$COLLECTION"

最佳实践

1. 中文笔记用中文扩展 — 避免跨语言损失
2. 术语用 lex，概念用 vec — 组合使用效果最好
3. 指定 collection — 缩小搜索范围提高准确度
4. --explain 调试 — 查看哪个变体匹配到了结果