DeepSeek-Reasonix会话目录架构：SQLite投影如何让桌面端秒开会话列表

DeepSeek-Reasonix会话目录架构：SQLite投影如何让桌面端秒开会话列表

【免费下载链接】DeepSeek-ReasonixDeepSeek-native AI coding agent for your terminal. Engineered around prefix-cache stability — leave it running.项目地址: https://gitcode.com/GitHub_Trending/de/DeepSeek-Reasonix

DeepSeek-Reasonix 是一款为终端而生的 DeepSeek 原生 AI 编程 Agent，它的桌面端能在积累数百个会话后依然"秒开"会话列表。答案就藏在它的**会话目录（Session Catalog）**里：Reasonix 用一个可丢弃的SQLite 查询投影替代了启动时的磁盘全量扫描，让项目树、话题列表、会话预览都能从内存级数据库直接读出。这篇指南带你读懂这套架构的设计思路与关键实现。

为什么会话列表曾经会慢：启动时实时扫盘的代价

想象一下：你开了 500 个会话，分散在 20 个项目目录里。如果桌面端每次启动都要遍历每个目录、逐个解码 JSONL 转录文件、统计轮次数、重建话题树，启动时间就会从秒级膨胀到分钟级，而且扫描期间侧边栏只能显示"加载中"。

传统的应对办法是写一个缓存，但缓存很快会带来新问题：缓存和磁盘文件不一致怎么办？缓存损坏怎么办？缓存跨版本升级怎么办？

Reasonix 的答案是把缓存的定位想清楚：它不是缓存，而是一个可以随时扔掉重建的"投影"（Projection）。真正权威的会话数据始终是磁盘上的转录文件、事件日志、metadata sidecar 和desktop-projects.json——删掉 SQLite 数据库不会损失任何一条对话。

核心设计：把 SQLite 当成一次性投影

投影数据库位于<缓存根目录>/session-catalog/v5.sqlite，整个生命周期由通用的projectiondb包托管（源码见internal/projectiondb/projectiondb.go）。它有几条值得借鉴的硬规则：

• 可丢弃性优先：业务数据必须保留在数据库之外，调用方永远有能力删库重建。
• 优雅降级：缓存目录不可写、或路径位于远程文件系统时，自动切换为内存模式（:memory:），存储故障绝不阻塞应用启动。
• 损坏自愈：打开时执行完整性检查，坏库被重命名为.corrupt-<时间戳>隔离，新库在后台从 sidecar 和转录文件重建；旧版本留下的v1~v4缓存文件原样保留，方便回滚，也避免新旧进程交叉写入同一文件。
• 只存查询字段：目录签名与扫描代次、项目的排序/标题/置顶、话题的聚合计数与活动时间、会话的路径/预览/指纹/健康状态——全是"列表页需要的东西"，不存任何对话正文。

表结构在internal/sessioncatalog/schema.go中通过版本化迁移维护（schema_migrations台账），本地文件开启 WAL +synchronous=NORMAL，配合短 busy timeout，读写互不阻塞。

数据同步：后台 Worker 队列保持索引常新

投影的价值在于"永远是新鲜的"。internal/sessioncatalog/catalog.go中的Catalog启动了多个后台 worker，把"写索引"从关键路径上挪走：

1. 非阻塞写队列：会话转录成功落盘后，才会把索引更新按会话路径**合并（coalesce）**后投入队列，同一会话的多次更新只写一次。
2. 后台对账（reconcile）：目录扫描每批最多提交 64 个 sidecar 并持久化检查点，队列拥塞时丢弃的更新由对账循环兜底修复。
3. 修复 worker（repair）：老会话缺少轮次计数时先标记unknown——会话立即可见，随后由单个修复 worker 在后台解码补齐。
4. 缺失宽限：文件首次消失只标记 degraded，连续第二次扫描仍缺失且超过 30 秒宽限期后才从投影中移除，避免误删。

运行时状态（open / running）则完全不进 SQLite，只来自内存 controller 叠加显示——投影里永远没有"过期状态"这种尴尬。

分页查询与增量刷新：cursor + revision 双保险

桌面端的读取路径被压缩到了极致，核心 API 定义在desktop/session_catalog.go：

• GetProjectTreeSnapshot：返回项目壳、目录状态、索引进度与 revision，不打开任何会话文件。
• ListProjectTopics：话题列表分页，使用(pinned, last_activity_at, topic_id)三元组keyset cursor游标（默认每页 50 条、上限 200 条），翻到第 100 页也不会出现 OFFSET 深分页的性能塌陷。
• project-tree:changed-v2事件：携带单调递增的 revision、受影响的 workspace root 和变更原因，客户端忽略旧 revision、只刷新已展开的受影响项目——滚动列表时没有整树重绘。

正因为启动和项目树请求从不解码 JSONL、不等目录扫描，会话列表的呈现只取决于一次索引查询，这就是"秒开"的全部秘密。

出问题时怎么办：只读诊断与一键重建

Reasonix 给运维留了两条安全命令（详见docs/SESSION_CATALOG.md及中文版docs/SESSION_CATALOG.zh-CN.md）：

# 只读检查：不创建、不修改任何索引 reasonix sessions diagnose --json # 替换一次性投影并重建全部桌面项目索引 reasonix sessions reindex --json

reindex绝不触碰转录、事件、metadata、recovery 或项目文件，重建后旧的索引文件保留为.replaced-*副本可回滚。项目树 UI 里也有对应的"手动重建"入口和实时索引进度展示。

关键源码与文档导读

总结：这套架构给普通项目留下了什么启发 🎯

DeepSeek-Reasonix 的会话目录架构证明了一件事：慢，往往不是查询不够快，而是把"扫描世界"放在了关键路径上。把权威数据留在磁盘、把数据库降级为可丢弃的查询投影，再配上后台对账、缺失宽限和一键重建，列表页就能同时做到秒开、常新、可恢复。如果你的应用也有"启动时全量扫盘"的痛点，internal/sessioncatalog和internal/projectiondb这两个包值得逐行读一遍。

【免费下载链接】DeepSeek-ReasonixDeepSeek-native AI coding agent for your terminal. Engineered around prefix-cache stability — leave it running.项目地址: https://gitcode.com/GitHub_Trending/de/DeepSeek-Reasonix