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的博客