[bug] DSH 侧边栏会话列表整体空白：持久化视图快照缺字段导致 sidebar.workspaces slot 崩溃

[TheJieee]

产品：DeepSeek Harness（dsh）
版本：Web UI 构建 0.1.5-rc.2-449af19（@deepseek-ai/dsh 0.1.5-rc.1 CLI + profiles/node_modules 内 0.1.5-rc.2 插件集）
平台：Windows 10/11（node v26.7.0，Edge）
严重级：高（核心导航功能不可用，且不会自愈）
类型：客户端状态持久化缺少容错（前端崩溃），非数据损坏

---

1. 摘要

升级到 0.1.5-rc.2 后，Web GUI 左侧边栏的会话/工作区列表整体空白：既看不到已有会话，也看不到工作区分组或「添加工作区」入口。会话数据本身完好（主机侧可正常枚举、可正常读取），崩溃完全发生在前端。

根因是 @deepseek-ai/dsh-client-ui-workspace 的持久化视图 store 在浏览器 localStorage 快照不完整时，水合（rehydrate）以「整体替换」方式覆盖初始状态，使 sessionUpdatedAtByAccount 等字段变成 undefined；随后 retainAccountKeys 对该字段调用 Object.entries()，抛出 TypeError，sidebar.workspaces 这个 slot 组件崩溃被错误边界捕获，整块区域渲染为空。

这既是 store 水合策略的健壮性缺陷（上游应修），也是 slot 内一个 action 缺少空值兜底的直接触发点。

---

2. 现象与复现

2.1 现象

1. 打开 dsh web 提供的 GUI（例：http://127.0.0.1:3080），主对话区正常、可以正常收发消息；
2. 左侧边栏只有外壳（品牌区、新会话按钮、面板图标、底部设置），中间「工作区 / 会话」区域完全空白；
3. 页面不会恢复，刷新后依旧空白；
4. 控制台可见明确报错（见 2.3）。

2.2 浏览器控制台报错（原文）

TypeError: Cannot convert undefined or null to object
    at Object.entries (<anonymous>)
    at retainAccountKeys (client.js:218:1)
    at index-BKQ_L1z6.js:56:69359
    at index-BKQ_L1z6.js:56:68694
    at produce (index-BKQ_L1z6.js:56:66201)
    at Object.update (index-BKQ_L1z6.js:56:68674)
    at a.<computed> [as retainAccountKeys] (index-BKQ_L1z6.js:56:69348)
    at client.js:2017:1
    at zi (index-BKQ_L1z6.js:56:24417)
    at bn (index-BKQ_L1z6.js:56:42760)
client.js:526 slot entry crashed in 'sidebar.workspaces': TypeError: Cannot convert undefined or null to object
    at Object.entries (<anonymous>)
    at retainAccountKeys (client.js:218:1)
    ...
componentDidCatch @ client.js:526

即：slot entry crashed in 'sidebar.workspaces'，崩溃点是 client.js:218 的 retainAccountKeys。

2.3 触发条件

浏览器 localStorage 中持久化的视图快照 dsh.workspace.view.v5 缺少 groupExpansion / sessionOrderByAccount / sessionUpdatedAtByAccount 三者之一，或该字段为 null。凡是这类不完整快照（例如被外部工具裁剪过、写入中断留下残片、旧构建写入后被当前构建读取等），每次加载都会稳定复现。

注：该快照里目前实际是缺少还是 null，可用 2.4 的命令读出确认；两种情形都会触发同一处崩溃。

2.4 现场确认命令（在出问题页面的 DevTools Console 执行）

// 1) 看当前快照内容，确认到底缺哪个字段
copy(localStorage.getItem('dsh.workspace.view.v5'));

// 2) 立即恢复（备份后清除该键并刷新；只丢失展开/排序等浏览器本地偏好）
(() => {
  const k = 'dsh.workspace.view.v5';
  const raw = localStorage.getItem(k);
  if (raw) { localStorage.setItem(k + '.bak', raw); localStorage.removeItem(k); }
  location.reload();
})();

---

3. 根因分析

3.1 直接原因：retainAccountKeys 未做空值兜底

@deepseek-ai/dsh-client-ui-workspace@0.1.5-rc.2 → lib/client.js（压缩后行 214-219）：

retainAccountKeys: (d, workspaceKeys) => {
  const retained = new Set(workspaceKeys);
  d.groupExpansion          = Object.fromEntries(Object.entries(d.groupExpansion).filter(([key]) => retained.has(key)));
  d.sessionOrderByAccount   = Object.fromEntries(Object.entries(d.sessionOrderByAccount).filter(([key]) => retained.has(key)));
  d.sessionUpdatedAtByAccount = Object.fromEntries(Object.entries(d.sessionUpdatedAtByAccount).filter(([key]) => retained.has(key)));  // ← :218 抛错
}

调用点 client.js:2017（WorkspaceBrowser 的 effect，workspacePhase === 'ready' 后执行）：

useEffect(() => {
  if (workspacePhase !== 'ready') return;
  actions.retainAccountKeys(['', FLAT_SESSION_ORDER_KEY, ...workspaces.map(w => w.workspaceId)]);
}, [actions.retainAccountKeys, workspacePhase, workspaces]);

只要 d.sessionUpdatedAtByAccount 为 undefined/null，Object.entries 就抛 TypeError: Cannot convert undefined or null to object。

3.2 根本原因：持久化 store 的「替换式水合」丢掉了 init() 默认值

前端 shell 内联的 @deepseek-ai/dsh-client-store（dist/assets/index-BKQ_L1z6.js）里，快照 store 的水合逻辑是：

function createSnapshotStore(initial, options) {
  const api = createStore(() => initial);          // 初始状态含完整默认值
  if (options?.persist) {
    const raw = localStorage.getItem(options.persist.name);
    if (raw !== null) api.setState(M6(JSON.parse(raw)), true);   // ← replace = true
    api.subscribe((state) => localStorage.setItem(name, JSON.stringify(state)));
  }
  ...
}

而 M6 只是 immer 的 freeze（function M6(t){return No(t,!0)}，No 是 freeze），不是 merge。底层 zustand store 的 setState 语义是：

setState: (partial, replace) => {
  const next = typeof partial === 'function' ? partial(state) : partial;
  state = replace ?? (typeof next !== 'object' || next === null)
    ? next                                   // replace === true → 直接替换
    : Object.assign({}, state, next);        // 否则才浅合并
}

由于水合传入 replace = true，快照里没有的键不会被 init() 的默认值补齐，于是 init() 里明明声明过的 sessionUpdatedAtByAccount: {} 在运行时是 undefined。这是"schema 漂移/残缺快照"场景的通用隐患：任何持久化 store 一旦被旧版本或残缺内容写坏，就会让消费方拿到 undefined。

init() 本身声明是完整的（同版本 lib/client.js 195-203 行）：

init: () => ({
  groupBy: 'workspace',
  orderBy: 'updated',
  groupExpansion: {},
  sessionOrderByAccount: {},
  sessionUpdatedAtByAccount: {},
}),
persist: 'dsh.workspace.view.v5',

3.3 为什么"整块空白"而不是显示错误

sidebar.workspaces 是 single 类型的 slot，由 ui-workspace 插件注册（client.js:2794）。该 slot 的组件在渲染期 effect 中抛错 → 被 slot 错误边界捕获（slot entry crashed in 'sidebar.workspaces'）→ 该 slot 渲染为空。而这一块正是"工作区/会话浏览区域"（SidebarRoot 里的 renderSlot('sidebar.workspaces', …)），所以表现为会话列表整体消失，外壳仍在。

3.4 与版本演进无关

已核对 npm 上 0.1.3-alpha.2、0.1.5-alpha.1/2、0.1.5-rc.1、0.1.5-rc.2、0.1.6-alpha.1 的 lib/client.js：三个字段与 persist: "dsh.workspace.view.v5" 在所有版本中都存在，即本崩溃不是"新增字段未迁移"造成，而是已有字段在持久化快照中缺失/为 null 时缺少兜底。

---

4. 最小确定性复现（无需浏览器）

附件 repro-store-crash.mjs 直接抽取已发布 bundle 中真实的 createWorkspaceViewStore 定义，配合按 shell 压缩代码逐行对齐复刻的 createSnapshotStore/defineStore/zustand setState 语义，注入不同的 localStorage 快照运行 retainAccountKeys：

$ node repro-store-crash.mjs
extracted 1342 chars of the shipped store definition
A. no persisted snapshot (fresh install)              -> OK
B. complete snapshot                                  -> OK
C. snapshot missing sessionUpdatedAtByAccount         -> THREW TypeError: Cannot convert undefined or null to object
D. snapshot with sessionUpdatedAtByAccount: null      -> THREW TypeError: Cannot convert undefined or null to object
E. snapshot missing groupExpansion                    -> THREW TypeError: Cannot convert undefined or null to object
F. snapshot missing sessionOrderByAccount             -> THREW TypeError: Cannot convert undefined or null to object

4 scenario(s) reproduced the sidebar crash

注：脚本默认读取已打过本地补丁的 lib/client.js，因此在报告作者的机器上会显示 0 崩溃（这本身也是补丁生效的回归证明）。要在未打补丁的原始 bundle 上看到崩溃，请指向随包备份或未修改的安装：

$env:DSH_WORKSPACE_CLIENT='C:\Users\<you>\.dsh\profiles\node_modules\@deepseek-ai\dsh-client-ui-workspace\lib\client.js.orig-backup'
node repro-sidebar-crash.mjs

预期输出：场景 C/D/E/F 全部 THREW TypeError: Cannot convert undefined or null to object。

复现命令（PowerShell，Windows）：

# 把附件 repro-store-crash.mjs 放到任意目录，改脚本内的 bundle 路径为你的安装路径后：
node repro-store-crash.mjs

脚本内默认读取：%USERPROFILE%\.dsh\profiles\node_modules\@deepseek-ai\dsh-client-ui-workspace\lib\client.js

---

5. 建议修复

5.1 上游（推荐，两处）

(a) packages/client/store：水合时以 init() 默认值兜底（治本，消除所有 store 的同类隐患）

// snapshot store：把初始状态作为默认层，快照覆盖其上，而不是整体替换
function rehydrate(store, name) {
  const raw = localStorage.getItem(name);
  if (raw === null) return;
  store.setState({ ...store.getInitialState(), ...JSON.parse(raw) }, true);
}

(b) packages/client/ui-workspace/src/client/stores.ts：action 内对三个字段做空值兜底（防御性，成本极低）

  retainAccountKeys: (d, workspaceKeys) => {
    const retained = new Set(workspaceKeys);
-   d.groupExpansion = Object.fromEntries(Object.entries(d.groupExpansion).filter(([key]) => retained.has(key)));
-   d.sessionOrderByAccount = Object.fromEntries(Object.entries(d.sessionOrderByAccount).filter(([key]) => retained.has(key)));
-   d.sessionUpdatedAtByAccount = Object.fromEntries(Object.entries(d.sessionUpdatedAtByAccount).filter(([key]) => retained.has(key)));
+   d.groupExpansion = Object.fromEntries(Object.entries(d.groupExpansion ?? {}).filter(([key]) => retained.has(key)));
+   d.sessionOrderByAccount = Object.fromEntries(Object.entries(d.sessionOrderByAccount ?? {}).filter(([key]) => retained.has(key)));
+   d.sessionUpdatedAtByAccount = Object.fromEntries(Object.entries(d.sessionUpdatedAtByAccount ?? {}).filter(([key]) => retained.has(key)));
  },

配套建议（防同类复发）：

• syncSessionOrderAccount 同样写入这两张表，可在写入前 ??= 初始化；
• 为 slot 组件建议增加"渲染期异常不应清空整个 slot"的降级路径（当前行为是整块消失，用户无从得知原因）；
• 若快照 schema 有变，persist 键升版（v5 → v6）或在水合时校验字段集合，比静默替换更安全。

5.2 本地临时修补（已验证可用）

本次已在安装目录打上等价补丁（升级 dsh 后会被覆盖）：

文件	修改
.dsh/profiles/node_modules/@deepseek-ai/dsh-client-ui-workspace/lib/client.js	三处 Object.entries(d.xxx) → Object.entries(d.xxx ?? {})
.dsh/profiles/node_modules/@deepseek-ai/dsh-web-frontend/dist/assets/index-*.js	水合 t.setState(M6(JSON.parse(i)),!0) → t.setState(M6(Object.assign({},gc(),JSON.parse(i))),!0)（gc 即该文件内的 getInitialState）

验证结果：node --check 对两文件均通过；复现脚本 6 个场景（含缺失/为 null 的三种字段）由 4 个崩溃降为 0 个崩溃；retainAccountKeys 全部返回 OK，快照缺失字段被 init() 默认值补齐。

回滚方式：同目录保留有 *.orig-backup 原文件，覆盖即可。

---

6. 影响范围

• 所有使用 Web 表面（dsh --profile web）且 localStorage 中 dsh.workspace.view.v5 不完整的用户；
• 失效功能：会话列表浏览、工作区分组、会话搜索入口、openSession 导航（均挂在 sidebar.workspaces 区域）；
• 会话数据、日志、格式迁移、session/list 主机接口均不受影响（实测主机侧 6 个会话全部可枚举、可 stat、可解析，含 v0 命名的历史会话）；
• 该故障不会自愈，必须修代码或清 localStorage。

---

7. 验证过的"不是这些原因"

为避免社区重复排查，以下均已实测排除：

1. 会话文件损坏/格式不支持 —— 直接用已安装的 @deepseek-ai/dsh-session-persistence-jsonl@0.1.5-rc.2 枚举 .dsh/sessions，6 个会话（含 session.jsonl.zstd 的 v0 历史会话）全部 LIST OK，stat 正常；
2. 工作区记录丢失 —— .dsh/storages/workspace.json 中两个工作区、全部 sessionIds 完整，archivedSessionIds 为空；
3. 插件未加载/配置缺失 —— dsh --dump-config --profile web 组合树正常，ui-workspace、session-query-sqlite（openAt: never）、session-controller 等行均在位；
4. 前端资源 404 —— index.html 引用的 index-BKQ_L1z6.js / vendor-*.js 与磁盘文件名一致，/plugins/... 路由按 rev 精确匹配属预期行为。

---

8. 环境明细

dsh CLI            : @deepseek-ai/dsh 0.1.5-rc.1
profile 插件       : @deepseek-ai/* 0.1.5-rc.2
Web 构建           : 0.1.5-rc.2-449af19
                 (client-ui-workspace/lib/client.js localBuildVersion())
前端资源           : dsh-web-frontend/dist/assets/index-BKQ_L1z6.js
崩溃文件           : dsh-client-ui-workspace/lib/client.js:218 (retainAccountKeys)
持久化键           : localStorage["dsh.workspace.view.v5"]
Node / OS          : node v26.7.0 / Windows (Edge)