DSH 存储结构参考

DSH 往磁盘上写了什么。基于真机实测（0.2.1-rc.2）。负载、列表条目、标题在磁盘上是三样东西；把它们当成一件，就会看到「文件都在、列表是空的」。

实测时间 2026-11-13，DSH 0.2.1-rc.2，Windows。

会话格式对照

	v4	legacy
文件名	`session.v4.jsonl.zstd`	`session.jsonl.zstd`
由谁产生	`DSH 0.2.x 网页版 / CLI / TUI`	`旧桌面版运行时`
帧结构	`多帧、追加写`	`多帧、追加写`
能否并存	`同一个会话目录里可以两个文件都在`
实测最大	`单文件 22,832,359 字节`	`单文件 21,360,396 字节`

两种格式都是「可独立解压的 zstd 帧」顺序追加而成。任何工具都应该把它们当不透明字节处理。

目录布局

工作区目录名是「绝对路径的 slug」，不是 workspace id。两台机器路径不同，同一个工作区会得到两个不同的目录名。

~/.dsh                          DSH 数据根（网页版 / CLI / TUI）
├─ sessions/
│  └─ --C-Users-you-my~0020project--/  "C:\Users\you\my project" 的 slug
│     └─ session-<uuid>/         一个会话一个目录，目录名原样使用
│        ├─ session.v4.jsonl.zstd
│        └─ session.jsonl.zstd   旧格式，可能与 v4 并存
└─ storages/
   ├─ workspace.json             工作区 + 会话列表
   ├─ session_projcache.json     标题与逐回合统计（聚合）
   ├─ session_projcache/sessions/<id>.json   同样的数据，逐会话一份
   └─ schedule.json              设备本地提醒（不要同步）

路径 slug 规则

由绝对路径推导：去掉冒号，反斜杠换成连字符，空格编码为 ~0020，两端各加两个连字符。C:\Users\you\my project → --C-Users-you-my~0020project--

workspace.json（unit 版本 2）

这个文件决定「会话在不在列表里」。只同步会话负载而不同步它，会话就是不可见的。

字段	含义	合并规则
`global.workspaceIds`	已注册的工作区	并集
`global.archivedSessionIds`	被隐藏的会话	并集（幂等）
`global.pinnedSessionIds`	置顶会话	并集
`tables.workspaces.<id>.path`	本机绝对路径	保留本地值，永不采用远端
`tables.workspaces.<id>.title`	显示名	本地有值就用本地
`tables.workspaces.<id>.sessionIds`	有序会话列表	并集
`tables.workspaces.<id>.createdAt / updatedAt`	时间戳	取小 / 取大

session_projcache.json（unit 版本 3）

标题、回合数与 token 用量在这里，不在 workspace.json。DSH 同时保存聚合表与逐会话文件，两者的记录都算「有标题」。行结构是 {ver, seq, val}，合并时先比 ver，再比 seq。

字段	含义
`tables.sessions.<id>.identity.cwd`	该会话工作区的绝对路径（把会话映射到工作区的权威依据）
`tables.sessions.<id>.rows.title`	显示标题；null 表示无标题
`tables.sessions.<id>.rows.sessionStats`	turns、steps、llmMs、decodeTokens 等
`tables.sessions.<id>.rows.tokenUsage`	累计与最后一回合的 token 分桶

现象 → 原因

现象	原因
会话文件在，DSH 列表里没有	该 session id 不在 tables.workspaces.<id>.sessionIds 里
会话在列表里，但没有标题	该 id 没有 projcache 记录（聚合或逐会话都算）
点开条目是空的	索引里的 id 在磁盘上没有对应的负载目录
会话显示的是旧状态	两种格式并存，DSH 只读其中一个，另一个变旧
归档了还占空间	归档只是隐藏，并不删除
同步「成功」了但列表是空的	只同步了 sessions/，没有同步 storages/

怎么检查你自己的安装

会话索引体检在本机跑完这些检查：选一个 DSH 数据根目录，得到不一致的 id 清单和每条的一行修法。

打开会话索引体检 →