NoteBrain CLI 技能(AI 代理專用)
NoteBrain 是一款高效能 Go CLI 工具,可將 Obsidian 筆記庫索引至本機 ChromaDB 向量資料庫。它提供跨 Markdown 筆記的語意搜尋、圖形遍歷、反向連結發現、隱藏關係尋找、完整筆記擷取與標籤分析。
核心執行原則與理由
為提高效率並避免浪費 token 或導致連線停滯,請遵循以下基本原則:
- 僅使用 NoteBrain — 不使用通用檔案搜尋:切勿使用
grep、find、ls或臨時 shell 腳本直接搜尋筆記庫的 Markdown 檔案來回答使用者問題。NoteBrain 的命令是基於索引後的向量與圖形資料庫專門設計,能產出比檔案系統層級文字搜尋更高品質、更相關的結果。將notebrain視為存取筆記庫內容的唯一介面。如果某個notebrain命令似乎沒回傳有用結果,請調整notebrain查詢(使用不同措辭、增加--limit、改用其他命令),而不是退而使用通用檔案搜尋。 - 非互動執行(
--format json):預設情況下,NoteBrain 會啟動互動式終端 TUI(Bubble Tea),專為人類瀏覽設計。此互動介面會導致自動化代理連線停滯。在查詢命令中務必加上--format json(或--format ndjson/--format tsv),以便立即取得結構化、可解析的資料。請注意,所有 JSON 信封欄位皆使用乾淨的snake_case鍵名(note_slug、title、file_path、score、tags、text)。 - AI 代理命令串接(
--jsonpath):當您只需要特定欄位(例如提取筆記 slug 或文字以傳給後續命令)時,請使用--jsonpath(例如--jsonpath="$.results[0].note_slug"或--jsonpath="$.results[*].note_slug")。使用--jsonpath時,純量值會以原始未加引號的字串輸出,陣列則每個元素印成一行,可無需jq就能直接提取 shell 變數。 - 擷取完整筆記(
notebrain get):當search傳回相關筆記區塊時,請使用notebrain get <note-slug-or-path>來擷取完整、重建的 Markdown 筆記文字(將其所有索引區塊拼接在一起),而非猜測區塊索引。切勿直接對底層筆記檔案執行cat—get能正確重建片段化的筆記,並反映筆記庫的索引狀態。 - 為綜合分析擷取內容(
--include-text):預設情況下,search與遍歷命令只回傳輕量中繼資料信封(標題、檔案路徑、標籤、相似度分數)。每當您的任務需要直接從搜尋結果摘要或推理個別區塊時,請加上--include-text。回傳的text欄位包含保留程式碼區塊的豐富 Markdown,方便直接複製貼上。 - 二進位檔路徑與引號處理:在開發環境中,若
notebrain不在系統 PATH 中,請執行./notebrain。筆記標題常包含空格或括號(例如"Q3 Planning [Draft]"),因此務必將筆記標題、標籤與搜尋查詢都用雙引號括起來。 - 內嵌持久儲存:NoteBrain 以內嵌資料庫(
~/.notebrain/chroma)執行。無需也不支援獨立的 ChromaDB Docker 容器或 HTTP 伺服器。 - 自動化索引:索引由作業系統排程器(cron/systemd 計時器,每三小時執行一次)處理。除非使用者明確要求編輯後立即重新索引,否則您無需在查詢前手動執行
ingest。
命令選擇指南
根據使用者分析目標選擇專門的命令:
| 使用者意圖 | 命令 | 原因與使用方式 |
|---|---|---|
| 「我的筆記對 X 有什麼看法?」 | search | 對所有筆記區塊執行向量相似度搜尋。使用 --tag="TagName" 依標籤過濾。 |
| 「讀取筆記 Y 的完整內容」 | get | 依 slug 或檔案路徑擷取並重建完整筆記文字與中繼資料。 |
| 「哪些筆記直接連結到這篇?」 | backlinks | 找出明確指向目標筆記的 [[wikilink]] 參照。 |
| 「圖形中結構上鄰近的內容有哪些?」 | connections | 在 wikilink 上執行廣度優先搜尋(BFS),最多 --hops N 層。為避免指數爆炸,請保留 --hops 1 或 --hops 2。 |
| 「哪些筆記在語意上相關但沒有連結?」 | hidden | 找出未連結但語意相似的筆記。對於發現概念橋樑極有價值。 |
| 「以筆記 Y 為中心,尋找與 X 相關的概念」 | boosted | 結合向量相似度與到 --seed 筆記的圖形鄰近度。 |
| 「哪些筆記與 X 共享標籤?」 | tags | 分析標籤重疊。在 tags 陣列中回傳潔淨的標籤字串。 |
| 「資料庫是否為最新狀態?」 | stats | 輸出集合計數(chunks、links)。支援 --format=json 和 --jsonpath。 |
| 「索引或重新索引筆記庫」 | ingest | 將 Markdown 筆記同步至 ChromaDB。重新索引是冪等的。 |
命令語法
語意搜尋與標籤過濾(search)
notebrain search "kubernetes reconciliation" --tag="Kubernetes" --limit 5 --format json --include-text
關鍵搜尋旗標
| 旗標 | 用途 | 預設值 |
|---|---|---|
--top-k N | 每篇筆記保留的最大區塊數。防止單一長筆記佔據結果,同時保留深度。 | 3 |
--context-window N | 擷取每個匹配前後 ±N 個相鄰區塊,並填入 context 陣列。大多任務使用 1 或 2。 | 0 |
--has-tasks | 僅回傳包含任務清單(核取方塊)的區塊。 | off |
--has-code | 僅回傳包含圍欄程式碼區塊的區塊。 | off |
--section | 將結果過濾至特定標題路徑下的區塊(例如 "Architecture > Components")。 | — |
--limit N | 最大傳回結果數。 | 10 |
--tag "TagName" | 依標籤名稱過濾或搜尋。 | — |
--min-score F | 隱藏低於此相似度分數(0–1)的結果。 | 0 |
何時使用 --context-window 與 notebrain get
- 使用
--context-window 1:當您需要同時對多個搜尋結果取得輕量級上下文時。這很有效率 — 一次搜尋呼叫就能同時取得匹配區塊及其鄰近區塊,足以理解區域上下文而無需擷取完整筆記。 - 使用
notebrain get:當您需要完整重建的筆記文字時 — 例如使用者要求閱讀或摘要特定筆記,或您需要查看完整文件結構時。
區塊視窗方法在處理多個搜尋結果時特別有價值,因為為每個結果擷取完整筆記會很浪費。先擷取視窗,然後選擇性地對真正需要完整上下文的筆記執行 get。
完整筆記擷取(get)
notebrain get "02areaskubernetesckadkubernetes-native-applications" --format json
圖形連線與隱藏連結(connections、hidden)
notebrain connections "Distributed Systems" --hops 2 --format json
notebrain hidden "Microservices" --limit 5 --format json --include-text
JSON 輸出結構
了解結果結構對於可靠欄位提取至關重要。每個查詢命令都會將結果包裝在以下信封中:
{
"command": "search",
"query": "Semantic Search: \"kubernetes\"",
"total": 3,
"results": [
{
"note_slug": "02areaskubernetes-architecture",
"title": "Kubernetes Architecture",
"file_path": "02.Areas/Kubernetes/Architecture.md",
"score": 0.82,
"chunk_index": 2,
"tags": ["Kubernetes", "DevOps"],
"heading_path": "Components > Control Plane",
"text": "The API server validates and configures...",
"context": [
"Previous chunk text about etcd storage...",
"The API server validates and configures...",
"The scheduler watches for newly created Pods..."
]
}
]
}
| 欄位 | 出現時機 | 說明 |
|---|---|---|
note_slug | 一律 | 從檔案路徑產生的 URL 安全識別碼。 |
title | 一律 | 來自 frontmatter 或檔案名稱的筆記標題。 |
file_path | 一律 | 筆記庫內的相對路徑。 |
score | 一律 | 搜尋時的相似度分數(0–1);連線時的跳數。 |
chunk_index | 搜尋、hidden、boosted | 匹配的是筆記的第幾個區塊(從 0 開始)。 |
tags | 當筆記有標籤時 | 標籤字串陣列。 |
heading_path | 當區塊位於某標題之下 | 階層路徑,例如 "Section > Subsection"。 |
text | 當傳入 --include-text 時 | 匹配區塊的完整 Markdown 文字,保留程式碼區塊。 |
context | 當 --context-window N > 0 時 | 前後 ±N 個相鄰區塊文字(依區塊索引排序)的陣列。 |
extra | connections、tags、boosted | 命令特定資訊(例如 "2 hop(s)"、"graph-boosted")。 |
深化答案品質:多重訊號擷取
在回答任何「我對 X 知道什麼」或「摘要我對 X 的筆記」這類問題之前,不要只做一次 search 呼叫。僅靠搜尋結果只能找出與查詢語意相近的區塊——它們會遺漏使用者刻意在圖形中建立的周圍上下文。務必擴大視野:
- 帶上下文的搜尋 — 使用
--context-window 1 --include-text --top-k 2執行search,以一次性取得最相關的區塊及其前後段落。這在單次呼叫中同時提供精確度(匹配區塊)與上下文(前後內容)。 - 為每個種子筆記擷取反向連結 — 執行
notebrain backlinks <seed-slug> --format json --include-text來找出所有明確連結至該種子筆記的筆記。這些都是使用者手動策劃為相關的筆記,因此其內容幾乎總是高訊號,應在綜合分析中給予較高權重。 - 向外探索連線 — 執行
notebrain connections <seed-slug> --hops 2 --format json來繪製種子筆記周圍的區域圖形鄰域。這會揭露在結構上相鄰的筆記(例如距離兩個連結的筆記),它們可能不會出現在純向量搜尋中,但屬於同一個知識叢集。 - 檢查隱藏連結 — 執行
notebrain hidden <seed-slug> --include-text --context-window 1來捕捉使用者尚未連結但概念相關的筆記。明確向使用者指出這些可能是其筆記庫中的遺漏連結,因為這是 NoteBrain 相較於純搜尋最有價值的差異化功能之一。 - 綜合分析而非單純列出 — 將種子筆記、其反向連結、
connections鄰域以及任何hidden結果合併成一個連貫的答案,並區分哪些是明確連結(高信心度)、哪些僅是語意相似(值得再次確認)。
這個 search → backlinks → connections → hidden 鏈應成為任何非瑣碎探索性問題的預設工作流程,而不僅僅是一次 search 呼叫,因為它能同時揭露使用者建立的顯式結構與 NoteBrain 可偵測的隱式結構。
AI 代理命令串接管線範例
# 1. 搜尋並帶入周圍上下文 — top-k 確保結果在不同筆記間保持多樣性
SLUG=$(notebrain search "message broker backpressure" --limit 3 --top-k 2 \
--context-window 1 --include-text --format json \
--jsonpath="$.results[0].note_slug")
# 2. 為最佳結果擷取完整重建的筆記文字
notebrain get "$SLUG" --jsonpath="$.text"
# 3. 找出連結至此筆記的所有反向連結筆記 slug 及其內容,
# 以將答案建立在使用者明確連結的基礎上
notebrain backlinks "$SLUG" --format json --include-text
# 4. 遍歷圖形鄰域以揭露純向量搜尋會遺漏的結構相鄰筆記
notebrain connections "$SLUG" --hops 1 --format json