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 少猜一点，多查一点。
参考
最后一句
qmd 的价值，是把本地 Markdown 文档变成 AI Agent 能稳定调用的搜索入口。
当项目文档从“给人看的说明”变成“给人和 AI 都能检索的上下文源”，AI 编程助手才更容易按项目规则做事。