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 編程助手才更容易按專案規則做事。