[Bug Report] 陈旧持久化状态使「工作区 / 会话列表」整格静默消失：retainAccountKeys 对反序列化状态缺键零容忍

[kkkikun]

概要

DSH Web GUI 左侧边栏的工作区与会话列表整块不再显示（只剩品牌行、新会话 按钮与底部设置入口），且没有任何可见错误提示。

取证实锤：客户端插件 @deepseek-ai/dsh-client-ui-workspace 已加载并注册了槽位 sidebar.workspaces，但其组件在首次渲染时抛异常；槽位级错误边界捕获后按 abdicate 语义将该 entry 永久退场，格子只剩一个空的 data-slot-error 占位 div：

<div data-slot="sidebar.workspaces" style="display: contents;"><div data-slot-error="sidebar.workspaces"></div></div>

崩溃来自一段纯视图偏好代码：浏览器持久化状态里缺少 sessionUpdatedAtByAccount 键，而 retainAccountKeys 对它直接 Object.entries(...)。

---

环境

项	值
OS	Windows（process.platform === "win32"）
Node	v22.22.3
DSH CLI	@deepseek-ai/dsh@0.1.5-rc.1
内嵌包	dsh-web-app / dsh-client-ui-workspace / dsh-client-ui-renderer / dsh-client-ui-sidebar / dsh-api-remotes 等均为 0.1.5-rc.2
profile	web（%USERPROFILE%\.dsh\profiles\web）
GUI	http://127.0.0.1:3080
第三方 Web UI 插件	另装有全家桶式第三方插件（@linxin666/dsh-web-all@0.3.23、dshmarket、dsh-pet、dsh-whale-widget、dsh-better-sidebar、dsh-context、@nanmicoder/dsh-agent-teams）；下文 §已排除 已说明其与本缺陷无关
工作区数据	1 个工作区 / 3 条会话，无归档（即数据侧正常）

---

复现步骤

1. 以上述 profile 启动 dsh web，浏览器打开 http://127.0.0.1:3080。
2. DevTools → Console 勾选 Preserve log，然后强刷（Ctrl+F5）。
3. 左侧边栏缺少工作区与会话列表。
4. Console 出现如下堆栈（原始输出）：

index-BKQ_L1z6.js:56 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
    ...
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

5. 槽位 DOM（原始值）：

document.querySelector('[data-slot="sidebar.workspaces"]').outerHTML
// '<div data-slot="sidebar.workspaces" style="display: contents;">'
//   + '<div data-slot-error="sidebar.workspaces"></div></div>'

补充：该现象跨 dsh web 进程重启稳定复现（重启前后 PID 不同、现象一致），与主机侧插件配置无关（曾把目录选择器由 auto 改为静态 browse 后重启，现象不变）。

实际结果

左侧边栏的「工作区 + 会话列表 + 会话搜索 + 重命名 / 分叉 / 归档 + 排序分组」入口全部消失，且无任何 UI 提示、无自愈路径（刷新后重新注册 → 再次崩溃 → 再次退场）。

期望结果

即使持久化状态陈旧/缺键，也应：

• 该组件不崩（缺失键按默认值处理）；且
• 万一崩了，用户应能看到「此面板加载失败」之类的可见提示与重试入口，而不是整格静默消失。

---

根因分析

1) 崩溃点：retainAccountKeys 对该 store 的键零容忍

@deepseek-ai/dsh-client-ui-workspace@0.1.5-rc.2，构建产物 lib/client.js：

// L194 工作区浏览器的「视图偏好」store
function createWorkspaceViewStore() {
  return defineStore({
    init: () => ({
      groupBy: "workspace",
      orderBy: "updated",
      groupExpansion: {},
      sessionOrderByAccount: {},
      sessionUpdatedAtByAccount: {}      // ← 后加的键
    }),
    persist: "dsh.workspace.view.v5",    // ← 版本号未随结构变更升级
    actions: {
      // ...
      retainAccountKeys: (d, workspaceKeys) => {                                       // L214
        const retained = new Set(workspaceKeys);
        d.groupExpansion = Object.fromEntries(
          Object.entries(d.groupExpansion).filter(([key]) => retained.has(key)));       // L216
        d.sessionOrderByAccount = Object.fromEntries(
          Object.entries(d.sessionOrderByAccount).filter(([key]) => retained.has(key)));// L217
        d.sessionUpdatedAtByAccount = Object.fromEntries(
          Object.entries(d.sessionUpdatedAtByAccount).filter(([key]) => retained.has(key))); // L218 ← 抛错
      },
      // ...
    }
  });
}

崩溃帧精确落在 L218（第三个 Object.entries），意味着 L216/L217 成功执行、即 groupExpansion 与 sessionOrderByAccount 在状态中是可用对象，而 d.sessionUpdatedAtByAccount 为 undefined。

2) 调用方：工作区就绪后的清理 effect

// L1976
function WorkspaceBrowser({ ..., useStore, actions, ... }) {
  const groupBy                   = useStore((s) => s.groupBy);                    // L1983
  const sessionUpdatedAtByAccount = useStore((s) => s.sessionUpdatedAtByAccount);  // L1987
  // ...
  useEffect(() => {                                                                // L2015
    if (workspacePhase !== "ready") return;
    actions.retainAccountKeys([
      "",
      FLAT_SESSION_ORDER_KEY,
      ...workspaces.map((workspace) => workspace.workspaceId)
    ]);
  }, [actions.retainAccountKeys, workspacePhase, workspaces]);                     // L2022-2026
}

workspaceKeys 恒为字符串数组，因此参数侧不是问题；崩溃只可能来自 d.* 缺键。该 effect 仅在工作区投影就绪后触发，与「边栏先空白、再无自愈」的观感一致。

3) 状态为何缺键

init() 提供了全部 5 个键，因此缺键只能来自持久化状态的再水合：浏览器里 dsh.workspace.view.v5 这份 blob 是旧结构（含 groupExpansion / sessionOrderByAccount，不含后加的 sessionUpdatedAtByAccount）。可能的设计缺口：

• persist 版本号仍为 v5，未随结构变更升级/迁移；
• retainAccountKeys 没有 ?? {} 兜底；
• 客户端 store 运行时（defineStore）表现为以持久化对象作为状态，而非 { ...init(), ...persisted } 之类的合并，因此新增键拿不到默认值。

说明：@deepseek-ai/dsh-client-store 在本机安装树中不存在为独立目录，defineStore 运行时实际内联在 Web shell bundle 中（堆栈里的压缩帧 index-BKQ_L1z6.js:56），故本报告只能给出行为观测，其再水合语义（替换 or 合并）需维护者确认。

同一 origin 下曾存在多个 DSH 安装来源（npm 全局安装 + 本地源码 checkout），共享同一份 localStorage，因此旧结构 blob 被当前构建采用的可能性较高。建议维护者按 §建议修复 的 7.1/7.2 一并处理，无需依赖这一具体成因。

4) 为什么一个偏好读取失败会让整个入口消失

@deepseek-ai/dsh-client-ui-renderer@0.1.5-rc.2（lib/client.js）：

// L519
var SlotErrorBoundary = class extends react.Component {
  state = { failed: false };
  static getDerivedStateFromError(error) {
    if (error instanceof SlotAssemblyError) throw error;   // 装配错误仍然响亮失败
    return { failed: true };
  }
  componentDidCatch(error) {
    console.error(`slot entry crashed in '${this.props.slotKey}':`, error);   // L526
    this.props.onEntryError(error);                                          // L527
  }
  render() {
    if (this.state.failed) return <div data-slot-error={this.props.slotKey} />;  // L530
    return this.props.children;
  }
};

// L789-790
const onEntryError = (error) => {
  host.reportEntryError(slotKey, entry, error, { abdicate: spec.kind !== "chain" });
};

sidebar.workspaces 的声明为 kind: "single"（@deepseek-ai/dsh-client-ui-sidebar，构建产物 lib/client.js L391-394），于是 abdicate: true：该 entry 被永久移除，格子变干后由出口渲染无内容的崩溃面；刷新只会重演同一过程。由于 ui-workspace 是该格子的唯一占据者，整个会话管理入口一次性消失。

5) 为什么用户几乎看不到错误

• 异常发生在加载瞬间的首轮渲染，console.error 只打一次，极易被后续插件日志淹没；
• 崩溃面是无文本空 div，UI 无提示；
• 主机侧一切正常：配置树中 ui-workspace 启用且 id 唯一、无第三方插件占用该槽位、GET /api/dsh-web-all/degraded 为空、工作区/会话数据正常。常规主机侧诊断会得出「没问题」的结论。

---

影响

• 用户侧：核心导航与会话管理（工作区切换、会话列表、搜索、重命名 / 分叉 / 归档、排序分组）全部不可用。
• 可诊断性：静默失败 + 主机侧全绿，误导排查方向。
• 持久性：状态在浏览器侧，跨重启存在，表现为「环境坏了」而非「这次运行坏了」。
• 触发面：任何在同一 origin 上发生过版本变更（升级 / 多 checkout 并存 / 回退）的浏览器都可能命中。

---

临时规避（用户侧）

清除该 origin 下过期的视图偏好状态（只影响分组/排序/展开态等本地偏好）：

(() => {
  const keys = Object.keys(localStorage).filter(k => /workspace/i.test(k));
  for (const k of keys) { console.log(k, '=>', localStorage.getItem(k)); localStorage.removeItem(k); }
  location.reload();
})()

或 DevTools → Application → Local Storage → http://127.0.0.1:3080 → 删除 dsh.workspace.view.v5*；兜底可 Clear site data。
验证标准：刷新后边栏恢复，且 Console 不再出现 slot entry crashed in 'sidebar.workspaces'。

---

建议修复

7.1 组件侧（最小止血）

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)));
}

7.2 store 侧（结构性，建议优先）

• 再水合时合并默认值：{ ...init(), ...persisted }（对声明键逐个补默认），使「新增键」对旧 blob 天然安全；
• persist 版本号随结构升级（新增 sessionUpdatedAtByAccount 时应为 dsh.workspace.view.v6）并提供迁移或直接丢弃旧版；
• 反序列化后做结构校验，不符则丢弃整份状态并记 warn，而不是把半成品交给 actions。

7.3 失败面收敛（本缺陷的放大器）

• kind: "single" 的崩溃面建议渲染可见提示（含错误摘要）并提供重挂载/重试入口；
• 将 reportEntryError 的错误汇总暴露为可查询状态（目前只进 ledger 订阅，用户与诊断手段都取不到）。

7.4 测试建议

1. 以「缺少 sessionUpdatedAtByAccount 的 v5 快照」初始化 store，调用 retainAccountKeys，断言不抛错且缺失键补为 {}；
2. 渲染测试：用该状态挂载 WorkspaceBrowser，断言 sidebar.workspaces 未进入错误边界；
3. 门禁：persist 键名与其状态形状的一致性检查（形状变更必须伴随版本变更）。

---

已排除项（供维护者参考，避免重复排查方向）

假设	排除依据
ui-workspace 被配置层禁用 / 未合成	只读合成整棵配置树：该行启用、id 唯一，无任何层禁用
第三方插件抢占 sidebar.workspaces	全量检索第三方插件代码：无 slots.register({ name: 'sidebar.workspaces' })，它们只做 DOM 行注入
目录选择器链条（remote.directoryPicker 缺失导致 apply 未执行）	静态钉 browse 后现象不变；且浏览器取证显示 apply 已执行（否则不会有 retainAccountKeys 崩溃帧）
客户端模块未下发 / bundle 404	window.__DSH_BOOT__.entries 含 @deepseek-ai/dsh-client-ui-workspace（10 项 client inject 齐全），Console 无 bundle 加载失败
槽位未声明	DOM 中 data-slot="sidebar.workspaces" 存在，外壳其他部分正常渲染
数据缺失	工作区存储含 1 工作区 / 3 会话；崩溃发生在 workspacePhase === "ready" 之后

---

诊断片段（复现/定位用）

console.log(JSON.stringify({
  entries: (window.__DSH_BOOT__?.entries ?? [])
    .filter(e => /workspace|sidebar|session/i.test(e.id)).map(e => ({ id: e.id, inject: e.inject })),
  slots: [...document.querySelectorAll('[data-slot]')].map(e => e.dataset.slot),
  wsHTML: document.querySelector('[data-slot="sidebar.workspaces"]')?.outerHTML ?? null
}, null, 1))

判别要点：wsHTML 出现 data-slot-error="sidebar.workspaces" ⇒ 注册成功但渲染崩溃（本缺陷）；若为空 div 且 entries 中无该插件 ⇒ 属插件未加载的另一类故障。

相关代码位置（本机 0.1.5-rc.2 构建产物）

用途	位置
崩溃代码	dsh-client-ui-workspace/lib/client.js L194-229、L1976、L2015-2026
错误边界	dsh-client-ui-renderer/lib/client.js L519-533、L789-790
槽位声明	dsh-client-ui-sidebar/lib/client.js L375-405
持久化键	localStorage["dsh.workspace.view.v5"]（或该前缀）