DeepSeek-Reasonix 会话索引Session CatalogSQLite 查询投影架构与桌面启动实践指南【免费下载链接】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本文以仓库文档 docs/SESSION_CATALOG.zh-CN.md 为核心骨架结合internal/sessioncatalog包源码与桌面端实现系统讲解 Reasonix 的会话索引机制它以 transcript/event log/metadata sidecar 为唯一权威数据将桌面项目树读取收敛为对缓存根目录/session-catalog/v8.sqlite的一次性 SQLite 查询投影。读完本文你将掌握该投影的设计动机、不变量、存储与迁移细节、桌面 API、运维命令以及发布门禁要求能够在实际排查与调优中直接落地。为什么需要一个可丢弃的会话索引Reasonix 是面向终端、围绕 prefix-cache 稳定性设计的 AI coding agent。一个长期运行的会话会不断追加 transcript JSONL、event log 与 metadata sidecar这些文件本身就是唯一权威数据authoritative data。如果桌面侧栏每刷新一次就扫描整个磁盘目录、解码全部 JSONL不仅启动变慢还会在 agent 忙于推理时与核心 IO 争抢资源破坏 prefix-cache 的稳定性。解决方案是把树形展示需要的一切沉淀为一次性 SQLite 查询投影位于缓存根目录/session-catalog/v8.sqlite。它的核心特征在 internal/sessioncatalog/types.go 的包注释中写得很清楚Package sessioncatalog maintains a disposable SQLite projection of Reasonix session sidecars. Session JSONL/event/meta files remain authoritative; every row in this package may be discarded and rebuilt.即索引里的每一行都可以被删除并重建删除该数据库不会删除或修改任何会话。这是理解整个模块的一把钥匙——投影是可推导的权威数据在文件系统上。目录中的早期v1.sqlite至v5.sqlite缓存会被保留。原因是防止仍在运行的旧版本进程或回滚降级后的版本与新版交叉写同一个投影文件v6 引入文件系统感知的路径身份后首次启动会从权威文件重新建立索引旧 v5 文件仅用于回滚且不会被新版本写入。同一 v6 索引的手动重建也会留下带时间戳的.replaced-*旧文件便于随时回退。当前实现中生产默认路径已演进到 DefaultPath() 返回的v8.sqlite注释明确说明 v8 是为了把 v12 的 head 投影与 v11 的写入者隔离。不变量保证索引永远可被丢弃、可重建原文档列出了九条不变量它们是整个模块的正确性契约逐条对应源码实现启动与项目树请求零负担启动和项目树请求不会解码 transcript JSONL、执行旧版迁移或等待目录扫描。桌面 API 全部走 catalog 快照见桌面 API一节ListProjectTree也声明不再回退到同步文件系统扫描。落盘后再更新只有 transcript 成功落盘后 catalog 才会更新。保存观察器只做词法队列入队不做文件系统探测后台 worker 解析文件系统身份SQLite 唯一约束作为最终去重边界目录对账reconcile会修复队列拥塞时丢弃的更新。对应实现见 index_queue.go 与 reconcile.go。路径拼写 vs 身份 keysession 和 workspace root 的原始路径拼写继续用于文件访问和展示独立的 identity key 会解析别名如符号链接并且只在所属文件系统目录不区分大小写时折叠大小写——大小写敏感卷上的不同文件和项目不会被错误合并。跨平台的路径身份实现见 path_identity.go 及 darwin/windows 平台变体。unknown状态立即可见缺少旧版计数时使用unknown状态会话立即在侧栏可见随后由单个 repair worker 在后台解码修复。TurnsState的三种取值unknown/valid/corrupt定义在 types.go。过期投影不消失保存在写入列表戳记前被中断产生的过期投影同样是unknown但保留最近一次已知的 preview 和回合数作为未认证的提示修复期间该行不会从侧栏消失。两级缺失判定文件首次缺失只标记为degraded只有连续第二次扫描仍缺失且超过宽限期后才会从查询投影移除。健康状态ok/missing/corrupt/degraded定义在 types.go宽限期可通过Options.MissingGrace配置。运行时状态不入库open、running等实时状态只来自内存 controller 并覆盖 catalog 结果永远不持久化到 SQLite。可取消、不阻塞退出catalog、迁移、插件和 MCP 工作都可取消不参与桌面退出锁退出最多等待 catalog 待写入数据 250 ms。桌面端退出路径见 shutdown.go 与 session_catalog_runtime.go。ready 状态必须一致只有磁盘会话路径、scope/workspace、topic 投影和恢复派生字段均与当前权威文件一致时 ready 状态才可复用数量相等但路径错位也会触发重建。状态机opening/ready/degraded/rebuilding/closed定义在 types.go。存储与迁移从 v1 到 v12 的演进迁移台账与打开语义internal/sessioncatalog使用schema_migrations版本台账来自internal/projectiondb的Migration结构数据库文件存在不代表迁移完成。打开时逐版本执行 sessionMigrations() 中注册的 12 个迁移。WAL 与降级策略本地缓存使用 WAL、synchronousNORMAL和 150ms 的较短 busy timeout。这些 pragma 在 internal/projectiondb/projectiondb.go 中统一设置PRAGMA journal_modeWAL PRAGMA synchronousNORMAL PRAGMA foreign_keysON PRAGMA busy_timeout150Windows 上还做了 DSN 规范化C:/Users/...→file:///C:/Users/...避免裸file:C:\...URI 打开失败导致静默降级到内存projectiondb.go。当缓存目录不可用或明确位于远程文件系统时会降级为内存 catalogModeMemory连接池限制为 1 以规避 shared-cache 并发写问题避免存储故障阻塞应用。磁盘模式默认连接池上限为 4。损坏恢复打开数据库时 Reasonix 会执行完整性检查。损坏或无法迁移的数据库会被重命名附加.corrupt-时间戳后缀并由新数据库替代随后在后台根据 sidecar 和 transcript 重建。隔离和重建都不会删除权威文件。投影中存什么catalog 只保存查询投影schema.go 的 v1 基表定义catalog_directories目录签名signature、扫描代次scan_generation、检查点scan_cursor与错误catalog_projects项目排序、标题、颜色、置顶状态及 workspace root identity keycatalog_topicstopic 排序、聚合计数turns、活动时间、恢复、健康状态及 workspace root identity keycatalog_sessionssession 访问路径及 path/directory/workspace root identity key、preview、计数、内容与元数据指纹content_fingerprint/meta_fingerprint、恢复与健康状态catalog_heads对 schema 2 事件日志记录日志格式log_format、选中 headselected_head_id以及每个 head 一行的 head 投影来源是内核写出的 head 索引侧车与BranchMeta镜像而不是重放日志v12 迁移schema.go。关键索引schema.go保证了分页与过滤的查询路径idx_catalog_topics_page直接支撑(pinned, last_activity_at, topic_id)的 keyset 分页idx_catalog_sessions_directory支撑按目录的(directory, seen_generation, missing_since)扫描。版本演进路线迁移历史本身就是索引设计的演进史schema.go版本内容意义v1基表与索引目录/项目/topic/session 四类投影v2topics 增加metadata_present区分 topic 标题来源v3sessions 增加历史查询索引按 workspace 的活动时间分页v4sessions 增加recovery_copy恢复副本标记v5sessions 增加recovery_group_id/role/canonical恢复血缘分组v6/v7 继续扩展 branch 计数与逻辑 topicv7sessions 增加logical_topic_id、ordinary_visible恢复副本重新锚定到逻辑 topicv8新增catalog_folded_topicstombstone防止恢复副本的旧 topic 在行移走后复活为侧栏行v9引入path_key/directory_key并清空重建文件系统感知的身份与访问拼写分离SQL 无法安全回填故删除全部投影等待对账重建v10引入workspace_root_key并清空重建身份扩展至 workspace root唯一性全部基于文件系统 keyv11sessions 增加 repair 调度字段持久化修复重试预算repair_state/attempts/retry_at/error_kindv12heads 投影 生成文件迁到 v8.sqliteschema 2 事件日志的多 head 展示支持其中 v9/v10 是破坏性迁移DELETE FROM全表注释明确说明现有投影是一次性的必须重建因为 SQL 无法推断卷级的大小写语义——这正是身份 key 与展示拼写分离设计的具体落地。对账与分页参数topic 分页使用(pinned, last_activity_at, topic_id)keyset cursortopic_cursor.go默认每页 50 条、最多 200 条DefaultLimit/MaxLimittypes.go目录对账每批最多提交 64 个 sidecar并在让出调度前持久化检查点reconcile.go 与commitDirectoryProjection中的同批 64 上限。手动排序ManualOrder是请求级作用域从未手动排序的用户保持活动时间排序即使 metadata 行已有 sort 值。桌面 API树、分页、状态与重建桌面端通过 Wails App 方法暴露 catalog 能力实现在 desktop/session_catalog.go 与 desktop/session_catalog_runtime.goGetProjectTreeSnapshotsession_catalog.go返回项目壳、catalog 状态、进度和 revision不打开 session 或 sidecar 文件ListProjectTopics基于 cursor 的分页搜索和时间过滤参数见TopicPageRequestscope、workspaceRoot、cursor、limit、query、timeFilter、sortMode、manualOrderGetTopicSummary为 active-turn UI 查询单个 topic无需重建整棵树GetSessionCatalogStatussession_catalog_runtime.go与RebuildSessionCatalogsession_catalog_rebuild.go提供安全诊断与索引替换。状态同时报告最近修复原因repairReason、源文件数量sourceCount和未完成的目录目标项目树提供手动重建入口。Status结构还包含repairPending/active/deferred/blocked队列计数、physicalSessions/logicalSessions、recoveryGroups/branches/diverged、cleanupEligible与quarantinedPath等诊断字段types.goproject-tree:changed-v2携带单调递增的 revision、受影响 workspace root 和原因。客户端忽略旧 revision只刷新受影响且已展开的项目。重建过程会先发出catalog_rebuild_started再发catalog_rebuild_finished并保证替换 watcher 是普通 watcher、永不拥有重建权session_catalog_rebuild.go。重建的并发语义值得注意RebuildSessionCatalog是 bounded、one-shot 的 single-flight 事务带 5 秒停止超时Windows 上为避免原子替换与旧 SQLite handle 的竞态必须先停旧实例再重建session_catalog_rebuild.go对应测试见 session_catalog_rebuild_concurrency_test.go 与 session_catalog_rebuild_timeout_test.go。ListProjectTree作为基于 catalog 的兼容包装继续保留不再回退到同步文件系统扫描——这是老 API 与索引架构之间的关键契约。运维诊断与重建命令只读检查 catalog不创建或修改它reasonix sessions diagnose reasonix sessions diagnose --json只替换一次性查询投影并索引所有已保存的桌面项目reasonix sessions reindex reasonix sessions reindex --json可重复传入--dir PATH从指定目录集合重建显式目录按 global scope 处理。reindex不会编辑或删除transcript、event、metadata、recovery、archive 或项目文件旧索引文件会保留.replaced-*便于回滚。底层对应RebuildWithRevisionFloorinternal/sessioncatalog/reconcile.go它保证新索引的 revision 不低于当前 revision避免重建期间丢失已经发布的事件。recovery-only 会话在普通树中显示为一个可恢复逻辑行被覆盖的物理副本仍只在恢复历史中展示RecoveryCopy为 true 且OrdinaryVisible仅对唯一的逻辑代表为 true见 types.go避免用户把未显示的副本误认为内容丢失。恢复角色的五种取值normal/covered_copy/adopted/preferred/diverged定义了血缘分类。插件隔离与发布门禁manifest 校验和插件握手与 catalog、项目树互相独立不兼容插件报告为disabled_incompatible核心 controller 仍可使用。Reasonix 管理目录中的旧版 manifest 会在生成备份后原子升级开发目录、外部绝对路径和软链接源码不会被自动改写而是给出手动迁移提示。作为可丢弃投影catalog 的改动必须纳入发布门禁。Preview/canary 晋级应观测catalog 修复积压repair pending/deferred/blocked重建失败率与隔离路径.corrupt-时间戳、quarantinedPath分页延迟idx_*_page索引命中情况队列压力与退出耗时250 ms 上限。必须覆盖的测试面旧版与损坏 fixture、确定性的生命周期竞态、go test -race、React 契约测试以及受支持 macOS、Windows 和 Linux 架构的CGO_ENABLED0构建。仓库中对应的大量测试catalog_test.go、reconcile_integrity_test.go、repair_fencing_test.go、path_identity_migration_test.go 等正是这些门禁的实现证据。小结会话索引的本质是一句口号权威数据在文件系统投影随时可重建。从 v1 到 v12 的迁移史展示了身份与拼写分离、恢复血缘、多 head 投影的演进九条不变量保证了索引永远不会反过来绑架权威数据桌面 API 让项目树读取零负担sessions diagnose/reindex让运维可以在不触碰任何会话文件的前提下完成诊断与重建。理解这套架构是排查桌面侧栏异常、评估索引延迟与规划发布晋级的第一步。延伸阅读索引设计文档docs/SESSION_CATALOG.zh-CN.md本文骨架另有英文版SESSION_CATALOG.md包实现入口internal/sessioncatalogschema/types/catalog/reconcile/repair/lineage/path_identity 等数据库基础设施internal/projectiondb/projectiondb.go桌面集成desktop/session_catalog.go、desktop/session_catalog_runtime.go、desktop/session_catalog_rebuild.go相关会话架构文档docs/SESSION_RECOVERY_AND_PARALLELISM.zh-CN.md、docs/SESSION_OWNERSHIP.zh-CN.md【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
