@wei840222/qmd 2026.8.23 → 2026.8.28

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wei840222/qmd",
-  "version": "2026.8.23",
+  "version": "2026.8.28",
   "packageManager": "pnpm@11.15.1",
   "description": "Query Markup Documents - On-device hybrid search for markdown files with BM25, vector search, and LLM reranking",
   "type": "module",
@@ -34,17 +34,15 @@
     "lint": "oxlint",
     "test": "node scripts/test-all.mjs",
     "test:types": "node ./node_modules/typescript/bin/tsc -p tsconfig.build.json --noEmit",
-    "test:node": "bun scripts/test-runtime.mjs node",
-    "test:bun": "bun scripts/test-runtime.mjs bun",
-    "test:models:node": "bun scripts/test-runtime.mjs node --models-only",
-    "test:models:bun": "bun scripts/test-runtime.mjs bun --models-only",
-    "test:unit": "CI=true node ./node_modules/vitest/vitest.mjs run --reporter=verbose --testTimeout 60000 test/ && CI=true bun test --timeout 60000 --preload ./src/test-preload.ts test/",
+    "test:models": "node scripts/test-runtime.mjs",
+    "test:models:only": "node scripts/test-runtime.mjs --models-only",
+    "test:unit": "CI=true node ./node_modules/vitest/vitest.mjs run --reporter=verbose --testTimeout 60000 test/",
     "test:quality": "node ./node_modules/vitest/vitest.mjs run --reporter=verbose test/eval-cjk.test.ts",
     "test:package": "node scripts/package-smoke.mjs",
     "smoke:package-grammars": "node scripts/check-package-grammars.mjs",
     "dict:sync": "node scripts/sync-zh-dict.mjs",
-    "measure:cjk": "bun scripts/measure-cjk.ts",
-    "inspector": "bunx @modelcontextprotocol/inspector tsx src/cli/qmd.ts mcp",
+    "measure:cjk": "tsx scripts/measure-cjk.ts",
+    "inspector": "npx @modelcontextprotocol/inspector tsx src/cli/qmd.ts mcp",
     "release": "./scripts/release.sh",
     "qmd": "tsx src/cli/qmd.ts",
     "index": "tsx src/cli/qmd.ts index",
@@ -52,7 +50,7 @@
     "search": "tsx src/cli/qmd.ts search",
     "vsearch": "tsx src/cli/qmd.ts vsearch",
     "rerank": "tsx src/cli/qmd.ts rerank",
-    "bench": "bun src/cli/qmd.ts bench"
+    "bench": "tsx src/cli/qmd.ts bench"
   },
   "publishConfig": {
     "access": "public"
@@ -67,7 +65,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/server": "2.0.0",
-    "@node-rs/jieba": "2.0.1",
+    "@node-rs/jieba": "2.0.2",
     "better-sqlite3": "^13.0.3",
     "fast-glob": "3.3.3",
     "node-llama-cpp": "3.20.0",
@@ -112,7 +110,7 @@
     "vite": "7.3.5"
   },
   "peerDependencies": {
-    "typescript": "^5.9.3"
+    "typescript": "^5.9.3 || ^6.0.0-0"
   },
   "engines": {
     "node": ">=22.0.0"
@@ -134,6 +132,6 @@
     "local-ai",
     "llm"
   ],
-  "author": "Tobi Lutke <tobi@lutke.com>",
+  "author": "Wan, Jiun Wei <wei840222@gmail.com>",
   "license": "MIT"
 }

package/scripts/check-package-grammars.mjs

@@ -24,6 +24,6 @@ for (const grammar of grammars) {
 }
 
 if (!ok) {
-  console.error("\nAST grammar package smoke check failed. Run `bun install` locally or repair a broken global install with the matching `bun add tree-sitter-...@<version>` command shown by `qmd status`.");
+  console.error("\nAST grammar package smoke check failed. Run `pnpm install` locally or repair a broken global install with the matching `pnpm add tree-sitter-...@<version>` command shown by `qmd status`.");
   process.exit(1);
 }

package/scripts/package-smoke.mjs

@@ -99,12 +99,6 @@ assertPath("THIRD_PARTY_NOTICES.md", "third-party notices");
 run("compiled CLI under Node", process.execPath, ["dist/cli/qmd.js", "--help"], { quiet: true });
 run("package wrapper", "sh", ["bin/qmd", "--help"], { quiet: true });
 
-if (process.env.QMD_SKIP_BUN_SMOKE === "1") {
-  console.log("==> compiled CLI under Bun (skipped by QMD_SKIP_BUN_SMOKE=1)");
-} else {
-  run("compiled CLI under Bun", "bun", ["dist/cli/qmd.js", "--help"], { quiet: true });
-}
-
 const packageSmokeRoot = process.env.QMD_PACKAGE_SMOKE_TMPDIR || join(root, ".tmp");
 mkdirSync(packageSmokeRoot, { recursive: true });
 const packageSmokeDir = mkdtempSync(join(packageSmokeRoot, "qmd-package-smoke-"));
@@ -129,9 +123,9 @@ try {
     `${JSON.stringify({ private: true, type: "module" }, null, 2)}\n`,
   );
   run(
-    "install packed tarball with Bun",
-    "bun",
-    ["add", "--ignore-scripts", join(packageSmokeDir, tarballName)],
+    "install packed tarball with npm",
+    "npm",
+    ["install", "--ignore-scripts", "--no-package-lock", join(packageSmokeDir, tarballName)],
     { cwd: consumerDir, quiet: true },
   );
 
@@ -179,14 +173,6 @@ try {
     ["--input-type=module", "--eval", jiebaSmoke],
     { cwd: consumerDir, env: smokeEnv, quiet: true },
   );
-  if (process.env.QMD_SKIP_BUN_SMOKE !== "1") {
-    run(
-      "packed jieba capability under Bun",
-      "bun",
-      ["--eval", jiebaSmoke],
-      { cwd: consumerDir, env: smokeEnv, quiet: true },
-    );
-  }
 } finally {
   rmSync(packageSmokeDir, { recursive: true, force: true });
 }

package/scripts/test-all.mjs

@@ -41,5 +41,4 @@ function run(label, command, args, options = {}) {
 
 run("TypeScript build typecheck", process.execPath, [join(root, "node_modules", "typescript", "bin", "tsc"), "-p", "tsconfig.build.json", "--noEmit"]);
 run("Vitest suite under Node", process.execPath, [join(root, "node_modules", "vitest", "vitest.mjs"), "run", "--reporter=verbose", "--testTimeout", "60000", "test/"], { env: { CI: "true" } });
-run("Bun test suite", "bun", ["test", "--timeout", "60000", "--preload", "./src/test-preload.ts", "test/"], { env: { CI: "true" } });
 run("Package smoke", process.execPath, ["scripts/package-smoke.mjs"]);

package/skills/qmd/SKILL.md

@@ -4,8 +4,8 @@ description: Search local markdown knowledge bases, notes, docs, and wikis with
 license: MIT
 compatibility: Requires qmd CLI or MCP server. Install via `npm install -g @wei840222/qmd`.
 metadata:
-  author: tobi
-  version: "2.6.3"
+  author: wei840222
+  version: 2026.8.23-1
 allowed-tools: Bash(qmd:*), mcp__qmd__*
 ---
 
@@ -209,8 +209,14 @@ When using the MCP server, prefer structured searches:
 {
   "searches": [
     { "type": "lex", "query": "cockpit OKR Goodhart" },
-    { "type": "vec", "query": "data informed not metric driven product judgment" },
-    { "type": "hyde", "query": "A concept note explains that metrics are useful as instruments, but leaders should not let OKRs or dashboards replace judgment." }
+    {
+      "type": "vec",
+      "query": "data informed not metric driven product judgment"
+    },
+    {
+      "type": "hyde",
+      "query": "A concept note explains that metrics are useful as instruments, but leaders should not let OKRs or dashboards replace judgment."
+    }
   ],
   "intent": "Find the concept note about using metrics as instruments without becoming metric-driven.",
   "collections": ["concepts"],
@@ -224,6 +230,8 @@ Query types:
 - `vec` — vector semantic search. Best for natural-language concepts.
 - `hyde` — vector search using a hypothetical answer/document passage.
 
+When invoking `query` with a plain `query` string instead of explicit `searches`, you can set `includeHyde: false` (to omit HyDE passage generation) and `expansion: "auto" | "force" | "skip"`.
+
 ## Query craft
 
 Good QMD searches mix three things:
@@ -245,6 +253,8 @@ qmd query $'intent: Find the customer proximity concept, not generic customer de
 qmd search "six-week cadence WhatsApp merchant relationships Shawn Ryan" -c sources -n 10
 ```
 
+For the complete EBNF grammar, search operators, and JSON payload specifications, see [Query Syntax Reference](references/query-syntax.md).
+
 ## Setup and maintenance
 
 Only mutate indexes when the user asked for setup or maintenance. Searching and
@@ -264,17 +274,17 @@ Configure models and custom endpoints in `~/.config/qmd/index.yml` under the `mo
 ```yaml
 models:
   embed: hf:Qwen/Qwen3-Embedding-0.6B-GGUF/Qwen3-Embedding-0.6B-Q8_0.gguf
-  embed_api_url: https://api.example.com/v1   # Both embed_api_url and embed_api_model enable remote embeddings
-  embed_api_model: text-embedding-3-small     # or text-embedding-3-large
-  embed_dimension: 1536                       # Optional: expected vector dimension; validates local output
+  embed_api_url: https://api.example.com/v1 # Both embed_api_url and embed_api_model enable remote embeddings
+  embed_api_model: text-embedding-3-small # or text-embedding-3-large
+  embed_dimension: 1536 # Optional: expected vector dimension; validates local output
 
   # Optional: Remote LLM Query Expansion (aliases: generate_url, generate_base_url, generate_api_url)
-  generate_api_url: https://api.example.com/v1    # Base URL (appends /chat/completions) or full endpoint
-  generate_api_model: qwen3-7b-instruct           # or your-model-name
+  generate_api_url: https://api.example.com/v1 # Base URL (appends /chat/completions) or full endpoint
+  generate_api_model: qwen3-7b-instruct # or your-model-name
 
   # Optional: Remote Reranking (supports rerank_url / rerank_base_url / rerank_api_url)
   rerank_api_url: https://api.example.com/v1/chat/completions # Supports both /v1/rerank and /v1/chat/completions LLM endpoints
-  rerank_api_model: bge-reranker-v2-m3        # or gpt-4o-mini / qwen3-7b-instruct
+  rerank_api_model: bge-reranker-v2-m3 # or gpt-4o-mini / qwen3-7b-instruct
 
 # Optional: Custom User Dictionary for CJK segmentation
 dictionary: ~/.config/qmd/dictionary.txt

package/skills/qmd/references/mcp-setup.md

@@ -10,30 +10,14 @@ qmd embed
 
 ## Configure MCP Client
 
-**Claude Code** (`~/.claude/settings.json`):
-```json
-{
-  "mcpServers": {
-    "qmd": { "command": "qmd", "args": ["mcp"] }
-  }
-}
-```
+Add QMD to your MCP client configuration (e.g. Cursor, Claude Desktop, Zed, OpenClaw, or other MCP-compatible clients):
 
-**Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`):
 ```json
 {
   "mcpServers": {
-    "qmd": { "command": "qmd", "args": ["mcp"] }
-  }
-}
-```
-
-**OpenClaw** (`~/.openclaw/openclaw.json`):
-```json
-{
-  "mcp": {
-    "servers": {
-      "qmd": { "command": "qmd", "args": ["mcp"] }
+    "qmd": {
+      "command": "qmd",
+      "args": ["mcp"]
     }
   }
 }

package/skills/qmd/references/query-syntax.md

@@ -0,0 +1,165 @@
+# QMD Query Syntax Reference
+
+QMD queries are structured documents composed of typed sub-queries. Each line specifies a search type and query text. The hybrid retrieval engine combines results via Reciprocal Rank Fusion (RRF) and reranks them.
+
+## Grammar
+
+```ebnf
+query          = policy_query | query_document ;
+policy_query   = [ policy_prefix ] text ;
+policy_prefix  = "lex:" | "expand:" ;
+query_document = [ intent_line ] { typed_line } ;
+intent_line    = "intent:" text newline ;
+typed_line     = type ":" text newline ;
+type           = "lex" | "vec" | "hyde" ;
+text           = quoted_phrase | plain_text ;
+quoted_phrase  = '"' { character } '"' ;
+plain_text     = { character } ;
+newline        = "\n" ;
+```
+
+## Query Types
+
+| Type | Method | Best For | Description |
+|------|--------|----------|-------------|
+| `lex` | BM25 (FTS5) | Exact terms, identifiers, code, titles | Keyword search with prefix, phrase, and negation support |
+| `vec` | Vector | Natural language concepts | Semantic similarity search using local/remote embeddings |
+| `hyde` | Vector | Complex conceptual questions | Hypothetical Document Embedding (generate expected passage) |
+
+## Default Policy & Expansion Behavior
+
+A query is either a single policy query or a multi-line query document:
+- **`auto` (Default)**: CJK queries and strong lexical matches automatically bypass model expansion. Other plain queries expand into `lex`, `vec`, and `hyde` variants.
+- **`--no-hyde`**: Disables HyDE (hypothetical document) in query expansion, generating only `lex` and `vec` variants (faster, avoids hallucinated passage drift).
+- **`expand:` / `--expand` (`force`)**: Explicitly forces expansion even if bypass heuristics apply.
+- **`lex:` (`skip`)**: Explicitly disables expansion and performs direct BM25 search.
+
+```bash
+# Automatic policy:
+qmd query "how does authentication work"
+
+# Disable HyDE during expansion:
+qmd query --no-hyde "how does authentication work"
+
+# Force expansion:
+qmd query "expand: how does authentication work"
+# or: qmd query --expand "資料庫同步"
+
+# Explicitly skip expansion:
+qmd query "lex: authentication"
+```
+
+## Lexical Search Syntax (`lex:`)
+
+Lex queries support powerful search operators:
+
+| Syntax | Meaning | Example | Notes |
+|--------|---------|---------|-------|
+| `word` | Prefix match | `perf` | Matches "performance", "perform", etc. |
+| `"phrase"` | Exact phrase match | `"rate limiter"` | Terms must appear consecutively in order |
+| `-word` | Exclude term | `-sports` | Documents containing this word are excluded |
+| `-"phrase"` | Exclude phrase | `-"test data"` | Documents containing this phrase are excluded |
+
+### Examples
+
+```
+lex: CAP theorem consistency
+lex: "machine learning" -"deep learning"
+lex: auth -oauth -saml
+```
+
+## Vector Search Syntax (`vec:`)
+
+Natural language questions or descriptive phrases:
+
+```
+vec: how does the rate limiter handle burst traffic
+vec: what is the tradeoff between consistency and availability
+```
+
+## Hypothetical Document Embeddings (`hyde:`)
+
+A 50–100 word hypothetical answer passage representing what the target document likely says:
+
+```
+hyde: The rate limiter uses a sliding window counter algorithm with a 60-second window. When a client exceeds 100 requests per minute, subsequent requests return 429 Too Many Requests.
+```
+
+When relying on query expansion, HyDE generation can be excluded using `--no-hyde` (CLI) or `"includeHyde": false` (MCP/SDK).
+
+## Multi-Line Structured Queries
+
+Combine multiple sub-query types for optimal retrieval. The first sub-query receives **2x weight** during Reciprocal Rank Fusion:
+
+```
+lex: rate limiter algorithm
+vec: how does rate limiting work in the API
+hyde: The API implements rate limiting using a token bucket algorithm...
+```
+
+## Disambiguating with `intent:`
+
+An optional `intent:` line provides background context to disambiguate ambiguous queries. It steers query expansion, reranking, and snippet selection without generating search vectors itself:
+
+- At most one `intent:` line per query document.
+- Must be combined with at least one `lex:`, `vec:`, or `hyde:` line.
+- Can also be passed via the `--intent` CLI flag or MCP `intent` parameter.
+
+```
+intent: web page load times and Core Web Vitals
+lex: performance
+vec: how to improve performance
+```
+
+## Collection Scoping
+
+Scope search to specific collections using `-c` (CLI) or `collections` (MCP/SDK):
+
+```bash
+# CLI:
+qmd query -c docs "how does auth work"
+qmd query -c docs -c notes $'lex: auth\nvec: authentication flow'
+```
+
+## MCP Tool Call Payloads
+
+When calling the `qmd` MCP server's `query` tool, provide a structured `searches` array:
+
+### Standard Multi-Modal Query
+
+```json
+{
+  "searches": [
+    { "type": "lex", "query": "CAP theorem" },
+    { "type": "vec", "query": "consistency vs availability tradeoffs in distributed storage" }
+  ],
+  "collections": ["docs"],
+  "limit": 10
+}
+```
+
+### Query with Disambiguating Intent
+
+```json
+{
+  "searches": [
+    { "type": "lex", "query": "performance metrics" },
+    { "type": "vec", "query": "page load and network latency optimization" }
+  ],
+  "intent": "Front-end web performance and Core Web Vitals optimization",
+  "collections": ["frontend", "notes"],
+  "limit": 5
+}
+```
+
+### Plain Query with Policy Control & Explain Trace
+
+```json
+{
+  "query": "authentication flow",
+  "expansion": "auto",
+  "includeHyde": false,
+  "explain": true,
+  "collections": ["docs"]
+}
+```