DeepSeek Harness 工作区与会话全消失:workspace.json 修复排查
DeepSeek Harness(DSH)启动后工作区列表一片空白、所有会话看起来「全没了」,前端却只给你一句 directoryPickerController is unavailable——这种「症状指向 A、根因在 B」的故障,最常见的一类就是 storages/workspace.json 里某条记录的 sessionIds 被外部脚本写成了字符串。 先把最重要的一句话放在前面:这不是数据丢失。会话文件仍在磁盘上,只是 workspace 域在加载时抛错、从未挂载,于是没有任何 RPC 能列出它们。 把字段改回合法形状,或者从备份还原该文件,重启后一切都能回来(#11612)。
先确认会话没丢:域没挂载不等于数据没了
一句话结论:界面显示「会话全消失」时,先区分「文件不在了」与「列表接口答不了」,前者才是数据丢失。 按下面三步判断:
-
直接看会话文件是否还在。 会话持久化在
~/.dsh/storages/sessions/(Windows 为%USERPROFILE%\.dsh\storages\sessions\,若DSH_HOME被重定向则在对应目录下)。预期:文件数量与会话数量相符,文件大小正常。文件在 = 数据没丢。 -
看工作区记录文件是否存在。 目标文件是
storages/workspace.json,预期:文件存在且能读,内容里能看到工作区条目。若这个文件本身读不动或解析失败,问题就在它身上。 -
对照启动日志里的「待激活条目数」。 预期:能看到类似
warning: 5 entries did not activate的行,紧接着是DomainError。这个数字说明有多少服务因为依赖的域没挂载而停在pending,它是「级联」的直接证据(#11612)。
只要第 1 步证明文件还在,就可以放心往下修,不必去碰会话数据本身。
定位:从两行日志锁定具体记录与具体字段
关键判据是:DomainError 给出记录 id,ZodError 给出字段路径,两行一起就把范围缩到一个字段。 步骤:
- 抓启动日志里的
DomainError那一行。
DomainError: domain 'workspace': stored record 'b7ac4724-…'
in table 'workspaces' does not match its schema
预期:拿到三样信息——域是 workspace、表是 workspaces、坏记录 id 是 b7ac4724-…。
- 抓紧随其后的
ZodError字段路径。
ZodError: path: ["sessionIds"], message: "Invalid input: expected array, received string"
预期:字段是 sessionIds,期望是数组,实际收到是字符串。到这里定位已经完成,不需要猜。
- 在
workspace.json里用记录 id 搜到那一条。
# macOS / Linux
grep -n "b7ac4724" ~/.dsh/storages/workspace.json
# Windows PowerShell
Select-String -Path "$env:USERPROFILE\.dsh\storages\workspace.json" -Pattern "b7ac4724"
预期:命中一条工作区记录,肉眼即可看到 "sessionIds": "session-7f2c108b-…" 这种标量写法。
- 顺手统计还有没有别的坏写法。 同一份文件里可能不止一条,搜索所有
"sessionIds": "形式的标量值,预期:如果只有一条,修完即可;如果多条,需要逐条修。
修复:把标量改回数组,然后重启
一句话结论:修复动作只有一个——sessionIds 必须是数组,"session-…" 要改成 ["session-…"],改完重启即可。 步骤:
- 先备份整个 storages 目录,复制到工作区外的位置,这是唯一的回退手段:
cp ~/.dsh/storages/workspace.json ~/.dsh/storages/workspace.json.bak。 - 只改
sessionIds的形状,不动其它字段。把"sessionIds": "session-7f2c108b-…"改成"sessionIds": ["session-7f2c108b-…"],也就是给值套上方括号。 - 校验 JSON 是否仍然合法。 用任意 JSON 解析器跑一遍,预期:无语法错误。手工编辑最常见的二次事故就是多一个或少一个逗号。
- 重启
dsh web。 预期:启动日志不再出现domain 'workspace'的DomainError,entries did not activate的计数下降或消失,工作区列表恢复。 - 验证会话是否回来。 打开会话列表,预期:之前「消失」的会话全部在列,点开可正常读取。
讨论里报告者与回复者各自验证过这条路径:改回数组、重启,工作区列表与全部会话完整恢复,没有数据丢失。若你手里有备份,直接用备份还原同一文件也可以,效果一致(#11612)。
机制解剖:一条坏记录为何能拖垮整个域
一句话结论:workspace 域按整域校验、按整域失败,没有逐条跳过;域打不开,所有等它的服务都停在 pending。 链路拆开看:
- schema 声明了数组。
packages/workspace/workspace/src/spec.ts:29声明sessionIds: z.array(sessionId)。这是唯一事实来源,写成字符串必然不匹配。 - 持久化边界整域抛错。
packages/storage/storage-domain/src/index.ts:200-209的parseRecord在解析记录时抛DomainError('invalid-record', ...),没有 skip 分支。所以一条坏记录 = 整个workspace域打开失败。 - 依赖它的服务集体 pending。 回复中列出的受影响服务是
sessionController、schedule、workspaceController、ui-deliverables。它们等不到域就绪,初始化一直挂起。 - 客户端只报最先命中的那个下游错误。 你看到的是
typert gateway: directoryPicker/list: active Service "directoryPickerController" is unavailable,因为点击「选择工作区目录」时最先触发的就是这条调用。这个报错与真正的根因隔了两层,照着它查会完全走偏。 - 版本一致性说明这不是某一版的偶发。 回复者核对过,
spec.ts的 schema 与parseRecord在 rc.2、rc.5 与 masterce7073d5上完全一致。换版本不改变行为,真正要动的只有数据或产品策略。
坏数据从哪来:写入不经过 DSH,DSH 就没机会校验
一句话结论:这类坏记录几乎都来自外部脚本直接改文件,而 DSH 的写前校验只在它自己写的时候生效。 讨论里给出的典型来源是 PowerShell 的一个老坑:
- 管道输出单个元素会坍缩成标量。 一个只有一项的数组经过管道后可能变成单个字符串,再序列化就写成
"sessionIds": "session-…"。 - 写回文件时没有校验环节。 脚本直接覆盖
workspace.json,DSH 既不知道这次写入,也无法在写前拦截。 - 下次启动才由读侧发现。
parseRecord在加载时才发现不匹配,故障延迟到下一次启动才爆发——这也是很多人觉得「我什么都没改,它自己就坏了」的原因。 - 降低风险的做法:脚本写 JSON 前把数组显式包好;PowerShell 7 可用
ConvertTo-Json -AsArray强制数组输出;写完用 JSON 解析器验一遍再落盘。另外日志里出现过default data dir not writable后回退到Desktop\HarnessData,回退本身与损坏无关,但把storages/放进了用户可见目录,外部编辑概率明显上升。
想加「跳过坏记录」要小心两写 mutation 标记
一句话结论:逐条容错是正确的产品方向,但实现时必须保留 workspace.json 里的两写 mutation 标记,否则半途中断的创建/删除会被静默掩盖。 回复者提醒了三点:
- 标记的位置:
spec.ts:36-40的两写 mutation 标记,用于表示某次创建或删除进行到一半;「逐条跳过 + 启动自愈」不能把整条记录连同标记一起丢掉。 - 理想行为是「跳过但大声」:跳过坏记录时至少记录
{domain, recordId, field, expected},让用户知道发生了什么,而不是静默少一条工作区。 - 当前没有这个开关:回应里说得很清楚,「跳过坏记录」是产品决策,不是用户漏开的配置项。所以不要去找隐藏开关,直接修数据;要提 issue 时附上
DomainError、ZodError两行与entries did not activate的计数。
排查注意事项
这类「级联失效」的排查原则是:从最上游的域错误往下读,不要从最下游的界面报错往上猜。 六条要点:
- 先证「数据还在」再动手,会话文件在盘上就不算数据丢失。
DomainError是根因,directoryPickerController is unavailable是症状,两者不能倒过来读。- 只改坏字段的形状,不要重排 JSON、不要改 id、不要动两写标记。
- 改前必备份,手工改存储文件的回退只能靠备份。
- 别期待换版本能修:schema 与
parseRecord在 rc.2、rc.5、master 一致,换版本不改变结果。 - 修完看启动日志确认:
DomainError消失、pending 计数下降,才算真的修好。
常见问题
DeepSeek Harness 的会话通常没有丢。会话文件仍在磁盘上,只是 workspace 域在加载时抛错、没有挂载,任何列举会话的 RPC 都无法应答,界面就表现成「全没了」。把 workspace.json 里坏掉的字段修回合法形状,或者从备份还原该文件,重启后会话列表会完整回来,讨论中的报告者与回复者都验证过这一点。
DeepSeek Harness 的这类日志要看 DomainError 里给出的 record id 与 table 名。它会写成 stored record '<id>' in table 'workspaces' does not match its schema,其中的 id 就是坏记录的主键;紧随其后的 ZodError 会给出字段路径 sessionIds 与期望类型 expected array, received string。两行合起来就能定位到具体记录与具体字段。
因为 DeepSeek Harness 的持久化边界按整域校验,不按单条记录跳过。parseRecord 在 storage-domain 里对整张表抛 DomainError,只要一条记录不符合 schema,workspace 域就打不开;依赖它的 sessionController、schedule、workspaceController、ui-deliverables 全部停在 pending,客户端只会显示最先命中的那个下游错误。
在 DeepSeek Harness 这边,关键是别让脚本把单元素数组序列化成标量。PowerShell 管道输出单个元素时会坍缩成标量,写回前先显式包成数组,或使用支持强制数组输出的序列化参数。另外改写 storages 目录下的文件前先备份,因为写入不经过 DSH,DSH 没有机会做写前校验。
相关术语
- DomainError
- DomainError 是 DeepSeek Harness 存储域在读写异常时抛出的错误类型,会带上域名称、记录 id 与表名。其中 invalid-record 形态表示某条持久化记录不符合该域的 schema,当前实现会让整个域加载失败。— https://github.com/deepseek-ai/deepseek-harness/discussions/11612
- parseRecord
- parseRecord 是 storage-domain 包在持久化边界上逐条解析存储记录的函数,位于 storage-domain/src/index.ts 约 200-209 行。它对不符合 schema 的记录直接抛出 DomainError,没有「跳过并继续」的路径。— https://github.com/deepseek-ai/deepseek-harness/discussions/11612
- 两写 mutation 标记
- 两写 mutation 标记是 storages/workspace.json 里用来表示创建或删除操作进行到一半的状态位(spec.ts 约 36-40 行)。它的作用是让半途中断的变更在下次启动时可见;任何跳过坏记录的逻辑都必须保留这个标记,否则半应用状态会被静默掩盖。— https://github.com/deepseek-ai/deepseek-harness/discussions/11612
来源
- #11612 — [Bug] workspace.json with a non-array sessionIds breaks the whole workspace domain and cascades into unrelated services· deepseek-ai(GitHub Discussions)