Kun 混合线程持久化边界:JSONL 权威存储与 SQLite 可重建索引的职责解耦实战
Kun 混合线程持久化边界:JSONL 权威存储与 SQLite 可重建索引的职责解耦实战
导读
本文围绕 Kun 健康改造(openspec 变更 remediate-project-health-hotspots)中的 hybrid-thread-persistence-boundaries 边界规范展开,讲解 Kun 的混合线程持久化(Hybrid Thread Persistence)如何在不迁移任何历史数据的前提下,把 SQLite 索引操作、线程/会话文档读取、投影组装、恢复与回填拆分为各自的单一拥有者。读完本文,你将掌握 Kun 线程数据「JSONL 为权威、SQLite 为可重建索引」的底层布局、HybridThreadStore 门面与各内部仓库的职责划分、字节级兼容的实现与验证方法,以及合并规则、事件高水位、后台回填在关机/异常场景下的保真机制。
一、规范背景:为什么需要为线程持久化划定边界
Kun 的混合线程存储是项目健康审计中体量最大的热点之一。在改造前的基线中,kun/src/adapters/hybrid/hybrid-thread-store.ts 单文件达到 1,382 行(见 baseline.md),它同时承担了线程索引、JSONL 文档读取、投影组装、恢复回填等多类职责,任何局部改动都会波及整条持久化链路。
remediate-project-health-hotspots 变更(见 proposal.md)的核心目标不是引入新功能,而是为每个负载状态机(load-bearing state machine)确立单一拥有者(narrow owner),让每个抽取出的服务在不依赖 Electron、网络、文件系统或 React 的情况下可独立测试、可回滚、可发布。其中 hybrid-thread-persistence-boundaries 这条能力边界明确定义了两条新增需求:
- 索引与文档所有权分离:SQLite 索引操作、线程/会话文档读取、投影组装、恢复与回填必须隔离在类型化边界(typed boundaries)之后;
- 持久化格式兼容:抽取过程不得改变 SQLite schema、JSONL 记录、遗留线程文件、文件名或恢复优先级,打开既有数据目录时 list / get / search / archive / usage recovery 及后续写入必须无需迁移、无数据丢失地工作(见 spec.md)。
二、核心架构:JSONL 权威 + SQLite 可重建索引
理解边界的先决条件是 Kun 混合存储的数据布局。HybridThreadStore 的类注释直接写明了设计取向(见 hybrid-thread-store.ts):
Hybrid store inspired by Codex: JSONL files are canonical and SQLite is a rebuildable index. SQLite writes always happen after metadata JSONL has been appended.
即:JSONL 文件是权威数据,SQLite 只是可从 JSONL 重建的索引,且 SQLite 的每次写入都发生在对应 JSONL 追加完成之后。这决定了整个边界拆分的两条铁律——文档层负责权威数据,索引层负责可重建的查询结构,投影层负责两者的组装。
2.1 数据目录布局
从 hybrid-thread-store.ts 与 hybrid-thread-documents.ts 的路径构造可以确认,混合存储的数据布局如下:
| 数据 | 路径 | 内容与角色 |
|---|---|---|
| SQLite 索引 | <dataDir>/index.sqlite3 |
线程摘要与 usage 索引,可整体删除后重建 |
| 线程元数据 | <dataDir>/threads/<id>/metadata.jsonl |
kind: "thread_metadata"、version: 1 的快照行,turn 字段不含 item 正文 |
| 会话条目 | <dataDir>/threads/<id>/messages.jsonl |
权威的 TurnItem 记录流 |
| 运行时事件 | <dataDir>/threads/<id>/events.jsonl |
RuntimeEvent 追加流,含 usage 事件 |
| 遗留线程文件 | <dataDir>/threads/<id>/thread.json |
改造前遗留的整线程 JSON,读取优先级低于 metadata.jsonl |
测试 hybrid-store.test.ts 验证了「item 正文只存在于 messages.jsonl、索引与 metadata 快照不含正文」这一事实:写入线程后,metadata.jsonl 不包含 hello from jsonl,而 messages.jsonl 包含,get() 能正确组装出 turn 与 item。
2.2 门面与端口契约
HybridThreadStore 本身在改造后收缩为 ThreadStore 门面(见 hybrid-thread-store.ts),对外实现 thread-store.ts 定义的端口接口:list、listPage、indexStatus、get、getMetadata、touch、upsert、upsertIfRevision、delete 等。该端口接口即规范所说「类型化边界」的一部分——上层(服务、循环、服务器)只依赖端口,不感知内部仓库的划分。门面持有的不再是散落的文件读写逻辑,而是以下四个明确拥有者的组合:索引仓库、文档仓库、投影组装逻辑、回填协调器。
三、边界一:索引与文档所有权分离
规范第一条需求要求把「SQLite 索引操作」与「线程/会话文档读取、投影组装、恢复、回填」隔离在类型化边界之后。改造后,这些职责分别落在四个独立模块上。
3.1 索引仓库:HybridThreadIndexRepository
hybrid-thread-index.ts 中的 HybridThreadIndexRepository 是 SQLite 侧的唯一拥有者,职责包括:
- 查询:
query(options)按ThreadStoreListOptions生成 WHERE 条件,支持 archivedOnly / includeArchived / includeSide / workspace / workspaces / search / keyset cursor 分页,按updated_at_ms DESC, id DESC排序;count(options)提供总数; - 写入:
upsert使用带ON CONFLICT(id) DO UPDATE的预编译语句,其中event_seq_high_water以MAX(threads.event_seq_high_water, excluded.event_seq_high_water)合并,保证高水位只增不减;upsertMany将整个回填批次放进单个事务; - 路径修复:
repairPaths(threadId)用于数据目录迁移后修正metadata_path / messages_path / events_path这三个派生绝对路径(见 hybrid-thread-store.ts 的rowHasReadableJsonl逻辑——JSONL 是权威、SQLite 路径是派生的,因此数据目录搬家不能让合法线程凭空消失); - 删除:
delete同时清理threads与usage_events中对应行。
行与记录的映射(rowFromIndexRecord、summaryFromRow、search_text 拼装)集中在 hybrid-thread-index-mapping.ts,这是索引层内部唯一的映射模块。
3.2 文档仓库:HybridThreadDocumentRepository
hybrid-thread-documents.ts 中的 HybridThreadDocumentRepository 是「canonical JSONL/legacy 读取、恢复优先级、记录缓存」的拥有者,关键设计:
- 恢复优先级:
readThread先读metadata.jsonl最新快照,缺失时回落到thread.json遗留文件(readLatestMetadata → readLegacyThread),再通过hydrateThreadItems用水合后的条目流组装完整记录; - 增量折叠(mirror):
metadataMirrors与itemsMirrors记录每个线程文件的ino / byteOffset / mtimeMs标记,追加日志只在尾部折叠新行(foldMetadataLines/foldItemLines),避免逐条重解析整段历史;isContinuation通过 inode、大小与 mtime 判断是追加还是重写,原子压缩改名(inode 换新)会强制全量重读; - 有界缓存:线程记录缓存限制为 128 条且最大 16 MiB(
THREAD_RECORD_CACHE_LIMIT/DEFAULT_THREAD_RECORD_CACHE_MAX_BYTES),镜像缓存分别限制为 256 / 16,防止无限增长。
3.3 投影组装:merge rules 的唯一拥有者
投影组装逻辑集中在 hybrid-thread-projection.ts,包括 stripThreadItemBodies(快照中剥离 item 正文)、hydrateThreadItems(把权威 item 流合入线程记录)、normalizeThreadMetadataFromRecovered 与 accumulateTurnMetadata(跨整段历史折叠恢复 turn 元数据)。规范第一条的验收场景「Read indexed thread with JSONL history」要求:当线程同时具备索引元数据与持久化 item 历史时,组装出的线程与摘要必须保持当前全部合并规则——这正是该模块的测试重点(详见第六节)。
3.4 回填协调器:HybridThreadBackfillCoordinator
hybrid-thread-backfill.ts 中的 HybridThreadBackfillCoordinator 被注释明确为「Single-flight owner for startup index/usage recovery and stale-row cleanup」,负责:
- 索引回填:枚举文件系统线程 ID,与 SQLite 已有行比对,将缺失线程按批次(默认 200)读取 metadata 并
upsertMany单事务写入; - usage 回填:对每个线程单遍扫描
events.jsonl(见 hybrid-thread-usage-scan.ts 的scanEventsForUsageBackfill),得到高水位与 usage 事件,再经 hybrid-usage-backfill-sqlite.ts 的insertUsageEventsChunked按 200 条分块写入usage_events,并推进usage_backfill_high_water,全部提交后才markUsageBackfilled; - 状态暴露:
indexStatus在not_started / running / ready / failed间流转,isIndexReady()/isUsageReady(threadIds)供门面决定走索引查询还是 JSONL 扫描降级。
四、边界二:持久化格式字节级兼容
规范第二条需求的核心约束是:抽取不得改变 SQLite schema、JSONL 记录、遗留线程文件、文件名或恢复优先级。这对应设计文档中的决策 6「Keep persisted formats byte-compatible」(见 design.md):混合存储抽取只包裹既有 schema 与读取器,本变更不新增任何字段、文件名、索引 schema 或迁移标记。
4.1 SQLite schema 只增不改
hybrid-thread-store-migrations.ts 的 migrateHybridThreadStore 采用 CREATE TABLE IF NOT EXISTS 建表,threads 表以 id TEXT PRIMARY KEY 为主键,包含 title / workspace / model / agent_surface / status / approval_policy / sandbox_mode / created_at / updated_at / event_seq_high_water / metadata_path / messages_path / events_path / search_text 等列,并建立 updated_at_ms DESC, id DESC 的索引族;usage_events 以 (thread_id, seq) 为复合主键。历史版本缺失的列通过 addColumnIfMissing 追加(如 todos_json、extension_metadata_json、agent_surface、provider_id),且 migrateHybridUsageBackfillState 只在引入回填状态列时一次性 UPDATE threads SET usage_backfilled = 0 重开所有行——这些都属于兼容已有数据目录的加法式演化,而非破坏性迁移。
4.2 JSONL 与遗留文件格式不变
- metadata 行保持
{ kind: "thread_metadata", version: 1, timestamp, thread }的结构,快照仍经stripThreadItemBodies剥离 item 正文(见 hybrid-thread-projection.ts); messages.jsonl仍为权威 TurnItem 流,events.jsonl仍为RuntimeEvent追加流;- 遗留
thread.json继续通过ThreadSchemaReadable解析(见 hybrid-thread-documents.ts),且readMetadata的优先级保持「metadata.jsonl 优先、thread.json 兜底」; - 文件名与目录结构(
threads/<id>/...)完全不变。
测试 hybrid-store.test.ts 专门覆盖「打开遗留 thread.json → 归档搜索可用 → 后续写入落到 metadata.jsonl」的兼容链路,验证 legacy 文件可被读取、归档/搜索语义保留、后续 upsert 正常追加 JSONL。
4.3 「不加迁移」的验收场景
规范第二条的验收场景是「Open existing data directory」:打开改造前创建的数据目录后,list / get / search / archive / usage recovery 与后续写入必须无迁移、无丢失地工作。对应实现事实包括:
list()在索引未就绪、索引失败或存在脏索引线程时回落到文件系统扫描(hybrid-thread-store.ts),首个侧边栏请求不会被全量顺序重建阻塞;get()遇到索引行但 JSONL 不可读时删除该索引行并仍从磁盘读取(同文件 L179-L194);- 数据目录整体搬移后,
rowHasReadableJsonl通过repairPaths修正派生路径而非丢线程(测试见 hybrid-store.test.ts); - SQLite 文件被删除后,回填可从 JSONL 整体重建索引(测试见 hybrid-store.test.ts)。
五、恢复与回填的并发安全与关机语义
回填是混合存储中最容易产生「第二个写入者」的地方,因此规范要求其拥有单一协调器。HybridThreadBackfillCoordinator 通过 indexPromise / promise 实现单飞(single-flight):start() 已在运行或被 stop() 标记时直接返回;stop() 置 stopped 标志,所有批处理循环在每步后检查该标志;wait() / waitForIndex() 暴露给门面的 waitForBackfill()。
专项测试 hybrid-thread-backfill.test.ts 用 deferred promise 验证了三类关键时序:
- 关机竞态:文件系统发现尚未完成时
stop(),之后isIndexReady()与isUsageReady()均为 false,且不触发任何scanEvents / insertUsage / markUsageBackfilled; - 迟到结果不落盘:扫描已发起后才
stop(),即使 deferred 晚些 resolve,noteExistingHighWater / insertUsage / markUsageBackfilled都不得被调用; - 失败可重试:索引发现失败或 usage 写失败时保持未就绪状态,下一次
start()可重试;单线程扫描失败不影响后续线程继续回填。
这与最终审计 audit.md 中关闭的 B 级缺陷一致:「Shutdown now cancels and awaits background backfill before SQLite/cache closure」。门面的 shutdown() 实现为 await ready() → backfill.stop() → await backfill.wait() → close()(hybrid-thread-store.ts),close() 内先 flush() 事件高水位缓冲再关库。
5.1 事件高水位:JSONL 权威的又一体现
events.jsonl 的 seq 高水位是恢复正确性的关键。门面通过 EventHighWaterBuffer 按刷新窗口批量提交(「一个刷新窗口一个事务,而不是每条事件一次 SQLite commit」,见 hybrid-thread-store.ts),getEventSeqHighWater 取「SQLite 已存值」与「缓冲中待提交值」的较大者;而 highestSeq 在 SQLite 落后时会直接用持久化的 JSONL 高水位,防止进程在「JSONL 追加完成、索引钩子未执行」之间死亡后 seq 被重复使用(测试见 hybrid-store.test.ts)。
六、合并规则保真:投影组装的行为证据
规范第一条要求组装结果「preserve all current merge rules」,源码中的合并规则主要由 hybrid-thread-projection.ts 实现:
hydrateThreadItems(L28-L70):从权威 item 流中先过滤仅模型可见的内部记录(如 stable active-goal context,isPublicTurnItem),再按turnId分组回填;可从 items 恢复丢失的历史 turn(turnFromItems),按createdAt排序,但不覆盖用户对 queued turn 的持久化顺序;normalizeThreadMetadataFromRecovered(L82-L96):对每个 turn 用mergeTurnMetadata合并快照,prompt取「next.prompt || previous.prompt」,attachmentIds / activeSkillIds / injectedMemoryIds / injectedDirectiveIds等用mergeStringArrays去重合并,item 用mergeTurnItems按 id 去重;accumulateTurnMetadata(L109-L143):跨整段metadata.jsonl历史增量折叠每个 turn 的attachmentIds / model / mode / guiPlan / actingModelRoute / approvalPolicy / sandboxMode / approvalReviewer,使尾部追加读取无需重解析全部历史行。
测试对这几条规则给出了直接证据:
- hybrid-thread-projection.test.ts 验证水合时不把内部 goal context 泄漏进公开线程投影,且 legacy 保留路径同样过滤模型私有 item;
- hybrid-store.test.ts 验证重复的损坏 turn 元数据会被去重,且能从更早的 metadata 行恢复 attachmentIds;
- hybrid-store.test.ts 验证元数据被剥离时能从 user message 的 items 恢复
attachmentIds; - hybrid-store.test.ts 验证
startTurn经混合存储写入不会合成重复 turn。
七、兼容性验证:黄金夹具、健康审计与验证证据
边界规范落地后的验证分三层:
- 黄金夹具:改造任务 7.1 要求「golden existing-data fixtures covering SQLite index, JSONL history, legacy threads, backfill, archive/search, and usage recovery」(见 tasks.md),确保既有数据目录的读取与写入语义不漂移;
- 最终审计对比:
HybridThreadStore从基线 1,382 行降至 817 行(缩减约 41%),并明确其当前拥有者为「index repository、document/legacy repository、projection assembler、backfill coordinator」,门面有意保留为唯一的 SQLite/schema 与元数据队列写入者(见 audit.md); - 端到端证据:审计的持久化兼容对比确认「legacy JSON、SQLite index、JSONL recovery、archive/search、usage backfill、projection golden tests pass」;真实混合 smoke 写出了
index.sqlite3、每线程events.jsonl与metadata.jsonl,关机后不留 WAL/SHM 侧车文件;真实 Electron-as-Node 混合 serve smoke 也验证了 thread list/create/read/fork/archive/search 与 SIGTERM 干净退出(见 audit.md)。
八、实操:查看数据、运行验证与降级提示
- 查看数据目录:Kun 的数据根目录下,线程数据位于
threads/<threadId>/,索引位于index.sqlite3;metadata.jsonl与messages.jsonl均可用文本工具直接查看(记录为逐行 JSON)。 - 运行持久化专项测试:在
kun/目录下执行npm test即可运行 hybrid-store.test.ts、hybrid-thread-backfill.test.ts、hybrid-thread-projection.test.ts 等用例(项目使用 Vitest,见 vitest.config.ts)。注意:部分用例依赖better-sqlite3原生模块,测试内部通过canOpenBetterSqlite探测可用性,不可用时断言 SQLite 文件不存在、存储以 JSONL 降级方式工作。 - 降级与 ABI 提示:当
better-sqlite3加载失败(常见于 Node/Electron ABI 不匹配)时,hybrid-thread-support.ts 的describeSqliteAbiMismatch会把NODE_MODULE_VERSION差异归类为「compiled=… current=…」,并在警告中提示npm rebuild better-sqlite3(或npm ci),同时存储自动进入 JSONL 扫描降级模式,列表、读取与后续写入仍可用。
结语
hybrid-thread-persistence-boundaries 是 Kun 健康改造中「先定边界、再动代码」的典型样本:它没有迁移任何一行数据,也没有改变任何公开契约,只是把索引、文档、投影、回填四个职责分别交给类型化边界之后的单一拥有者,并用黄金夹具、专项时序测试与端到端 smoke 证明了「打开既有数据目录一切照旧」。对于任何以 JSONL 为权威、以 SQLite 为可重建索引的本地优先应用,这套「门面 + 仓库 + 协调器」的拆解与验证路径都值得直接借鉴。