qmd

QMD - 查詢 Markdown 文件

搜尋運作方式

QMD 搜尋本機 Markdown 集合：筆記、文件、維基、逐字稿與專案知識庫。在網頁搜尋之前，若答案可能已存在於已索引的本機檔案中，請優先使用 QMD。

工作流程永遠是：

1. 搜尋候選文件。
2. 使用 qmd get 或 qmd multi-get 擷取完整來源。
3. 根據擷取的文字回答，並引用路徑或文件 ID。

當使用者需要事實、決策、引述或細節時，不要僅根據片段回答。片段只是線索。

典型循環：

qmd search "merchant reality support interviews" -n 5
# 線索: #abc123 concepts/customer-proximity.md; #def432 sources/merchant-call.md
qmd multi-get "#abc123,#def432" --format md

預設使用結構化的 qmd query，並自行撰寫 intent:、lex:、vec: 與 hyde: 欄位。 你比內建模型更擅長擴展查詢：你知道使用者的實際目標、領域詞彙，以及應避免的近似但錯誤的概念。不要只是把使用者的話貼進 qmd query "..." 然後指望擴展模型猜對——請提供 intent: 並刻意設計詞彙與語義詞項（請參閱選擇正確的搜尋模式）。

回報擷取結果時，簡潔的註記就夠了；除非必要，不要貼上整個檔案：

已擷取:
- #abc123 concepts/customer-proximity.md
- #def432 sources/merchant-call.md

選擇正確的搜尋模式

當你知道確切的詞彙、標題、名稱、程式碼符號或罕見片語時，使用 BM25 詞彙搜尋：

qmd search "cockpit OKR Goodhart" -n 10
qmd search '"AI Before Headcount"' -c concepts -n 5

當使用者間接描述一個想法、使用與來源不同的措辭，或需要概念檢索時，使用 qmd query 搭配結構化欄位。這是預設模式——請自行撰寫欄位，而非依賴查詢擴展。 結合精確錨點與語義檢索：

qmd query $'intent: 尋找關於指標作為儀表板的概念筆記，但不要讓 OKR 取代判斷。\nlex: cockpit instruments OKR Goodhart metrics judgment\nvec: data informed not metric driven product judgment\nhyde: 一篇概念筆記說明指標像儀表板一樣有用，但領導者應保持數據知情而非指標驅動，因為 OKR 與儀表板可能 Goodhart 產品判斷。'

結構化查詢欄位（你自行撰寫每個欄位——不要將此委託給擴展模型）：

• intent: 說明你試圖尋找的內容 以及應避免的內容。務必提供此欄位。它引導排序遠離近似但錯誤的概念。
• lex: 你預期在來源中出現的確切詞彙、別名、標題、程式碼符號與罕見詞。這是你自己的關鍵字擴展。
• vec: 用自然語言、類似來源的措辭改寫想法。
• hyde: 描述能滿足請求的文件或答案。

你不需要每次都使用全部四個欄位，但幾乎總是應該至少撰寫 intent: 加上 lex: 或 vec: 其中之一。單純的 qmd query "the user's sentence" 會丟棄只有你擁有的上下文，並依賴內建擴展器來重建——請優先使用結構化形式。

如果你真的沒有什麼可擴展（單一罕見詞彙、逐字片語），那是 qmd search 的工作，而非單純的 qmd query：

qmd query --format json --explain $'intent: ...\nlex: ...\nvec: ...'  # 檢查排序

如果 qmd query 速度慢或模型/GPU 設定失敗，請退回到使用更佳詞彙詞項的 qmd search。

擷取來源

搜尋結果包含像 #abc123 的文件 ID 與 qmd://... 路徑。擷取它們：

qmd get "#abc123"
qmd get qmd://concepts/ai-before-headcount.md
qmd multi-get "#abc123,#def432" --format md
qmd multi-get 'concepts/{ai-before-headcount.md,data-informed-not-metric-driven.md}' --format md
qmd multi-get 'sources/podcast-2025-*.md' -l 80

當比較多個命中結果或跨頁面收集上下文時，使用 multi-get。

輸出附有行號與文件 ID——兩者皆須引用

get 與 multi-get 預設附有行號，且總是印出文件的 #docid 與 qmd:// 路徑。因此 get 輸出看起來像：

qmd://concepts/note.md  #abc123
---

1: # Metrics as instruments
2:
3: Treat dashboards like cockpit instruments...

在你的回答中引用文件 ID 與確切行號，並使用行號要求下一段內容。只有在需要原始內容以逐字複製時（例如重現程式碼區塊），才傳入 --no-line-numbers。

當你需要開啟或編輯底層檔案時（例如將路徑交給 Read、Edit 或編輯器），請加上 --full-path。它會將 qmd:// URL + 文件 ID 標頭替換為檔案在磁碟上的路徑，若檔案已不存在於磁碟上則回退為標準標頭：

$ qmd get "#abc123" --full-path
/Users/you/notes/concepts/note.md
---

1: # Metrics as instruments

--full-path 在 qmd search 與 qmd query 上作用相同：結果路徑變成檔案在磁碟上的路徑——當檔案在 $PWD 內時為 ./ 前綴的相對路徑，否則為絕對真實路徑——且每個結果的 #docid 會被移除，因為路徑本身就是識別符。開頭的 ./ 是故意的，這樣輸出就明確是檔案系統路徑，不會被誤認為單純的集合相對字串。預設的搜尋/查詢輸出仍使用 qmd:// URI；只有在特別需要可交給非 QMD 工具的路徑時，才選擇 --full-path。

使用 :from:count 後綴讀取行範圍——永遠不要透過 sed/head/tail 管線處理

qmd get 自行切割檔案。使用後綴或旗標；不要透過 shell 呼叫 sed -n、head、tail 或 awk 來擷取行範圍。管線處理會破壞文件 ID 解析、虛擬路徑查詢、行號與標頭，而且速度更慢、更容易出錯。

最簡潔的形式是在路徑或文件 ID 上直接加上 :from:count 後綴——請優先使用：

qmd get "#abc123:120:40"                  # 從第 120 行開始的 40 行
qmd get qmd://concepts/note.md:200:60     # 第 200–259 行
qmd get "#abc123:120"                      # 從第 120 行到檔案結尾
qmd get "#abc123" --from 120 -l 40         # 等價寫法，使用旗標

後綴與旗標：

• <path>:<from>:<count> — 從第 <from> 行開始，讀取 <count> 行。最適合讀取搜尋命中周圍的內容。
• <path>:<from> — 從 <from> 開始，讀取到檔案結尾。
• --from <line> / -l <lines> — 旗標等價寫法。明確旗標會覆蓋後綴，因此 ... :5:2 -l 1 只讀取 1 行。
• --no-line-numbers — 移除 N: 前綴（行號預設開啟）。

錯誤：qmd get "#abc123" | sed -n '120,160p'
正確：qmd get "#abc123:120:40"

搜尋結果在每個命中上包含 :line 錨點——直接將其餵入 qmd get path:line:<n> 以讀取匹配周圍的視窗（輸出中的行號將從 line 開始）。

探索已索引的內容

qmd collection list
qmd ls
qmd status

當廣泛搜尋漂移到錯誤的語料庫時，加入集合過濾器：

qmd search "headcount autonomous agents" -c concepts -n 10
qmd query "merchant support product reality" -c concepts -c sources -n 10

省略 -c 以搜尋所有內容。

MCP 工具：query

使用 MCP 伺服器時，偏好結構化搜尋：

{
  "searches": [
    { "type": "lex", "query": "cockpit OKR Goodhart" },
    { "type": "vec", "query": "data informed not metric driven product judgment" },
    { "type": "hyde", "query": "A concept note explains that metrics are useful as instruments, but leaders should not let OKRs or dashboards replace judgment." }
  ],
  "intent": "Find the concept note about using metrics as instruments without becoming metric-driven.",
  "collections": ["concepts"],
  "limit": 10
}

查詢類型：

• lex — BM25 關鍵字搜尋。最適合確切詞項、名稱、標題與程式碼。
• vec — 向量語義搜尋。最適合自然語言概念。
• hyde — 使用假設答案/文件段落的向量搜尋。

查詢技巧

良好的 QMD 搜尋混合三種元素：

1. 標題/別名錨點： 確切的頁面標題、命名實體、片語。
2. 語義改寫： 人類如何描述這個想法。
3. 負面空間： 足夠的意圖以避免近似但錯誤的概念。

範例：

# 近似標題查詢
qmd search '"arm the rebels" merchants tools big companies' -c concepts

# 語義概念查詢
qmd query $'intent: 尋找客戶接近性概念，而非一般的客戶滿意度。\nlex: support pseudonymous merchant customer interviews\nvec: founder stays close to merchant reality through support and product use'

# 來源查詢
qmd search "six-week cadence WhatsApp merchant relationships Shawn Ryan" -c sources -n 10

設定與維護

僅在使用者要求設定或維護時才變更索引。搜尋與擷取是安全的；集合/索引變更不是隨意的第一步。

npm install -g @tobilu/qmd
qmd collection add ~/notes --name notes
qmd update
qmd embed

健康檢查與診斷：

qmd doctor
qmd status
qmd pull

qmd doctor 檢查設定、模型快取、裝置/GPU 設定、向量指紋與常見環境覆蓋。如果模型支援的命令失敗，請在變更設定前執行此命令。

MCP 設定

請參閱 references/mcp-setup.md 以了解 Claude Code、Claude Desktop、OpenClaw 與 HTTP 伺服器設定。

常見陷阱

• 不要停留在片段。 在做出斷言前先擷取文件。
• 不要使用 sed/head/tail 切割檔案。 使用 path:from:count 後綴（例如 qmd get "#abc123:120:40"）或 --from/-l。輸出已附行號；管線處理會破壞文件 ID 解析、標頭與虛擬路徑。
• 不要依賴查詢擴展。 自行撰寫 intent:/lex:/vec:/hyde:。單純的 qmd query "user sentence" 會丟棄只有你擁有的上下文。你擴展查詢；模型只是排序。
• 不要過度使用語義搜尋。 如果你知道確切標題或詞項，BM25 更快且通常更好。
• 不要隨意變更索引。 qmd collection add、qmd update 與 qmd embed 會改變本機狀態且可能耗費資源。
• 模型支援的命令可能對環境敏感。 如果 qmd query、qmd vsearch 或重新排序因本機模型/GPU 不可用而失敗，請使用 qmd search 與更強的詞彙/結構化詞項。
• 模糊的使用者措辭需要意圖。 加入 intent:，而不是指望查詢擴展猜對正確領域。
• 集合名稱很重要。 在 concepts 中搜尋綜合維基頁面，在 sources 中搜尋逐字稿/原始來源頁面，在 docs 集合中搜尋程式碼或專案文件。