better-dsh 0.2.5 → 0.3.0-c

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/i18n/zh-Hans/user-guide/skills/optional/research/research-qmd.md

@@ -1,435 +0,0 @@
----
-title: "Qmd"
-sidebar_label: "Qmd"
-description: "使用 qmd 在本地搜索个人知识库、笔记、文档和会议记录 — 一个集成 BM25、向量搜索和 LLM 重排序的混合检索引擎"
----
-
-{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}
-
-# Qmd
-
-使用 qmd 在本地搜索个人知识库、笔记、文档和会议记录 — 一个集成 BM25、向量搜索和 LLM 重排序的混合检索引擎。支持 CLI 和 MCP 集成。
-
-## Skill 元数据
-
-| | |
-|---|---|
-| 来源 | 可选 — 通过 `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` |
-| 相关 skill | [`obsidian`](/user-guide/skills/bundled/note-taking/note-taking-obsidian), [`hermes-agent`](/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-hermes-agent), [`arxiv`](/user-guide/skills/bundled/research/research-arxiv) |
-
-## 参考：完整 SKILL.md
-
-:::info
-以下是 Hermes 在触发此 skill 时加载的完整 skill 定义。这是 agent 在 skill 激活时所看到的指令内容。
-:::
-
-# 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（必需）
-
-```bash
-# 检查版本
-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 安装：
-
-```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 | 向量 embedding（嵌入） | ~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` | 生成/更新向量 embedding | 不定 |
-| `qmd status` | 显示索引健康状态和集合信息 | 即时 |
-| `qmd mcp` | 启动 MCP 服务器（stdio） | 持久运行 |
-| `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. 生成 Embedding
-
-```bash
-qmd embed
-```
-
-此命令处理所有集合中的所有文档并生成向量 embedding。添加新文档或集合后需重新运行。
-
-### 4. 验证
-
-```bash
-qmd status   # shows index health, collection stats, model info
-```
-
-## 搜索模式
-
-### 快速关键词搜索（BM25）
-
-适用场景：精确词语、代码标识符、名称、已知短语。
-无需加载模型 — 近乎即时返回结果。
-
-```bash
-qmd search "authentication middleware"
-qmd search "handleError async"
-```
-
-### 语义向量搜索
-
-适用场景：自然语言问题、概念性查询。
-首次查询时加载 embedding 模型（约 3s）。
-
-```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（假设文档 Embedding）
-
-对于复杂主题，可描述你期望答案的样子：
-
-```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 无需每次加载此 skill 即可自动获得 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`。
-
-**权衡：** 模型在首次搜索调用时加载（冷启动约 19s），之后在会话期间保持热启动状态。偶尔使用时可接受。
-
-### 方案 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-3s）。适合频繁搜索的用户。
-
-### 保持 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 用户服务）
-
-```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 融合** — 倒数排名融合（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 个 token，重叠率 15%。代码块不会在中间被截断。
-
-## 最佳实践
-
-1. **始终添加上下文描述** — `qmd context add` 可显著提升检索准确性。描述每个集合包含的内容。
-2. **添加文档后重新 embed** — 向集合添加新文件后必须重新运行 `qmd embed`。
-3. **速度优先用 `qmd search`** — 需要快速关键词查找（代码标识符、精确名称）时，BM25 即时响应且无需模型。
-4. **质量优先用 `qmd query`** — 问题具有概念性或用户需要最佳结果时，使用混合搜索。
-5. **优先使用 MCP 集成** — 配置完成后，agent 无需每次加载此 skill 即可获得原生工具。
-6. **频繁用户使用 daemon 模式** — 如果用户经常搜索知识库，建议设置 HTTP daemon。
-7. **结构化搜索中第一个查询获得 2 倍权重** — 组合 lex 和 vec 时，将最重要/最确定的查询放在首位。
-
-## 故障排查
-
-### "首次运行时模型正在下载"
-正常现象 — qmd 首次使用时会自动下载约 2GB 的 GGUF 模型。
-这是一次性操作。
-
-### 冷启动延迟（约 19s）
-模型未加载到内存时会出现此情况。解决方案：
-- 使用 HTTP daemon 模式（`qmd mcp --http --daemon`）保持热启动
-- 不需要模型时使用 `qmd search`（仅 BM25）
-- MCP stdio 模式在首次搜索时加载模型，会话期间保持热启动
-
-### macOS："unable to load extension"
-安装 Homebrew SQLite：`brew install sqlite`
-然后确保其在系统 SQLite 之前出现在 PATH 中。
-
-### "未找到集合"
-运行 `qmd collection add <path> --name <name>` 添加目录，
-然后运行 `qmd embed` 进行索引。
-
-### Embedding 模型覆盖（CJK/多语言）
-为非英语内容设置 `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)