Obsidian search

前置条件

Obsidian 1.12.7 及以上，并已启用 CLI：Settings → General → Command line interface（一次性注册后会生成 obsidian 命令）。若命令报「command not found」，说明 CLI 尚未注册，请如实报告，不要改用其他工具绕开。

命令依赖 Obsidian 应用运行，但不必手动先开；首条命令会自动把它启动起来，可能略有延迟。

总则

你在这里只运行查询与读取类命令，绝不修改笔记。

步骤一到步骤三的任务是定向和检索，三步都绝不打开整篇笔记读正文。读全文是步骤四定位到具体文件之后才做的事。

必须一步一步执行，不能跳过任何一个步骤。在执行到每一个大小步骤之前，都要先陈述该步骤的目的。

绝不把命令包进 for、while、if 这类控制结构，也不用变量、命令替换这类 shell 语法。需要跑多个查询时，拆成多条命令逐条执行，不要用循环一次跑完。

步骤一：定向

定向的目的是侦察而非取答案。

先判断有没有候选 vault，这一步只看用户给的东西，先不跑命令。候选 vault 要么来自参数 $ARGUMENTS[0]，要么是用户在请求里指名的 vault。据此分两条路：

• 没有候选时，目标就是当前活跃 vault，绝对不要擅自改选别的 vault，也不要去拉 vault 清单看。跑 obsidian vault 拿默认 vault 的详细信息。此后针对当前 vault 的命令一律不带 vault=。
• 有候选时，直接跑 obsidian vault="<vault 名>" vault。返回详细信息就说明连上了，目标 vault 就是它，此后每条 obsidian 命令都在子命令前加 vault="<vault 名>"。返回 Vault not found. 就说明这个 vault 不存在，如实告知用户，不再继续搜。

围绕检索目标，从下表挑至少三条最相关的命令执行。

命令	典型用法
tags	obsidian tags counts sort=count
aliases	obsidian aliases verbose
folders	obsidian folders folder=X
files	obsidian files folder=X ext=md
backlinks	obsidian backlinks path=X counts
outline	obsidian outline path=X format=tree

folders 与 files 摸清目录的命名约定，认出哪些只是模板、附件、配置这类噪声目录，哪些目录装内容则记下。别凭目录名印象就跳过某个内容目录，更不要提前押注某一个目录，拿不准就用 files 抽样文件名来定。

aliases 收录同一概念的不同叫法，弥合用户用词与笔记术语的落差。

tags 列出整个 vault 的标签，露出这个 vault 用哪些词组织主题。

backlinks 找出被大量引用的枢纽笔记，outline 看其骨架，顺结构定位而非全文盲搜。

步骤二：语义联想

候选词不能凭通用常识顺着用户这轮请求的 prompt 和对话 context 想出来，也不是照抄定向清单，而是由「用户要什么」和「这个 vault 实际怎么组织这块内容」两者共同推出。从下面三个角度推：

• 真实意图：表层用词背后用户到底在找什么主题，最该先想。
• 近义与改写、上位与下位：vault 里可能换的说法，更抽象的主题或更具体的实例。
• 关联实体与概念：相关的人物、组织、作品、地点，以及常与该主题共现的概念，或与之对立的观点、流派。

每个概念都要一并收齐各种写法：不同译名、别名、跨语言的中英对照都算，凡有通用英文说法都要收齐，普通概念词也不例外。写法两种及以上就当场写成能直接用作查询的概念组，如「大语言模型」写成 (大语言模型 OR LLM OR "large language model")，只有一种写法的（如 Memex）写裸词即可。组内必须用 OR 连接，绝不用空格，漏掉 OR 会让同一概念的多个写法变成必须同时出现。一组只装同一概念的可替换写法，不同概念分属不同组。

把三个角度的候选词按下面的格式列出，每个概念组紧跟它自己的来源：连到步骤一定向到的哪条别名、标签、目录、文件名或大纲小标题，确实没有对应的才标「纯语义」。

• 真实意图：
  • (写法一 OR 写法二)（来源）
  • (写法)（来源）
  • ……
• 近义与改写、上位与下位：
  • (写法一 OR 写法二)（来源）
  • ……
• 关联实体与概念：
  • (写法一 OR 写法二)（来源）
  • ……

步骤三：搜内容

这一步是个回路：从最严的查询起步，每级先用带 total 的 search 数出命中，照命中数决定是收口去读还是放宽重来；没拿到本级结果，绝不预跑下一级更宽的命令。严格度指多词共现的要求有多紧，由两件事一起定，一是要几个概念组同时出现，二是它们挤在多窄的范围里；两者都收到最紧是第一级，之后逐级放宽，每次只松一级：

1. 最严：两个概念组在同一段落内共现。从步骤二取区分度最高的两个概念组，整组逐字搬来，绝不拆成单词、绝不跨组重拼，概念组之间留空格表示共现，再用 block:(……) 限在同一段落。完整命令形如 obsidian search query='block:((大语言模型 OR LLM OR "large language model") (智能体 OR agent))' total。
2. 放宽范围：去掉 block:，两组从同一段落放宽到同一篇笔记内共现。
3. 放弃共现：减到一个概念组，不再要求多词共现，只要这个词出现。

三级走完仍不行，回步骤二另配一对，换掉其中一个或两个都行，配成尚未试过的新组合，重走这条阶梯。

每级照 total 命中数分三种走法：

• 太少：放宽一级，到底了就换词。
• 合适：用 search:context 取匹配行，输出接 | sort -u 去重，从中定位要读的文件。
• 过多：把本级查询的 total 去掉重跑，让 search 返回命中的文件路径，从路径前缀看命中集中在哪些目录，再用 path=<folder> 把 search:context 限定到那里。

步骤四：读内容

定位到具体文件后，读全文用内置 Read 工具直接读那个 .md。注意 search 返回的是相对目标 vault 根目录的路径，若当前目录恰好就是目标 vault 时，相对路径可直接交给 Read；否则拼上目标 vault 根目录的绝对路径再读，该路径取自步骤一获取的 vault path。只想先看标题层级再决定是否细读时，用 obsidian outline path=X。

检索命令与查询语法参考

obsidian search 与 obsidian search:context

search 只返回匹配的文件路径，适合判断某些词出现在哪些笔记里；search:context 返回 grep 风格的 path:line: text，适合需要看到匹配行内容的场景。先按需要选命令，再拼 query。

参数	必填	含义	默认
query=<text>	是	搜索查询，语法见下文	无
path=<folder>	否	限定到某个文件夹（注意此选项值不是文件路径）	整个 vault
limit=<n>	否	最多返回的文件数	无
format=text|json	否	输出格式	text
total	否	只返回匹配数量，仅 search 支持，search:context 会忽略此参数	关闭
case	否	区分大小写	关闭

以下查询语法用于 query= 取值，默认只检索笔记内容。

词与短语

基础搜索独立匹配每个词。精确短语用引号包裹，如 "star wars"。短语内部的引号用反斜杠转义，如 "they said \"hello\" to each other"。

布尔逻辑

• meeting work：同时匹配两个词。
• meeting OR work：匹配其中任一。
• meeting work OR meetup personal：与、或混合。
• meeting (work OR meetup) personal：用括号设优先级。
• meeting -work：用负号排除。
• meeting -(work meetup)：用括号一次排除一组。

搜索运算符

运算符	用途	轴
match-case: ignore-case:	控制大小写，如 match-case:HappyCat	—
section:	匹配同一小节内（两标题之间）	共现范围
block:	匹配同一块内（同一段落或列表项），因需解析而较慢	共现范围
line:	匹配同一行内，可用 -line: 取反	共现范围