sense-setup

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

sense setup and tree design

sense设置与树结构设计

Use this skill to create or change a sense configuration. Querying an existing tree belongs to the

sense

skill. Worked configurations for common tree shapes are in EXAMPLES.md.

使用此skill来创建或更改sense配置。查询现有树结构属于

sense

skill的范畴。常见树结构的工作配置示例见EXAMPLES.md。

Set up the tree

设置树结构

Install the CLI and initialize it at the markdown root:

npm install -g sensemaking
cd path/to/notes
sense init
sense status

sense init

writes

sense.config.json

. Config discovery walks upward from the current directory.

--config <path>

selects another file.

By default, the config indexes its own directory. A top-level

root

can point at another markdown tree. Relative roots resolve from the config directory, and

.sense/

remains beside the config. Use this when separate consumers need their own presets, saved queries, or caches over one tree.

Globs and indexed paths are relative to the selected root. Run

sense status

and

sense map

after changing the config to confirm preset coverage and the selected store. A change that affects indexed content rebuilds the relevant cache and reports the reason.

安装CLI并在markdown根目录初始化它：

npm install -g sensemaking
cd path/to/notes
sense init
sense status

sense init

会写入

sense.config.json

。配置发现会从当前目录向上逐级查找。

--config <path>

可选择另一个文件。

默认情况下，配置会索引其自身所在目录。顶层的

root

字段可以指向另一个markdown树结构。相对根路径从配置目录解析，且

.sense/

保留在配置旁边。当不同的使用者需要对同一棵树拥有各自的预设、保存的查询或缓存时，可以使用此功能。

Glob模式和被索引的路径相对于所选根目录。更改配置后运行

sense status

和

sense map

，以确认预设覆盖范围和所选存储引擎。影响索引内容的更改会重建相关缓存并报告原因。

Choose the store

选择存储引擎

Choose from the intended use of the cache. Start with

sqlite

when no surrounding workflow favors another engine, then consider interoperability, SQL, connection behavior, and representative Sense measurements. A current timing result does not define an engine's long-term suitability.

Store	Choose it when	Main trade-off
`sqlite`	The tree needs the smallest setup, advanced FTS5 search syntax, or concurrent Sense commands	Included with Node; raw SQL is SQLite
`duckdb`	The cache belongs in DuckDB analytical work over large datasets or in a local/cloud workflow, or needs DuckDB types and SQL	Experimental Sense adapter, large native install, one open connection at a time
`turso`	The tree benefits from the embedded Rust engine or Tantivy index, or is evaluating the engine as its adapter evolves	Experimental Sense adapter, restricted search grammar, one open connection at a time

Read the matching selection guide before recommending or configuring a non-default store:

SQLite selection guide
DuckDB selection guide
Turso selection guide

Read the current store benchmark summary only when performance could change the choice. The release assessment generates that shipped summary from the latest accepted all-store run.

Each store uses a separate cache file. Changing

store

rebuilds the index instead of migrating the old cache. Commands and public tables are shared, while raw SQL and advanced word-search syntax follow the selected engine.

根据缓存的预期用途进行选择。当周围的工作流程没有偏向其他引擎时，从

sqlite

开始，然后考虑互操作性、SQL、连接行为以及具有代表性的Sense测量结果。当前的计时结果并不能定义引擎的长期适用性。

存储引擎	选择时机	主要权衡
`sqlite`	树结构需要最小的设置、高级FTS5搜索语法或并发Sense命令	随Node附带；原始SQL为SQLite
`duckdb`	缓存属于DuckDB对大数据集的分析工作，或属于本地/云工作流，或需要DuckDB类型和SQL	实验性Sense适配器，本地安装包较大，一次只能打开一个连接
`turso`	树结构受益于嵌入式Rust引擎或Tantivy索引，或在其适配器演进过程中评估该引擎	实验性Sense适配器，受限的搜索语法，一次只能打开一个连接

在推荐或配置非默认存储引擎之前，请阅读相应的选择指南：

SQLite选择指南
DuckDB选择指南
Turso选择指南

仅在性能可能影响选择时，阅读当前存储基准测试摘要。发布评估会根据最新被接受的全存储运行生成该随附摘要。

每个存储引擎使用单独的缓存文件。更改

store

会重建索引，而不是迁移旧缓存。命令和公共表是共享的，而原始SQL和高级单词搜索语法则遵循所选引擎。

Design presets

设计预设

A preset is a named, self-contained scope. The required

default

preset serves bare commands. Other presets are selected by name.

Field	Meaning	Default
`include` and `exclude`	Files covered by the preset	`include` is required
`k`	Search result count	10
`signals`	Enabled search signals and their reciprocal-rank weights	Every available signal at weight 1
`where`	Standing frontmatter filter	None

A file is indexed when any preset includes it. Presets can overlap. Files outside every preset do not enter the index.

Use paths for stable layers such as

raw/

notes/

, and

archive/

. Use frontmatter filters for changing state such as

status

project

, and dates. A preset controls indexing, so its coverage must be computable from paths before frontmatter queries run.

Use separate presets when parts of the tree need different search signals or result counts. A single-purpose tree does not need extra preset vocabulary.

预设是一个命名的、自包含的作用域。必需的

default

预设用于处理不带参数的裸命令。其他预设通过名称选择。

字段	含义	默认值
`include` 和 `exclude`	预设覆盖的文件	`include` 为必填
`k`	搜索结果数量	10
`signals`	启用的搜索信号及其倒数排名权重	每个可用信号的权重为1
`where`	常驻frontmatter过滤器	无

当任何预设包含某个文件时，该文件就会被索引。预设可以重叠。不在任何预设范围内的文件不会进入索引。

对稳定层级使用路径，例如

raw/

、

notes/

和

archive/

。对变化状态使用frontmatter过滤器，例如

status

、

project

和日期。预设控制索引，因此其覆盖范围必须在运行frontmatter查询之前可由路径计算得出。

当树结构的不同部分需要不同的搜索信号或结果数量时，请使用单独的预设。单一用途的树结构不需要额外的预设词汇。

Configure vectors

配置向量

Vectors require two choices. The top-level

embed

block names the model and provider. Each preset's

signals

decides whether that scope uses vectors.

json

{
  "embed": {
    "model": "minishlab/potion-retrieval-32M",
    "provider": "static"
  },
  "presets": {
    "default": {
      "include": ["notes/**/*.md"],
      "signals": { "words": 1, "links": 1, "vectors": 1 }
    },
    "raw": {
      "include": ["raw/**/*.md"],
      "signals": { "words": 1, "links": 1 }
    }
  }
}

The first vector search downloads a named static model and embeds the covered notes.

sense download

fetches the model earlier when CI, offline work, or timing makes that useful. A config change that alters the model, vector coverage, or chunking can rebuild vectors.

Read embedding setup when choosing a provider or model, supporting a non-English tree, changing chunk size, or tuning signal weights.

向量需要两个选择。顶层的

embed

块指定模型和提供者。每个预设的

signals

决定该作用域是否使用向量。

json

{
  "embed": {
    "model": "minishlab/potion-retrieval-32M",
    "provider": "static"
  },
  "presets": {
    "default": {
      "include": ["notes/**/*.md"],
      "signals": { "words": 1, "links": 1, "vectors": 1 }
    },
    "raw": {
      "include": ["raw/**/*.md"],
      "signals": { "words": 1, "links": 1 }
    }
  }
}

首次向量搜索会下载指定的静态模型并嵌入所覆盖的笔记。当CI、离线工作或时机需要时，

sense download

可以提前获取模型。更改模型、向量覆盖范围或分块方式的配置变更可以重建向量。

在选择提供者或模型、支持非英语树结构、更改块大小或调整信号权重时，请阅读嵌入设置。

Design queryable notes

设计可查询的笔记

Sense accepts heterogeneous markdown. These choices decide which queries will be reliable:

Consistent frontmatter fields make exact filters and saved reports possible. Inspect actual coverage and types with
```
sense map
```
.
ISO 8601 dates can be compared by the selected store's date functions. Mixed date formats can still be stored, but do not make a dependable time range.
A one-line
```
summary
```
appears in results and receives more lexical weight than body text. Its cost is keeping it current.
Folders are the natural unit for preset coverage. Frontmatter is the natural unit for status and ownership.
Small notes give precise hits and cheap whole-file reads. Large notes still work because
```
peek
```
,
```
sections
```
, and search
```
lines
```
point at ranges, and vector chunking splits long sections.
Save recurring questions under
```
queries
```
. Use
```
{ "sql": "..." }
```
for deterministic filters and reports, and
```
{ "search": "..." }
```
for ranked retrieval.

Field names in examples are illustrative. The tree defines its own schema. Reserved frontmatter keys are

path

_mtime

_ctime

_size

_rank

_parse_error

content

links

, and

sections

; sense drops them with a warning.

Sense接受异构的markdown。以下选择决定了哪些查询将是可靠的：

一致的frontmatter字段使精确过滤器和保存的报告成为可能。使用
```
sense map
```
检查实际覆盖范围和类型。
ISO 8601日期可以通过所选存储引擎的日期函数进行比较。混合日期格式仍然可以存储，但不能构成可靠的时间范围。
单行
```
summary
```
会出现在结果中，并比正文获得更多词法权重。其代价是必须保持其最新。
文件夹是预设覆盖范围的天然单位。Frontmatter是状态和所有权的天然单位。
小型笔记能提供精确的命中结果和廉价的整文件读取。大型笔记仍然有效，因为
```
peek
```
、
```
sections
```
和搜索
```
lines
```
指向范围，向量分块会拆分长章节。
将重复出现的问题保存在
```
queries
```
下。使用
```
{ "sql": "..." }
```
进行确定性过滤和报告，使用
```
{ "search": "..." }
```
进行排序检索。

示例中的字段名仅作说明。树结构定义自己的schema。保留的frontmatter键为

path

、

_mtime

、

_ctime

、

_size

、

_rank

、

_parse_error

、

content

、

links

和

sections

；sense会丢弃它们并发出警告。

Validate the result

验证结果

Run

sense status

to confirm the store, cache, document count, embedding state, watcher state, and preset coverage. Run

sense map

to confirm the discovered fields and their observed types.

Run every saved query after editing it. A parameterized SQL query can use any value because preparing the statement validates its columns and syntax before the parameter changes the result.

Record choices that should outlive the setup conversation in the tree's maintained agent guidance or in an authored note. The sense config should contain executable settings and reusable queries, not prose policy.

运行

sense status

以确认存储引擎、缓存、文档数量、嵌入状态、监视器状态和预设覆盖范围。运行

sense map

以确认发现的字段及其观察到的类型。

编辑后运行每个保存的查询。参数化SQL查询可以使用任何值，因为准备语句会在参数改变结果之前验证其列和语法。

将应在设置对话之后继续有效的选择记录在树结构维护的Agent指南或撰写的笔记中。sense配置应包含可执行设置和可重用查询，而不是散文式策略。