核心用法
qmd 是一款专为 Markdown 笔记和文档设计的本地搜索引擎，采用"索引一次，极速搜索"的设计理念。用户通过 qmd collection add 将笔记目录加入集合，执行一次性 qmd embed 启用向量检索后，即可通过三种模式灵活查询：
- `qmd search`（默认推荐）：基于 BM25 的关键词检索，毫秒级响应，适合日常使用
- `qmd vsearch`：语义相似度搜索，依赖本地 LLM 进行查询扩展，冷启动可能耗时约1分钟
- `qmd query`：混合检索+LLM 重排序，结果质量最高但速度最慢，可能超时
支持按集合过滤、阈值筛选、JSON/文件列表等机器友好格式输出，以及 qmd get 单文档获取和 qmd multi-get 批量检索功能。
显著优点
1. 完全本地化：所有索引和模型均运行在本地，无需网络连接，数据隐私零风险
2. 速度分层设计：BM25 即时响应满足高频查询，向量检索兜底语义理解需求
3. 智能分块策略：基于内容而非严格标题结构分块，对" messy Markdown"包容性强
4. 自动化维护：支持 qmd update 增量更新和 cron 定时任务，保持索引新鲜
5. 零配置模型管理：首次运行自动下载 GGUF 格式本地模型，缓存于 ~/.cache/qmd/
潜在缺点与局限性
- 冷启动性能问题：
vsearch和query模式每次可能重新加载 Qwen3-1.7B 等本地模型，导致1分钟级延迟，不适合交互式高频使用 - 非代码搜索工具：明确不适用于源代码仓库检索，专为笔记文档设计
- 依赖 Bun 运行时：需安装 Bun >= 1.0.0 和 SQLite 扩展，对 macOS/Linux 环境有前置要求
- 语义检索维护成本：如需保持向量索引最新，需定期运行较慢的
qmd embed - 无 Windows 支持：metadata 显示仅支持 darwin/linux 平台
适合的目标群体
- 知识管理重度用户：Obsidian、Logseq、Notion 导出 Markdown 等本地笔记库维护者
- 开发者/技术写作者：需要快速检索技术文档、RFC、ADR 等 Markdown 格式资料
- 隐私敏感场景：法律、医疗、金融等领域禁止数据上云的知识检索需求
- 离线工作者：经常处于无网络环境但需要高效信息检索的用户
常规使用风险
1. 上游二进制安全风险：Skill 本身为纯 Markdown 文档，但实际依赖 bun install -g 安装的 qmd 二进制程序。建议审查 https://github.com/tobi/qmd 源代码并固定版本
2. 敏感数据索引泄露：自动索引可能意外包含含密码、密钥、PII 的 Markdown 文件，需严格控制 --mask 路径范围
3. 定时任务资源占用：cron 示例中的 qmd embed 夜间任务可能消耗显著 CPU/GPU 资源，需评估机器负载
4. 模型缓存膨胀：自动下载的 GGUF 模型可能占用数 GB 磁盘空间，需关注 ~/.cache/qmd/ 增长
5. 个人维护风险：项目为 T3 来源（tobi 个人开发者），长期维护持续性需自行评估