装了 dsh-genui 却只看到代码块？七个真实故障的定位与修复-开发者社区

dsh-genui 装完之后最常见的抱怨不是「装不上」，而是「装上了，但回答里那个该变成看板的围栏，还是一坨代码」。这类问题的成因分散在激活链、宿主版本、包名、依赖与版本解析五个地方，但每一个都有明确的现象和判据。下面把七个高频故障拆开讲，每个都按现象、原因、解决三段走。

排错前先立一条铁律：区分「下载成功」和「激活成功」

在动手之前先记住一件事：client.js返回 200，或者它出现在 ModuleLoader 缓存里，只能证明文件下载成功，不代表插件已经被宿主激活。真正激活后，浏览器控制台一定会打印[genui] client active; fence-channel=registry|dom。绝大多数「显示成代码块」的问题，第一步都是去找这行日志在不在。更多同类插件的排错对照，可以顺带看完整插件清单与汉化避坑指南。

七个真实故障

坑一 · 围栏原样显示成代码块，界面一点动静都没有

现象。模型按要求输出了dsh-ui围栏，但回答里只有一段被框起来的 JSON，既没有变成看板，控制台也没有任何反应。

原因。这基本等价于「插件下载了但没被激活」。常见触发点是 profile 依赖名、package.json.name、cordis.patch.yml、ModuleLoader id 与配置里的 bundle 名彼此对不上，激活链在某一环断掉。

解决。先在控制台确认有没有[genui] client active; fence-channel=…这行。没有这行就去核对上面那几个身份标识是否一致；有这行再回去看围栏标签和正文写得对不对。宿主没有 registry 扩展点时，插件会自动走 DOM 通道，这是预期行为，不用手动干预。

坑二 · 一渲染 dsh-ui 围栏，整个聊天界面直接白屏

现象。平时正常，一旦回答里出现 dsh-ui 围栏，聊天界面就变白，整页卡死。

原因。版本不匹配。这一版 dsh-genui 要求宿主 DSH 落在支持范围内；使用 DSH<=0.1.1-rc.x的用户，直接用当前版本会出问题。

解决。先确认自己的 DSH 版本。低于0.1.2-rc.1这条线的，改用 dsh-genui 0.9.8；处于受支持范围内的，升级到 npm 上 latest 的插件版本即可。不要在版本明显超界的情况下继续排查别的原因，那是在浪费时间。

坑三 · 命令行报 dsh: pnpm not found on PATH

现象。执行dsh plugin --profile web add …时，终端直接报dsh: pnpm not found on PATH，安装根本走不到下一步。

原因。dsh plugin命令依赖 pnpm，而当前环境没把它放进 PATH。

解决。用corepack enable或npm i -g pnpm补上，然后新开一个终端再试。这一步的关键是「新开终端」——很多人装完就在原 shell 里重试，旧 PATH 还没刷新，命令照样报同样的错。确认手段是pnpm -v能打印版本号。

坑四 · 装是装上了，可 scene3d / mermaid / 图表就是不出来

现象。基础卡片、表格都正常，但一涉及 3D 场景、mermaid 图或 ECharts 图表，位置空着或者只显示源码。

原因。这些引擎不再内联进 client.js。mermaid、three.js、echarts 被拆成按需资产，首次用到时才通过插件自注册的 HTTP 路由（/plugins/@changfenhuang/dsh-genui/assets/*.js）加载。所以「不渲染」很多时候不是坏，而是资产没被触发或没加载成功。

解决。先重启 dsh web 并硬刷新（Cmd+Shift+R）；仍然不行就把插件卸掉重装一次（dsh plugin --profile web remove @changfenhuang/dsh-genui，然后再add）。如果宿主版本过旧、缺少资产路由，会降级显示源码或加载失败提示，这种情况下更新 dsh 即可。

坑五 · 装成了同名但不带 scope 的那个包

现象。命令看着成功了，但描述对不上，宿主随后拒绝安装，或行为完全不是预期的那套。

原因。npm 上另有一个同名但不带 scope 的dsh-genui（Vue / OpenTiny 实现，维护者与本仓库无关）。如果安装列表里写的是「interactive charts, forms, calculators, dashboards, and mini apps」，那就是那个项目。

解决。认准带 scope 的@changfenhuang/dsh-genui，卸载装错的包后按正确包名重装。装错的那个会因 peer 不兼容被宿主拒绝，所以「刚装就被拒」是很典型的信号。

坑六 · 解析到的版本总比 latest 低一档

现象。明明 latest 已经更新了，自己这边解析出来的却总是旧一点，重装也不变。

原因。多半是pnpm 的发布冷静期在起作用。它默认会跳过发布不满 24 小时的版本，而且不提示——于是你看到的就是「怎么装都装不到最新」。

解决。等一天重试；或者在 profile 的pnpm-workspace.yaml的minimumReleaseAgeExclude里加入目标版本。如果 profile 里曾经精确 pin 过旧版本，先把依赖声明改掉再重装。

坑七 · 用 link: 装刚 clone 的目录，渲染器直接挂

现象。本地 clone 了仓库，用link:装上，结果渲染器报错或组件根本出不来。

原因。link:不会安装插件的依赖（mermaid / three / react）。渲染器缺了这些依赖，自然跑不起来。

解决。正常安装一律用 npm 命令dsh plugin --profile web add @changfenhuang/dsh-genui；link:只留给本地开发迭代，而且要自己先把依赖装齐。想确认自己是不是踩了这条，看看是不是走的link:$PWD就知道了。收尾之前再对照一遍完整插件清单与汉化避坑指南，能少走不少弯路。