QMD 本地笔记与文档检索

要解决的问题

Agent 在回答需要引用个人笔记、项目文档或会议记录时，常把大量无关文件塞进上下文，或者只能人工把资料复制到聊天窗口。这类资料散落在本地目录，格式和目录结构不统一，只靠文件名匹配容易漏掉语义相关但用词不同的片段。更麻烦的是，当 Agent 需要“只取相关上下文”时，现有检索结果要么只是路径列表，要么需要额外转换格式。

技能如何工作

这个技能围绕 QMD 建立索引和检索层。QMD 将三种检索信号组合起来：BM25 全文搜索负责关键词、编号和专有名词；向量语义搜索负责理解同义表述和跨文档的意图；LLM 重排序负责在候选集中调整顺序。三者都通过 node-llama-cpp 在本地运行，可选使用本地 GGUF 模型。技能的目标不是替你写文档，而是先把本地笔记、文档和会议记录索引起来，再根据查询返回排序后的文件或结构化 JSON，让 Agent 只拉取它真正需要的上下文。

流程上，需要先准备 Node.js 或 Bun 运行环境，以及要纳入检索的本地文档目录。如果要做语义搜索和重排序，还要准备本地 GGUF 模型。QMD 可作为库嵌入 Node.js 或 Bun 应用，SDK 要求显式传入 dbPath，不提供默认路径，这样集成时不会在后台悄悄写文件。查询阶段，QMD 先执行关键词与向量召回，再做 LLM 重排，最后输出适合程序消费的排序结果或 JSON。对 Agent 来说，这意味着它可以在上下文预算内选择少量高相关文件或片段，而不是盲目加载整个目录。

适用边界与注意点

这套方案适合数据已经在本地、文档目录相对可控、希望把检索嵌入 Agent 工作流的场景。它解决的是“找到上下文”，不负责自动同步网盘、抓取网页、转录音频或重写文档。索引质量取决于源文件是否可读、目录是否稳定、会议记录是否已经整理为文本；如果文档频繁更新，需要重新索引或确认索引策略。

LLM 重排序依赖本地模型能力和提示词设计，结果可能受模型大小与量化影响。BM25 对精确词项有效，但对高度口语化或多语言混合的会议记录可能不够稳；向量检索则可能受嵌入模型影响。因此，在生产中使用时应先对少量样例做评估，确认返回的排序文件或 JSON 是否满足 Agent 的上下文要求。