AI 代理的 NoteBrain CLI 技能
NoteBrain 是一个高性能的 Go CLI 工具,可将 Obsidian Vault 索引到本地 ChromaDB 向量数据库中。它提供跨 Markdown 笔记的语义搜索、图遍历、反向链接发现、隐藏关系查找、完整笔记检索和标签分析功能。
核心执行原则与原理
为高效运行并防止浪费 Token 或挂起会话,请遵循以下基本原则:
- 仅使用 NoteBrain — 不使用通用文件搜索:切勿使用
grep、find、ls或针对 Vault Markdown 文件的临时 Shell 脚本来回答用户问题。NoteBrain 的命令是基于索引的向量和图数据库专门构建的,始终能产生比文件系统级文本搜索更高质量、更相关的结果。将notebrain视为访问 Vault 内容的唯一接口。如果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 笔记文本,而不是猜测块索引。切勿对底层 Vault 文件使用cat—get能正确重建分块的笔记,并尊重 Vault 的索引状态。 - 为综合内容检索内容(
--include-text):默认情况下,search和遍历命令返回轻量级的元数据信封(标题、文件路径、标签、相似度分数)。只要你的任务需要直接从搜索结果中总结或推理单个块,请附加--include-text。返回的text字段包含保留代码块的丰富 Markdown,因此代码片段是可复制粘贴的。 - 二进制文件解析与引号使用:在开发环境中,如果
notebrain不在系统 PATH 中,请执行./notebrain。笔记标题通常包含空格或方括号(如"Q3 Planning [Draft]"),因此务必用双引号括住笔记标题、标签和搜索查询。 - 嵌入式持久化存储:NoteBrain 仅作为嵌入式数据库运行(
~/.notebrain/chroma)。不需要也不支持独立的 ChromaDB Docker 容器或 HTTP 服务器。 - 自动摄取:摄取由操作系统调度程序处理(每 3 小时 cron/systemd 定时任务)。除非用户明确要求在编辑笔记后立即重新索引,否则在查询前无需手动运行
ingest。
命令选择指南
根据用户的分析目标选择专门的命令:
| 用户意图 | 命令 | 原因与使用方法 |
|---|---|---|
| “我的笔记对 X 有什么说法?” | search | 对所有笔记块执行向量相似度搜索。使用 --tag="TagName" 按标签过滤。 |
| “阅读笔记 Y 的完整内容” | get | 通过 slug 或文件路径检索并重建完整的笔记文本和元数据。 |
| “什么直接链接到这篇笔记?” | backlinks | 查找指向目标笔记的显式 [[wikilink]] 引用。 |
| “图中哪部分在结构上相邻?” | connections | 在 wiki 链接上执行广度优先搜索(BFS),最多 --hops N 跳。保持 --hops 1 或 --hops 2 以避免指数级膨胀。 |
| “什么在语义上相关但未被链接?” | hidden | 展示未链接但语义相似的笔记。对于发现概念性桥梁非常有价值。 |
| “查找与 X 相关的概念,围绕笔记 Y 展开” | boosted | 结合向量相似度和与 --seed 笔记的图邻近度。 |
| “哪些笔记与 X 共享标签?” | tags | 分析标签重叠。在 tags 数组中返回干净的标签字符串。 |
| “数据库是最新的吗?” | stats | 输出集合计数(chunks、links)。支持 --format=json 和 --jsonpath。 |
| “索引或重新索引 Vault” | 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 vs 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 | 始终 | 来自前置元数据或文件名的笔记标题。 |
file_path | 始终 | Vault 内的相对路径。 |
score | 始终 | 搜索的相似度分数(0–1);连接的跳数。 |
chunk_index | 搜索、隐藏、增强 | 匹配的笔记块索引(从 0 开始)。 |
tags | 笔记有标签时 | 标签字符串数组。 |
heading_path | 块在标题下时 | 类似 "Section > Subsection" 的面包屑路径。 |
text | 传递 --include-text 时 | 匹配块的完整 Markdown 文本,保留代码块。 |
context | --context-window N > 0 时 | 按块索引排序的 ±N 个相邻块文本数组。 |
extra | 连接、标签、增强 | 命令特定信息(例如 "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
…