sense

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

sense

Use sense to locate evidence in a markdown tree before reading files. Every command reconciles changed files first. Results contain paths, metadata, excerpts, and line ranges. Read the returned files or ranges when the task needs their prose.

Setup, store selection, presets, and note design belong to the

sense-setup

skill. Translating an Obsidian Bases file belongs to

sense-bases

在读取文件之前，使用 sense 在 markdown 树中定位证据。每条命令都会先对变更的文件进行同步。结果包含路径、元数据、摘录和行范围。当任务需要这些文件的正文时，请阅读返回的文件或行范围。

设置、存储选择、预设和笔记设计属于

sense-setup

skill。翻译 Obsidian Bases 文件属于

sense-bases

。

Start with the tree

从目录树开始

Run these when the tree or its configuration is unfamiliar:

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

If a command reports a missing config, run

sense init

only when the user wants the tree configured. A one-off query does not authorize changing the tree.

当目录树或其配置不熟悉时，运行以下命令：

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

如果命令报告缺少配置，仅当用户希望配置该目录树时才运行

sense init

。一次性查询并不授权修改目录树。

Choose the command

选择命令

Need	Command
Exact count, filter, grouping, or known-field report	`sense sql` or a saved SQL query
Notes about a subject	`sense search`
One note's frontmatter, outline, links, and backlinks	`sense peek`
Shortest link chain between two notes	`sense path`
Similar notes that a note does not link to	`sense related`
Tree shape and available fields	`sense map`

Start with a bounded result. Raise

--k

, widen the preset, or broaden the words only when the first result does not answer the question.

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

需求	命令
精确计数、过滤、分组或已知字段报告	`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

Read the store guide before composing syntax

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

The config's

store

key selects the SQL dialect and text-search grammar. An omitted key means

sqlite

. Bare words and quoted phrases work in

sense search

on every store. Advanced operators and raw text-index SQL differ.

Read the matching guide before writing raw SQL that uses engine functions, dates, JSON, text matching, or native types. Also read it before using advanced search operators.

SQLite query guide
DuckDB query guide
Turso query guide

The tables,

placeholders, quoted identifiers,

has()

basename()

, and preset

scope

binding are shared. Portable SQL documents the schema and queries that work without depending on one engine.

配置中的

store

键选择 SQL 方言和文本搜索语法。省略该键表示

sqlite

。裸词和带引号的短语在每个存储的

sense search

中都能使用。高级运算符和原始文本索引 SQL 则各不相同。

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

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

这些表、

占位符、带引号的标识符、

has()

、

basename()

和预设的

scope

绑定是通用的。可移植 SQL 记录了不依赖于单一引擎即可工作的 schema 和查询。

Search and evidence

搜索与证据

search

combines the signals enabled by the selected preset:

Signal	Evidence
`match`	The note contains the search words. `snippets` shows the matching passages.
`link`	A note that matched links to this note.
`vector`	The embedding model placed this note near the query. The search words may be absent.

Combinations such as

match+link

mean that more than one signal produced the row.

score

ranks rows within that result only. Do not compare it across searches.

similarity

ranks vector evidence within the current result and model. Do not carry a fixed similarity cutoff between trees.

The

lines

value points at the section that earned the row. Read that range when it is present. A null range means the whole note is the reference. A vector-only row has no lexical snippet and is a lead, not proof that the note contains the query terms.

Read search evidence and troubleshooting when a search will support a factual claim, when absence matters, when results look noisy, or when tuning signal weights.

search

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

信号	证据
`match`	笔记包含搜索词。 `snippets` 显示匹配的段落。
`link`	一篇匹配的笔记链接到该笔记。
`vector`	嵌入模型将该笔记放置在查询附近。搜索词可能不存在。

类似

match+link

的组合意味着不止一个信号产生了该行。

score

仅对当前结果中的行进行排名，不要跨搜索比较。

similarity

对当前结果和模型中的向量证据进行排名。不要在目录树之间携带固定的相似度截止值。

lines

值指向产生该行的章节。当存在该范围时，请阅读该范围。null 范围意味着整篇笔记都是参考。仅向量行没有词法摘录，它是一个线索，而不是笔记包含查询词组的证据。

当搜索将支持事实性断言、缺失很重要、结果看起来有噪声或需要调整信号权重时，请阅读搜索证据与故障排查。

Scope and output

范围与输出

Bare commands use the

default

preset.

--preset <name>

chooses another. For

search

--include

--exclude

, and

--no-exclude

change the query scope for one invocation, but cannot reach files that no preset indexes.

sense status

shows actual coverage.

--where

filters search and graph commands against frontmatter alias

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

sense sql

is index-wide by default. With

--preset

, the command binds a temporary

scope(path)

table. The SQL must join it:

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

Table output is for people. Use

--format json

when code or an agent will parse rows. Use

--format csv

when redirecting a large row set to a file.

sql

search

related

, and saved queries support all three formats.

map

peek

status

, and

path

support table and JSON.

裸命令使用

default

预设。

--preset <name>

选择其他预设。对于

search

，

--include

、

--exclude

和

--no-exclude

会在一次调用中更改查询范围，但无法访问任何预设均未索引的文件。

sense status

显示实际覆盖范围。

--where

根据 frontmatter 别名

过滤搜索和图命令：

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。

Saved queries

已保存查询

Save a query in

sense.config.json

only when it will be reused:

json

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

Run these as

sense by-tag urgent

and

sense hot

. Invocation flags override a saved search's

preset

, or

where

value.

Running a saved entry validates it. Exit code 0 means it ran, 2 means the invocation needs different arguments, and 1 means the query or store failed. An empty result can be valid data, so interpret it from the query's purpose.

仅在需要重复使用时，才将查询保存到

sense.config.json

：

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

、

或

where

值。

运行已保存条目会对其进行验证。退出码 0 表示运行成功，2 表示调用需要不同的参数，1 表示查询或存储失败。空结果也可能是有效数据，因此要根据查询的目的来解释。

Tables

数据表

Table	Holds
`frontmatter`	One discovered column per frontmatter key, plus `path` , `_mtime` , `_ctime` , `_size` , `_rank` , and `_parse_error`
`content`	`path` , `title` , `summary` , and authored text, plus store-owned search columns
`links`	`src` , written `target` , resolved `dst` , and `embed`
`tags`	Merged and deduplicated frontmatter and inline tags
`sections`	Heading, level, line range, and token estimate
`preset_files`	Paths covered by each preset

Features can add tables.

sense map

and

sense status

show which features are active.

A non-null

_parse_error

means the file has no recovered frontmatter values. To distinguish a missing field from invalid frontmatter, include

_parse_error IS NULL

in the filter. Fixes appear on the next command because reconciliation runs first.

表	内容
`frontmatter`	每个 frontmatter 键对应一个发现的列，外加 `path` 、 `_mtime` 、 `_ctime` 、 `_size` 、 `_rank` 和 `_parse_error`
`content`	`path` 、 `title` 、 `summary` 和作者文本，以及存储自有的搜索列
`links`	`src` 、写入的 `target` 、解析后的 `dst` 和 `embed`
`tags`	合并并去重后的 frontmatter 和内联标签
`sections`	标题、层级、行范围和 token 估算
`preset_files`	每个预设覆盖的路径

功能可以添加表。

sense map

和

sense status

会显示哪些功能处于活动状态。

非 null 的

_parse_error

表示该文件没有可恢复的 frontmatter 值。要区分缺失字段与无效 frontmatter，请在过滤条件中包含

_parse_error IS NULL

。由于对账（reconciliation）首先执行，修复会在下一条命令时体现。

Reading discipline

阅读纪律

Select only the columns needed for the answer. Use

LIMIT

for row-returning exploration. Prefer

path

title

summary

, and bounded snippets over

content.text

. Aggregates such as

COUNT

and

GROUP BY

are already bounded by their result shape.

When a result identifies a large note, use

peek

and then read the relevant line range. Small files are often cheaper to read whole.

Worked command traces are in EXAMPLES.md.

只选择回答问题所需的列。对于返回行的探索，使用

LIMIT

。优先选择

path

、

title

、

summary

和有界的摘录，而不是

content.text

。诸如

COUNT

和

GROUP BY

之类的聚合已由其结果形态限定了边界。

当结果指向一篇较大的笔记时，使用

peek

，然后阅读相关的行范围。小文件通常整体读取成本更低。

完整的命令示例参见 EXAMPLES.md。

Upkeep

维护

Install a missing CLI with
```
npm install -g sensemaking
```
.
```
sense status
```
prints the cache path and watcher state.
Delete the cache directory printed by
```
sense status
```
only when the derived index is in doubt. The next command rebuilds it.
Use
```
sense watch
```
when another process should keep the index warm during frequent edits. Queries remain responsible for their own freshness check.

使用
```
npm install -g sensemaking
```
安装缺失的 CLI。
```
sense status
```
打印缓存路径和 watcher 状态。
仅当派生的索引存在疑问时，才删除
```
sense status
```
打印的缓存目录。下一条命令会重建它。
当需要另一个进程在频繁编辑期间保持索引热时，使用
```
sense watch
```
。查询仍需自行负责新鲜度检查。