sense-setup

sense 配置与树结构设计

使用此技能创建或更改 sense 配置。查询现有树属于 sense 技能。常见树形结构的配置示例见 EXAMPLES.md。

设置树

安装 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，确认预设覆盖范围和所选存储。影响索引内容的更改会重建相关缓存，并报告原因。启用构建的命令会替换不兼容的派生缓存格式，并修复不完整的功能状态；配置中的 "build": false 或 --no-build 会报告所需的构建，但不会重建或修复 Sense 索引。

选择存储

根据缓存的预期用途进行选择。如果周边工作流没有倾向于其他引擎，请先从 sqlite 开始，再考虑互操作性、SQL、连接行为以及有代表性的 Sense 测量结果。当前的耗时结果并不能决定某个引擎的长期适用性。

存储	适用情况	主要权衡
sqlite	树需要尽可能简单的设置、高级 FTS5 搜索语法，或并发运行 Sense 命令	随 Node 一同提供；原始 SQL 使用 SQLite
duckdb	缓存需要用于大型数据集上的 DuckDB 分析工作，或用于本地／云端工作流，或需要 DuckDB 类型和 SQL	Sense 适配器处于实验阶段，原生安装包较大，同一时间只能打开一个连接
turso	树可从嵌入式 Rust 引擎或 Tantivy 索引中受益，或正在评估该引擎随适配器演进的表现	Sense 适配器处于实验阶段，搜索语法受限，同一时间只能打开一个连接

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

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

只有在延迟或检索质量可能影响选择时，才阅读性能权衡。这份简短比较根据已认可的版本报告生成；详细测量结果保留在 Git 中。

每种存储都使用单独的缓存文件。更改 store 会重建索引，而不是迁移旧缓存。命令和公共表是通用的，但原始 SQL 和高级词语搜索语法取决于所选引擎。

设计预设

预设是一个命名的、自包含的范围。必需的 default 预设用于无参数命令。其他预设通过名称选择。

字段	含义	默认值
include 和 exclude	预设涵盖的文件	必须指定 include
k	搜索结果数量	10
signals	启用的搜索信号及其倒数排名权重	每个可用信号的权重均为 1
where	固定的 frontmatter 筛选条件	无

只要某个预设包含文件，该文件就会被索引。预设可以重叠。不属于任何预设的文件不会进入索引。

对 raw/、notes/ 和 archive/ 等稳定层级使用路径。对 status、project 和日期等可变状态使用 frontmatter 筛选条件。预设控制索引范围，因此在运行 frontmatter 查询之前，必须能通过路径计算出其覆盖范围。

如果树的不同部分需要不同的搜索信号或结果数量，请使用单独的预设。用途单一的树无需额外的预设名称。

配置向量

向量需要做出两项选择。顶层 embed 块指定模型和提供方。每个预设的 signals 决定该范围是否使用向量。

{
  "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 }
    }
  }
}

配置中的 "build": true 默认值允许 CLI 查询准备所需的能力。对于手动构建或监视工作流，请设置 "build": false。首次启用构建的向量搜索会下载指定的静态模型，并为符合条件的范围生成嵌入。无论此设置如何，sense build 和 sense watch 都会准备所有已配置的能力；如果 CI、离线工作或时间安排需要，sense download 可提前获取模型。更改提供方、模型、有效端点、向量覆盖范围或分块方式的配置变更，可能会使向量失效或触发重建。配置中的 "build": false 或 --no-build 要求所请求的向量范围已就绪，且不会读取更新的实时文件。

选择提供方或模型、支持非英语目录、调整分块大小或调整信号权重时，请阅读嵌入设置。

设计可查询的笔记

Sense 接受多种格式的 Markdown。以下选择决定了哪些查询能够可靠运行：

• 一致的 frontmatter 字段可实现精确筛选和保存报告。使用 sense map 检查实际覆盖范围和字段类型。
• ISO 8601 日期可通过所选存储的日期函数进行比较。可以存储混合日期格式，但它们无法支持可靠的时间范围查询。
• 单行 summary 会显示在结果中，且获得的词法权重高于正文文本。代价是需要及时更新。
• 文件夹是预设覆盖范围的自然单位。Frontmatter 是状态和归属信息的自然单位。
• 小型笔记能提供精确命中，也能低成本地读取整个文件。大型笔记同样适用，因为 peek、sections 和搜索结果中的 lines 会指向具体范围，而向量分块会拆分较长的章节。
• 将常见问题保存在 queries 下。使用 { "sql": "..." } 执行确定性的筛选和报告，使用 { "search": "..." } 进行排序检索。

示例中的字段名称仅作说明。目录定义自己的架构。保留的 frontmatter 键包括 path、_mtime、_ctime、_size、_rank、_parse_error、content、links 和 sections；sense 会发出警告并丢弃这些键。

验证结果

运行 sense status，确认存储、缓存、文档数量、嵌入状态、监视器状态和预设覆盖范围。运行 sense map，确认发现的字段及其观察到的类型。

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

将需要在设置对话结束后继续生效的选择，记录在目录维护的 Agent 指引或自行撰写的笔记中。sense 配置应包含可执行的设置和可复用的查询，而不是策略说明文字。