第三方插件设置页渲染抛错时整页空白：SlotErrorBoundary 只渲染空 div，且 primitives 图标跨版本改名缺少兼容

[Hu-LiHua]

Summary

第三方插件向 settings.section 贡献的整个设置页，只要渲染期抛出一次异常，宿主就只渲染一个空的 <div data-slot-error="settings.section"> —— 用户看到的是一整块空白，没有任何可见提示；同时该条目被 abdicate 后又重新注册、再次崩溃，控制台被 slot entry crashed in 'settings.section' 刷屏。

而这类异常极易被一个与业务无关的原因触发：primitives 种子包的图标导出在 dsh 0.2.0 里改名了（去掉尺寸后缀），第三方插件里写死的旧名取出来是 undefined，jsx(undefined) 即 React #130。也就是说，一个「图标缺了」级别的小问题，最终结果是第三方插件的整页设置面板消失。

受影响对象：所有向 settings.section 贡献页面、且引用了 primitives.Icon* 的第三方插件作者及其用户。

Reproduction

最小复现（任意第三方插件客户端）：

ctx.slots.inject("settings.section", () => ctx.slots.register({
  name: "settings.section", id: "mine", order: 99,
  label: () => "Mine", locale: NS,
}, function MineSection() {
  // 0.2.0-rc.2 的 primitives 里不存在这个名字
  return jsx(primitives.IconSkillOutline16, { size: 14 });
}));

在 dsh 0.2.0-rc.2 上打开「设置」并选中该条目：

1. 内容列整块空白；
2. 控制台反复输出：

client.js:618 slot entry crashed in 'settings.section': Error: Minified React error #130;
visit https://reactjs.org/docs/error-decoder.html?invariant=130&args[]=undefined&args[]= ...
componentDidCatch @ client.js:618

实际触发案例（从 0.2.0-rc.2 发布产物 @deepseek-ai/dsh-client-ui-primitives 反查，三个旧名均已不存在）：

第三方插件引用的旧名	0.2.0-rc.2 实际导出
IconSkillOutline16	IconSkillOutline
IconSearchOutline16	IconSearchOutline
IconChevronDownOutline14	IconChevronDownOutline

Current behavior

从 0.2.0-rc.2 发布产物 @deepseek-ai/dsh-client-ui-renderer 反查到的行为：

1. 回退面不可见。SlotErrorBoundary 命中后只渲染一个空块：

   render() {
     if (this.state.failed) return jsx("div", { "data-slot-error": this.props.slotKey });
     return this.props.children;
   }

   该 div 没有任何样式与文案，高度为 0 —— 用户侧的表现是「设置页没了」，无法区分是插件坏了、被卸载了，还是宿主出问题了。

2. 崩溃被放大成循环。componentDidCatch 走 reportEntryError(slotKey, entry, error, { abdicate: spec.kind !== "chain" })，settings.section 是 list 槽所以会 abdicate；条目被摘除后插件侧 ctx.slots.inject("settings.section", () => ctx.slots.register(…)) 再次注册，于是「注册 → 崩溃 → 摘除 → 再注册」循环，控制台被同一条错误刷屏。

3. getDerivedStateFromError 对两类错误一视同仁：SlotAssemblyError（宿主装配问题）主动 rethrow，其余渲染异常一律吞掉并渲染空 div。但上面这种「可选图标取不到」本质上是可降级的局部问题，不是装配错误。

Expected behavior

1. 可见回退：data-slot-error 容器带上可读文案与出错条目身份（slot key + entry id / label），例如「此设置页加载失败：技能（dsh-skill-mcp-panel）」。让用户与插件作者都能一眼定位是谁、哪个页面坏了。
2. 循环限幅：同一 entry 反复以同一错误崩溃时，停止重注册（或指数退避），避免控制台刷屏。
3. primitives 种子契约的兼容或告警：图标这类导出跨版本改名时，要么保留旧名别名一个次版本周期，要么在插件物化阶段（materialize）就 console.error 明确列出缺失的导出名 —— 现在只能在渲染崩溃后从一条被 React 压缩过的 安全建议：在远程认证完善前，不建议绕过 dsh web 的非 loopback 暴露限制 #130 里反推，定位成本很高。
4. （可选）给 entry 一个 onEntryError / 自定义 fallback 的口子，让插件作者能渲染自己的降级 UI。

Environment

• dsh 桌面运行时：@deepseek-ai/dsh-desktop-runtime 0.2.0-rc.2（Electron 44.0.0 / Node 24.18.1）
• 对照组：dsh CLI 0.1.5-rc.1 下同一插件客户端正常（旧图标名在当时存在）
• 平台：Windows 11 x64
• 影响面：任何贡献 settings.section 且引用 primitives.Icon* 的第三方插件

附注

插件侧我已通过「图标兼容层 + 全部图标走解析函数」规避了这次崩溃（按新名→旧名取第一个存在的导出，全缺失时渲染 null），但这只是把风险从「整页空白」压回「图标不显示」。上面 1–3 才是治本：一个图标缺失，不应该让第三方插件的整页设置面板消失。

[PerryLink]

你把两件事串起来了，而两件我都能对上代码

1. 插槽崩溃只留一个空 div——这点我核过

packages/client/ui-renderer/src/client/scoped-slots.tsx：

console.error(`slot entry crashed in '${this.props.slotKey}':`, error)      // :413
if (this.state.failed) return <div data-slot-error={this.props.slotKey} />  // :417

⇒ 一旦条目崩溃，它只渲染一个带 data-slot-error 的空占位、不再渲染真正的组件，而它是组件状态 ⇒ 不刷新就一直死。你描述的现象完全吻合：整块设置页空白、控制台被 slot entry crashed in 'settings.section' 刷屏（:413 那行正是你看到的文案）。

注意你报告里那句"abdicate 后又重新注册、再次崩溃"——这解释了刷屏：重新注册 ⇒ 新条目 ⇒ 再次崩溃，而没有退避或上限。建议把这句写成一条独立诉求：同一插槽反复崩溃时应有退避/上限。

2. 图标改名这条：导出面确实带 Regular/Medium 后缀

packages/client/ui-primitives/src/icons/index.tsx 里匹配 Icon*Regular 的导出有 94 个。⇒ 导出名带尺寸/字重后缀是这套包的命名形态；第三方插件若写死旧名（例如带尺寸后缀的写法），取到 undefined ⇒ jsx(undefined) ⇒ React #130。你的因果链与导出面形态一致。

建议的诉求（两条，都可验收）：

1. 渲染期异常时给出可见提示，而不是只留空 div（例如渲染一行错误摘要 + 重试），因为"整页空白"让用户无法自助；
2. 改名后的图标导出保留兼容别名（或提供一个稳定的语义名），避免"一个图标改名 ⇒ 第三方设置页整页失效"这种不成比例的后果。

3. 为什么这两条要一起提（你自己的判断对）

你指出"一个图标缺了级别的小问题导致整页不可用"——这就是"错误作用域被放大"，与近期另两条独立报告同一主题（工具挂载失败连坐会话创建、单个插件不兼容让整页不可用）。建议在报告里点明这层主题，它会让这条从"插件兼容问题"上升为宿主该有的隔离边界。

4. 请补一样

插件里那行图标导入的原文（import { Icon… } from '…'）与它期望的名字。有它就能确认"是不是旧名导致 undefined"，也能给维护者一个具体的兼容别名清单。

5. 版本

你在 0.2.0 ⇒ 属当前发布线（latest/next 均 0.2.0-rc.2，最新 alpha = 0.2.1-alpha.1）。⚠️ 注意 latest 不再是旧的 0.1.5-rc.3。

一条边界

我确认的是空占位机制（:413/:417）与图标导出带 Regular/Medium 后缀的形态。**"你那个插件用的是旧名"**要看你补的导入原文——我没有核对该插件。

[Gruu6y]

确认一下：这个缺陷在 0.2.1-rc.3 上仍然存在，而且触发面不止 settings.section——它能让一整列侧栏消失。

我们遇到的真实案例（不是最小复现，是用户侧事故）：一个第三方插件（ds-bot 0.2.2，向宿主做了 35 处 ctx.slots.inject / shadow() 注册，其中侧栏是 sidebar.workspaces）在一次热更新后，左侧整列变成空白。用户看到的现象是「Bot 列表没了」，界面上没有任何提示、没有任何可以自助的操作；重启 App 才恢复。也就是说，一个插件在某个槽位里抛一次渲染异常，用户侧的表现是「这个功能被删了」。

以下代码坐标都取自 0.2.1-rc.3 的 app.asar（抽出 @deepseek-ai/dsh-client-ui-renderer 后逐行读过，1,885 行）：

ui-renderer.js:632   var SlotErrorBoundary = class extends react.Component {
ui-renderer.js:634       static getDerivedStateFromError(error) {
ui-renderer.js:635           if (error instanceof SlotAssemblyError) throw error;
ui-renderer.js:636           return { failed: true };
ui-renderer.js:644       if (this.state.failed) return jsx(Anchor, { "data-slot-error": this.props.slotKey });   // 无 children / 无文案 / 无 aria
ui-renderer.js:1141      host.reportEntryError(slotKey, entry, error, { abdicate: spec.kind !== "chain" });
ui-renderer.js:1173  const deadCell = () => jsx(Anchor, { "data-slot-error": slotKey });
ui-renderer.js:1176  if (!entry) return entries.length > 0 ? deadCell() : jsx(...)
ui-renderer.js:1117  const ANCHOR_STYLE = { display: "contents" };

在楼主报告的基础上，我们往前多走了一步：那个空 div 是永久的

楼主停在「边界接住后只渲染一个空 div」。实际链路还长一节：

1. reportEntryError(..., { abdicate: spec.kind !== "chain" }) 对非 chain 槽位（list/single/keyed 都是）直接 abdicate——把条目永久注销；
2. entriesOfSlot() 会过滤掉已注销项（if (this.abdicated.has(s)) continue），而 entriesOf() 不过滤，于是 :1176 走 deadCell()；
3. deadCell() 与 :644 渲染的都是 Anchor，而 ANCHOR_STYLE 是 display: contents——零高度、零可见内容；
4. 这个 failed 是 React 组件状态，不刷新就不重置；而被 abdicate 的条目不会自己回来。

我们现查了 app.asar 内的 11 个 .css，没有任何一条 slot-error 规则；data-slot-error 在 renderer 源码里出现 4 处（:644 :1173 :1222 :1240），全部只输出空标记，没有一处带文案。

所以用户侧的感受不是「某块渲染失败了」，而是「这块区域从来就不存在」。这一点比「空 div」更严重：空 div 至少还暗示「这里应该有东西」。

一个附带观察（供参考，不是本条的诉求）

SlotErrorBoundary 只对 SlotAssemblyError 主动 rethrow，其余渲染异常一律吞掉。但第三方插件里最常见的崩溃恰恰是可降级的局部问题（比如导出改名后 jsx(undefined) → React #130，正是楼主那条），把它和「装配错误」用同一条兜底路径处理，代价不成比例。

诉求（与楼主一致，按我们的场景再压一遍）

1. 可见回退：data-slot-error 容器至少带一句可读文案 + 出错条目身份（slot key + entry id / label），长什么样都行，别是空的；
2. 可恢复：abdicate 之后给一次重试/退避机会，或者至少让用户能手动重载该槽位，而不是必须重启整个 App；
3. （可选）给 entry 一个 onEntryError / 自定义 fallback 的口子，让插件作者渲染自己的降级 UI——第三方比宿主更清楚「这块坏了该显示什么」。

我们这边能做的规避只是把风险从「整列消失」压回「图标不显示」（所有插件内组件都包了自己的边界），但那是每个插件作者各包一遍，治不了根。

Environment

• DSH 桌面运行时 0.2.1-rc.3（Electron / React 18.3.1）
• 平台：Windows 11 x64
• 出事插件：ds-bot 0.2.2（向宿主注册 35 个槽位条目，崩溃点为 sidebar.workspaces）
• 复现方式：任意第三方插件在其贡献的槽位里抛一次渲染期异常（例如取到 undefined 的图标后 jsx(undefined)），该槽位整列空白且不再自行恢复；重启 App 后恢复

🤖Powered by Gruu6y-DSH🤖