AI-Wiki

文档概览

该页当前可见的摘录内容并不是一篇完整的文字化架构说明，而是直接给出一段 SQL schema。这段 schema 用来表达一种架构演进方向：把“观察记录”统一落入 observations 主表，并围绕结构化存储、渐进披露、可检索性以及全文搜索同步进行设计。因此，这个来源页更像是“用数据库结构描述目标架构”的片段，而不是逐段解释设计动机、迁移步骤或权衡取舍的文档。

关键事实

observations 表的定位

原文首先创建 observations 表，并在注释中将其描述为“Rich, structured schema”，即更丰富、结构化的 schema。该表承担观察记录的主存储职责，字段可按以下几组理解。

1. 标识字段

id INTEGER PRIMARY KEY AUTOINCREMENT：自增主键。
session_id TEXT NOT NULL：会话标识，不能为空。
project TEXT NOT NULL：项目标识，不能为空。

此外，表末尾声明了外键：

FOREIGN KEY(session_id) REFERENCES sdk_sessions(id) 这表示 session_id 关联到 sdk_sessions(id)。

2. 渐进披露元数据

原文在这组字段前写有注释 -- Progressive disclosure metadata。对应字段为：

title TEXT NOT NULL：标题，不能为空。
subtitle TEXT：副标题，可为空。
type TEXT NOT NULL：类型，不能为空。

其中 type 后面的注释给出示例：

-- decision, bugfix, feature, etc. 也就是说，类型字段至少被设想用于表示 decision、bugfix、feature 等类别。

3. 内容字段

原文在 -- Content 注释下定义内容相关字段：

narrative TEXT NOT NULL：正文性叙述内容，不能为空。
facts TEXT：事实集合。

其中 facts 的注释非常关键：

-- JSON array 这说明 facts 虽然在 SQLite 中以 TEXT 形式存放，但语义上被设计为 JSON 数组，而不是普通自由文本列。

4. 可检索字段

原文在 -- Searchability 注释下定义可检索相关字段：

concepts TEXT
files_read TEXT
files_modified TEXT

这几个字段的注释进一步说明了预期结构：

concepts TEXT, -- JSON array of tags
files_read TEXT, -- JSON array
files_modified TEXT, -- JSON array

也就是说：

concepts 被设计为标签集合，语义上是 JSON array of tags。
files_read 被设计为读取过的文件列表，语义上是 JSON array。
files_modified 被设计为修改过的文件列表，语义上是 JSON array。

5. 时间字段

原文在 -- Timestamps 注释下定义时间相关字段：

created_at TEXT NOT NULL
created_at_epoch INTEGER NOT NULL

这里同时保留文本时间和 epoch 整数时间，两者都被要求非空。

重要细节

observations 表中必须点名的字段

按原文，observations 表至少明确包含以下字段：

session_id
project
title
subtitle
type
narrative
facts
concepts
files_read
files_modified
created_at
created_at_epoch

若连同主键一起计入，则还包括：

id

JSON array 注释的边界

原文并没有把 facts、concepts、files_read、files_modified 定义成 SQLite 的专门 JSON 列类型，而是都写成 TEXT。但注释明确表明它们承载的是 JSON 数组语义：

facts：JSON array
concepts：JSON array of tags
files_read：JSON array
files_modified：JSON array

因此，这里的结构化依赖于约定的数据编码，而不是依赖列类型本身强制约束。

全文检索使用 SQLite FTS5

原文随后创建虚拟表：

CREATE VIRTUAL TABLE observations_fts USING fts5(...)

这明确指出全文检索机制采用的是 SQLite FTS5。被纳入全文检索的列共有 5 个：

title
subtitle
narrative
facts
concepts

值得注意的是，files_read 与 files_modified 并未被放入该 FTS5 表定义中，因此至少在这段 schema 里，它们不是全文索引同步的对象。

observations_fts 与主表的关联方式

原文在 FTS5 定义中包含：

content=observations

这说明 observations_fts 通过 content=observations 与主表 observations 关联，而不是完全独立维护一份无绑定内容的搜索表。

自动同步触发器 observations_ai

原文最后定义了一个插入触发器：

CREATE TRIGGER observations_ai AFTER INSERT ON observations BEGIN ... END;

这说明在 observations 表发生插入后，会自动执行同步逻辑。触发器内部执行的 SQL 为：

INSERT INTO observations_fts(rowid, title, subtitle, narrative, facts, concepts)
VALUES (new.id, new.title, new.subtitle, new.narrative, new.facts, new.concepts);

可以据此确认以下事实：

触发器名称是 observations_ai。
触发时机是 AFTER INSERT。
触发对象是 observations。
同步写入的目标是 observations_fts。
observations_fts.rowid 使用 new.id。
被同步的字段正好是 title、subtitle、narrative、facts、concepts。

该摘录没有展开的内容

虽然页面标题为 “Architecture Evolution”，但当前摘录只展示 schema 与触发器定义，没有进一步展开：

为什么要从旧架构演进到这套结构；
与旧表或旧搜索方案相比的差异；
更新、删除时如何保持 FTS 一致性；
JSON 数组内部的具体格式约束；
查询示例、索引维护策略或迁移脚本。

因此，本页只能忠实整理“当前摘录明确出现的结构设计”，不能把未出现的迁移逻辑或设计理由补写成既成事实。

Architecture Evolution 摘要