| name | obsidian-search |
| description | 根据用户的自然语言检索需求，生成合适的 Obsidian CLI 查询命令，执行查询，并将结果总结返回。用于用户想在 Obsidian 仓库中搜索笔记、查找上下文、筛选任务、标签、属性、反链、文件列表或结构化查询时，例如“帮我找最近的会议记录”“搜一下包含某关键词的笔记”“看看某篇笔记有哪些反向链接”。 |
Obsidian Search
使用 Obsidian CLI 把自然语言需求转换为可执行查询，再基于输出给出简洁结论。优先复用 obsidian search、search:context、tasks、tags、properties、backlinks、files、outline 等现成命令，而不是手写文件遍历逻辑。
工作流
按以下顺序执行：
- 判断用户真正想要的结果类型：文件列表、命中上下文、任务、标签、属性、链接关系、某篇笔记内容，还是需要组合查询。
- 读取 references/cli-query-patterns.md，选择最贴切的命令模式。
- 组装命令时优先使用：
query= 传入用户关键词或搜索表达式path= 缩小目录范围file= 用文件名解析目标笔记format=json 在需要稳定总结时优先使用limit= 控制结果规模，避免输出过长
- 使用 Bash 执行 Obsidian CLI 命令。
- 如果
search:context 执行成功但没有返回内容，不要立刻假设“无结果”；先改用同关键词的 obsidian search 验证是否存在匹配文件，再决定是否补充 read、outline 等后续命令。
- 阅读结果并直接回答用户问题，不原样倾倒大段终端输出。
- 如果首轮结果过宽或歧义明显，基于结果再执行一轮更具体的查询。
查询决策
先匹配下列场景：
- 用户要“找包含某词的笔记” ->
obsidian search
- 用户要“看匹配词出现在哪些行/上下文” ->
obsidian search:context
- 用户要“找待办/已完成事项” ->
obsidian tasks
- 用户要“看标签、某标签用了多少次” ->
obsidian tags 或 obsidian tag
- 用户要“看属性分布或某文件属性” ->
obsidian properties
- 用户要“看谁链接到这篇笔记” ->
obsidian backlinks
- 用户要“看这篇笔记链接到了谁” ->
obsidian links
- 用户要“列出某目录下文件” ->
obsidian files folder=<path>
- 用户要“看文档结构/标题层级” ->
obsidian outline
- 用户要“直接读某篇命中的笔记内容” -> 先
search/files 定位，再 obsidian read
如果用户的问题本质上是“总结某个主题在知识库中的分布或观点”，优先采用两步法：
obsidian search 或 obsidian search:context 缩小范围- 对最相关的少量文件使用
obsidian read、outline 或 backlinks 补充信息后总结
命令构造规则
- 把
vault=<name> 放在命令最前，仅在必须切换仓库时使用。
- 包含空格的值用双引号包裹，例如
query="会议纪要"。
file= 适合按笔记名解析；需要精确定位时改用 path=。- 用户说“最近”“最新”时，CLI 本身不直接支持按时间排序；先查出候选文件，再结合仓库工具补充判断。
- 用户要统计数量时，优先加
total 或选择 format=json 后自行汇总。
- 用户要机器可读结果时，优先
format=json；用户只要快速答复时可用默认文本格式。
- 单次不要返回过多文件；除非用户明确要求全量，一般加
limit=10 或更小。
- 当前环境下
search:context 可能出现“命令成功但无输出”的情况；遇到这种情况时，优先降级到 obsidian search，必要时再对候选文件执行 read。
总结规则
- 先给结论，再给依据。
- 结果少时，直接列出关键文件或关键行。
- 结果多时，聚类总结主题、标签、目录分布或高频模式。
- 若没有结果，明确说明“未找到”，并给出下一步可尝试的更宽松查询词。
- 若
search:context 无输出但 search 有命中，应明确告诉用户“已找到相关文件，但当前 CLI 未返回上下文行”，并改为总结候选文件。
- 若查询语义不够清晰，先做最稳妥的一轮搜索，再根据结果决定是否追问。
输出格式
默认按这个顺序组织回答：
- 一句话回答用户问题
- 关键发现（2-5条）
- 必要时给出执行过的命令
- 必要时建议下一步更精确的查询方向
参考资料
