sense

sense

先使用 sense 在 Markdown 树中定位证据，再阅读文件。配置默认值为 "build": true 时，CLI 查询会增量扫描已配置的树，以查找所需功能；向量准备仅限于符合条件的范围。配置为 "build": false，或单次查询使用 --no-build 时，会读取最近一次已完成的索引代，检查所请求的就绪状态，且不会扫描实时文件。无论默认设置如何，显式构建和监视都会进行准备。结果包含路径、元数据、片段和行范围。如果任务需要阅读文件内容，请读取返回的文件或范围。

配置、存储选择、预设和笔记设计请参阅 sense-setup skill。翻译 Obsidian Bases 文件请参阅 sense-bases。

解释结果或输出控制时，请使用共享的 Sense 术语表。在区分片段、章节、章节描述、大纲、块或链接类型时，请阅读该文件；这些名称不可互换。

从树开始

如果不熟悉该树或其配置，请运行以下命令：

sense status     # config, store, cache, document count, preset coverage
sense map        # fields, hubs, recent notes
sense --list     # saved queries

如果命令报告缺少配置，只有在用户希望配置该树时才运行 sense init。单次查询并不授权修改该树。

选择命令

需求	命令
精确计数、筛选、分组或已知字段报告	sense sql 或已保存的 SQL 查询
有关某个主题的笔记	sense search
单篇笔记的 frontmatter、大纲、链接和反向链接	sense peek
两篇笔记之间最短的链接链路	sense path
与某篇笔记相似但未被其链接的笔记	sense related
树的结构和可用字段	sense map

从范围有限的结果开始。只有当首个结果未能回答问题时，才提高 --k、扩大预设范围或拓宽关键词。

sense search "pricing" --k 10
sense search "sourcing quotes" --preset raw
sense peek notes/pricing-model.md
sense path onboarding.md pricing-model.md
sense related notes/pricing-model.md --k 10
sense sql "SELECT path FROM frontmatter WHERE status = ? LIMIT 50" active

编写语法前先阅读存储指南

配置中的 store 键决定 SQL 方言和文本搜索语法。省略该键时，默认使用 sqlite。在所有存储类型中，sense search 都支持裸词和带引号的短语。高级运算符和原始文本索引 SQL 则因存储类型而异。

编写使用引擎函数、日期、JSON、文本匹配或原生类型的原始 SQL 之前，请阅读相应指南。使用高级搜索运算符之前，也请阅读相应指南。

• SQLite 查询指南
• DuckDB 查询指南
• Turso 查询指南

表、? 占位符、带引号的标识符、has()、basename() 和预设 scope 绑定都是通用的。可移植 SQL 介绍了架构以及无需依赖特定引擎即可运行的查询。

搜索与证据

search 会组合所选预设启用的信号：

信号	证据
match	笔记中包含搜索词。snippets 会显示匹配段落。
link	与搜索匹配的笔记链接到了这篇笔记。
vector	嵌入模型将这篇笔记放在了查询附近。搜索词可能并未出现。

match+link 等组合表示不止一种信号产生了该行。score 仅用于对当前结果中的行排序，不要跨搜索比较。similarity 用于对当前结果和模型中的向量证据排序。不要在不同笔记树之间沿用固定的相似度阈值。

lines 值给出索引笔记中的行范围。它可能指出包含词语匹配的段落，也可能指向一个嵌入文本块。存在该值时，请阅读对应范围。范围为 null 表示整篇笔记都是参考内容。仅有向量证据的行不包含词法片段，只能作为线索，不能证明笔记包含查询词。

当搜索将用于支持事实性陈述、缺失结果很重要、结果看起来杂乱，或需要调整信号权重时，请阅读搜索证据与故障排查。

sense search --explain --format json 会补充返回笔记的实际排序贡献。它不会改变排序，也不会解释所有缺失结果。搜索指南会说明这些贡献与 via 证据标签有何不同。

范围与输出

不带参数的命令使用 default 预设。--preset <name> 可选择其他预设。对于 search、map、peek、path 和 related，--include、--exclude 和 --no-exclude 可以更改单次调用的查询范围，但无法访问任何预设都未索引的文件。sense status 会显示实际覆盖范围。范围用于筛选结果；预设不是安全边界。

peek 会先拒绝范围外的精确路径，再尝试按 basename 查找；它会在范围内解析 basename，并且只显示范围内已解析的链接和反向链接；未解析的目标则保持原样。path 会在整个索引树中解析两端的路径，并将中间笔记限制在范围内。related 会在整个索引树中解析种子笔记，并将结果候选限制在范围内。

peek --section-count-limit n 限制章节描述的数量。--link-count-limit n 则分别限制每组出站链接、反向链接和未解析链接的数量。两者默认值均为 20，且要求使用正的安全整数。当所需大纲或链接被截断时，可请求更多；用于初步筛查时，可请求更少。总数仍表示完整选定组的数量；这些限制不会扩大范围。章节描述会指出应阅读的位置，但不会返回章节正文。

--where 会根据 frontmatter 别名 f 筛选搜索和图命令：

sense search "pricing" --where "f.status = 'active' AND has(f.tags, 'sales')"

默认情况下，sense sql 的查询范围为整个索引。使用 --preset 时，该命令会绑定一个临时的 scope(path) 表。SQL 必须与该表联接：

sense sql "SELECT f.path FROM frontmatter f JOIN scope ON scope.path = f.path" --preset default

表格输出供人阅读。代码或 Agent 需要解析行时，请使用 --format json。将大量行重定向到文件时，请使用 --format csv。sql、search、related 和已保存的查询支持这三种格式。map、peek、status 和 path 支持表格和 JSON 格式。

已保存的查询

仅当查询会重复使用时，才将其保存在 sense.config.json 中：

{
  "queries": {
    "by-tag": { "sql": "SELECT path, title FROM frontmatter WHERE has(tags, ?) ORDER BY path" },
    "hot": { "search": "pricing", "preset": "raw", "k": 20 }
  }
}

可通过 sense by-tag urgent 和 sense hot 运行这些查询。调用标志会覆盖已保存搜索中的 preset、k 或 where 值。

运行已保存的条目时，会对其进行验证。退出码 0 表示运行成功；6 表示调用需要不同的参数；4 表示发生操作失败，例如查询、存储或 CLI 引导失败。空结果也可能是有效数据，因此应根据查询目的进行解读。

表

表	存储内容
frontmatter	每个发现的 frontmatter 键对应一列，以及 path、_mtime、_ctime、_size、_rank 和 _parse_error
content	path、title、summary 和创作文本，以及由存储管理的搜索列
links	src、写入的 target、解析后的 dst 和 embed
tags	合并并去重后的 frontmatter 标签和行内标签
sections	标题、级别、行范围和令牌估算值
preset_files	每个预设涵盖的路径

功能可以添加表。sense map 和 sense status 会显示哪些功能处于启用状态。

非空的 _parse_error 表示该文件没有恢复出 frontmatter 值。要区分字段缺失和 frontmatter 无效，请在筛选条件中加入 _parse_error IS NULL。由于会先运行协调，修复会在下条命令中显示。

阅读规范

只选择回答所需的列。探索返回行的结果时使用 LIMIT。优先使用 path、title、summary 和有界片段，而不是 content.text。COUNT 和 GROUP BY 等聚合操作已通过结果形状限制了结果范围。

当结果指出某篇笔记很长时，使用 peek，然后读取相关行范围。读取小文件的全部内容通常更省资源。

命令执行示例见 EXAMPLES.md。

维护

• 使用 npm install -g sensemaking 安装缺失的 CLI。
• sense status 会打印缓存路径和监视器状态。
• 若对派生索引的状态存疑，请使用 sense build --force 重新创建；源文件、配置和监视器所有权声明都会保留。
• 如果需要其他进程在频繁编辑期间保持所有已配置功能就绪，请使用 sense watch。默认查询会扫描已配置的树以准备所需功能，并将向量准备限制在符合条件的路径内；--no-build 只读取已完成的生成结果。