AI-Wiki

定义

FTS-backed Observation Search 是该架构中为 observations 记录提供全文检索能力的一层实现机制。它的核心不是给主表加普通索引，而是使用 SQLite 的 FTS5（Full-Text Search 5）建立专门的全文检索表，以支持对 observation 文本内容进行搜索。

在当前架构里，这个检索层直接服务于 observations 表，因此它可以看作 Observation Schema 的搜索配套结构，也是 Architecture Evolution 摘要所描述架构演进中的一个具体实现点。

在本文档中的语境

来源展示的是一段数据库 schema 设计代码：一方面定义了 observations 主表，另一方面紧接着定义了全文搜索所需的 FTS 表和自动同步触发器。这说明搜索并不是外置系统，也不是后处理流程，而是内嵌在 SQLite 数据层中的一部分。

这层机制的关注点很明确：让 observation 的核心描述性内容在写入数据库后即可进入全文检索索引，而不需要应用层手工维护一份独立搜索副本。

关键机制与组成

基于 SQLite FTS5，而不是普通索引

来源中明确使用的是：CREATE VIRTUAL TABLE observations_fts USING fts5(...)。这表示搜索层采用的是 SQLite FTS5 虚拟表机制，而不是在 observations 表上为若干文本列建立普通 B-tree 索引。

这个区别很重要：普通索引更适合精确匹配、排序或范围查询；这里的目标则是全文检索，因此使用的是 FTS5。

`observations_fts` 是虚拟表

全文检索表名为 observations_fts，并且它是通过 CREATE VIRTUAL TABLE 创建的虚拟表，不是普通实体表。

该虚拟表纳入全文索引的字段共有 5 个：

title
subtitle
narrative
facts
concepts

这意味着 observation 的标题、子标题、叙述正文，以及以 JSON 形式保存的 facts、concepts，都会被写入全文搜索层，成为可检索内容。

`content=observations` 表示它与主表关联

FTS 表定义里包含 content=observations。这表示 observations_fts 不是完全孤立的一份搜索表，而是声明其内容来源关联到主表 observations。

从架构含义上说，observations 是主数据，observations_fts 是围绕主数据建立的全文检索表示层。搜索索引与主表记录之间存在明确对应关系，而不是一份来源不明的冗余副本。

自动同步方式

不是手工维护，而是由触发器自动完成

来源没有展示任何“应用层每次插入后再自己更新搜索表”的逻辑，相反，它直接在数据库里定义了自动同步触发器：CREATE TRIGGER observations_ai AFTER INSERT ON observations。

这说明搜索索引的插入同步不是手工维护，而是由数据库在 observations 表发生插入后自动执行。

`observations_ai` 的具体行为

触发器名称是 observations_ai，触发时机是 AFTER INSERT ON observations，即在主表新增一条 observation 之后执行。

其执行内容是：向 observations_fts 插入一条对应记录，并写入以下列：

rowid ← new.id
title ← new.title
subtitle ← new.subtitle
narrative ← new.narrative
facts ← new.facts
concepts ← new.concepts

也就是说，主表新记录的主键 new.id 被直接映射为 FTS 表中的 rowid，从而把一条 observation 与其全文索引项一一对应起来；与此同时，所有被声明为可搜索的文本字段也会从 new.* 写入 observations_fts。

细节与边界

当前摘录只展示了插入同步

来源代码只给出了一个 AFTER INSERT 触发器，也就是 observations_ai。因此当前能够明确确认的，是“新 observation 写入后会自动进入全文索引”。

但这段摘录没有展示：

AFTER UPDATE 类型的更新同步触发器
AFTER DELETE 类型的删除同步触发器

因此，基于现有材料，不能断言更新或删除时也一定会自动维护 observations_fts；只能说当前可见实现明确覆盖了插入场景，而未展示更新、删除场景的同步机制。

被索引的是特定字段，不是整张表所有列

FTS 表只包含 title、subtitle、narrative、facts、concepts 五个字段。像 session_id、project、type、files_read、files_modified、created_at、created_at_epoch 等列，在这段定义中都没有被纳入 observations_fts。

这说明该搜索层关注的是 observation 的可读内容与概念标签，而不是把主表中的每个元数据字段都做成全文索引。