Kun 混合线程持久化边界:JSONL 权威存储与 SQLite 可重建索引的职责解耦实战

原创2026-10-11 09:02:001,428 阅读
文章标签:AI 应用人工智能AI Agent代码智能体交互助手桌面应用多智能体Agent 编排Agent 工作流工具调用Agent 记忆本地部署LLM 网关MCP Clients前端CLI

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 这条能力边界明确定义了两条新增需求:

  1. 索引与文档所有权分离:SQLite 索引操作、线程/会话文档读取、投影组装、恢复与回填必须隔离在类型化边界(typed boundaries)之后;
  2. 持久化格式兼容:抽取过程不得改变 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 验证了三类关键时序:

  1. 关机竞态:文件系统发现尚未完成时 stop(),之后 isIndexReady() 与 isUsageReady() 均为 false,且不触发任何 scanEvents / insertUsage / markUsageBackfilled;
  2. 迟到结果不落盘:扫描已发起后才 stop(),即使 deferred 晚些 resolve,noteExistingHighWater / insertUsage / markUsageBackfilled 都不得被调用;
  3. 失败可重试:索引发现失败或 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。

七、兼容性验证:黄金夹具、健康审计与验证证据

边界规范落地后的验证分三层:

  1. 黄金夹具:改造任务 7.1 要求「golden existing-data fixtures covering SQLite index, JSONL history, legacy threads, backfill, archive/search, and usage recovery」(见 tasks.md),确保既有数据目录的读取与写入语义不漂移;
  2. 最终审计对比:HybridThreadStore 从基线 1,382 行降至 817 行(缩减约 41%),并明确其当前拥有者为「index repository、document/legacy repository、projection assembler、backfill coordinator」,门面有意保留为唯一的 SQLite/schema 与元数据队列写入者(见 audit.md);
  3. 端到端证据:审计的持久化兼容对比确认「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 为可重建索引的本地优先应用,这套「门面 + 仓库 + 协调器」的拆解与验证路径都值得直接借鉴。

登录后查看全文
Kun