ChatGPTClaudeGrok / X / CursorGemini

DeepSeek Harness 工作区与会话全消失:workspace.json 修复排查

故障排查发布于 2026-11-03作者: DeepSeek Plugin 插件市场
DeepSeek Harnessworkspace 域sessionIdsDomainErrorZodError数据未丢失
DeepSeek Harness 启动后工作区空白、会话全消失,前端只提示 directoryPickerController 不可用。真因常是 workspace.json 的 sessionIds 被写成字符串,整个 workspace 域加载失败。本文先破除会话丢失的错觉,再给字段级修复。

DeepSeek Harness(DSH)启动后工作区列表一片空白、所有会话看起来「全没了」,前端却只给你一句 directoryPickerController is unavailable——这种「症状指向 A、根因在 B」的故障,最常见的一类就是 storages/workspace.json 里某条记录的 sessionIds 被外部脚本写成了字符串。 先把最重要的一句话放在前面:这不是数据丢失。会话文件仍在磁盘上,只是 workspace 域在加载时抛错、从未挂载,于是没有任何 RPC 能列出它们。 把字段改回合法形状,或者从备份还原该文件,重启后一切都能回来(#11612)。

先确认会话没丢:域没挂载不等于数据没了

一句话结论:界面显示「会话全消失」时,先区分「文件不在了」与「列表接口答不了」,前者才是数据丢失。 按下面三步判断:

  1. 直接看会话文件是否还在。 会话持久化在 ~/.dsh/storages/sessions/(Windows 为 %USERPROFILE%\.dsh\storages\sessions\,若 DSH_HOME 被重定向则在对应目录下)。预期:文件数量与会话数量相符,文件大小正常。文件在 = 数据没丢。

  2. 看工作区记录文件是否存在。 目标文件是 storages/workspace.json,预期:文件存在且能读,内容里能看到工作区条目。若这个文件本身读不动或解析失败,问题就在它身上。

  3. 对照启动日志里的「待激活条目数」。 预期:能看到类似 warning: 5 entries did not activate 的行,紧接着是 DomainError。这个数字说明有多少服务因为依赖的域没挂载而停在 pending,它是「级联」的直接证据(#11612)。

只要第 1 步证明文件还在,就可以放心往下修,不必去碰会话数据本身。

定位:从两行日志锁定具体记录与具体字段

关键判据是:DomainError 给出记录 id,ZodError 给出字段路径,两行一起就把范围缩到一个字段。 步骤:

  1. 抓启动日志里的 DomainError 那一行。
text
DomainError: domain 'workspace': stored record 'b7ac4724-…'
             in table 'workspaces' does not match its schema

预期:拿到三样信息——域是 workspace、表是 workspaces、坏记录 id 是 b7ac4724-…。

  1. 抓紧随其后的 ZodError 字段路径。
text
ZodError: path: ["sessionIds"], message: "Invalid input: expected array, received string"

预期:字段是 sessionIds,期望是数组,实际收到是字符串。到这里定位已经完成,不需要猜。

  1. 在 workspace.json 里用记录 id 搜到那一条。
bash
# 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-…" 这种标量写法。

  1. 顺手统计还有没有别的坏写法。 同一份文件里可能不止一条,搜索所有 "sessionIds": " 形式的标量值,预期:如果只有一条,修完即可;如果多条,需要逐条修。

修复:把标量改回数组,然后重启

一句话结论:修复动作只有一个——sessionIds 必须是数组,"session-…" 要改成 ["session-…"],改完重启即可。 步骤:

  1. 先备份整个 storages 目录,复制到工作区外的位置,这是唯一的回退手段:cp ~/.dsh/storages/workspace.json ~/.dsh/storages/workspace.json.bak。
  2. 只改 sessionIds 的形状,不动其它字段。把 "sessionIds": "session-7f2c108b-…" 改成 "sessionIds": ["session-7f2c108b-…"],也就是给值套上方括号。
  3. 校验 JSON 是否仍然合法。 用任意 JSON 解析器跑一遍,预期:无语法错误。手工编辑最常见的二次事故就是多一个或少一个逗号。
  4. 重启 dsh web。 预期:启动日志不再出现 domain 'workspace' 的 DomainError,entries did not activate 的计数下降或消失,工作区列表恢复。
  5. 验证会话是否回来。 打开会话列表,预期:之前「消失」的会话全部在列,点开可正常读取。

讨论里报告者与回复者各自验证过这条路径:改回数组、重启,工作区列表与全部会话完整恢复,没有数据丢失。若你手里有备份,直接用备份还原同一文件也可以,效果一致(#11612)。

机制解剖:一条坏记录为何能拖垮整个域

一句话结论:workspace 域按整域校验、按整域失败,没有逐条跳过;域打不开,所有等它的服务都停在 pending。 链路拆开看:

  1. schema 声明了数组。 packages/workspace/workspace/src/spec.ts:29 声明 sessionIds: z.array(sessionId)。这是唯一事实来源,写成字符串必然不匹配。
  2. 持久化边界整域抛错。 packages/storage/storage-domain/src/index.ts:200-209 的 parseRecord 在解析记录时抛 DomainError('invalid-record', ...),没有 skip 分支。所以一条坏记录 = 整个 workspace 域打开失败。
  3. 依赖它的服务集体 pending。 回复中列出的受影响服务是 sessionController、schedule、workspaceController、ui-deliverables。它们等不到域就绪,初始化一直挂起。
  4. 客户端只报最先命中的那个下游错误。 你看到的是 typert gateway: directoryPicker/list: active Service "directoryPickerController" is unavailable,因为点击「选择工作区目录」时最先触发的就是这条调用。这个报错与真正的根因隔了两层,照着它查会完全走偏。
  5. 版本一致性说明这不是某一版的偶发。 回复者核对过,spec.ts 的 schema 与 parseRecord 在 rc.2、rc.5 与 master ce7073d5 上完全一致。换版本不改变行为,真正要动的只有数据或产品策略。

坏数据从哪来:写入不经过 DSH,DSH 就没机会校验

一句话结论:这类坏记录几乎都来自外部脚本直接改文件,而 DSH 的写前校验只在它自己写的时候生效。 讨论里给出的典型来源是 PowerShell 的一个老坑:

  1. 管道输出单个元素会坍缩成标量。 一个只有一项的数组经过管道后可能变成单个字符串,再序列化就写成 "sessionIds": "session-…"。
  2. 写回文件时没有校验环节。 脚本直接覆盖 workspace.json,DSH 既不知道这次写入,也无法在写前拦截。
  3. 下次启动才由读侧发现。 parseRecord 在加载时才发现不匹配,故障延迟到下一次启动才爆发——这也是很多人觉得「我什么都没改,它自己就坏了」的原因。
  4. 降低风险的做法:脚本写 JSON 前把数组显式包好;PowerShell 7 可用 ConvertTo-Json -AsArray 强制数组输出;写完用 JSON 解析器验一遍再落盘。另外日志里出现过 default data dir not writable 后回退到 Desktop\HarnessData,回退本身与损坏无关,但把 storages/ 放进了用户可见目录,外部编辑概率明显上升。

想加「跳过坏记录」要小心两写 mutation 标记

一句话结论:逐条容错是正确的产品方向,但实现时必须保留 workspace.json 里的两写 mutation 标记,否则半途中断的创建/删除会被静默掩盖。 回复者提醒了三点:

  1. 标记的位置:spec.ts:36-40 的两写 mutation 标记,用于表示某次创建或删除进行到一半;「逐条跳过 + 启动自愈」不能把整条记录连同标记一起丢掉。
  2. 理想行为是「跳过但大声」:跳过坏记录时至少记录 {domain, recordId, field, expected},让用户知道发生了什么,而不是静默少一条工作区。
  3. 当前没有这个开关:回应里说得很清楚,「跳过坏记录」是产品决策,不是用户漏开的配置项。所以不要去找隐藏开关,直接修数据;要提 issue 时附上 DomainError、ZodError 两行与 entries did not activate 的计数。

排查注意事项

这类「级联失效」的排查原则是:从最上游的域错误往下读,不要从最下游的界面报错往上猜。 六条要点:

  1. 先证「数据还在」再动手,会话文件在盘上就不算数据丢失。
  2. DomainError 是根因,directoryPickerController is unavailable 是症状,两者不能倒过来读。
  3. 只改坏字段的形状,不要重排 JSON、不要改 id、不要动两写标记。
  4. 改前必备份,手工改存储文件的回退只能靠备份。
  5. 别期待换版本能修:schema 与 parseRecord 在 rc.2、rc.5、master 一致,换版本不改变结果。
  6. 修完看启动日志确认:DomainError 消失、pending 计数下降,才算真的修好。

来源:Discussion #11612。

ChatGPTClaudeGrok / X / CursorGemini

常见问题

DeepSeek Harness 启动后工作区列表空了、所有会话都看不见,是不是会话数据已经丢了,还能不能恢复?

DeepSeek Harness 的会话通常没有丢。会话文件仍在磁盘上,只是 workspace 域在加载时抛错、没有挂载,任何列举会话的 RPC 都无法应答,界面就表现成「全没了」。把 workspace.json 里坏掉的字段修回合法形状,或者从备份还原该文件,重启后会话列表会完整回来,讨论中的报告者与回复者都验证过这一点。

DeepSeek Harness 日志报 domain workspace 与 sessionIds,该看哪一行定位?

DeepSeek Harness 的这类日志要看 DomainError 里给出的 record id 与 table 名。它会写成 stored record '<id>' in table 'workspaces' does not match its schema,其中的 id 就是坏记录的主键;紧随其后的 ZodError 会给出字段路径 sessionIds 与期望类型 expected array, received string。两行合起来就能定位到具体记录与具体字段。

为什么 workspace.json 里只有一条记录坏了,整个界面里工作区、会话列表、目录选择全都不可用?

因为 DeepSeek Harness 的持久化边界按整域校验,不按单条记录跳过。parseRecord 在 storage-domain 里对整张表抛 DomainError,只要一条记录不符合 schema,workspace 域就打不开;依赖它的 sessionController、schedule、workspaceController、ui-deliverables 全部停在 pending,客户端只会显示最先命中的那个下游错误。

DeepSeek Harness 的 workspace.json 被外部脚本写坏,怎么避免下次再发生?

在 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

来源