@baimingtao/lbs-agent 1.0.0

package/extensions/skills/optional/research/qmd/SKILL.md

@@ -0,0 +1,417 @@
+---
+name: qmd
+description: 使用 qmd 在本地搜索个人知识库、笔记、文档和会议记录 —— 这是一个结合了 BM25、向量搜索和 LLM 重排序的混合检索引擎。支持 CLI 和 MCP 集成。
+version: 1.0.0
+author: Hermes Agent + Teknium
+license: MIT
+platforms: [macos, linux]
+metadata:
+  hermes:
+    tags: [Search, Knowledge-Base, RAG, 说明, MCP, Local-AI]
+    related_skills: [obsidian, native-mcp, arxiv]
+---
+
+# QMD — Query Markup Documents
+
+本地、设备端个人知识库搜索引擎。它可以为 markdown 笔记、会议记录、文档以及任何基于文本的文件建立索引，然后提供结合了关键词匹配、语义理解和 LLM 驱动重排序的混合搜索 —— 所有这些都在本地运行，无需依赖云端。
+
+由 [Tobi Lütke](https://github.com/tobi/qmd) 创建。采用 MIT 许可协议。
+
+## 何时使用
+
+- 用户要求搜索他们的笔记、文档、知识库或会议记录
+- 用户希望在大量 markdown/文本文件中查找内容
+- 用户需要语义搜索（“查找关于 X 概念的笔记”），而不仅仅是关键词 grep
+- 用户已经设置了 qmd 集合并希望查询它们
+- 用户要求建立本地知识库或文档搜索系统
+- 关键词：“search my notes”、“find in my docs”、“knowledge base”、“qmd”
+
+## 前置条件
+
+### Node.js >= 22 (required)
+
+```bash
+# 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 with Extension Support (仅限 macOS)
+
+macOS 系统 SQLite 缺少扩展加载功能。通过 Homebrew 安装：
+
+```bash
+brew install sqlite
+```
+
+### 安装 qmd
+
+```bash
+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 |
+
+### 验证安装
+
+```bash
+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 服务器 | 持续运行 |
+| `qmd mcp --http --daemon` | 启动 MCP 服务器 (HTTP，保持模型热启动) | 持续运行 |
+
+## 配置工作流
+
+### 1. 添加集合
+
+将 qmd 指向包含您的文档的目录：
+
+```bash
+# 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. 添加上下文描述
+
+上下文元数据可帮助搜索引擎了解每个集合包含的内容。这能显著提高检索质量：
+
+```bash
+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. 生成嵌入
+
+```bash
+qmd embed
+```
+
+这将处理所有集合中的所有文档并生成向量嵌入。添加新文档或集合后需要重新运行此命令。
+
+### 4. 验证
+
+```bash
+qmd status   # shows index health, collection stats, model info
+```
+
+## 搜索模式
+
+### 快速关键词搜索 (BM25)
+
+适用场景：精确术语、代码标识符、名称、已知短语。
+不加载模型 —— 几乎瞬间返回结果。
+
+```bash
+qmd search "authentication middleware"
+qmd search "handleError async"
+```
+
+### 语义向量搜索
+
+适用场景：自然语言提问、概念查询。
+加载嵌入模型（首次查询约需 3 秒）。
+
+```bash
+qmd vsearch "how does the rate limiter handle burst traffic"
+qmd vsearch "ideas for improving onboarding flow"
+```
+
+### 带有重排序的混合搜索（质量最佳）
+
+适用场景：对质量要求极高的重要查询。
+使用全部 3 个模型 —— 查询扩展、并行 BM25+向量搜索、重排序。
+
+```bash
+qmd query "what decisions were made about the database migration"
+```
+
+### 结构化多模式查询
+
+在单个查询中组合不同的搜索类型以提高精准度：
+
+```bash
+# BM25 for exact term + vector for concept
+qmd query $'lex: rate limiter\nvec: how does throttling work under load'
+
+# With query expansion
+qmd query $'expand: database migration plan\nlex: "schema change"'
+```
+
+### 查询语法（lex/BM25 模式）
+
+| 语法 | 效果 | 示例 |
+|--------|--------|---------|
+| `term` | 前缀匹配 | `perf` 匹配 "performance" |
+| `"phrase"` | 精确短语 | `"rate limiter"` |
+| `-term` | 排除术语 | `performance -sports` |
+
+### HyDE (假设文档嵌入)
+
+对于复杂主题，写出您期望的答案形式：
+
+```bash
+qmd query $'hyde: 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
+```
+
+### 输出格式
+
+```bash
+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`：
+
+```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 Daemon 模式（快速，推荐用于重度使用）
+
+单独启动 qmd daemon —— 它会使模型在内存中保持热启动状态：
+
+```bash
+# Start daemon (persists across agent restarts)
+qmd mcp --http --daemon
+
+# Runs on http://localhost:8181 by default
+```
+
+然后配置 Hermes Agent 通过 HTTP 连接：
+
+```yaml
+mcp_servers:
+  qmd:
+    url: "http://localhost:8181/mcp"
+    timeout: 30
+```
+
+**权衡：** 运行时会占用约 2GB 内存，但每次查询都很快（约 2-3 秒）。最适合频繁搜索的用户。
+
+### 保持 Daemon 运行
+
+#### macOS (launchd)
+
+```bash
+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 user service)
+
+```bash
+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 查询以进行多模式搜索：
+
+```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. **查询扩展** — 微调过的 1.7B 模型会生成 2 个备选查询。原始查询在融合时将获得 2 倍的权重。
+2. **并行检索** — BM25 (SQLite FTS5) 和向量搜索会针对所有查询变体同时运行。
+3. **RRF 融合** — 倒数排名融合 (RRF, Reciprocal Rank Fusion) (k=60) 合并结果。排名加成：第 1 名获得 +0.05，第 2-3 名获得 +0.02。
+4. **LLM 重排序** — qwen3-reranker 对前 30 名候选结果进行评分 (0.0-1.0)。
+5. **位置感知混合** — 第 1-3 名：75% 检索 / 25% 重排序。第 4-10 名：60 / 40。第 11 名及以后：40 / 60（在长尾结果中更信任重排序器）。
+
+**智能分块：** 文档会在自然断点（标题、代码块、空行）处进行切分，目标大小约为 900 个 tokens，并带有 15% 的重叠。代码块绝不会在块中间被切分。
+
+## 最佳实践
+
+1. **务必添加上下文描述** — `qmd context add` 可以显著提高检索准确性。详细描述每个集合包含的内容。
+2. **添加文档后重新嵌入** — 当向集合添加新文件时，必须重新运行 `qmd embed`。
+3. **追求速度时使用 `qmd search`** — 当需要快速进行关键词查找（代码标识符、精确名称）时，BM25 是瞬间完成的，且不需要模型。
+4. **追求质量时使用 `qmd query`** — 当提问属于概念性的，或者用户需要尽可能好的结果时，请使用混合搜索。
+5. **首选 MCP 集成** — 配置完成后，Agent 将获得原生工具，而无需每次加载此技能。
+6. **频繁使用者建议开启 Daemon 模式** — 如果用户经常搜索其知识库，推荐使用 HTTP daemon 设置。
+7. **结构化搜索中的首个查询会获得 2 倍权重** — 在组合 lex 和 vec 时，请将最重要/最确定的查询放在首位。
+
+## 故障排查
+
+### "Models downloading on first run"
+正常现象 — qmd 在首次使用时会自动下载约 2GB 的 GGUF 模型。这是一次性操作。
+
+### 冷启动延迟（约 19 秒）
+当模型未加载到内存时会发生这种情况。解决方案：
+- 使用 HTTP daemon 模式 (`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` 对其进行索引。
+
+### 嵌入模型覆盖（中日韩/多语言）
+为非英语内容设置 `QMD_EMBED_MODEL` 环境变量：
+```bash
+export QMD_EMBED_MODEL="your-multilingual-model"
+```
+
+## 数据存储
+
+- **索引和向量:** `~/.cache/qmd/index.sqlite`
+- **模型:** 首次运行时自动下载到本地缓存
+- **无云端依赖** — 一切均在本地运行
+
+## 参考链接
+
+- [GitHub: tobi/qmd](https://github.com/tobi/qmd)
+- [QMD 更新日志](https://github.com/tobi/qmd/blob/main/CHANGELOG.md)