qmd：给 AI Agent 使用的本地 Markdown 文档搜索工具

Fri, 01 May 2026 03:12:57 +0800

qmd 是一个面向本地 Markdown 文档的搜索工具，重点服务对象是 AI Agent。

它解决的问题很具体：当你的项目里有大量 .md 文档时，AI 编程助手经常不知道该读哪一份、该引用哪一段、哪些说明才是最新的。靠全文 grep 可以找到关键词，但很难理解语义；直接把整套文档塞进上下文，又浪费窗口，还容易混入无关内容。

qmd 的思路是先为 Markdown 文档建立索引，再通过搜索接口把最相关的片段交给 AI 使用。它既可以作为命令行工具使用，也可以通过 SDK 集成，还可以作为 MCP Server 接入支持 MCP 的客户端。

它解决什么问题

真实项目里的文档通常不是一两篇 README。

你可能会有：

架构说明
API 文档
开发规范
部署流程
设计决策记录
故障排查笔记
需求文档
AI 使用说明
各种工具链备忘录

人类查文档时可以顺着目录慢慢看，但 AI Agent 更需要一个明确的检索入口。否则它可能会：

读错文档
漏掉关键约束
使用过时说明
把不相关内容塞进上下文
在回答里凭经验补全不存在的规则

qmd 的价值就在这里：它把本地 Markdown 文档变成可检索的知识源，让 AI 在需要上下文时先搜索，再基于匹配片段回答或执行任务。

搜索方式有什么特点

README 中提到，qmd 使用了多种检索方式组合：

BM25 关键词搜索
向量搜索
LLM reranking

BM25 适合处理明确关键词。比如你搜索某个函数名、配置项、错误码、文件名，它通常很直接。

向量搜索更适合语义问题。比如你问“这个项目怎么处理权限校验”，文档里未必正好写了“权限校验”四个字，但可能有相关的认证、访问控制、角色判断说明。

LLM reranking 则用于重新排序候选结果。前两步先把可能相关的内容找出来，再让模型判断哪些片段更符合当前问题。

这种组合比单纯关键词搜索更适合 AI Agent。因为 Agent 的问题往往不是固定关键词，而是任务意图。

为什么是 Markdown

Markdown 是开发项目里最常见的文档格式。

它足够简单，可以放进 Git；也足够结构化，有标题、列表、代码块、链接和表格。对 AI 来说，Markdown 也比 PDF、网页快照或截图更容易解析。

qmd 专注 Markdown，意味着它可以围绕开发文档做更直接的处理：

按标题和段落切分内容
保留代码块
保留文档路径
返回适合引用的片段
让 Agent 知道答案来自哪份文档

这比让 AI 随机扫描仓库更稳，也比把所有文档一次性塞进 prompt 更省上下文。

三种使用入口

qmd 提供 CLI、SDK 和 MCP Server 三种入口。

1. CLI

CLI 适合直接在终端里使用，也适合放进脚本。

你可以把文档目录索引起来，然后用命令搜索相关内容。对开发者来说，CLI 是最容易验证效果的入口：先看它能不能搜到正确文档，再考虑接入更复杂的工作流。

这类工具放在本地项目里很有用。比如你可以在改代码前先搜索设计文档，在排错前先查故障笔记，在写接口时先查 API 约定。

2. SDK

SDK 适合把 qmd 接入自己的工具。

如果你正在做内部开发助手、文档问答系统、代码审查机器人或项目知识库，可以通过 SDK 调用搜索能力，而不是让用户直接敲命令。

SDK 的好处是可以更自由地控制：

搜索目录
查询内容
返回数量
结果格式
后续是否交给模型总结

这适合需要深度集成的场景。

3. MCP Server

MCP 是 qmd 对 AI Agent 最有价值的入口。

通过 MCP Server，支持 MCP 的客户端可以把 qmd 当作一个文档搜索工具来调用。这样 Agent 在执行任务时，不必猜项目规则，而是可以先检索本地 Markdown 文档。

典型流程可以是：

用户要求 AI 修改某个功能
AI 先调用 qmd 搜索相关设计文档
qmd 返回最相关的 Markdown 片段
AI 基于文档约束再修改代码

这比“开新会话时手动把所有规则贴进去”更自然，也更适合长期项目。

适合什么场景

qmd 适合这些场景：

项目里有大量 Markdown 文档
AI Agent 经常需要查项目规则
团队希望 AI 回答时引用本地文档
文档分散在多个目录里
需要在 CLI、SDK、MCP 之间复用同一套检索能力
想减少 AI 编程助手凭空猜测项目约定
想把本地知识库接入 Claude Desktop、Claude Code 或其他 MCP 客户端

如果你的项目只有一份很短的 README，直接让 AI 读取文件就够了。

但如果文档已经增长到几十篇、几百篇，或者你希望 Agent 每次先查文档再行动，这类索引工具就有意义。

和 grep 有什么区别

grep、rg 这类工具非常适合精确搜索。

比如你知道要找 DATABASE_URL、authMiddleware、404、docker compose，直接搜关键词通常最快。

qmd 更适合你不知道精确词的情况。

例如你想问：

这个项目的发布流程是什么
新增 API 时要遵守哪些规范
之前有没有记录过缓存策略
AI 修改代码前应该读哪些文档
某个模块的设计背景在哪里

这些问题往往需要语义检索，而不是只匹配一个词。qmd 的 BM25 + 向量 + reranking 组合，就是为了让这类问题更容易找到正确上下文。

和 RAG 有什么关系

qmd 可以看作一个面向 Markdown 文档的轻量 RAG 组件。

它不试图替你完成整套问答系统，而是专注在“把相关文档片段找出来”这一步。至于后续怎么使用这些片段，可以交给 CLI、SDK、MCP 客户端或你自己的 Agent 流程。

这种定位比较实用。很多项目并不需要一个庞大的知识库系统，只需要让 AI 在本地文档里查得准一点、快一点，并且能把结果带回当前任务。

使用时要注意

第一，文档质量仍然重要。

检索工具只能帮你找到已有内容。如果文档本身过时、重复、互相矛盾，AI 仍然可能拿到错误上下文。把 qmd 接入 Agent 之前，最好先清理关键文档。

第二，索引范围不要过宽。

把整个仓库所有 Markdown 都塞进去不一定更好。比如依赖包文档、临时记录、旧方案草稿可能会污染结果。更好的做法是明确哪些目录是可信文档源。

第三，搜索结果需要保留来源。

AI 使用文档片段时，最好知道它来自哪份文件、哪个章节。这样人类复核时才能追溯，也能减少“看起来像文档结论，其实只是模型总结”的问题。

第四，不要完全替代人工判断。

qmd 能提高上下文召回质量，但它不是项目真理源的替代品。重要变更仍然要看当前代码、测试结果和最新需求。

适合怎样的团队

如果你的团队已经开始把 AI Agent 放进日常开发流程，qmd 这类工具会很有价值。

尤其是下面几种团队：

文档写得比较多
项目历史比较长
新人和 AI 都需要快速理解背景
经常维护架构决策记录
有大量 Markdown 规范文档
希望 AI 修改代码前先查规则

它的目标不是让 AI “全知全能”，而是让 AI 少猜一点，多查一点。

参考

tobi/qmd

最后一句

qmd 的价值，是把本地 Markdown 文档变成 AI Agent 能稳定调用的搜索入口。

当项目文档从“给人看的说明”变成“给人和 AI 都能检索的上下文源”，AI 编程助手才更容易按项目规则做事。

文档检索 on KnightLi的博客