Storage and Data Model zh CN

存储与数据模型

语言： English · 简体中文

LWC 把持久知识保存在 SQLite 中，并明确规定所有文件系统投影都从属于规范数据库。本页说明公开 CLI 背后的数据归属、表族、身份与迁移规则。

修改 schema、备份行为、Source identity、Page replacement 或文件布局之前，应先阅读本页。

文件系统布局

project/
`-- .lwc/
    |-- wiki.db                 规范 project Wiki
    |-- config.json             项目部署配置
    |-- wiki/                   生成的 Markdown
    |-- work/                   live 持久 Work
    |-- checkpoints/            命名式 SQLite checkpoint
    |-- changesets/
    |   |-- <name>.db           稀疏草稿数据库
    |   `-- draft-<name>/       草稿 Work 与图 sidecar
    |-- graph-grafeo/           当前派生文档图
    |-- graph-surrealdb/
    `-- codegraph/              项目本地代码索引

user home/
`-- .lwc/
    |-- wiki.db                 global Wiki
    |-- config.json             全局默认配置
    |-- runtime/codegraph/      按版本和 target 缓存的固定 runtime
    `-- agent-installs/         集成 ownership receipt

具体存在的 graph sidecar 取决于配置。以上目录都不是受支持的手工编辑入口。

规范表族

表族	主要记录	Invariant
身份与治理	meta	Store ID 稳定；规范状态改变时 revision 改变；Purpose 与 Schema 非空
证据	sources、source_path_revisions	Source 内容不可变并按 SHA-256 去重；path observation 有 revision
维护知识	pages、page_sources、page_provenance、links	Page replacement 同时更新正文、grounding、provenance 与 links
Ingest	ingest_jobs	每个 Source 对应一个持久状态机
强上下文	tags、page_tags	成员关系显式声明并按 priority 排序
语义图	semantic_relations	显式 typed relation 保留 provenance、reason 与 cited Source IDs
检索控制	retrieval_weights、retrieval_feedback	可审计调整不能凭空创造 lexical candidate
检索投影	search_fts、search_spans、span_fts	派生行与 active 规范文档及其指纹一致
审计与恢复	operations、changesets 和 inverse metadata	状态变更可追溯、可恢复

SQLite foreign key 与 CHECK constraint 会尽可能约束受支持状态、provenance class、weight range、tag budget 和 relation ownership。跨投影的高层 invariant 则由 Store transaction 与 lint 负责。

Source 身份

Source 具有两种互补身份：

1. content_hash 在单个 Wiki 内标识不可变 UTF-8 bytes；
2. source_path_revisions 记录某个 tracked path 在 revision N 指向哪一份 Source。

加入相同内容时会复用已有 Source，不会存第二份。文件内容变化后会获得新 Source ID 并推进 path head，历史 revision 保持冻结。

删除当前 tracked revision 会取消该 path 的跟踪，不会让旧 revision 自动重新成为 current。Page 或历史仍依赖一份 Source 时，删除证据会受到约束。

Page 身份与替换

Page slug 是稳定身份和 Wiki 文件名。Replacement 会保留 created_at、更新 updated_at，并把以下维护字段作为一个逻辑操作整体替换：

• title、kind、summary 与 body；
• cited Source set；
• explicit provenance set；
• 从 [[wikilinks]] 解析出的 outgoing links；
• document 与 span search rows；
• operation record 与 Store revision；
• 图投影启用时的 dirty graph document key。

调用方必须先读取当前页面并保留仍然有效的知识。替换语义是刻意设计的：本次省略的 citation 或 provenance 不会暗中残留。

检索文档与 Span

Document FTS row 是按 document type 和 identifier 定位的 contentless projection。独立的 active span record 指向当前正文中的准确 byte range，并携带：

• passage 或 sentence 类型；
• parent 与 ordinal；
• byte start 与 end；
• content fingerprint；
• segmenter version。

文档变化后，旧 locator 会变成 inactive。span get 会拒绝 stale fingerprint，而不会猜测附近的新文本。

Operation 与 Revision Fingerprint

规范 mutation 会追加一条 operations 记录，包含 action、target、结构化 detail 和 timestamp。Search 与 lint 默认是私密读取，只有调用方显式要求时才记录。

Store revision 是内容指纹，并非单调递增整数。Changeset 为 touched entity 捕获 base fingerprint；checkpoint restore 也会检查安全快照与替换之间 live revision 是否推进。

不要通过 revision 字符串推断时间顺序，应使用 operation ID 与 timestamp 做审计排序。

Transaction 模型

LWC 使用开启 foreign key、带有界 busy timeout 的 WAL-mode SQLite。Mutation 如果需要在读取和修改关联行之前先占用写入路径，会使用 immediate transaction。

Transaction 覆盖规范状态与 SQLite search projection。External graph Work 和文件系统物化位于数据库 transaction 之外，只能在规范提交后执行。

这种分割会明确报告 partial-success，而不是假装存在跨系统分布式 transaction。

生成 Markdown

Materialization 会根据 SQLite 渲染 Purpose、Schema、index、Pages 和面向 Source 的导航。文件先暂存，再作为 owned artifact 替换；多余或过期文件只通过 LWC 的 manifest-aware projection 清理。

直接修改 .lwc/wiki/ 的内容会被覆盖或忽略。知识变更必须使用 Page、Source、tag、Purpose 或 Schema 命令。

草稿存储

稀疏 changeset 只保存 touched entity、base observation、staged operation 与 merge metadata。查询和 lint 时，会只读 attach live store 构成 overlay。

每份草稿都有根据合法名称派生的独立运行目录。Work 与 graph sidecar 都限定在其中，因此草稿 A 无法查询或取消草稿 B 的 Work，也看不到对方的图节点。

Commit 在合并 live 之前持久化带 checksum 的 inverse payload。可选字段保持兼容序列化，升级后仍能验证旧 inverse patch。

Checkpoint

命名式 checkpoint 使用 SQLite online backup API，作为普通 .db 文件存放在 checkpoints/ 下。Restore 会在写入 live 前校验私有 candidate，并创建 pre-restore-* 安全 checkpoint。

Checkpoint 文件包含完整 SQLite 数据库，包括派生 FTS 表，但不包含外部文件系统状态。Restore 之后会重新物化 Markdown，并排入新的文档图投影。

Schema 版本

PRAGMA user_version 与 meta.format_version 标识 Store 格式。Tokenizer identifier 也会持久化，因为 normalization 变化会使检索投影失效。

受支持迁移按照明确顺序执行。耗时 schema migration 会通过 shadow database 和安全 checkpoint 作为 Work 运行，而不是在没有恢复手段的情况下直接改旧数据库。

遇到未知的未来版本时返回 unsupported_store_version。LWC 不会猜测如何降级较新的 Store。

完整性规则

禁止：

• 用数据库 GUI 打开并编辑 wiki.db；
• WAL 写入可能活动时只复制一个 wiki.db；
• 在 checkpoint 目录中伪造数据库文件；
• 脱离已校验 live binding 移动草稿数据库；
• 通过修改 FTS、Work、graph 或 materialized file 修复规范知识；
• 把 .lwc runtime state 提交到源码仓库。

应使用 CLI mutation、lint、checkpoint、changeset recovery、maintenance Work 与 graph verify。

下一篇：检索、排序与索引